From 476422addbae297135015a756443f9bc65efee81 Mon Sep 17 00:00:00 2001 From: Matthias Ringwald Date: Wed, 9 Mar 2016 17:24:13 +0100 Subject: [PATCH] docs: start collecting migration info --- doc/manual/docs/appendix/migration.md | 108 ++++++++++++++++++++++++++ doc/manual/mkdocs.yml | 5 +- 2 files changed, 111 insertions(+), 2 deletions(-) create mode 100644 doc/manual/docs/appendix/migration.md diff --git a/doc/manual/docs/appendix/migration.md b/doc/manual/docs/appendix/migration.md new file mode 100644 index 000000000..ff871d934 --- /dev/null +++ b/doc/manual/docs/appendix/migration.md @@ -0,0 +1,108 @@ +BTstack has grown organically since its creation and mostly kept the APIs compatible. +After the second listing with the Bluetooth SIG, we decided that it's time for a major overhaul of the API - making easier for new users. This version will be released as v1.0. + +In the following, we provide an overview of the changes and guidelines for updating an existing code base. + +# Changes + +## Project structure + +### include folder +The header files had been split between *src/* and *include/btstack*/. Now, the *include/* folder is gone and the headers are provided in *src/*, *src/classic/*, *src/ble/* or by the *platform/* folders. There's a new "btstack.h" header that includes all BTstack headers. + +### Defines +All defines that originate from the Bluetooth Specification are now in *src/bluetooth.h*. BTstack defines are collected in *src/btstack_defines.h* + +### Plural folder names +Folder with plural names have been renamed to singular, examples: *doc*, *chipset*, *platform*, *tool*. + +### ble and src folders +The *ble* folder has been renamed into *src/ble*. Files only relevant for using BTstack in Classic mode, have been moved to *src/classic*. Files in *src* that are specific to individual platforms are moved to *platform* or *port*. + +### platform and port +The *platforms* folder has been cleaned up. Now, the *port* folder contains a complete port of BTstack for a specific setup consisting of a MCU and a Bluetooth chipset. Code that didn't belong to the BTstack core in *src* have been moved to *platform* or *port* + +## Function and file names +- The _internal suffix has been an artefact from the iOS port. All public functions with the _internal suffix have been stripped of this suffix. +- Types with generic names like linked_list have been prefixed with btstack_ (e.g. btstack_linked_list) to avoid problems when integrating with other environments like vendor SDKs. + +## Event names +All events names have the form MODULE_EVENT_NAME now. + +## Packet Handlers +We streamlined the use of packet handlers and their types. Most callbacks are now of type *btstack_packet_handler_t* and receive a pointer to an HCI Event packet. Often a void * connection was the first argument - this has been removed resp. pushed up into the BTstack Daemon. + +To facilitate working with HCI Events and get rid of manually calculating offsets into packets, we're providing the auto-generated getters for all fields of all elements in *src/hci_event.h*. All functions are defined as static inline, so they are not wasting any program memory. + +Feel free to start using these getters as needed. + +## Event forwarding +In the past, events have been forwarded up the stack with the effect that an app that used the *att_server* and the *security_manager* would get each HCI event twice. This has been cleaned up by providing a way to register multiple listeners for HCI events. + +## remote_device_db.h +Has been split into *src/classic/btstack_link_key_db*, *platform/daemon/btstack_device_name_db*, and *platform/daemon/rfcomm_service_db*. + +## bt_control.h +Has been split into *src/btstack_chipset.h* and *src/bstack_control.h* + +## Security Manager +- In all Security Manager calls that refer to an active connection, pass in the current handle instead of addr + addr type. +- All Security Manager events are now regular HCI Events instead of sm_* structs +- Multiple packet handler can be registered with sm_add_event_handler() + +## RFCOMM +- Packet handler per service and outgoing connection + +## HCI / GAP +- In hci_init() only the HCI Transport and it's configuration have to be provided. A link key db can be set via hci_set_link_key_db. Similar, hci_set_chipset() and hci_set_control can be called if needed. +- HCI Event handlers can be registered with hci_add_event_handler +- HCI functions that are commonly placed in GAP have been moved from *src/hci.h* to *src/gap.h* + +## btstack_util.h +- The functions to read/store values in little/bit endian have been renamed into bit/little_endian_read/write_16/24/32. +- swapX -> reverse_x + +## Linked List +- Renamed to btstack_linked_list +- Removed user data field + +## Timers +- Added context field + +## Run Loop +- Run loop type selection via implementation run_loop_t struct (see run_loop_NAME_instance()) + +## GATT Client +- All GATT Client events are now regular HCI Events instead of gatt_* structs. +- The subclient_id has been replaced by a complete handler for GATT Client requests + +## ANCS Client +Renamed to *src/ble/ancs_client* + +## SDP Server +- Has been renamed to */src/sdp_server*. +- The API for adding a service record was different for + +## SDP Client +- SDP Query structs have been repalced by HCI events + + +## btstack_config.h +- *btstack-config.h* is now *btstack_config.h* +- Defines have been sorted. HAVE_ specify features that are particular to your port. ENABLE_ features can then be added as needed +- EMBEDDED dropped + +## Flow control / DAEMON_EVENT_PACKET_SENT +- TODO -- don't hand out local credits + +## Daemon +- Moved into *platform/daemon/*. Not tested yet. +- Header for clients: *platform/daemon/btstack_client.h* +- Java bindings are now at *platform/daemon/bindings* + +## Unsorted + + + +# Migration + diff --git a/doc/manual/mkdocs.yml b/doc/manual/mkdocs.yml index b2a10ca47..f7334e0a4 100644 --- a/doc/manual/mkdocs.yml +++ b/doc/manual/mkdocs.yml @@ -1,6 +1,6 @@ site_name: BTstack Manual v1.0 site_dir: btstack -docs_dir: docs_final +docs_dir: docs pages: - [index.md, Welcome] - [quick_start.md, Quick Start] @@ -13,4 +13,5 @@ pages: - [integration.md, Integrating with Existing Systems] - [appendix/apis.md, APIs] - [appendix/events_errors.md, Events and Errors] -theme: readthedocs \ No newline at end of file +- [appendix/migration.md, Migration to v1.0] +theme: readthedocs