ScStw/esp-nimble-cpp
2
0
Fork 0
mirror of https://github.com/h2zero/esp-nimble-cpp.git synced 2024-12-18 09:10:47 +01:00
Code Issues Projects Releases Packages Wiki Activity

Update migration guide

Browse source
This commit is contained in:
h2zero 2024-12-07 10:44:50 -07:00 committed by h2zero
parent 0e5eb9c55f
commit eba6d8bfbb
1 changed files with 32 additions and 35 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

67
docs/Migration_guide.md
View file

@ -4,7 +4,7 @@ This guide describes the required changes to existing projects migrating from th
**The changes listed here are only the required changes that must be made**, and a short overview of options for migrating existing applications. **The changes listed here are only the required changes that must be made**, and a short overview of options for migrating existing applications.
For more information on the improvements and additions please refer to the [class documentation](https://h2zero.github.io/NimBLE-Arduino/annotated.html) and [Improvements and updates](Improvements_and_updates.md) For more information on the improvements and additions please refer to the [class documentation](https://h2zero.github.io/esp-nimble-cpp/annotated.html) and [Improvements and updates](Improvements_and_updates.md)
* [General Changes](#general-information) * [General Changes](#general-information)
* [Server](#server-api) * [Server](#server-api)
@ -48,7 +48,7 @@ For example `BLEAddress addr(11:22:33:44:55:66, 1)` will create the address obje
As this parameter is optional no changes to existing code are needed, it is mentioned here for information. As this parameter is optional no changes to existing code are needed, it is mentioned here for information.
`BLEAddress::getNative` (`NimBLEAddress::getNative`) returns a uint8_t pointer to the native address byte array. In this library the address bytes are stored in reverse order from the original library. This is due to the way the NimBLE stack expects addresses to be presented to it. All other functions such as `toString` are not affected as the endian change is made within them. `BLEAddress::getNative` is now named `NimBLEAddress::getBase` and returns a pointer to `const ble_addr_t` instead of a pointer to the address value.
<br/> <br/>
<a name="server-api"></a> <a name="server-api"></a>
@ -72,7 +72,7 @@ void onDisconnect(NimBLEServer* pServer, NimBLEConnInfo& connInfo, int reason)`
``` ```
<br/> <br/>
`BLEServerCallbacks::onMtuChanged` (`NimBLEServerCallbacks::onMtuChanged`) takes the parameter `NimBLEConnInfo & connInfo` instead of `esp_ble_gatts_cb_param_t`, which has methods to get information about the connected peer. `BLEServerCallbacks::onMtuChanged` is now (`NimBLEServerCallbacks::onMtuChange`) and takes the parameter `NimBLEConnInfo & connInfo` instead of `esp_ble_gatts_cb_param_t`, which has methods to get information about the connected peer.
``` ```
onMTUChange(uint16_t MTU, NimBLEConnInfo& connInfo) onMTUChange(uint16_t MTU, NimBLEConnInfo& connInfo)
@ -139,6 +139,7 @@ BLECharacteristic *pCharacteristic = pService->createCharacteristic(
<a name="characteristic-callbacks"></a> <a name="characteristic-callbacks"></a>
#### Characteristic callbacks #### Characteristic callbacks
`BLECharacteristicCallbacks` (`NimBLECharacteristicCallbacks`) has a new method `NimBLECharacteristicCallbacks::onSubscribe` which is called when a client subscribes to notifications/indications. `BLECharacteristicCallbacks` (`NimBLECharacteristicCallbacks`) has a new method `NimBLECharacteristicCallbacks::onSubscribe` which is called when a client subscribes to notifications/indications.
`BLECharacteristicCallbacks::onRead` (`NimBLECharacteristicCallbacks::onRead`) only has a single callback declaration, which takes an additional (required) parameter of `NimBLEConnInfo& connInfo`, which provides connection information about the peer. `BLECharacteristicCallbacks::onRead` (`NimBLECharacteristicCallbacks::onRead`) only has a single callback declaration, which takes an additional (required) parameter of `NimBLEConnInfo& connInfo`, which provides connection information about the peer.
@ -179,8 +180,7 @@ NimBLE automatically creates the 0x2902 descriptor if a characteristic has a not
It was no longer useful to have a class for the 0x2902 descriptor as a new callback `NimBLECharacteristicCallbacks::onSubscribe` was added It was no longer useful to have a class for the 0x2902 descriptor as a new callback `NimBLECharacteristicCallbacks::onSubscribe` was added
to handle callback functionality and the client subscription status is handled internally. to handle callback functionality and the client subscription status is handled internally.
**Note:** Attempting to create a 0x2902 descriptor will trigger an assert to notify the error, **Note:** Attempting to create a 0x2902 descriptor will trigger a warning message and flag it internally as removed and will not be functional.
allowing the creation of it would cause a fault in the NimBLE stack.
All other descriptors are now created just as characteristics are by using the `NimBLECharacteristic::createDescriptor` method (except 0x2904, see below). All other descriptors are now created just as characteristics are by using the `NimBLECharacteristic::createDescriptor` method (except 0x2904, see below).
Which are defined as: Which are defined as:
@ -208,22 +208,15 @@ pDescriptor = pCharacteristic->createDescriptor("ABCD",
Would create a descriptor with the UUID 0xABCD, publicly readable but only writable if paired/bonded (encrypted) and has a max value length of 25 bytes. Would create a descriptor with the UUID 0xABCD, publicly readable but only writable if paired/bonded (encrypted) and has a max value length of 25 bytes.
<br/> <br/>
For the 0x2904, there is a special class that is created when you call `createDescriptor("2904"). For the 0x2904, there is a specialized class that is created through `NimBLECharacteristic::create2904` which returns a pointer to a `NimBLE2904` instance which has specific
functions for handling the data expect in the Characteristic Presentation Format Descriptor specification.
The pointer returned is of the base class `NimBLEDescriptor` but the call will create the derived class of `NimBLE2904` so you must cast the returned pointer to
`NimBLE2904` to access the specific class methods.
##### Example
```
p2904 = (NimBLE2904*)pCharacteristic->createDescriptor("2904");
```
<br/> <br/>
<a name="descriptor-callbacks"></a> <a name="descriptor-callbacks"></a>
#### Descriptor callbacks #### Descriptor callbacks
> `BLEDescriptorCallbacks::onRead` (`NimBLEDescriptorCallbacks::onRead`) > `BLEDescriptorCallbacks::onRead` (`NimBLEDescriptorCallbacks::onRead`)
`BLEDescriptorCallbacks::onwrite` (`NimBLEDescriptorCallbacks::onwrite`) `BLEDescriptorCallbacks::onWrite` (`NimBLEDescriptorCallbacks::onWrite`)
The above descriptor callbacks take an additional (required) parameter `NimBLEConnInfo& connInfo`, which contains the connection information of the peer. The above descriptor callbacks take an additional (required) parameter `NimBLEConnInfo& connInfo`, which contains the connection information of the peer.
<br/> <br/>
@ -255,8 +248,7 @@ Calling `NimBLEAdvertising::setAdvertisementData` will entirely replace any data
> BLEAdvertising::start (NimBLEAdvertising::start) > BLEAdvertising::start (NimBLEAdvertising::start)
Now takes 2 optional parameters, the first is the duration to advertise for (in milliseconds), the second is a callback that is invoked when advertising ends and takes a pointer to a `NimBLEAdvertising` object (similar to the `NimBLEScan::start` API). Now takes 2 optional parameters, the first is the duration to advertise for (in milliseconds), the second `NimBLEAddress` to direct advertising to a specific device.
This provides an opportunity to update the advertisement data if desired.
<br/> <br/>
<a name="client-api"></a> <a name="client-api"></a>
@ -268,15 +260,17 @@ Multiple client instances can be created, up to the maximum number of connection
`BLEClient::connect`(`NimBLEClient::connect`) Has had it's parameters altered. `BLEClient::connect`(`NimBLEClient::connect`) Has had it's parameters altered.
Defined as: Defined as:
> NimBLEClient::connect(bool deleteServices = true); > NimBLEClient::connect(bool deleteServices = true, , bool asyncConnect = false, bool exchangeMTU = true);
> NimBLEClient::connect(NimBLEAdvertisedDevice\* device, bool deleteServices = true); > NimBLEClient::connect(const NimBLEAddress& address, bool deleteAttributes = true, bool asyncConnect = false, bool exchangeMTU = true);
> NimBLEClient::connect(NimBLEAddress address, bool deleteServices = true); > NimBLEClient::connect(const NimBLEAdvertisedDevice* device, bool deleteServices = true, bool asyncConnect = false, bool exchangeMTU = true);
The type parameter has been removed and a new bool parameter has been added to indicate if the client should delete the attribute database previously retrieved (if applicable) for the peripheral, default value is true. The type parameter has been removed and a new bool parameter has been added to indicate if the client should delete the attribute database previously retrieved (if applicable) for the peripheral, default value is true.
If set to false the client will use the attribute database it retrieved from the peripheral when previously connected. If set to false the client will use the attribute database it retrieved from the peripheral when previously connected. This allows for faster connections and power saving if the devices dropped connection and are reconnecting.
This allows for faster connections and power saving if the devices dropped connection and are reconnecting. The parameter `bool asyncConnect` if true, will cause the client to send the connect command to the stack and return immediately without blocking. The return value will represent wether the command was sent successfully or not and the `NimBLEClientCallbacks::onConnect` or `NimBLEClientCallbacks::onConnectFail` will be called when the operation is complete.
The parameter `bool exchangeMTU` if true, will cause the client to perform the exchange MTU process upon connecting. If false the MTU exchange will need to be performed by the application by calling `NimBLEClient::exchangeMTU`. If the connection is only sending small payloads it may be advantageous to not exchange the MTU to gain performance in the connection process.
<br/> <br/>
> `BLEClient::getServices` (`NimBLEClient::getServices`) > `BLEClient::getServices` (`NimBLEClient::getServices`)
@ -301,8 +295,7 @@ This method has been removed.
> `BLERemoteService::getCharacteristics` (`NimBLERemoteService::getCharacteristics`) > `BLERemoteService::getCharacteristics` (`NimBLERemoteService::getCharacteristics`)
This method now takes an optional (bool) parameter to indicate if the characteristics should be retrieved from the server (true) or This method now takes an optional (bool) parameter to indicate if the characteristics should be retrieved from the server (true) or the currently known database returned, default = false.
the currently known database returned (false : default).
Also now returns a pointer to `std::vector` instead of `std::map`. Also now returns a pointer to `std::vector` instead of `std::map`.
<br/> <br/>
@ -326,12 +319,12 @@ Has been removed.
Are the new methods added to replace it. Are the new methods added to replace it.
<br/> <br/>
> `BLERemoteCharacteristic::readUInt8` (`NimBLERemoteCharacteristic::readUInt8`) > `BLERemoteCharacteristic::readUInt8` (`NimBLERemoteCharacteristic::readUInt8`)
> `BLERemoteCharacteristic::readUInt16` (`NimBLERemoteCharacteristic::readUInt16`) > `BLERemoteCharacteristic::readUInt16` (`NimBLERemoteCharacteristic::readUInt16`)
> `BLERemoteCharacteristic::readUInt32` (`NimBLERemoteCharacteristic::readUInt32`) > `BLERemoteCharacteristic::readUInt32` (`NimBLERemoteCharacteristic::readUInt32`)
> `BLERemoteCharacteristic::readFloat` (`NimBLERemoteCharacteristic::readFloat`) > `BLERemoteCharacteristic::readFloat` (`NimBLERemoteCharacteristic::readFloat`)
Are **deprecated** a template: `NimBLERemoteCharacteristic::readValue<type\>(time_t\*, bool)` has been added to replace them. Are **removed** a template: `NimBLERemoteCharacteristic::readValue<type\>(time_t\*, bool)` has been added to replace them.
<br/> <br/>
> `BLERemoteCharacteristic::readRawData` > `BLERemoteCharacteristic::readRawData`
@ -339,10 +332,10 @@ Are **deprecated** a template: `NimBLERemoteCharacteristic::readValue<type\>(tim
**Has been removed from the API** **Has been removed from the API**
Originally it stored an unnecessary copy of the data and was returning a `uint8_t` pointer to volatile internal data. Originally it stored an unnecessary copy of the data and was returning a `uint8_t` pointer to volatile internal data.
The user application should use `NimBLERemoteCharacteristic::readValue` or `NimBLERemoteCharacteristic::getValue`. The user application should use `NimBLERemoteCharacteristic::readValue` or `NimBLERemoteCharacteristic::getValue`.
To obtain a copy of the data, then cast the returned std::string to the type required such as: To obtain a copy of the data as a `NimBLEAttValue` instance and use the `NimBLEAttValue::data` member function to obtain the pointer.
``` ```
std::string value = pChr->readValue(); NimBLEAttValue value = pChr->readValue();
uint8_t *data = (uint8_t*)value.data(); const uint8_t *data = value.data();
``` ```
Alternatively use the `readValue` template: Alternatively use the `readValue` template:
``` ```
@ -352,8 +345,7 @@ my_struct_t myStruct = pChr->readValue<my_struct_t>();
> `BLERemoteCharacteristic::getDescriptors` (`NimBLERemoteCharacteristic::getDescriptors`) > `BLERemoteCharacteristic::getDescriptors` (`NimBLERemoteCharacteristic::getDescriptors`)
This method now takes an optional (bool) parameter to indicate if the descriptors should be retrieved from the server (true) or This method now takes an optional (bool) parameter to indicate if the descriptors should be retrieved from the server (true) or the currently known database returned, default = false.
the currently known database returned (false : default).
Also now returns a pointer to `std::vector` instead of `std::map`. Also now returns a pointer to `std::vector` instead of `std::map`.
<br/> <br/>
@ -373,7 +365,12 @@ The default configuration will use "just-works" pairing with no bonding, if you
<a name="scan-api"></a> <a name="scan-api"></a>
## BLE Scan ## BLE Scan
The scan API is mostly unchanged from the original except for `NimBLEScan::start`, in which the duration parameter is now in milliseconds instead of seconds. The scan API is mostly unchanged from the original except for `NimBLEScan::start`, which has the following changes:
* The duration parameter is now in milliseconds instead of seconds.
* The callback parameter has been removed.
* A new parameter `bool restart` has been added, when set to true to restart the scan if already in progress and clear the duplicate cache.
The blocking overload of `NimBLEScan::start` has been replaced by an overload of `NimBLEScan::getResults` with the same parameters.
<br/> <br/>
<a name="security-api"></a> <a name="security-api"></a>
@ -386,7 +383,7 @@ The callback methods are:
> `bool onConfirmPasskey(NimBLEConnInfo& connInfo, uint32_t pin)` > `bool onConfirmPasskey(NimBLEConnInfo& connInfo, uint32_t pin)`
Receives the pin when using numeric comparison authentication. Receives the pin when using numeric comparison authentication.
Call `NimBLEDevice::injectConfirmPIN(connInfo, true);` to accept or `NimBLEDevice::injectConfirmPIN(connInfo, false);` to reject. Call `NimBLEDevice::injectConfirmPasskey(connInfo, true);` to accept or `NimBLEDevice::injectConfirmPasskey(connInfo, false);` to reject.
<br/> <br/>
> `void onPassKeyEntry(NimBLEConnInfo& connInfo)` > `void onPassKeyEntry(NimBLEConnInfo& connInfo)`