2.0.2

Fixed

• Compile error when only advertising role is enabled.
• Possible crash if bonded client reconnects.

Changed

• NimBLEHIDDevice can now create more than one in/out/feature report map.

2.0.1

Fixed

• NimBLEHIDDevice::getOutputReport will now return the correct characteristic.
• Compile error when central is disabled, class NimBLEServer has no member named m_pClient.

Changed

• Added missing includes for NimBLEConnInfo and NimBLEUtils to NimBLEDevice.h.

2.0.0

Finally! A new release with something more than a bugfix or some minor additions!

I'm excited to present this release properly after the unfortunate Arduino Library Manager debacle 🎉.

This was a complete overhaul of the codebase, every file as been touched up and some completely re-designed, removed, added, or changed significantly. This required A LOT of changes, many will break your current application code, but don't worry, it will be much better!

This release has so much in it!

Highlights

• Reduced the code size by over 40KB.
• Significant reduction in memory use.
• Huge performance boost.
• Asynchronous client connect, MTU exchange, and secure connection options to speed up the connecting process.
• Asynchronous passkey entry/confirmation so the client/server can have time to properly display/enter the passkey before action is performed.
• Scan restart option to clear the duplicate cache so the same devices will be found again.
• New scan callbacks class with extra functions that will get called on first discovery, before and scan response data is received.
• Ability to update advertised data while advertising.
• Improved support for dynamically changing services/characteristics/descriptors.
• Simplified code for easier maintenance and understanding for contributors.

Full Changelog

Breaking changes

• All connection oriented callbacks now receive a reference to NimBLEConnInfo, the ble_gap_conn_desc has also been replace with NimBLEConnInfo in the functions that received it.
• All functions that take a time input parameter now expect the value to be in milliseconds instead of seconds.
• Removed Eddystone URL as it has been shutdown by google since 2021.
• NimBLESecurity class removed.
• NimBLEDevice Ignore list functions removed.
• 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.
• NimBLEDevice::setOwnAddrType no longer takes a bool nrpa parameter.
• NimBLEDevice::getClientListSize replaced with NimBLEDevice::getCreatedClientCount.
• NimBLEDevice::getClientList was removed.
• NimBLEServer::disconnect now returns bool, true = success, instead of int to be consistent with the rest of the library.
• NimBLEServerCallbacks::onMTUChanged renamed to NimBLEServerCallbacks::onMTUChange to be consistent with the client callback.
• NimBLEServer::getPeerIDInfo renamed to NimBLEServer::getPeerInfoByHandle to better describe it's use.
• NimBLEServerCallbacks::onPassKeyRequest has been replaced with NimBLEServer::onPassKeyDisplay which should display the pairing pin that the client is expected to send.
• NimBLEServerCallbacks::onAuthenticationComplete now takes a NimBLEConnInfo& parameter.
• 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.
• NimBLEClientCallbacks::onDisconnect now takes an additional int reason parameter to let the application know why the disconnect occurred.
• NimBLEClientCallbacks::onPassKeyRequest has been changed to NimBLEClientCallbacks::onPassKeyEntry which takes a NimBLEConnInfo& parameter and does not return a value. Instead or returning a value this callback should prompt a user to enter a pin number which is sent later via NimBLEDevice::injectPassKey.
• NimBLEClientCallbacks::onConfirmPIN renamed to NimBLEClientCallbacks::onConfirmPasskey and no longer returns a value and now takes a NimBLEConnInfo& parameter. This should be used to prompt a user to confirm the pin on the display (YES/NO) after which the response should be sent with NimBLEDevice::injectConfirmPasskey.
• NimBLEAdvertising::setMinPreferred and NimBLEAdvertising::setMaxPreferred have been removed, use NimBLEAdvertising::setPreferredParams instead.
• Advertising the name and TX power of the device will no longer happen by default and should be set manually by the application.
• NimBLEAdvertising::setAdvertisementType has been renamed to NimBLEAdvertising::setConnectableMode to better reflect it's function.
• NimBLEAdvertising::setScanResponse has been renamed to NimBLEAdvertising::enableScanResponse to better reflect it's function.
• NimBLEAdvertising; Scan response is no longer enabled by default.
• NimBLEAdvertising::start No longer takes a callback pointer parameter, instead the new method NimBLEAdvertising::setAdvertisingCompleteCallback should be used.
• NimBLEAdvertisementData::addData now takes either a std::vector<uint8_t> or uint8_t* + length instead of std::string or char + length.
• NimBLEAdvertisementData::getPayload now returns std::vector<uint8_t> instead of std::string.
• 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.
• NimBLEAdvertisedDeviceCallbacks Has been replaced by NimBLEScanCallbacks which contains the following methods: onResult, onScanEnd, and `onDiscovered
• • 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.
• NimBLEScan::stop will no longer call the onScanEnd callback as the caller should know its been stopped when this is called.
• NimBLEScan::clearDuplicateCache has been removed as it was problematic and only for the esp32. Stop and start the scanner for the same effect.
• NimBLEScanResults::getDevice methods now return const NimBLEAdvertisedDevice*.
• NimBLEScanResults iterators are now const_iterator.
• 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.
• NimBLECharacteristic::notify no longer takes a bool is_notification parameter, instead indicate() should be called to send indications.
• 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 for success/failure.
• NimBLERemoteCharacteristic::getRemoteService now returns a const NimBLERemoteService* instead of non-const.
• NimBLERemoteCharacteristic::readUInt32 Has been removed.
• NimBLERemoteCharacteristic::readUInt16 Has been removed.
• NimBLERemoteCharacteristic::readUInt8 Has been removed.
• NimBLERemoteCharacteristic::readFloat Has been removed.
• NimBLERemoteCharacteristic::registerForNotify Has been removed.
• NimBLERemoteService::getCharacteristics now returns a const std::vector<NimBLERemoteCharacteristic*>& instead of non-const std::vector<NimBLERemoteCharacteristic*>*.
• NimBLERemoteService::getValue now returns NimBLEAttValue instead of std::string.
• NimBLEService::getCharacteristics now returns a const std::vector<NimBLECharacteristic*>& instead of std::vector<NimBLECharacteristic *>.
• NimBLEUUID::getNative method replaced with NimBLEUUID::getBase which returns a read-only pointer to the underlying ble_uuid_t struct.
• NimBLEUUID; msbFirst parameter has been removed from constructor, caller should reverse the data first or call the new reverseByteOrder method after.
• NimBLEAddress constructor; default value for the type parameter removed, caller should know the address type and specify it.
• NimBLEAddress::getNative replaced with NimBLEAddress::getBase and now returns a pointer to const ble_addr_t instead of a pointer to the address value.
• NimBLEAddress::equals method and NimBLEAddress::== operator will now also test if the address types are the same.
• NimBLEUtils::dumpGapEvent function removed.
• NimBLEUtils::buildHexData replaced with NimBLEUtils::dataToHexString, which returns a std::string containing the hex string.
• NimBLEEddystoneTLM::setTemp now takes an int16_t parameter instead of float to be friendly to devices without floating point support.
• NimBLEEddystoneTLM::getTemp now returns int16_t to work with devices that don't have floating point support.
• NimBLEEddystoneTLM::setData now takes a reference to * NimBLEEddystoneTLM::BeaconData instead of std::string.
• NimBLEEddystoneTLM::getData now returns a reference to * NimBLEEddystoneTLM::BeaconData instead of std::string.
• NimBLEBeacon::setData now takes const NimBLEBeacon::BeaconData& instead of std::string.
• NimBLEBeacon::getData now returns const NimBLEBeacon::BeaconData& instead of std::string.
• NimBLEHIDDevice::reportMap renamed to NimBLEHIDDevice::getReportMap.
• NimBLEHIDDevice::hidControl renamed to NimBLEHIDDevice::getHidControl.
• NimBLEHIDDevice::inputReportrenamed to NimBLEHIDDevice::getInputReport.
• `NimBLEHIDDevice::out...

v1.4.1

Fixed

• NimBLEDevice::getPower incorrect value when power level is -3db.
• Failed pairing when already in progress.

Changed

• Revert previous change that forced writing with response when subscribing in favor of allowing the application to decide.

Added

• Added NimBLEHIDDevice::batteryLevel.
• Added NimBLEDevice::setDeviceName allowing for changing the device name while the BLE stack is active.
• CI Builds

v1.4.0

Fixed

• Fixed missing data from long notification values.
• Fixed NimbleCharacteristicCallbacks::onRead not being called when a non-long read command is received.
• Prevent a potential crash when retrieving characteristics from a service if the result was successful but no characteristics found.
• logs/typos.

Changed

• AD flags are no longer set in the advertisements of non-connectable beacons, freeing up 3 bytes of advertisement room.
• Save resources when retrieving descriptors if the characteristic handle is the same as the end handle (no descriptors).
• Subscribing to characteristic notifications/indications will now always use write with response, as per BLE specifications.
• NimBLEClient::discoverAttributes now returns a bool value to indicate success/failure.
• Scan result callbacks are no longer called when the scan response data is updated in order to reduce duplicates.

Added

• Preliminary support for non-esp devices, NRF51 and NRF52 devices supported with n-able arduino core
• Alias added for NimBLEServerCallbacks::onMTUChange to onMtuChanged in order to support porting code from original library.
• NimBLEAttValue Class added to reduce and control RAM footprint of characteristic/descriptor values and support conversions from Arduino Strings and many other data types.
• Bluetooth 5 extended advertising support for capable devices. CODED Phy, 2M Phy, extended advertising data, and multi-advertising are supported, periodic advertising will be implemented in the future.

v1.3.3

Changed

• If attribute retrieval fails with a "not found" try again with the 16 bit version if a 128 bit base uuid is used.

Fixed

• Memory leak when deleting client instance.
• IDf version check for data length extension.
• Memory leak when server services changed.
• Compiler warnings for non-esp32 devices.

v1.3.2

Fixed

• Initialize advertising complete callback in NimBLEAdvertising constructor.
• Clear client disconnect timer in constructor before initializing.
• Fix missing data when reading large values.
• Fix missing data in notifications when using a large MTU size and more than 270 bytes of data are sent.
• Workaround fix added for cases when the task notification value is not cleared, causing various functions that should block not to block.

Added

• NimBLEClient::getLastError : Gets the error code of the last function call that produces a return code from the stack.
• NimBLECharacteristic::notify : Overload method to send notifications/indications with custom values.
• Added conditional checks for ESP32 specific functions/values to support use of the library on non-esp32 devices.
• Added an alias to use the callback name from the original library onMtuChanged.
• NimBLEClient::setDataLen and NimBLEServer::setDataLen: Data length extension support (IDF version >= 4.3.2 only)
• Config option to set logging level for esp-nimble-cpp

Changed

• Critical section calls now use the NimBLE API instead of FreeRTOS directly. This removes the need for a portMUX_TYPE variable in the class definitions.
• Removed unnecessary variables in NimBLEService and changed the constructor no no longer accept numHandles and inst_id parameters.

1.3.1

Fixed

• Corrected a compiler/linker error when an application or a library uses bluetooth classic due to the redefinition of btInUse.

1.3.0

Added

• NimBLECharacteristic::removeDescriptor: Dynamically remove a descriptor from a characterisic. Takes effect after all connections are closed and sends a service changed indication.

• NimBLEService::removeCharacteristic: Dynamically remove a characteristic from a service. Takes effect after all connections are closed and sends a service changed indication

• NimBLEServerCallbacks::onMTUChange: This is callback is called when the MTU is updated after connection with a client.

• ESP32C3 support

• Whitelist API:

  • NimBLEDevice::whiteListAdd: Add a device to the whitelist.
  • NimBLEDevice::whiteListRemove: Remove a device from the whitelist.
  • NimBLEDevice::onWhiteList: Check if the device is on the whitelist.
  • NimBLEDevice::getWhiteListCount: Gets the size of the whitelist
  • NimBLEDevice::getWhiteListAddress: Get the address of a device on the whitelist by index value.

• Bond management API:

  • NimBLEDevice::getNumBonds: Gets the number of bonds stored.
  • NimBLEDevice::isBonded: Checks if the device is bonded.
  • NimBLEDevice::deleteAllBonds: Deletes all bonds.
  • NimBLEDevice::getBondedAddress: Gets the address of a bonded device by the index value.

• NimBLECharacteristic::getCallbacks to retrieve the current callback handler.

• Connection Information class: NimBLEConnInfo.

• NimBLEScan::clearDuplicateCache: This can be used to reset the cache of advertised devices so they will be immediately discovered again.

Changed

• FreeRTOS files have been removed as they are not used by the library.
• Services, characteristics and descriptors can now be created statically and added after.
• Excess logging and some asserts removed.
• Use ESP_LOGx macros to enable using local log level filtering.

Fixed

• NimBLECharacteristicCallbacks::onSubscribe Is now called after the connection is added to the vector.
• Corrected bonding failure when reinitializing the BLE stack.
• Writing to a characterisic with a std::string value now correctly writes values with null characters.
• Retrieving remote descriptors now uses the characterisic end handle correctly.
• Missing data in long writes to remote descriptors.
• Hanging on task notification when sending an indication from the characteristic callback.
• BLE controller memory could be released when using Arduino as a component.
• Complile errors with NimBLE release 1.3.0.

Release version 1.2.0

Many additions and changes, check the changelog and documentation for complete details.