btstack/doc/manual/docs/appendix/migration.md

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