NimBLE updates (#24163)

Author: Staars

lib/libesp32_div/esp-nimble-cpp/.gitignore

@@ -1,6 +1,36 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
+## [2.3.3] 2025-09-05
+
+## Fixed
+- NimBLEAdvertisedDevice::isConnectable returning incorrect result.
+- Extended advertisements not reporting full data.
+
+## Added
+- Support up to 1650 bytes of advertisement with extended advertising
+
+## [2.3.2] 2025-09-02
+
+## Fixed
+- Build failures with esp-idf versions 4.x.
+- Workaround for upstream issue causing onConnectFail to not be called.
+- Build failures with idf v5.5+ and specific roles are not enabled.
+
+## Changed
+- Allow peripheral and central roles to be used without broadcaster/observer roles.
+- Where applicable, `MYNEWT_VAL_` macros are used to control feature availability instead of `CONFIG_`
+
+## [2.3.1] 2025-06-11
+
+## Fixed
+- Build errors when disabling BLE roles.
+- `NimBLEClient::readValue` call not returning when the instance was created with a`NimBLEServer` and reading a secured characteristic.
+- `NimBLEScan` destructor potentially causing a crash.
+
+## Added
+- `NimBLEBeacon::BeaconData` `std::vector<uint8_t>` operator to allow it to be used as a parameter to `NimBLEAdvertisementData::setManufacturerData`.
+
 ## [2.3.0] 2025-05-19
 
 ## Fixed

lib/libesp32_div/esp-nimble-cpp/CHANGELOG.md

@@ -37,6 +37,7 @@ idf_component_register(
     "esp32c3"
     "esp32c5"
     "esp32c6"
+    "esp32c61"
     "esp32h2"
     "esp32p4"
   INCLUDE_DIRS

lib/libesp32_div/esp-nimble-cpp/CMakeLists.txt

@@ -204,6 +204,10 @@ config NIMBLE_CPP_FREERTOS_TASK_BLOCK_BIT
         Configure the bit to set in the task notification value when a task is blocked waiting for an event.
         This should be set to a bit that is not used by other notifications in the system.
 
+config NIMBLE_CPP_IDF
+    bool
+    default BT_NIMBLE_ENABLED
+
 #
 # BT config
 #

lib/libesp32_div/esp-nimble-cpp/Kconfig

@@ -9,6 +9,8 @@
 
 NimBLE CPP library for use with ESP32 that attempts to maintain compatibility with the [nkolban cpp_utils BLE API](https://github.com/nkolban/esp32-snippets/tree/master/cpp_utils).
 
+The library is threadsafe, characteristics can be set from any thread.
+
 **An Arduino version of this library, including NimBLE, can be [found here.](https://github.com/h2zero/NimBLE-Arduino)**
 
 This library **significantly** reduces resource usage and improves performance for ESP32 BLE applications as compared    

lib/libesp32_div/esp-nimble-cpp/README.md

@@ -43,6 +43,7 @@ The changes listed here are only the required changes that must be made, and a s
     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`.  
+- `NimBLEDevice::getClientByID(uint16_t conn_id);` has been changed to `NimBLEDevice::getClientByHandle(uint16_t connHandle)`
 <br/>
 
 ## BLE Addresses
@@ -54,7 +55,7 @@ The default address type is public `0`, whereas many devices use a random `1` ad
 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`.  
+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.val` and type is in `ble_addr_t.type`.  
 <br/>
 
 ## BLE UUID's
@@ -133,6 +134,7 @@ Have been removed, instead the application should use `NimBLERemoteCharacteristi
 - - `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::setAdvertisedDeviceCallbacks(NimBLEAdvertisedDeviceCallbacks* callbacks, bool wantDuplicates)` has been changed to `NimBLEScan::setScanCallbacks(NimBLEScanCallbacks* callbacks, bool wantDuplicates);`
 <br/>
 
 ### Advertised Device

lib/libesp32_div/esp-nimble-cpp/docs/1.x_to2.x_migration_guide.md

@@ -48,8 +48,7 @@ PROJECT_NAME           = esp-nimble-cpp
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 2.3.0
-
+PROJECT_NUMBER         = 2.3.3
 # 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
 # quick idea about the purpose of the project. Keep the description short.
@@ -2417,12 +2416,12 @@ INCLUDE_FILE_PATTERNS  =
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
 PREDEFINED             = _DOXYGEN_ \
-                         CONFIG_BT_ENABLED \
-                         CONFIG_BT_NIMBLE_ROLE_CENTRAL \
-                         CONFIG_BT_NIMBLE_ROLE_OBSERVER \
-                         CONFIG_BT_NIMBLE_ROLE_PERIPHERAL \
-                         CONFIG_BT_NIMBLE_ROLE_BROADCASTER \
-                         CONFIG_BT_NIMBLE_EXT_ADV
+                         CONFIG_BT_NIMBLE_ENABLED=1 \
+                         MYNEWT_VAL_BLE_ROLE_CENTRAL=1 \
+                         MYNEWT_VAL_BLE_ROLE_OBSERVER=1 \
+                         MYNEWT_VAL_BLE_ROLE_PERIPHERAL=1 \
+                         MYNEWT_VAL_BLE_ROLE_BROADCASTER=1 \
+                         MYNEWT_VAL_BLE_EXT_ADV=1
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

lib/libesp32_div/esp-nimble-cpp/docs/Doxyfile

@@ -234,7 +234,7 @@ This can be changed to use passkey authentication or numeric comparison. See [Se
 Advertising works the same as the original API except:
 
 Calling `NimBLEAdvertising::setAdvertisementData` will entirely replace any data set with `NimBLEAdvertising::addServiceUUID`, or
-`NimBLEAdvertising::setAppearance` or similar methods. You should set all the data you wish to advertise within the `NimBLEAdvertisementData` instead.  
+`NimBLEAdvertising::setAppearance` or similar methods. You should set all the data you wish to advertise within the `NimBLEAdvertisementData` instead if calling `NimBLEAdvertising::setAdvertisementData`.  
 <br/>
 
 > BLEAdvertising::start (NimBLEAdvertising::start)

lib/libesp32_div/esp-nimble-cpp/docs/Migration_guide.md

@@ -1,11 +1,8 @@
 # Usage Tips
 
-## Put BLE functions in a task running on the NimBLE stack core
+## Threadsafety
 
-When commands are sent to the stack from a different core they can experience delays in execution.  
-This library detects this and invokes the esp32 IPC to reroute these commands through the correct core but this also increases overhead.  
-Therefore it is highly recommended to create tasks for BLE to run on the same core, the macro `CONFIG_BT_NIMBLE_PINNED_TO_CORE` can be used to set the core.
-<br/>  
+This library is threadsafe. Attribues can be manipulated freely.
 
 ## Do not delete client instances unless necessary or unused
 
@@ -32,6 +29,41 @@ or nullptr such as when  calling `NimBLEClient::getService`. The latter being a
 Most of the functions in this library return something that should be checked before proceeding.  
 <br/>  
 
+## Persisted bonds can be lost due to low MAX_CCCDS
+
+The symptom: CONFIG_BT_NIMBLE_MAX_BONDS is set to N, but a smaller number of bonds is preserved, perhaps even a single bond. The limitation of persisted bonds can be observed via NimBLEDevice::getNumBonds(). The number may not reach CONFIG_BT_NIMBLE_MAX_BONDS.
+
+Cause: For each bond, NimBLE persists each of the CCCD (client characteristic configuration descriptor) values that have been subscribed
+to by the client. If CONFIG_BT_NIMBLE_MAX_CCCDS is too low, the older CCCD values are overwritten by the newer ones. The loss of the older
+CCCDs values results in those bonds being lost.
+
+Fix: Increase CONFIG_BT_NIMBLE_MAX_CCCDS. These take approximately 40 bytes in NVS, 2 bytes for the CCCD value and the NVS metadata overhead. The value of
+CONFIG_BT_NIMBLE_MAX_CCCDS should conservatively be no less than (CONFIG_BT_NIMBLE_MAX_BONDS * {maximum number of characteristics that can be subscribed to}).
+
+## Device 'Local Name'
+
+'Local name' refers to how the device is seen and displayed.
+
+A devices 'Local name' can be thought of as coming from two places, the <i>Advertising "Local name"</i> and the <i>the GATT Device Name</i>.
+
+### Advertising "Local name"
+
+Field found in the advertising data payload. Value is set via NimBLEAdvertising::setName().
+
+### GATT Device Name
+
+Characteristic UUID 0x2A00 in the Generic Access service. Set via NimBLEDevice::init() or NimBLEDevice::setDeviceName().
+
+This characteristic is read <b>after</b> connecting to the device.
+
+### Important considerations
+
+* OSes cache the <i>'GATT Device Name'</i>.
+* OSes update the device name based on the <i>'GATT Device Name'</i> after connecting to a device. This means that if you set the <i>Advertising 'Local name'</i> to "ABCD" but the <i>'GATT Device Name'</i> to "12345", the device will be seen as "ABCD" until connecting to the device, at which time the devices name will change to "12345".
+* If no <i>'Advertising "Local name"'</i> is set, OSes, such as iOS, may display the devices name as 'Unnamed' until the device is connected to, at which time the <i>'GATT Device Name'</i> is read and used instead.
+
+It is recommended that both <i>'Advertising "Local name"'</i> <b>and</b> <i>'GATT Device Name'</i> be set appropriately, after considering the above described behavior.
+
 ## There will be bugs - please report them
 
 No code is bug free and unit testing will not find them all on it's own. If you encounter a bug, please report it along with any logs and decoded backtrace if applicable.  

lib/libesp32_div/esp-nimble-cpp/docs/Usage_tips.md

@@ -112,7 +112,7 @@ bool connectToServer() {
 
     /** No client to reuse? Create a new one. */
     if (!pClient) {
-        if (NimBLEDevice::getCreatedClientCount() >= NIMBLE_MAX_CONNECTIONS) {
+        if (NimBLEDevice::getCreatedClientCount() >= MYNEWT_VAL(BLE_MAX_CONNECTIONS)) {
             printf("Max clients reached - no more connections available\n");
             return false;
         }
@@ -261,8 +261,7 @@ extern "C" void app_main(void) {
      *  These are the default values, only shown here for demonstration.
      */
     // NimBLEDevice::setSecurityAuth(false, false, true);
-
-    NimBLEDevice::setSecurityAuth(/*BLE_SM_PAIR_AUTHREQ_BOND | BLE_SM_PAIR_AUTHREQ_MITM |*/ BLE_SM_PAIR_AUTHREQ_SC);
+    // NimBLEDevice::setSecurityAuth(BLE_SM_PAIR_AUTHREQ_BOND | BLE_SM_PAIR_AUTHREQ_MITM | BLE_SM_PAIR_AUTHREQ_SC);
 
     /** Optional: set the transmit power */
     NimBLEDevice::setPower(3); /** 3dbm */