diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index cd474db2c..d42f612f5 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -1,7 +1,7 @@ name: Build on: - workflow_dispatch: # Start a workflow + workflow_dispatch: pull_request: push: branches: @@ -277,6 +277,6 @@ jobs: steps: - uses: actions/checkout@v4 - name: Doxygen Action - uses: mattnotmitt/doxygen-action@v1.9.5 + uses: mattnotmitt/doxygen-action@v1.9.8 with: working-directory: 'docs/' diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ba1e08b5..a7057776a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,12 +3,242 @@ All notable changes to this project will be documented in this file. ## [Unreleased] -### Changed +## **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 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` or `uint8_t* + length` instead of `std::string` or `char + length`. +- `NimBLEAdvertisementData::getPayload` now returns `std::vector` 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&` instead of std::vector. +- `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&` instead of non-const `std::vector*`. +- `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` instead of a pointer to internal memory. +- `NimBLEAdvertisedDevice` Timestamp removed, if needed then the app should track the time from the callback. +- `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`. + +## 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& 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&` 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`. + +## [1.4.3] 2024-11-27 + +### Fixed + - BT5 examples for non-esp devices. + - Build errors when configured as a non-connecting device + +### Added + - Coded PHY support for nRF52833 and nRF52820 + +## [1.4.2] 2024-06-17 + +### Fixed + - `CONFIG_BT_NIMBLE_NVS_PERSIST` value not being used to enable/disable persistance. + - Set service handle in `NimBLEService::getHandle` function if not set already. + - NimBLE_service_data_advertiser example updated to initialize the advertising pointer after stack initialization. + - Unhandled exception on `NimBLECharacteristic::handleGapEvent` when the connection handle is invalid. + - `NimBLEHIDDevice::pnp` now correctly sets the byte order. + - `NimBLEEddystoneTLM` now correctly sets/gets negative temperatures. + - Adding to the whitelist will now allow the device to be added again if the previous attempts failed. + - The IPC calls added to esp_nimble_hci have been removed to prevent IPC stack crashing. + - Espressif log tag renamed from "TAG" to "LOG_TAG" to avoid conflict with Arduino core definition. + - Removed broken links in docs + +### Added + - `NimBLEAdvertisedDevice` new method: `getAdvFlags`, to read the flags advertised. + - `NimBLEAdvertising::setManufacturerData` new overload method that accepts a vector of `uint8_t`. + - `NimBLEAdvertisementData::setManufacturerData` new overload method that accepts a vector of `uint8_t`. + - `NimBLEAdvertisedDevice` new method: `getPayloadByType`, to get data from generic data types advertised. + - `NimBLEService` new method: `isStarted`, checks if the service has been started. + - `NimBLEAdvertising` new method: `removeServices` removes all service UUID's from the advertisement. + - `NimBLEAdvertisementData` new method: `clearData` sets all data to NULL to reuse the instance. + +### Changed + - `NimBLEAdvertisedDevice::getManufacturerData`, now takes an index value parameter to use when there is more than 1 instance of manufacturer data. + - `NimBLEAdvertising` directed peer address parameter to advertising start. + - Update NimBLE core to esp-nimble @0fc6282 + - Can now create more than 255 Characteristics/Descriptors in a service. + - `nimble_port_freertos_get_hs_hwm` function is now available to the application to get the core task stack usage. + - changed default pairing keys shared to include ID key which is now needed by iOS + - Removed abort in server start when a service is not found, logs a warning message instead. + - `NimBLEAdvertising::start` on complete callback is now a std::function to allow the use of std::bind to class methods + - `NimBLEAdvertising` setXXX methods will now properly clear the previous data before setting the new values. + - Removed asserts in `NimBLECharacteristic` event handler when conn_handle is invalid, sends a NULL conn info to the callback instead. ## [1.4.1] - 2022-10-23 diff --git a/README.md b/README.md index 42e58fd97..071a8268d 100644 --- a/README.md +++ b/README.md @@ -42,8 +42,6 @@ If you have not used the original Bluedroid library please refer to the [New use If you are familiar with the original library, see: [The migration guide](docs/Migration_guide.md) for details about breaking changes and migration. -Also see [Improvements_and_updates](docs/Improvements_and_updates.md) for information about non-breaking changes. - [Full API documentation and class list can be found here.](https://h2zero.github.io/NimBLE-Arduino/) For added performance and optimizations see [Usage tips](docs/Usage_tips.md). @@ -52,16 +50,14 @@ Check the Refactored_original_examples in the examples folder for highlights of More advanced examples highlighting many available features are in examples/ NimBLE_Server, NimBLE_Client. -Beacon examples provided by @beegee-tokyo are in examples/ BLE_Beacon_Scanner, BLE_EddystoneTLM_Beacon, BLE_EddystoneURL_Beacon. +Beacon examples provided by @beegee-tokyo are in examples/ BLE_Beacon_Scanner, BLE_EddystoneTLM_Beacon. Change the settings in the `src/nimconfig.h` file to customize NimBLE to your project, -such as increasing max connections, default is 3, absolute maximum connections is 9. +such as increasing max connections, default is 3 for the esp32.
# Development Status -This Library is tracking the esp-nimble repo, nimble-1.4.0-idf branch, currently [@3df0d20.](https://github.com/espressif/esp-nimble) - -Also tracking the NimBLE related changes in ESP-IDF, master branch, currently [@95db4bb.](https://github.com/espressif/esp-idf/tree/master/components/bt/host/nimble) +This Library is tracking the esp-nimble repo, nimble-1.5.0-idf branch, currently [@e3cbdc0.](https://github.com/espressif/esp-nimble)
# Acknowledgments diff --git a/docs/1.x_to2.x_migration_guide.md b/docs/1.x_to2.x_migration_guide.md new file mode 100644 index 000000000..8c38095d4 --- /dev/null +++ b/docs/1.x_to2.x_migration_guide.md @@ -0,0 +1,165 @@ +# 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](#general-changes) +* [BLE Device](#ble-device) +* [BLE Addresses](#ble-addresses) +* [BLE UUID's](#ble-uuids) +* [Server](#server) + * [Services](#services) + * [Characteristics](#characteristics) + * [Characteristic Callbacks](#characteristic-callbacks) + * [Security](#server) +* [Client](#client) + * [Client Callbacks](#client-callbacks) + * [Remote Services](#remote-services) + * [Remote characteristics](#remote-characteristics) +* [Scanning](#scan) + * [Advertise device](#advertised-device) +* [Advertising](#advertising) +* [Beacons](#beacons) +* [Utilities](#utilities) +
+ +## 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 +- `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 `NimBLEUUID::reverseByteOrder` method after. +
+ +## Server +- `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. +
+ +### Services +- `NimBLEService::getCharacteristics` now returns a `const std::vector&` instead of a copy of the vector. +
+ +### Characteristics +- `NimBLECharacteristic::notify` no longer takes a `bool is_notification` parameter, instead `NimBLECharacteristic::indicate` should be called to send indications. +
+ +#### 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 +- `NimBLEServerCallbacks::onPassKeyRequest` has been renamed to `NimBLEServerCallbacks::onPassKeyDisplay` as it is intended that the device should display the passkey for the client to enter. +- `NimBLEServerCallbacks::onAuthenticationComplete` now takes a `NimBLEConnInfo&` parameter. +
+ +## Client +- `NimBLEClient::getServices` now returns a const reference to std::vector 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 +- `NimBLEClientCallbacks::onConfirmPIN` renamed to `NimBLEClientCallbacks::onConfirmPasskey`, takes a `NimBLEConnInfo&` parameter and no longer returns a value. 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`. +- `NimBLEClientCallbacks::onPassKeyRequest` has been changed to `NimBLEClientCallbacks::onPassKeyEntry` which takes a `NimBLEConnInfo&` parameter and no longer returns a value. Instead of returning a value this callback should prompt a user to enter a passkey number which is sent later via `NimBLEDevice::injectPassKey`. +
+ +### Remote Services +- `NimBLERemoteService::getCharacteristics` now returns a `const std::vector&` instead of non-const `std::vector*`. +
+ +### 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`. +
+ +## 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&` instead of a pointer to internal memory. +- `NimBLEAdvertisedDevice` Timestamp removed, if needed then the app should track the time from the callback. +
+ +## Advertising +- `NimBLEAdvertising::setMinPreferred` and `NimBLEAdvertising::setMaxPreferred` have been removed and replaced by `NimBLEAdvertising::setPreferredParams` which takes both the min and max parameters. +- Advertising the name and TX power of the device will no longer happen by default and should be set manually by the application using `NimBLEAdvertising::setName` and `NimBLEAdvertising::addTxPower`. +- `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 to set the callback function. +
+ +## Beacons +- 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`. +
+ +## Utilities +- `NimBLEUtils::dumpGapEvent` function removed. +- `NimBLEUtils::buildHexData` replaced with `NimBLEUtils::dataToHexString`, which returns a `std::string` containing the hex string. +
diff --git a/docs/Doxyfile b/docs/Doxyfile index e6539d735..ad2341dfb 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -1,4 +1,4 @@ -# Doxyfile 1.9.5 +# Doxyfile 1.10.. # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. @@ -48,7 +48,7 @@ PROJECT_NAME = NimBLE-Arduino # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 2.0.0 +PROJECT_NUMBER = 2.1.0 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a @@ -63,6 +63,12 @@ PROJECT_BRIEF = PROJECT_LOGO = +# With the PROJECT_ICON tag one can specify an icon that is included in the tabs +# when the HTML document is shown. Doxygen will copy the logo to the output +# directory. + +PROJECT_ICON = + # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path # into which the generated documentation will be written. If a relative path is # entered, it will be relative to the location where doxygen was started. If @@ -86,7 +92,7 @@ CREATE_SUBDIRS = NO # level increment doubles the number of directories, resulting in 4096 # directories at level 8 which is the default and also the maximum value. The # sub-directories are organized in 2 levels, the first level always has a fixed -# numer of 16 directories. +# number of 16 directories. # Minimum value: 0, maximum value: 8, default value: 8. # This tag requires that the tag CREATE_SUBDIRS is set to YES. @@ -363,6 +369,17 @@ MARKDOWN_SUPPORT = YES TOC_INCLUDE_HEADINGS = 5 +# The MARKDOWN_ID_STYLE tag can be used to specify the algorithm used to +# generate identifiers for the Markdown headings. Note: Every identifier is +# unique. +# Possible values are: DOXYGEN use a fixed 'autotoc_md' string followed by a +# sequence number starting at 0 and GITHUB use the lower case version of title +# with any whitespace replaced by '-' and punctuation characters removed. +# The default value is: DOXYGEN. +# This tag requires that the tag MARKDOWN_SUPPORT is set to YES. + +MARKDOWN_ID_STYLE = GITHUB + # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can # be prevented in individual cases by putting a % sign in front of the word or @@ -487,6 +504,14 @@ LOOKUP_CACHE_SIZE = 0 NUM_PROC_THREADS = 1 +# If the TIMESTAMP tag is set different from NO then each generated page will +# contain the date or date and time when the page was generated. Setting this to +# NO can help when comparing the output of multiple runs. +# Possible values are: YES, NO, DATETIME and DATE. +# The default value is: NO. + +TIMESTAMP = NO + #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- @@ -568,7 +593,8 @@ HIDE_UNDOC_MEMBERS = YES # If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all # undocumented classes that are normally visible in the class hierarchy. If set # to NO, these classes will be included in the various overviews. This option -# has no effect if EXTRACT_ALL is enabled. +# will also hide undocumented C++ concepts if enabled. This option has no effect +# if EXTRACT_ALL is enabled. # The default value is: NO. HIDE_UNDOC_CLASSES = YES @@ -859,14 +885,29 @@ WARN_IF_INCOMPLETE_DOC = YES WARN_NO_PARAMDOC = NO +# If WARN_IF_UNDOC_ENUM_VAL option is set to YES, doxygen will warn about +# undocumented enumeration values. If set to NO, doxygen will accept +# undocumented enumeration values. If EXTRACT_ALL is set to YES then this flag +# will automatically be disabled. +# The default value is: NO. + +WARN_IF_UNDOC_ENUM_VAL = NO + # If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when # a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS # then doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but # at the end of the doxygen process doxygen will return with a non-zero status. -# Possible values are: NO, YES and FAIL_ON_WARNINGS. +# If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS_PRINT then doxygen behaves +# like FAIL_ON_WARNINGS but in case no WARN_LOGFILE is defined doxygen will not +# write the warning messages in between other messages but write them at the end +# of a run, in case a WARN_LOGFILE is defined the warning messages will be +# besides being in the defined file also be shown at the end of a run, unless +# the WARN_LOGFILE is defined as - i.e. standard output (stdout) in that case +# the behavior will remain as with the setting FAIL_ON_WARNINGS. +# Possible values are: NO, YES, FAIL_ON_WARNINGS and FAIL_ON_WARNINGS_PRINT. # The default value is: NO. -WARN_AS_ERROR = YES +WARN_AS_ERROR = NO # The WARN_FORMAT tag determines the format of the warning messages that doxygen # can produce. The string should contain the $file, $line, and $text tags, which @@ -908,7 +949,8 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = . \ +INPUT = ../CHANGELOG.md \ + . \ ../src # This tag can be used to specify the character encoding of the source files @@ -942,12 +984,12 @@ INPUT_FILE_ENCODING = # Note the list of default checked file patterns might differ from the list of # default file extension mappings. # -# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, -# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, -# *.hh, *.hxx, *.hpp, *.h++, *.l, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, -# *.inc, *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C -# comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, -# *.vhdl, *.ucf, *.qsf and *.ice. +# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cxxm, +# *.cpp, *.cppm, *.ccm, *.c++, *.c++m, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, +# *.idl, *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp, *.h++, *.ixx, *.l, *.cs, *.d, +# *.php, *.php4, *.php5, *.phtml, *.inc, *.m, *.markdown, *.md, *.mm, *.dox (to +# be provided as doxygen C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, +# *.f18, *.f, *.for, *.vhd, *.vhdl, *.ucf, *.qsf and *.ice. FILE_PATTERNS = *.c \ *.cc \ @@ -1010,11 +1052,7 @@ RECURSIVE = YES # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = ./README.md \ - ./examples \ - ./CMakelists.txt \ - ../src/nimconfig_rename.h \ - ../src/nimble +EXCLUDE = ../src/nimconfig_rename.h # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -1037,9 +1075,6 @@ EXCLUDE_PATTERNS = # output. The symbol name can be a fully qualified name, a word, or if the # wildcard * is used, a substring. Examples: ANamespace, AClass, # ANamespace::AClass, ANamespace::*Test -# -# Note that the wildcards are matched against the file with absolute path, so to -# exclude all test directories use the pattern */test/* EXCLUDE_SYMBOLS = @@ -1153,7 +1188,8 @@ FORTRAN_COMMENT_AFTER = 72 SOURCE_BROWSER = NO # Setting the INLINE_SOURCES tag to YES will include the body of functions, -# classes and enums directly into the documentation. +# multi-line macros, enums or list initialized variables directly into the +# documentation. # The default value is: NO. INLINE_SOURCES = NO @@ -1225,46 +1261,6 @@ USE_HTAGS = NO VERBATIM_HEADERS = YES -# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the -# clang parser (see: -# http://clang.llvm.org/) for more accurate parsing at the cost of reduced -# performance. This can be particularly helpful with template rich C++ code for -# which doxygen's built-in parser lacks the necessary type information. -# Note: The availability of this option depends on whether or not doxygen was -# generated with the -Duse_libclang=ON option for CMake. -# The default value is: NO. - -CLANG_ASSISTED_PARSING = NO - -# If the CLANG_ASSISTED_PARSING tag is set to YES and the CLANG_ADD_INC_PATHS -# tag is set to YES then doxygen will add the directory of each input to the -# include path. -# The default value is: YES. -# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. - -CLANG_ADD_INC_PATHS = YES - -# If clang assisted parsing is enabled you can provide the compiler with command -# line options that you would normally use when invoking the compiler. Note that -# the include paths will already be set by doxygen for the files and directories -# specified with INPUT and INCLUDE_PATH. -# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. - -CLANG_OPTIONS = - -# If clang assisted parsing is enabled you can provide the clang parser with the -# path to the directory containing a file called compile_commands.json. This -# file is the compilation database (see: -# http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) containing the -# options used when the source files were built. This is equivalent to -# specifying the -p option to a clang tool, such as clang-check. These options -# will then be passed to the parser. Any options specified with CLANG_OPTIONS -# will be added as well. -# Note: The availability of this option depends on whether or not doxygen was -# generated with the -Duse_libclang=ON option for CMake. - -CLANG_DATABASE_PATH = - #--------------------------------------------------------------------------- # Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- @@ -1276,10 +1272,11 @@ CLANG_DATABASE_PATH = ALPHABETICAL_INDEX = YES -# In case all classes in a project start with a common prefix, all classes will -# be put under the same header in the alphabetical index. The IGNORE_PREFIX tag -# can be used to specify a prefix (or a list of prefixes) that should be ignored -# while generating the index headers. +# The IGNORE_PREFIX tag can be used to specify a prefix (or a list of prefixes) +# that should be ignored while generating the index headers. The IGNORE_PREFIX +# tag works for classes, function and member names. The entity will be placed in +# the alphabetical list under the first letter of the entity name that remains +# after removing the prefix. # This tag requires that the tag ALPHABETICAL_INDEX is set to YES. IGNORE_PREFIX = @@ -1358,7 +1355,12 @@ HTML_STYLESHEET = # Doxygen will copy the style sheet files to the output directory. # Note: The order of the extra style sheet files is of importance (e.g. the last # style sheet in the list overrules the setting of the previous ones in the -# list). For an example see the documentation. +# list). +# Note: Since the styling of scrollbars can currently not be overruled in +# Webkit/Chromium, the styling will be left out of the default doxygen.css if +# one or more extra stylesheets have been specified. So if scrollbar +# customization is desired it has to be added explicitly. For an example see the +# documentation. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_EXTRA_STYLESHEET = @@ -1374,17 +1376,13 @@ HTML_EXTRA_STYLESHEET = HTML_EXTRA_FILES = # The HTML_COLORSTYLE tag can be used to specify if the generated HTML output -# should be rendered with a dark or light theme. Default setting AUTO_LIGHT -# enables light output unless the user preference is dark output. Other options -# are DARK to always use dark mode, LIGHT to always use light mode, AUTO_DARK to -# default to dark mode unless the user prefers light mode, and TOGGLE to let the -# user toggle between dark and light mode via a button. -# Possible values are: LIGHT Always generate light output., DARK Always generate -# dark output., AUTO_LIGHT Automatically set the mode according to the user -# preference, use light mode if no preference is set (the default)., AUTO_DARK -# Automatically set the mode according to the user preference, use dark mode if -# no preference is set. and TOGGLE Allow to user to switch between light and -# dark mode via a button.. +# should be rendered with a dark or light theme. +# Possible values are: LIGHT always generate light mode output, DARK always +# generate dark mode output, AUTO_LIGHT automatically set the mode according to +# the user preference, use light mode if no preference is set (the default), +# AUTO_DARK automatically set the mode according to the user preference, use +# dark mode if no preference is set and TOGGLE allow to user to switch between +# light and dark mode via a button. # The default value is: AUTO_LIGHT. # This tag requires that the tag GENERATE_HTML is set to YES. @@ -1420,15 +1418,6 @@ HTML_COLORSTYLE_SAT = 100 HTML_COLORSTYLE_GAMMA = 80 -# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML -# page will contain the date and time when the page was generated. Setting this -# to YES can help to show when doxygen was last run and thus if the -# documentation is up to date. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_TIMESTAMP = NO - # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML # documentation will contain a main index with vertical navigation menus that # are dynamically created via JavaScript. If disabled, the navigation index will @@ -1448,6 +1437,33 @@ HTML_DYNAMIC_MENUS = YES HTML_DYNAMIC_SECTIONS = NO +# If the HTML_CODE_FOLDING tag is set to YES then classes and functions can be +# dynamically folded and expanded in the generated HTML source code. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_CODE_FOLDING = YES + +# If the HTML_COPY_CLIPBOARD tag is set to YES then doxygen will show an icon in +# the top right corner of code and text fragments that allows the user to copy +# its content to the clipboard. Note this only works if supported by the browser +# and the web page is served via a secure context (see: +# https://www.w3.org/TR/secure-contexts/), i.e. using the https: or file: +# protocol. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COPY_CLIPBOARD = YES + +# Doxygen stores a couple of settings persistently in the browser (via e.g. +# cookies). By default these settings apply to all HTML pages generated by +# doxygen across all projects. The HTML_PROJECT_COOKIE tag can be used to store +# the settings under a project specific key, such that the user preferences will +# be stored separately. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_PROJECT_COOKIE = + # With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries # shown in the various tree structured indices initially; the user can expand # and collapse entries dynamically later on. Doxygen will expand the tree to @@ -1578,6 +1594,16 @@ BINARY_TOC = NO TOC_EXPAND = NO +# The SITEMAP_URL tag is used to specify the full URL of the place where the +# generated documentation will be placed on the server by the user during the +# deployment of the documentation. The generated sitemap is called sitemap.xml +# and placed on the directory specified by HTML_OUTPUT. In case no SITEMAP_URL +# is specified no sitemap is generated. For information about the sitemap +# protocol see https://www.sitemaps.org +# This tag requires that the tag GENERATE_HTML is set to YES. + +SITEMAP_URL = + # If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and # QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that # can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help @@ -1814,8 +1840,8 @@ MATHJAX_RELPATH = https://cdn.jsdelivr.net/npm/mathjax@2 # The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax # extension names that should be enabled during MathJax rendering. For example -# for MathJax version 2 (see https://docs.mathjax.org/en/v2.7-latest/tex.html -# #tex-and-latex-extensions): +# for MathJax version 2 (see +# https://docs.mathjax.org/en/v2.7-latest/tex.html#tex-and-latex-extensions): # MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols # For example for MathJax version 3 (see # http://docs.mathjax.org/en/latest/input/tex/extensions/index.html): @@ -2066,9 +2092,16 @@ PDF_HYPERLINKS = YES USE_PDFLATEX = YES -# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode -# command to the generated LaTeX files. This will instruct LaTeX to keep running -# if errors occur, instead of asking the user for help. +# The LATEX_BATCHMODE tag signals the behavior of LaTeX in case of an error. +# Possible values are: NO same as ERROR_STOP, YES same as BATCH, BATCH In batch +# mode nothing is printed on the terminal, errors are scrolled as if is +# hit at every error; missing files that TeX tries to input or request from +# keyboard input (\read on a not open input stream) cause the job to abort, +# NON_STOP In nonstop mode the diagnostic message will appear on the terminal, +# but there is no possibility of user interaction just like in batch mode, +# SCROLL In scroll mode, TeX will stop only for missing files to input or if +# keyboard input is necessary and ERROR_STOP In errorstop mode, TeX will stop at +# each error, asking for user intervention. # The default value is: NO. # This tag requires that the tag GENERATE_LATEX is set to YES. @@ -2089,14 +2122,6 @@ LATEX_HIDE_INDICES = NO LATEX_BIB_STYLE = plain -# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated -# page will contain the date and time when the page was generated. Setting this -# to NO can help when comparing the output of multiple runs. -# The default value is: NO. -# This tag requires that the tag GENERATE_LATEX is set to YES. - -LATEX_TIMESTAMP = NO - # The LATEX_EMOJI_DIRECTORY tag is used to specify the (relative or absolute) # path from which the emoji images will be read. If a relative path is entered, # it will be relative to the LATEX_OUTPUT directory. If left blank the @@ -2262,13 +2287,39 @@ DOCBOOK_OUTPUT = docbook #--------------------------------------------------------------------------- # If the GENERATE_AUTOGEN_DEF tag is set to YES, doxygen will generate an -# AutoGen Definitions (see http://autogen.sourceforge.net/) file that captures +# AutoGen Definitions (see https://autogen.sourceforge.net/) file that captures # the structure of the code including all documentation. Note that this feature # is still experimental and incomplete at the moment. # The default value is: NO. GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# Configuration options related to Sqlite3 output +#--------------------------------------------------------------------------- + +# If the GENERATE_SQLITE3 tag is set to YES doxygen will generate a Sqlite3 +# database with symbols found by doxygen stored in tables. +# The default value is: NO. + +GENERATE_SQLITE3 = NO + +# The SQLITE3_OUTPUT tag is used to specify where the Sqlite3 database will be +# put. If a relative path is entered the value of OUTPUT_DIRECTORY will be put +# in front of it. +# The default directory is: sqlite3. +# This tag requires that the tag GENERATE_SQLITE3 is set to YES. + +SQLITE3_OUTPUT = sqlite3 + +# The SQLITE3_RECREATE_DB tag is set to YES, the existing doxygen_sqlite3.db +# database file will be recreated with each doxygen run. If set to NO, doxygen +# will warn if a database file is already found and not modify it. +# The default value is: YES. +# This tag requires that the tag GENERATE_SQLITE3 is set to YES. + +SQLITE3_RECREATE_DB = YES + #--------------------------------------------------------------------------- # Configuration options related to the Perl module output #--------------------------------------------------------------------------- @@ -2417,15 +2468,15 @@ TAGFILES = GENERATE_TAGFILE = -# If the ALLEXTERNALS tag is set to YES, all external class will be listed in -# the class index. If set to NO, only the inherited external classes will be -# listed. +# If the ALLEXTERNALS tag is set to YES, all external classes and namespaces +# will be listed in the class and namespace index. If set to NO, only the +# inherited external classes will be listed. # The default value is: NO. ALLEXTERNALS = NO # If the EXTERNAL_GROUPS tag is set to YES, all external groups will be listed -# in the modules index. If set to NO, only the current project's groups will be +# in the topic index. If set to NO, only the current project's groups will be # listed. # The default value is: YES. @@ -2439,16 +2490,9 @@ EXTERNAL_GROUPS = YES EXTERNAL_PAGES = YES #--------------------------------------------------------------------------- -# Configuration options related to the dot tool +# Configuration options related to diagram generator tools #--------------------------------------------------------------------------- -# You can include diagrams made with dia in doxygen documentation. Doxygen will -# then run dia to produce the diagram and insert it in the documentation. The -# DIA_PATH tag allows you to specify the directory where the dia binary resides. -# If left empty dia is assumed to be found in the default search path. - -DIA_PATH = - # If set to YES the inheritance and collaboration graphs will hide inheritance # and usage relations if the target is undocumented or is not a class. # The default value is: YES. @@ -2457,7 +2501,7 @@ HIDE_UNDOC_RELATIONS = YES # If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is # available from the path. This tool is part of Graphviz (see: -# http://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent +# https://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent # Bell Labs. The other options in this section have no effect if this option is # set to NO # The default value is: NO. @@ -2510,13 +2554,19 @@ DOT_NODE_ATTR = "shape=box,height=0.2,width=0.4" DOT_FONTPATH = -# If the CLASS_GRAPH tag is set to YES (or GRAPH) then doxygen will generate a -# graph for each documented class showing the direct and indirect inheritance -# relations. In case HAVE_DOT is set as well dot will be used to draw the graph, -# otherwise the built-in generator will be used. If the CLASS_GRAPH tag is set -# to TEXT the direct and indirect inheritance relations will be shown as texts / -# links. -# Possible values are: NO, YES, TEXT and GRAPH. +# If the CLASS_GRAPH tag is set to YES or GRAPH or BUILTIN then doxygen will +# generate a graph for each documented class showing the direct and indirect +# inheritance relations. In case the CLASS_GRAPH tag is set to YES or GRAPH and +# HAVE_DOT is enabled as well, then dot will be used to draw the graph. In case +# the CLASS_GRAPH tag is set to YES and HAVE_DOT is disabled or if the +# CLASS_GRAPH tag is set to BUILTIN, then the built-in generator will be used. +# If the CLASS_GRAPH tag is set to TEXT the direct and indirect inheritance +# relations will be shown as texts / links. Explicit enabling an inheritance +# graph or choosing a different representation for an inheritance graph of a +# specific class, can be accomplished by means of the command \inheritancegraph. +# Disabling an inheritance graph can be accomplished by means of the command +# \hideinheritancegraph. +# Possible values are: NO, YES, TEXT, GRAPH and BUILTIN. # The default value is: YES. CLASS_GRAPH = TEXT @@ -2524,15 +2574,21 @@ CLASS_GRAPH = TEXT # If the COLLABORATION_GRAPH tag is set to YES then doxygen will generate a # graph for each documented class showing the direct and indirect implementation # dependencies (inheritance, containment, and class references variables) of the -# class with other documented classes. +# class with other documented classes. Explicit enabling a collaboration graph, +# when COLLABORATION_GRAPH is set to NO, can be accomplished by means of the +# command \collaborationgraph. Disabling a collaboration graph can be +# accomplished by means of the command \hidecollaborationgraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. COLLABORATION_GRAPH = YES # If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for -# groups, showing the direct groups dependencies. See also the chapter Grouping -# in the manual. +# groups, showing the direct groups dependencies. Explicit enabling a group +# dependency graph, when GROUP_GRAPHS is set to NO, can be accomplished by means +# of the command \groupgraph. Disabling a directory graph can be accomplished by +# means of the command \hidegroupgraph. See also the chapter Grouping in the +# manual. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2574,8 +2630,8 @@ DOT_UML_DETAILS = NO # The DOT_WRAP_THRESHOLD tag can be used to set the maximum number of characters # to display on a single line. If the actual line length exceeds this threshold -# significantly it will wrapped across multiple lines. Some heuristics are apply -# to avoid ugly line breaks. +# significantly it will be wrapped across multiple lines. Some heuristics are +# applied to avoid ugly line breaks. # Minimum value: 0, maximum value: 1000, default value: 17. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2592,7 +2648,9 @@ TEMPLATE_RELATIONS = NO # If the INCLUDE_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are set to # YES then doxygen will generate a graph for each documented file showing the # direct and indirect include dependencies of the file with other documented -# files. +# files. Explicit enabling an include graph, when INCLUDE_GRAPH is is set to NO, +# can be accomplished by means of the command \includegraph. Disabling an +# include graph can be accomplished by means of the command \hideincludegraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2601,7 +2659,10 @@ INCLUDE_GRAPH = YES # If the INCLUDED_BY_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are # set to YES then doxygen will generate a graph for each documented file showing # the direct and indirect include dependencies of the file with other documented -# files. +# files. Explicit enabling an included by graph, when INCLUDED_BY_GRAPH is set +# to NO, can be accomplished by means of the command \includedbygraph. Disabling +# an included by graph can be accomplished by means of the command +# \hideincludedbygraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2641,7 +2702,10 @@ GRAPHICAL_HIERARCHY = YES # If the DIRECTORY_GRAPH tag is set to YES then doxygen will show the # dependencies a directory has on other directories in a graphical way. The # dependency relations are determined by the #include relations between the -# files in the directories. +# files in the directories. Explicit enabling a directory graph, when +# DIRECTORY_GRAPH is set to NO, can be accomplished by means of the command +# \directorygraph. Disabling a directory graph can be accomplished by means of +# the command \hidedirectorygraph. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2657,7 +2721,7 @@ DIR_GRAPH_MAX_DEPTH = 1 # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images # generated by dot. For an explanation of the image formats see the section # output formats in the documentation of the dot tool (Graphviz (see: -# http://www.graphviz.org/)). +# https://www.graphviz.org/)). # Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order # to make the SVG files visible in IE 9+ (other browsers do not have this # requirement). @@ -2694,11 +2758,12 @@ DOT_PATH = DOTFILE_DIRS = -# The MSCFILE_DIRS tag can be used to specify one or more directories that -# contain msc files that are included in the documentation (see the \mscfile -# command). +# You can include diagrams made with dia in doxygen documentation. Doxygen will +# then run dia to produce the diagram and insert it in the documentation. The +# DIA_PATH tag allows you to specify the directory where the dia binary resides. +# If left empty dia is assumed to be found in the default search path. -MSCFILE_DIRS = +DIA_PATH = # The DIAFILE_DIRS tag can be used to specify one or more directories that # contain dia files that are included in the documentation (see the \diafile @@ -2775,3 +2840,19 @@ GENERATE_LEGEND = YES # The default value is: YES. DOT_CLEANUP = YES + +# You can define message sequence charts within doxygen comments using the \msc +# command. If the MSCGEN_TOOL tag is left empty (the default), then doxygen will +# use a built-in version of mscgen tool to produce the charts. Alternatively, +# the MSCGEN_TOOL tag can also specify the name an external tool. For instance, +# specifying prog as the value, doxygen will call the tool as prog -T +# -o . The external tool should support +# output file formats "png", "eps", "svg", and "ismap". + +MSCGEN_TOOL = + +# The MSCFILE_DIRS tag can be used to specify one or more directories that +# contain msc files that are included in the documentation (see the \mscfile +# command). + +MSCFILE_DIRS = diff --git a/docs/Improvements_and_updates.md b/docs/Improvements_and_updates.md deleted file mode 100644 index a7504d5fb..000000000 --- a/docs/Improvements_and_updates.md +++ /dev/null @@ -1,149 +0,0 @@ -# Improvements and updates - -Many improvements have been made to this library vs the original, this is a brief overview of the most significant changes. Refer to the [class documentation](https://h2zero.github.io/esp-nimble-cpp/annotated.html) for further information on class specifics. - -* [Server](#server) -* [Advertising](#advertising) -* [Client](#client) -* [General](#general) -
- - -# Server - -`NimBLEService::NimBLEService::createCharacteristic` takes a 3rd parameter to specify the maximum data size that can be stored by the characteristic. This allows for limiting the RAM use of the characteristic in cases where small amounts of data are expected. -
- -`NimBLECharacteristic::setValue(const T &s)` -`NimBLEDescriptor::setValue(const T &s)` - -Now use the `NimbleAttValue` class and templates to accommodate standard and custom types/values. - -**Example** -``` -struct my_struct { - uint8_t one; - uint16_t two; - uint32_t four; - uint64_t eight; - float flt; -} myStruct; - - myStruct.one = 1; - myStruct.two = 2; - myStruct.four = 4; - myStruct.eight = 8; - myStruct.flt = 1234.56; - - pCharacteristic->setValue(myStruct); - - // Arduino String support - String myString = "Hello"; - pCharacteristic->setValue(myString); - ``` -This will send the struct to the receiving client when read or a notification sent. - -`NimBLECharacteristic::getValue` now takes an optional timestamp parameter which will update it's value with the time the last value was received. In addition an overloaded template has been added to retrieve the value as a type specified by the user. - -**Example** -``` - time_t timestamp; - myStruct = pCharacteristic->getValue(×tamp); // timestamp optional -``` -
- -**Advertising will automatically start when a client disconnects.** - -A new method `NimBLEServer::advertiseOnDisconnect(bool)` has been implemented to control this, true(default) = enabled. -
- -`NimBLEServer::removeService` takes an additional parameter `bool deleteSvc` that if true will delete the service and all characteristics / descriptors belonging to it and invalidating any pointers to them. - -If false the service is only removed from visibility by clients. The pointers to the service and it's characteristics / descriptors will remain valid and the service can be re-added in the future using `NimBLEServer::addService`. -
- - -# Advertising -`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). - -This provides an opportunity to update the advertisement data if desired. - -Also now returns a bool value to indicate if advertising successfully started or not. -
- - -# Client - -`NimBLERemoteCharacteristic::readValue(time_t\*, bool)` -`NimBLERemoteDescriptor::readValue(bool)` - -Have been added as templates to allow reading the values as any specified type. - -**Example** -``` -struct my_struct{ - uint8_t one; - uint16_t two; - uint32_t four; - uint64_t eight; - float flt; -}myStruct; - - time_t timestamp; - myStruct = pRemoteCharacteristic->readValue(×tamp); // timestamp optional -``` -
- -`NimBLERemoteCharacteristic::registerForNotify` -Has been removed. - -`NimBLERemoteCharacteristic::subscribe` and `NimBLERemoteCharacteristic::unsubscribe` have been implemented to replace it. - -The internally stored characteristic value is now updated when notification/indication is recieved. Making a callback no longer required to get the most recent value unless timing is important. Instead, the application can call `NimBLERemoteCharacteristic::getValue` to get the most recent value any time. -
- -The `notify_callback` function is now defined as a `std::function` to take advantage of using `std::bind` to specify a class member function for the callback. - -Example: -``` -using namespace std::placeholders; -notify_callback callback = std::bind(&::, this, _1, _2, _3, _4); - -->subscribe(true, callback); -``` - -`NimBLERemoteCharacteristic::readValue` and `NimBLERemoteCharacteristic::getValue` take an optional timestamp parameter which will update it's value with -the time the last value was received. - -> NimBLEClient::getService -> NimBLERemoteService::getCharacteristic -> NimBLERemoteCharacteristic::getDescriptor - -These methods will now check the respective vectors for the attribute object and, if not found, will retrieve (only) -the specified attribute from the peripheral. - -These changes allow more control for the user to manage the resources used for the attributes. -
- -`NimBLEClient::connect()` can now be called without an address or advertised device parameter. This will connect to the device with the address previously set when last connected or set with `NimBLEDevice::setPeerAddress()`. - - -# General -To reduce resource use all instances of `std::map` have been replaced with `std::vector`. - -Use of `FreeRTOS::Semaphore` has been removed as it was consuming too much ram, the related files have been left in place to accomodate application use. - -Operators `==`, `!=` and `std::string` have been added to `NimBLEAddress` and `NimBLEUUID` for easier comparison and logging. - -New constructor for `NimBLEUUID(uint32_t, uint16_t, uint16_t, uint64_t)` added to lower memory use vs string construction. See: [#21](https://github.com/h2zero/NimBLE-Arduino/pull/21). - -Security/pairing operations are now handled in the respective `NimBLEClientCallbacks` and `NimBLEServerCallbacks` classes, `NimBLESecurity`(deprecated) remains for backward compatibility. - -Configuration options have been added to add or remove debugging information, when disabled (default) significantly reduces binary size. -In ESP-IDF the options are in menuconfig: `Main menu -> ESP-NimBLE-cpp configuration`. -For Arduino the options must be commented / uncommented in nimconfig.h. - -Characteristics and descriptors now use the `NimBLEAttValue` class to store their data. This is a polymorphic container class capable of converting to/from many different types efficiently. See: [#286](https://github.com/h2zero/NimBLE-Arduino/pull/286) - diff --git a/docs/Migration_guide.md b/docs/Migration_guide.md index a0e4670ec..516ad6d41 100644 --- a/docs/Migration_guide.md +++ b/docs/Migration_guide.md @@ -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. -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/NimBLE-Arduino/annotated.html). * [General Changes](#general-information) * [Server](#server-api) @@ -20,12 +20,11 @@ For more information on the improvements and additions please refer to the [clas * [Remote characteristics](#remote-characteristics) * [Client Callbacks](#client-callbacks) * [Security](#client-security) -* [Scanning](#scan-api) +* [BLE scan](#ble-scan) * [General Security](#security-api) * [Configuration](#arduino-configuration)
- ## General Information ### Header Files @@ -48,10 +47,9 @@ 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. -`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.
- ## Server API Creating a `BLEServer` instance is the same as original, no changes required. For example `BLEDevice::createServer()` will work just as it did before. @@ -72,7 +70,7 @@ void onDisconnect(NimBLEServer* pServer, NimBLEConnInfo& connInfo, int reason)` ```
-`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) @@ -81,13 +79,11 @@ onMTUChange(uint16_t MTU, NimBLEConnInfo& connInfo) **Note:** All callback methods have default implementations which allows the application to implement only the methods applicable.
- ### Services Creating a `BLEService` (`NimBLEService`) instance is the same as original, no changes required. For example `BLEServer::createService(SERVICE_UUID)` will work just as it did before.
- ### Characteristics `BLEService::createCharacteristic` (`NimBLEService::createCharacteristic`) is used the same way as originally except the properties parameter has changed. @@ -137,8 +133,8 @@ BLECharacteristic *pCharacteristic = pService->createCharacteristic( ```
- #### Characteristic callbacks + `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. @@ -168,7 +164,6 @@ my_struct_t myStruct = pChr->getValue(); ```
- ### Descriptors Descriptors are now created using the `NimBLECharacteristic::createDescriptor` method. @@ -179,8 +174,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 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, -allowing the creation of it would cause a fault in the NimBLE stack. +**Note:** Attempting to create a 0x2902 descriptor will trigger a warning message and flag it internally as removed and will not be functional. All other descriptors are now created just as characteristics are by using the `NimBLECharacteristic::createDescriptor` method (except 0x2904, see below). Which are defined as: @@ -197,7 +191,7 @@ NimBLEDescriptor* createDescriptor(NimBLEUUID uuid, NIMBLE_PROPERTY::WRITE, uint16_t max_len = 100); ``` -##### Example +#### Example ``` pDescriptor = pCharacteristic->createDescriptor("ABCD", NIMBLE_PROPERTY::READ | @@ -208,27 +202,18 @@ 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.
-For the 0x2904, there is a special class that is created when you call `createDescriptor("2904"). - -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"); -``` +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.
- #### Descriptor callbacks > `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.
- ### Server Security Security is set on the characteristic or descriptor properties by applying one of the following: > NIMBLE_PROPERTY::READ_ENC @@ -245,7 +230,6 @@ When a peer wants to read or write a characteristic or descriptor with any of th This can be changed to use passkey authentication or numeric comparison. See [Security API](#security-api) for details.
- ## Advertising API Advertising works the same as the original API except: @@ -255,11 +239,9 @@ Calling `NimBLEAdvertising::setAdvertisementData` will entirely replace any data > 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). -This provides an opportunity to update the advertisement data if desired. +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.
- ## Client API Client instances are created just as before with `BLEDevice::createClient` (`NimBLEDevice::createClient`). @@ -268,15 +250,17 @@ Multiple client instances can be created, up to the maximum number of connection `BLEClient::connect`(`NimBLEClient::connect`) Has had it's parameters altered. Defined as: -> NimBLEClient::connect(bool deleteServices = true); -> NimBLEClient::connect(NimBLEAdvertisedDevice\* device, bool deleteServices = true); -> NimBLEClient::connect(NimBLEAddress address, bool deleteServices = true); +> NimBLEClient::connect(bool deleteServices = true, , bool asyncConnect = false, bool exchangeMTU = true); +> NimBLEClient::connect(const NimBLEAddress& address, bool deleteAttributes = true, bool asyncConnect = false, bool exchangeMTU = 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. -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. + +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. -This allows for faster connections and power saving if the devices dropped connection and are reconnecting. +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.
> `BLEClient::getServices` (`NimBLEClient::getServices`) @@ -290,7 +274,6 @@ Also now returns a pointer to `std::vector` instead of `std::map`. **Added:** `NimBLEClient::discoverAttributes` for the user to discover all the peripheral attributes to replace the the removed automatic functionality.
- ### Remote Services `BLERemoteService` (`NimBLERemoteService`) Methods remain mostly unchanged with the exceptions of: @@ -301,12 +284,10 @@ This method has been removed. > `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 -the currently known database returned (false : default). +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. Also now returns a pointer to `std::vector` instead of `std::map`.
- ### Remote Characteristics `BLERemoteCharacteristic` (`NimBLERemoteCharacteristic`) There have been a few changes to the methods in this class: @@ -326,12 +307,12 @@ Has been removed. Are the new methods added to replace it.
-> `BLERemoteCharacteristic::readUInt8` (`NimBLERemoteCharacteristic::readUInt8`) -> `BLERemoteCharacteristic::readUInt16` (`NimBLERemoteCharacteristic::readUInt16`) -> `BLERemoteCharacteristic::readUInt32` (`NimBLERemoteCharacteristic::readUInt32`) +> `BLERemoteCharacteristic::readUInt8` (`NimBLERemoteCharacteristic::readUInt8`) +> `BLERemoteCharacteristic::readUInt16` (`NimBLERemoteCharacteristic::readUInt16`) +> `BLERemoteCharacteristic::readUInt32` (`NimBLERemoteCharacteristic::readUInt32`) > `BLERemoteCharacteristic::readFloat` (`NimBLERemoteCharacteristic::readFloat`) -Are **deprecated** a template: `NimBLERemoteCharacteristic::readValue(time_t\*, bool)` has been added to replace them. +Are **removed** a template: `NimBLERemoteCharacteristic::readValue(time_t\*, bool)` has been added to replace them.
> `BLERemoteCharacteristic::readRawData` @@ -339,10 +320,10 @@ Are **deprecated** a template: `NimBLERemoteCharacteristic::readValue(tim **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. 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(); -uint8_t *data = (uint8_t*)value.data(); +NimBLEAttValue value = pChr->readValue(); +const uint8_t *data = value.data(); ``` Alternatively use the `readValue` template: ``` @@ -352,12 +333,10 @@ my_struct_t myStruct = pChr->readValue(); > `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 -the currently known database returned (false : default). +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. Also now returns a pointer to `std::vector` instead of `std::map`.
- ### Client callbacks > `BLEClientCallbacks::onDisconnect` (`NimBLEClientCallbacks::onDisconnect`) @@ -365,18 +344,20 @@ Also now returns a pointer to `std::vector` instead of `std::map`. This now takes a second parameter `int reason` which provides the reason code for disconnection.
- ### Client Security The client will automatically initiate security when the peripheral responds that it's required. The default configuration will use "just-works" pairing with no bonding, if you wish to enable bonding see below.
- ## 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.
- ## Security API Security operations have been moved to `BLEDevice` (`NimBLEDevice`). The security callback methods are now incorporated in the `NimBLEServerCallbacks` / `NimBLEClientCallbacks` classes. @@ -426,7 +407,6 @@ If we are the initiator of the security procedure this sets the keys we will dis Sets the keys we are willing to accept from the peer during pairing.
- ## Arduino Configuration Unlike the original library pre-packaged in the esp32-arduino, this library has all the configuration options that are normally set in menuconfig available in the *src/nimconfig.h* file. diff --git a/docs/New_user_guide.md b/docs/New_user_guide.md index 506a368b3..a08dfd580 100644 --- a/docs/New_user_guide.md +++ b/docs/New_user_guide.md @@ -21,7 +21,6 @@ If you're not creating a server or do not want to advertise a name, simply pass This can be called any time you wish to use BLE functions and does not need to be called from app_main(IDF) or setup(Arduino) but usually is.
- ## Creating a Server BLE servers perform 2 tasks, they advertise their existence for clients to find them and they provide services which contain information for the connecting client. @@ -137,7 +136,6 @@ Now if you scan with your phone using nRFConnect or any other BLE app you should For more advanced features and options please see the server examples in the examples folder.
- ## Creating a Client BLE clients perform 2 tasks, they scan for advertising servers and form connections to them to read and write to their characteristics/descriptors. diff --git a/docs/index.md b/docs/index.md index 2f1af75a2..71d5fd8e5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -36,8 +36,6 @@ If you have not used the original BLE library please refer to the [New user guid If you are familiar with the original library, see: [The migration guide](Migration_guide.md) for details. -Also see [Improvements and updates](Improvements_and_updates.md) for information about non-breaking changes. - For more advanced usage see [Usage tips](Usage_tips.md) for more performance and optimization.
@@ -46,7 +44,7 @@ See the Refactored_original_examples in the examples folder for highlights of th More advanced examples highlighting many available features are in examples/NimBLE_Server, NimBLE_Client. -Beacon examples provided by [beegee-tokyo](https://github.com/beegee-tokyo) are in examples/BLE_Beacon_Scanner, BLE_EddystoneTLM_Beacon, BLE_EddystoneURL_Beacon. +Beacon examples provided by [beegee-tokyo](https://github.com/beegee-tokyo) are in examples/BLE_Beacon_Scanner, BLE_EddystoneTLM_Beacon. Change the settings in the nimconfig.h file to customize NimBLE to your project, such as increasing max connections (default is 3).