NimBLE-Arduino 2.1.2
Loading...
Searching...
No Matches
Migrating from 1.x to 2.x

Nearly all of the codebase has been updated and changed under the surface, which has greatly reduced the resource use of the library and improved it's performance. To be able to support these changes it required various API changes and additions.

This guide will help you migrate your application code to use the new API.

The changes listed here are only the required changes that must be made, and a short overview of options for migrating existing applications.

General changes

  • All functions that take a time parameter now require the time in milliseconds instead of seconds, i.e. NimBLEScan::start(10000); // 10 seconds
  • NimBLESecurity class has been removed it's functionality has been merged into the NimBLEServer and NimBLEClient classes.
  • All connection oriented callbacks now receive a reference to NimBLEConnInfo and the ble_gap_conn_desc parameter has been replaced with NimBLEConnInfo in the functions that received it.
    For instance onAuthenticationComplete(ble_gap_conn_desc* desc) signature is now onAuthenticationComplete(NimBLEConnInfo& connInfo) and
    NimBLEServerCallbacks::onConnect(NimBLEServer* pServer) signature is now NimBLEServerCallbacks::onConnect(NimBLEServer* pServer, NimBLEConnInfo& connInfo).

BLE Device

  • Ignore list functions and vector have been removed, the application should implement this if desired. It was no longer used by the library.
  • NimBLEDevice::startSecurity now returns a bool, true on success, instead of an int to be consistent with the rest of the library.
  • NimBLEDevice::getInitialized renamed to NimBLEDevice::isInitialized.
  • NimBLEDevice::setPower no longer takes the esp_power_level_t and esp_ble_power_type_t, instead only an integer value in dbm units is accepted, so instead of ESP_PWR_LVL_P9 an int8_t value of 9 would be used for the same result.
  • NimBLEDevice::setOwnAddrType no longer takes a bool nrpa parameter, the random address type will be determined by the bits the in the address instead.
    Note: If setting a custom address, it should be set with NimBLEDevice::setOwnAddr first before calling NimBLEDevice::setOwnAddrType.
  • NimBLEDevice::getClientListSize replaced with NimBLEDevice::getCreatedClientCount.
  • NimBLEDevice::getClientList was removed and NimBLEDevice::getConnectedClients can be used instead which returns a std::vector of pointers to the connected client instances. This was done because internally the clients are managed in a std::array which replaced the 'std::list`.

BLE Addresses

NimBLEAddress comparisons have changed to now consider the address type. If 2 address values are the same but the type is different then they are no longer considered equal. This is a correction to the 1.x version which did not consider the type, whereas the BLE specification states:

‍Whenever two device addresses are compared, the comparison shall include the device address type (i.e. if the two addresses have different types, they are different even if the two 48-bit addresses are the same).

This means that if in your application you create a NimBLEAddress instance and are comparing a scan result or some other address created by the library and you did not define the address type then the comparison may fail. The default address type is public 0, whereas many devices use a random 1 address type. If you experience this issue please create your address instances with the address type specified, i.e. NimBLEAddress address("11:22:33:44:55:66", TYPE_HERE)

NimBLEAddress::getNative has been removed and replaced with NimBLEAddress::getBase. This returns a pointer to const ble_addr_t instead of a pointer to the address value that getNative did. The value can be accessed through this struct via ble_addr_t.value and type is in ble_addr_t.type.

BLE UUID's

Server

Services

Characteristics

Characteristic callbacks

  • NimBLECharacteristicCallbacks::onNotify removed as unnecessary, the library does not call notify without app input.
  • NimBLECharacteristicCallbacks::onStatus No longer takes a status parameter, refer to the return code parameter for success/failure.

Server Security

Client

  • NimBLEClient::getServices now returns a const reference to std::vector<NimBLERemoteService*> instead of a pointer to the internal vector.
  • NimBLEClient::getConnId has been renamed to getConnHandle to be consistent with bluetooth terminology.
  • NimBLEClient::disconnect now returns a bool, true on success, instead of an int to be consistent with the rest of the library.

Client callbacks

Remote Services

Remote Characteristics

  • NimBLERemoteCharacteristic::getRemoteService now returns a const NimBLERemoteService* instead of non-const.
  • NimBLERemoteCharacteristic::registerForNotify, has been removed, the application should use NimBLERemoteCharacteristic::subscribe and NimBLERemoteCharacteristic::unSubscribe. 
      `NimBLERemoteCharacteristic::readUInt32`
  `NimBLERemoteCharacteristic::readUInt16`
  `NimBLERemoteCharacteristic::readUInt8`
  `NimBLERemoteCharacteristic::readFloat`
    Have been removed, instead the application should use NimBLERemoteCharacteristic::readValue<type\>.

Scan

  • NimBLEScan::stop will no longer call the onScanEnd callback as the caller should know it has been stopped either by initiating a connection or calling this function itself.
  • NimBLEScan::clearDuplicateCache has been removed as it was problematic and only for the original esp32. The application should stop and start the scanner for the same effect or call NimBLEScan::start with the new bool restart parameter set to true.
  • NimBLEScanResults::getDevice methods now return const NimBLEAdvertisedDevice* instead of a non-const pointer.
  • NimBLEScanResults iterators are now const_iterator.

  • The callback parameter for NimBLEScan::start has been removed and the blocking overload of NimBLEScan::start has been replaced by an overload of NimBLEScan::getResults with the same parameters.

    So if your code prior was this: 

    NimBLEScanResults results = pScan->start(10, false);

    It should now be: 

    NimBLEScanResults results = pScan->getResults(10000, false); // note the time is now in milliseconds
  • NimBLEAdvertisedDeviceCallbacks Has been replaced by NimBLEScanCallbacks which contains the following methods:
  • - NimBLEScanCallbacks::onResult, functions the same as the old NimBLEAdvertisedDeviceCallbacks::onResult but now takes aa const NimBLEAdvertisedDevice* instead of non-const.
  • - NimBLEScanCallbacks::onScanEnd, replaces the scanEnded callback passed to NimBLEScan::start and now takes a const NimBLEScanResults& and int reason parameter.
  • - NimBLEScanCallbacks::onDiscovered, This is called immediately when a device is first scanned, before any scan response data is available and takes a const NimBLEAdvertisedDevice* parameter.

Advertised Device

  • NimBLEAdvertisedDevice::hasRSSI removed as redundant, RSSI is always available.
  • NimBLEAdvertisedDevice::getPayload now returns const std::vector<uint8_t>& instead of a pointer to internal memory.
  • NimBLEAdvertisedDevice Timestamp removed, if needed then the app should track the time from the callback.

Advertising

Beacons

Utilities

  • NimBLEUtils::dumpGapEvent function removed.
  • NimBLEUtils::buildHexData replaced with NimBLEUtils::dataToHexString, which returns a std::string containing the hex string.