mirror/btstack
1
0
Fork 0
mirror of https://github.com/bluekitchen/btstack.git synced 2025-02-20 18:40:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

first pass migration docu

Browse Source
This commit is contained in:
Milanka Ringwald 2016-03-24 15:41:16 +01:00
parent 12754bbe05
commit 9c72a64abd
1 changed files with 23 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
doc/manual/docs/appendix/migration.md
View File

@ -1,27 +1,25 @@
We already had two listings with the Bluetooth SIG, but no official BTstack v1.0 release. After the second listing, we decided that it's time for a major overhaul of the API - making it easier for new users.
BTstack has grown organically since its creation and mostly kept the API 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.
In the following, we provide an overview of the changes and guidelines for updating an existing code base. At the end, we present a comand line tool and as an alternativ a Web service, that can simplify the migration to hte new v1.0 API.
# Changes
## Repository structure
### *include/btstack* 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.
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 *src/btstack.h* header that includes all BTstack headers.
### Plural folder names
Folder with plural names have been renamed to the singular form, 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 have been moved to *platform* or *port*.
The *ble* folder has been renamed into *src/ble*. Files that are relevant for using BTstack in Classic mode, have been moved to *src/classic*. Files in *src* that are specific to individual platforms have been moved to *platform* or *port*.
### platform and port
The *platforms* folder has been cleaned up. Now, the *port* folder contains a complete BTstack port of for a specific setup consisting of an MCU and a Bluetooth chipset. Code that didn't belong to the BTstack core in *src* have been moved to *platform* or *port* as well, e.g. *hci_transport_h4_dma.c*.
### platform and port folders
The *platforms* folder has been split into *platform* and "port" folders. The *port* folder contains a complete BTstack port of for a specific setup consisting of an MCU and a Bluetooth chipset. Code that didn't belong to the BTstack core in *src* have been moved to *platform* or *port* as well, e.g. *hci_transport_h4_dma.c*.
### Common file names
Types with generic names like linked_list have been prefixed with btstack_ (e.g. btstack_linked_list.h) to avoid problems when integrating with other environments like vendor SDKs.
Types with generic names like *linked_list* have been prefixed with btstack_ (e.g. btstack_linked_list.h) to avoid problems when integrating with other environments like vendor SDKs.
## Defines and event names
All defines that originate from the Bluetooth Specification are now in *src/bluetooth.h*. Addition defines by BTstack are collected in *src/btstack_defines.h*. All events names have the form MODULE_EVENT_NAME now.
@ -38,17 +36,17 @@ To facilitate working with HCI Events and get rid of manually calculating offset
## Event Forwarding
In the past, events have been forwarded up the stack from layer to layer, with the undesired effect that an app that used both *att_server* and *security_manager* would get each HCI event twice. To fix this and other potential issues, this has been cleaned up by providing a way to register multiple listeners for HCI events. If you need to receive HCI or GAP events, you can now directly register your callback with *hci_add_event_handler*.
## util
Utils has been renamed into btstack_util to avoid compile issues with other frameworks.
## util folder
The *utils* folder has been renamed into *btstack_util* to avoid compile issues with other frameworks.
- The functions to read/store values in little/bit endian have been renamed into bit/little_endian_read/write_16/24/32.
- The functions to read/store values in little/bit endian have been renamed into big/little_endian_read/write_16/24/32.
- The functions to reverse bytes swap16/24/32/48/64/128/X habe been renamed to reverse_16/24/32/48/64/128/X.
## 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.
- _NO_ has been replaced with _NR_ for the BTstack static memory allocation, e.g., *MAX_NO_HCI_CONNECTIONS8 -> *MAX_NR_HCI_CONNECTIONS*
- The #define EMBEDDED was dropped. The signature for sdp_register_service did differ with/without EMBEDDED being defined or not.
- Defines have been sorted: HAVE_ specify features that are particular to your port. ENABLE_ features can be added as needed.
- _NO_ has been replaced with _NR_ for the BTstack static memory allocation, e.g., *MAX_NO_HCI_CONNECTIONS8 -> MAX_NR_HCI_CONNECTIONS*
- The #define EMBEDDED is dropped, i.e. the distinction if the API is for embedded or not has been removed.
## Linked List
- The file has been renamed to btstack_linked_list.
@ -84,8 +82,8 @@ The function to create an SPP SDP record has been moved into *spp_server.h*
- SDP Query structs have been replaced by HCI events. You can use btstack_event.h to access the fields.
## SDP Server
- Has been renamed to *src/sdp_server*.
- The API for adding a service record was different for
- Has been renamed to *src/classic/sdp_server.h*.
- The distinction if the API is for embedded or not has been removed.
## Security Manager
- In all Security Manager calls that refer to an active connection, pass in the current handle instead of addr + addr type.
@ -100,9 +98,10 @@ The function to create an SPP SDP record has been moved into *spp_server.h*
Renamed to *src/ble/ancs_client*
## Flow control / DAEMON_EVENT_PACKET_SENT
When an application was allowed to send the next L2CAP or RFCOMM packet haven't been clear in the past and we suggested to check with l2cap_can_send_packet_now(..) or rfcomm_can_send_packet(..) whenever an HCI event was received. This has been cleaned up and streamlined as well in v1.0.
Both L2CAP and RFCOMM now emit a L2CAP_EVENT_CAN_SEND_NOW or a RFCOMM_EVENT_CAN_SEND_NOW after the connection gets established. The app can now send a packet if it is ready to sent. If the app later wants to send, it has to call l2cap/rfcomm_can_send_packet_now(..). If the result is negative, BTstack will emit the L2CAP/RCOMM_EVENT_CAN_SEND_NOW as soon as sending becomes possible again. We hope that this design leads to simpler application code.
In BTstack teh functions l2cap_can_send_packet_now(..) and rfcomm_can_send_packet(..) must be called before sending the next L2CAP or RFCOMM packet. Before v1.0, we suggested to check with l2cap_can_send_packet_now(..) or rfcomm_can_send_packet(..) whenever an HCI event was received. This has been cleaned up and streamlined in v1.0.
Now, both L2CAP and RFCOMM now emit a L2CAP_EVENT_CAN_SEND_NOW or a RFCOMM_EVENT_CAN_SEND_NOW after the connection gets established. The app can now send a packet if it is ready to send. If the app later wants to send, it has to call l2cap/rfcomm_can_send_packet_now(..). If the result is negative, BTstack will emit the L2CAP/RCOMM_EVENT_CAN_SEND_NOW as soon as sending becomes possible again. We hope that this design leads to simpler application code.
## Daemon
- Not tested since API migration!
@ -110,25 +109,24 @@ Both L2CAP and RFCOMM now emit a L2CAP_EVENT_CAN_SEND_NOW or a RFCOMM_EVENT_CAN_
- Header for clients: *platform/daemon/btstack_client.h*
- Java bindings are now at *platform/daemon/bindings*
# Migration to v1.0
## Migration to v1.0 with a script
To simplify the migration to the new v1.0 API, we've provided a tool in *tool/migration_to_v1.0* that fixes include path changes, handles all function renames and also updates the packet handlers to the btstack_packet_handler_t type. It also has a few rules that try to rename file names in Makefile as good as possible.
It's possible to migrate most of the provided embedded exmpamples to v1.0. The one change that it cannot handle is the switch from structs to HCI Events for the SDP, GATT, and ANCS clients. The migration tool updates the packet handler signature to btstack_packet_handler_t, but it does not convert the field accesses to sue the appropriate getters in *btstack_event.h*. This has to be done manually, but it is straight forward. E.g., to read the field *status* of the GATT_EVENT_QUERY_COMPLETE, you call call gatt_event_query_complete_get_status(packet).
It's possible to migrate most of the provided embedded examples to v1.0. The one change that it cannot handle is the switch from structs to HCI Events for the SDP, GATT, and ANCS clients. The migration tool updates the packet handler signature to btstack_packet_handler_t, but it does not convert the field accesses to sue the appropriate getters in *btstack_event.h*. This has to be done manually, but it is straight forward. E.g., to read the field *status* of the GATT_EVENT_QUERY_COMPLETE, you call call gatt_event_query_complete_get_status(packet).
## Requirements
### Requirements
- bash
- sed
- [Coccinelle](http://coccinelle.lip6.fr/). On Debian-based distributions, it's available via apt. On OS X, it can be installed via Homebrew.
## Usage
### Usage
tool/migration_to_v1.0/migration.sh PATH_TO_ORIGINAL_PROJECT PATH_TO_MIGRATED_PROJECT
The tool first creates a copy of the original project and then uses sed and coccinelle to update the source files.
## Web Service
## Migration to v1.0 with a Web Service
BlueKitchen GmbH is providing a [web service](http://buildbot.bluekitchen-gmbh.com/migration) to help migrate your sources if you don't want or cannot install Coccinelle yourself.