Skip to content

2.1.0
Compare
Choose a tag to compare
@h2zero h2zero released this 15 Dec 00:08
· 10 commits to release/2.1 since this release
2.1.0
267d8a6

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

  • NimBLESecurity class removed.
  • 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.
  • 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.
  • NimBLEServer::getPeerIDInfo renamed to NimBLEServer::getPeerInfoByHandle to better describe it's use.
  • NimBLEServerCallbacks::onMTUChanged renamed to NimBLEServerCallbacks::onMTUChange to be consistent with the client callback.
  • 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.
  • NimBLEService::getCharacteristics now returns a const std::vector<NimBLECharacteristic*>& instead of std::vector<NimBLECharacteristic *>.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • NimBLEUtils::dumpGapEvent function removed.
  • NimBLEUtils::buildHexData replaced with NimBLEUtils::dataToHexString, which returns a std::string containing the hex string.
  • Removed Eddystone URL as it has been shutdown by google since 2021.
  • 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::outputReportrenamed to NimBLEHIDDevice::getOutputReport.
  • NimBLEHIDDevice::featureReportrenamed to NimBLEHIDDevice::getFeatureReport.
  • NimBLEHIDDevice::protocolModerenamed to NimBLEHIDDevice::getProtocolMode.
  • NimBLEHIDDevice::bootOutputrenamed to NimBLEHIDDevice::getBootOutput.
  • NimBLEHIDDevice::pnprenamed to NimBLEHIDDevice::setPnp.
  • NimBLEHIDDevice::hidInforenamed to NimBLEHIDDevice::setHidInfo.
  • NimBLEHIDDevice::deviceInforenamed to NimBLEHIDDevice::getDeviceInfoService.
  • NimBLEHIDDevice::hidServicerenamed to NimBLEHIDDevice::getHidService.
  • NimBLEHIDDevice::batteryServicerenamed to NimBLEHIDDevice::getBatteryService.

Fixed

  • NimBLEDevice::getPower and NimBLEDevice::getPowerLevel bug worked around for the esp32s3 and esp32c3.
  • NimBLEDevice::setPower and NimBLEDevice::getPower now support the full power range for all esp devices.
  • NimBLEDevice::setOwnAddrType will now correctly apply the provided address type for all devices.
  • NimBLEDevice::getPower (esp32) return value is now calculated to support devices with different min/max ranges.
  • Crash if NimBLEDevice::deinit is called when the stack has not been initialized.
  • NimBLEServer service changed notifications will now wait until the changes have taken effect and the server re-started before indicating the change to peers, reducing difficultly for some clients to update their data.
  • NimBLEService::getHandle will now fetch the handle from the stack if not valid to avoid returning an invalid value.
  • std::vector input to set/write values template.
  • Pairing failing when the process was started by the peer first.

Changed

  • NimBLEClient::secureConnection now takes an additional parameter bool async, if true, will send the secure command and return immediately with a true value for successfully sending the command, else false. This allows for asynchronously securing a connection.
  • Deleting the client instance from the onDisconnect callback is now supported.
  • NimBLEClient::connect will no longer cancel already in progress connections.
  • NimBLEClient::setDataLen now returns bool, true if successful.
  • NimBLEClient::updateConnParams now returns bool, true if successful.
  • NimBLEClient::setPeerAddress now returns a bool, true on success.
  • NimBLEDevice::startSecurity now takes and additional parameter int* rcPtr which will provide the return code from the stack if provided.
  • NimBLEDevice::deleteClient no longer blocks tasks.
  • NimBLEDevice::getAddress will now return the address currently in use.
  • NimBLEDevice::init now returns a bool with true indicating success.
  • NimBLEDevice::deinit now returns a bool with true indicating success.
  • NimBLEDevice::setDeviceName now returns a bool with true indicating success.
  • NimBLEDevice::setCustomGapHandler now returns a bool with true indicating success.
  • NimBLEDevice::setOwnAddrType now returns a bool with true indicating success and works with non-esp32 devices.
  • NimBLEDevice::setPower now returns a bool value, true = success.
  • NimBLEDevice::setMTU now returns a bool value, true = success.
  • NimBLEDevice::deleteAllBonds now returns true on success, otherwise false.
  • NimBLEEddystoneTLM internal data struct type BeaconData is now public and usable by the application.
  • NimBLEBeacon internal data struct type BeaconData is now public and can be used by the application.
  • Removed tracking of client characteristic subscription status from NimBLEServer and NimBLECharacteristic and instead uses
    the functions and tracking in the host stack.
  • NimBLECharacteristic::indicate now takes the same parameters as notify.
  • NimBLECharacteristic::notify and NimBLECharacteristic::indicate now return a bool, true = success.
  • Added optional connHandle parameter to NimBLECharacteristic::notify to allow for sending notifications to specific clients.
  • NimBLEServer Now uses a std::array to store client connection handles instead of std::vector to reduce memory allocation.
  • NimBLEExtAdvertisement; All functions that set data now return bool, true = success.
  • NimBLEAdvertising Advertising data is now stored in instances of NimBLEAdvertisingData and old vectors removed.
  • NimBLEAdvertising::setAdvertisementData and NimBLEAdvertising::setScanResponseData now return bool, true = success.
  • Added optional NimBLEAddress parameter to NimBLEAdvertising::start to allow for directed advertising to a peer.
  • All NimBLEAdvertising functions that change data values now return bool, true = success.
  • All NimBLEAdvertisementData functions that change data values now return bool, true = success.
  • NimBLEAdvertisementData::setName now takes an optional bool parameter to indicate if the name is complete or incomplete, default = complete.
  • NimBLEAdvertisementData moved to it's own .h and .cpp files.
  • NimBLEScan::start takes a new bool restart parameter, default true, that will restart an already in progress scan and clear the duplicate filter so all devices will be discovered again.
  • Scan response data that is received without advertisement first will now create the device and send a callback.
  • NimBLEScan::start will no longer clear cache or results if scanning is already in progress.
  • NimBLEScan::start will now allow the start command to be sent with updated parameters if already scanning.
  • NimBLEScan::clearResults will now reset the vector capacity to 0.
  • Host reset will now no longer restart scanning and instead will call NimBLEScanCallbacks::onScanEnd.
  • Added optional index parameter to NimBLEAdvertisedDevice::getPayloadByType
  • NimBLEUtils: Add missing GAP event strings.
  • NimBLEUtils: Add missing return code strings.
  • NimBLEUtils: Event/error code strings optimized.
  • NimBLEAttValue cleanup and optimization.
  • cleaned up code, removed assert/abort calls, replaced with a configurable option to enable debug asserts.

Added

  • (esp32 specific) NimBLEDevice::setPowerLevel and NimBLEDevice::getPowerLevel which take and return the related esp_power_level* types.
  • NimBLEDevice::setDefaultPhy which will set the default preferred PHY for all connections.
  • NimBLEDevice::getConnectedClients, which returns a vector of pointers to the currently connected client instances.
  • NimBLEDevice::setOwnAddr function added, which takes a uint8_t* or NimBLEAddress& and will set the mac address of the device, returns bool true = success.
  • NimBLEDevice::injectPassKey Used to send the pairing passkey instead of a return value from the client callback.
  • NimBLEDevice::injectConfirmPasskey Used to send the numeric comparison pairing passkey confirmation instead of a return value from the client callback.
  • NimBLEDevice::setDeviceName to change the device name after initialization.
  • NimBLECharacteristic::create2904 which will specifically create a Characteristic Presentation Format (0x2904) descriptor.
  • NimBLEAdvertising::refreshAdvertisingData refreshes the advertisement data while still actively advertising.
  • NimBLEClient::updatePhy to request a PHY change with a peer.
  • NimBLEClient::getPhy to read the current connection PHY setting.
  • Config struct to NimBLEClient to efficiently set single bit config settings.
  • NimBLEClient::setSelfDelete that takes the bool parameters deleteOnDisconnect and deleteOnConnectFail, which will configure the client to delete itself when disconnected or the connection attempt fails.
  • NimBLEClient::setConfig and NimBLEClient::getConfig which takes or returns a NimBLEClient::Config object respectively.
  • NimBLEClient::cancelConnect() to cancel an in-progress connection, returns bool, true = success.
  • Non-blocking NimBLEClient::connect option added via 2 new bool parameters added to the function:
    • asyncConnect; if true, will send the connect command and return immediately.
    • exchangeMTU; if true will send the exchange MTU command upon connection.
  • NimBLEClientCallbacks::onConnectFail callback that is called when the connection attempt fail while connecting asynchronously.
  • NimBLEClientCallbacks::onMTUChange callback which will be called when the MTU exchange completes and takes a NimBLEClient* and uint16_t MTU parameter.
  • NimBLEClientCallbacks::onPhyUpdate and -NimBLEServerCallbacks::onPhyUpdate Which are called when the PHY update is complete.
  • Extended scan example.
  • NimBLEServer::updatePhy to request a PHY change with a peer.
  • NimBLEServer::getPhy to read the PHY of a peer connection.
  • NimBLEServer::getClient which will create a client instance from the provided peer connHandle or connInfo to facilitate reading/write from the connected client.
  • NimBLEServerCallbacks::onConnParamsUpdate callback.
  • NimBLEScan::erase overload that takes a const NimBLEAdvertisedDevice* parameter.
  • NimBLEScan::setScanPhy to enable/disable the PHY's to scan on (extended advertising only).
  • NimBLEScan::setScanPeriod which will allow for setting a scan restart timer in the controller (extended advertising only).
  • NimBLEAdvertisedDevice::isScannable() that returns true if the device is scannable.
  • NimBLEAdvertisedDevice::begin and NimBLEAdvertisedDevice::end read-only iterators for convenience and use in range loops.
  • NimBLEAdvertisedDevice::haveType Generic use function that returns true if the advertisement data contains a field with the specified type.
  • NimBLEExtAdvertisement::removeData, which will remove the data of the specified type from the advertisement.
  • NimBLEExtAdvertisement::addServiceUUID, which will append to the service uuids advertised.
  • NimBLEExtAdvertisement::removeServiceUUID, which will remove the service from the uuids advertised.
  • NimBLEExtAdvertisement::removeServices, which will remove all service uuids advertised.
  • New overloads for NimBLEExtAdvertisement::setServiceData with the parameters const NimBLEUUID& uuid, const uint8_t* data, size_t length and const NimBLEUUID& uuid, const std::vector<uint8_t>& data.
  • NimBLEExtAdvertisement::getDataLocation, which returns the location in the advertisement data of the type requested in parameter uint8_t type.
  • NimBLEExtAdvertisement::toString which returns a hex string representation of the advertisement data.
  • NimBLEAdvertising::getAdvertisementData, which returns a reference to the currently set advertisement data.
  • NimBLEAdvertising::getScanData, which returns a reference to the currently set scan response data.
  • New overloads for NimBLEAdvertising::removeServiceUUID and NimBLEAdvertisementData::removeServiceUUID to accept a const char*
  • NimBLEAdvertising::setManufacturerData Overload that takes a const uint8_t* and , size_t` parameter.
  • NimBLEAdvertising::setServiceData Overload that takes const NimBLEUUID& uuid, const uint8_t* data, size_t length as parameters.
  • NimBLEAdvertising::setServiceData Overload that takes const NimBLEUUID& uuid, const std::vector<uint8_t>& as parameters.
  • NimBLEAdvertising::setDiscoverableMode to allow applications to control the discoverability of the advertiser.
  • NimBLEAdvertising::setAdvertisingCompleteCallback sets the callback to call when advertising ends.
  • NimBLEAdvertising::setPreferredParams that takes the min and max preferred connection parameters as an alternative for setMinPreferred and setMaxPreferred.
  • NimBLEAdvertising::setAdvertisingInterval Sets the advertisement interval for min and max to the same value instead of calling setMinInterval and setMaxInterval separately if there is not value difference.
  • NimBLEAdvertisementData::removeData, which takes a parameter uint8_t type, the data type to remove.
  • NimBLEAdvertisementData::toString, which will print the data in hex.
  • NimBLEUtils::taskWait which causes the calling task to wait for an event.
  • NimBLEUtils::taskRelease releases the task from and event.
  • NimBLEUtils::generateAddr function added with will generate a random address and takes a bool parameter, true = create non-resolvable private address, otherwise a random static address is created, returns NimBLEAddress.
  • NimBLEUUID::getValue which returns a read-only uint8_t pointer to the UUID value.
  • NimBLEUUID::reverseByteOrder, this will reverse the bytes of the UUID, which can be useful for advertising/logging.
  • NimBLEUUID constructor overload that takes a reference to ble_uuid_any_t.
  • NimBLEAddress::isNrpa method to test if an address is random non-resolvable.
  • NimBLEAddress::isStatic method to test if an address is random static.
  • NimBLEAddress::isPublic method to test if an address is a public address.
  • NimBLEAddress::isNull methods to test if an address is NULL.
  • NimBLEAddress::getValue method which returns a read-only pointer to the address value.
  • NimBLEAddress::reverseByteOrder method which will reverse the byte order of the address value.
  • NimBLEHIDDevice::batteryLevel returns the HID device battery level characteristic.
  • NimBLEBeacon::setData overload that takes uint8_t* data and uint8_t length.
  • NimBLEHIDDevice::getPnp function added to access the pnp characteristic.
  • NimBLEHIDDevice::getHidInfo function added to access the hid info characteristic.
Assets 2
Loading