Update docs and workflows.

Author: h2zero

.github/workflows/build.yml

@@ -17,11 +17,11 @@ jobs:
           - "examples/NimBLE_Server"
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.x"
+          python-version: "3.13"
       - name: Install platformio
         run: |
           python -m pip install --upgrade pip
@@ -57,7 +57,7 @@ jobs:
           - "examples/Bluetooth_5/NimBLE_extended_server"
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
@@ -96,7 +96,7 @@ jobs:
           - "examples/NimBLE_Server"
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
@@ -142,7 +142,7 @@ jobs:
           - "examples/Bluetooth_5/NimBLE_extended_server"
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
@@ -195,7 +195,7 @@ jobs:
           - esp32h2
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Build arduino-esp32
         uses: arduino/compile-sketches@v1.1.0
         with:
@@ -221,7 +221,7 @@ jobs:
           - esp32h2
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Set config for BT5
         run: |
           sed -i '0,/#include \"nimconfig_rename.h\"/a #define CONFIG_BT_NIMBLE_EXT_ADV 1' ./src/nimconfig.h
@@ -250,7 +250,7 @@ jobs:
           - Generic_nRF52840
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Build n-able Arduino
         uses: arduino/compile-sketches@v1.1.0
         with:
@@ -273,7 +273,7 @@ jobs:
           - Generic_nRF52840
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Set config for BT5
         run: |
           echo "-DCONFIG_BT_NIMBLE_EXT_ADV=1" > ${{ matrix.example }}/build_opt.h
@@ -297,7 +297,7 @@ jobs:
           - "examples/NimBLE_Server"
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
@@ -340,7 +340,7 @@ jobs:
           - "examples/Bluetooth_5/NimBLE_extended_server"
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
@@ -369,7 +369,7 @@ jobs:
   build_docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Doxygen Action
         uses: mattnotmitt/doxygen-action@v1.9.8
         with:

.github/workflows/release.yml

@@ -9,7 +9,7 @@ jobs:
   build_docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Doxygen Action
         uses: mattnotmitt/doxygen-action@v1.9.8
         with:
@@ -19,4 +19,13 @@ jobs:
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs/doxydocs/html
+          publish_dir: ./docs/doxydocs/html
+
+  upload_to_platformio_registry:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Upload component to PlatformIO Registry
+        uses: bojit/platformio-publish@main
+        with:
+          token: ${{ secrets.PLATFORMIO_AUTH_TOKEN }}

.github/workflows/sponsors.yml

@@ -1,6 +1,32 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+## Fixed
+- GATT attribute handles are now assigned from the registration callback so duplicate UUID attributes are identified correctly.
+- Dynamic service changes now properly remove characteristics/descriptors and reset the GATT database when advertising starts.
+- Missing notification/indication payload data when the value spans multiple mbufs, such as values larger than 255 bytes with small ACL buffers.
+- `NimBLEDevice::createServer` will longer crash when called before the stack is initialized.
+- Re-pairing after deleting all bonds now works by unpairing each stored bond instead of only deleting NVS data.
+- Whitelist bounds checks.
+- `NimBLEDevice::getBondedAddress` index bounds validation.
+- ESP32 linker error when both central and peripheral roles are disabled.
+- Compiler warnings when bonds are disabled.
+
+## Added
+- `NimBLEStream`, `NimBLEStreamClient`, and `NimBLEStreamServer` classes and examples.
+- `NimBLECppVersion.h` with compile-time version macros.
+- `NimBLEDevice::getVersion` runtime version string helper.
+- Matching passkey callbacks for both roles: `NimBLEServerCallbacks::onPassKeyEntry` and `NimBLEClientCallbacks::onPassKeyDisplay`.
+- Bond migration helpers to convert bond storage between v1 and current formats while preserving existing bonds.
+- `NimBLEUUID` constructor overload for `ble_uuid_t*`.
+- Optional `index` parameter for `NimBLECharacteristic::getDescriptorByUUID` to access multiple descriptors with the same UUID.
+
+## Changed
+- `NimBLEService::start` is deprecated; services are now added when the server starts.
+- `NimBLEHIDDevice::startServices()` is deprecated; services are now added when the server starts.
+
 ## [2.3.9] 2026-03-08
 
 ## Fixed

CHANGELOG.md

@@ -31,7 +31,7 @@ For Nordic devices, this library provides access to a completely open source and
 * Open platformio.ini, a project configuration file located in the root of PlatformIO project.  
 * Add the following line to the lib_deps option of [env:] section:
 ```
-h2zero/NimBLE-Arduino@^2.1.0
+h2zero/NimBLE-Arduino
 ```
 * Build a project, PlatformIO will automatically install dependencies.
 
@@ -56,15 +56,9 @@ Change the settings in the `src/nimconfig.h` file to customize NimBLE to your pr
 such as increasing max connections, default is 3 for the esp32.
 <br/>
 
-# Development Status
-This Library is tracking the esp-nimble repo, nimble-1.5.0-idf branch, currently [@e3cbdc0.](https://github.com/espressif/esp-nimble)  
-<br/>
-
 # Sponsors
 Thank you to all the sponsors who support this project!
 
-<!-- sponsors --><!-- sponsors -->
-
 If you use this library for a commercial product please consider [sponsoring the development](https://github.com/sponsors/h2zero) to ensure the continued updates and maintenance.  
 <br/>
 

README.md

@@ -7,6 +7,7 @@ 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)
+* [Bond migration](#bond-migration)
 * [BLE Device](#ble-device)
 * [BLE Addresses](#ble-addresses)
 * [BLE UUID's](#ble-uuids)
@@ -34,6 +35,49 @@ The changes listed here are only the required changes that must be made, and a s
     `NimBLEServerCallbacks::onConnect(NimBLEServer* pServer)` signature is now `NimBLEServerCallbacks::onConnect(NimBLEServer* pServer, NimBLEConnInfo& connInfo)`.  
 <br/>
 
+## Bond migration
+If your 1.x application stores bonds and you want paired devices to continue working after upgrading to 2.x, the library provides helper functions to migrate the bond data stored in NVS.
+
+The helpers are declared in `NimBLEBondMigration.h`:
+
+- `NimBLEBondMigration::migrateBondStoreToCurrent()` converts 1.x bond data to the current 2.x format.
+- `NimBLEBondMigration::migrateBondStoreToV1()` converts current bond data back to the 1.x format.
+- `NimBLEBondMigration::dumpBondData()` returns a human-readable dump of the stored bond records for debugging.
+
+These functions must be called **before** `NimBLEDevice::init()` so the bond store can be updated before the stack starts using it.
+
+Typical migration flow:
+
+1. Build and flash a temporary migration firmware that includes `NimBLEBondMigration.h`.
+2. Call `migrateBondStoreToCurrent()` once during startup before BLE initialization.
+3. If the function returns `true`, stop there and then flash the final 2.x application firmware.
+4. After the migration is complete, do not run the migration again in normal application startup.
+
+Example:
+
+    #include <NimBLEDevice.h>
+    #include <NimBLEBondMigration.h>
+
+    void setup() {
+        bool success = NimBLEBondMigration::migrateBondStoreToCurrent();
+        if (success) {
+            // Flash the normal 2.x firmware after this one-time step.
+            while (true) {
+                delay(1000);
+            }
+        }
+
+        NimBLEDevice::init("NimBLE");
+    }
+
+Notes:
+
+- These helpers currently require `ESP_PLATFORM` because they operate directly on the ESP NVS bond storage.
+- `dumpBondData()` is useful before and after migration to verify what records are present.
+- If you need to temporarily return to a 1.x firmware image while preserving bonds, run `migrateBondStoreToV1()` first, then flash the 1.x application.
+- See the `examples/NimBLE_Bond_Migration` example for a complete one-time migration sketch.
+<br/>
+
 ## 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.

docs/1.x_to2.x_migration_guide.md

@@ -1,5 +1,5 @@
 name=NimBLE-Arduino
-version=2.3.9
+version=2.4.0-rc
 author=h2zero
 maintainer=Ryan Powell <ryan@nable-embedded.io>
 sentence=Bluetooth low energy (BLE) library for Arduino based on NimBLE.

library.properties

@@ -16,6 +16,13 @@
 #include "nvs.h"
 #include "syscfg/syscfg.h"
 
+/**
+ * @brief Helpers for converting NimBLE bond data stored in ESP NVS between
+ *        the legacy 1.x layout and the current 2.x layout.
+ *
+ * These helpers are intended for one-time migration firmware and must be used
+ * before calling `NimBLEDevice::init()`.
+ */
 namespace NimBLEBondMigration {
 
 namespace detail {
@@ -487,6 +494,17 @@ inline bool migrateBondStore(bool toCurrent, uint16_t maxEntries) {
 
 } // namespace detail
 
+/**
+ * @brief Read and format the contents of the NimBLE bond store.
+ *
+ * This is intended for diagnostics before or after migration and returns a
+ * human-readable summary of each `our_sec_*`, `peer_sec_*`, and `local_irk_*`
+ * record found in the NVS bond namespace.
+ *
+ * @param[in] maxEntries The maximum number of bond slots to inspect.
+ * @return A formatted string describing the stored bond data, or an error
+ *         message if the NVS namespace could not be opened.
+ */
 inline std::string dumpBondData(uint16_t maxEntries = MYNEWT_VAL(BLE_STORE_MAX_BONDS)) {
     std::string out;
     out.reserve(2048);
@@ -649,10 +667,31 @@ inline std::string dumpBondData(uint16_t maxEntries = MYNEWT_VAL(BLE_STORE_MAX_B
     return out;
 }
 
+/**
+ * @brief Convert legacy 1.x bond data in NVS to the current 2.x format.
+ *
+ * This function should be called once, before `NimBLEDevice::init()`, by a
+ * temporary migration firmware when upgrading an existing installation that
+ * needs to preserve bonded peers.
+ *
+ * @param[in] maxEntries The maximum number of bond slots to inspect and
+ *            convert.
+ * @return `true` if migration completed successfully, otherwise `false`.
+ */
 inline bool migrateBondStoreToCurrent(uint16_t maxEntries = MYNEWT_VAL(BLE_STORE_MAX_BONDS)) {
     return detail::migrateBondStore(true, maxEntries);
 }
 
+/**
+ * @brief Convert current 2.x bond data in NVS back to the legacy 1.x format.
+ *
+ * This is intended for rollback scenarios where bond data must be preserved
+ * before flashing firmware built against the 1.x library.
+ *
+ * @param[in] maxEntries The maximum number of bond slots to inspect and
+ *            convert.
+ * @return `true` if migration completed successfully, otherwise `false`.
+ */
 inline bool migrateBondStoreToV1(uint16_t maxEntries = MYNEWT_VAL(BLE_STORE_MAX_BONDS)) {
     return detail::migrateBondStore(false, maxEntries);
 }

src/NimBLEBondMigration.h

@@ -22,10 +22,10 @@
 #define NIMBLE_CPP_VERSION_MAJOR 2
 
 /** @brief NimBLE-Arduino library minor version number. */
-#define NIMBLE_CPP_VERSION_MINOR 3
+#define NIMBLE_CPP_VERSION_MINOR 4
 
 /** @brief NimBLE-Arduino library patch version number. */
-#define NIMBLE_CPP_VERSION_PATCH 9
+#define NIMBLE_CPP_VERSION_PATCH 0
 
 /**
  * @brief Macro to create a version number for comparison.
@@ -58,7 +58,7 @@
  * @details Include the leading '-' when defined, for example: "-beta.1"
  */
 #ifndef NIMBLE_CPP_VERSION_PRERELEASE
-# define NIMBLE_CPP_VERSION_PRERELEASE ""
+# define NIMBLE_CPP_VERSION_PRERELEASE "-rc.1"
 #endif
 
 /**