Release 2.1.0

Skipping 2.0.0 as it was accidently published in the Arduino library manager already.

Author: h2zero

.github/workflows/release.yml

@@ -9,7 +9,7 @@ jobs:
   build_docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Doxygen Action
         uses: mattnotmitt/doxygen-action@v1.9.8
         with:

.github/workflows/sponsors.yml

@@ -0,0 +1,17 @@
+name: Generate Sponsors README
+on:
+  workflow_dispatch:
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v4
+
+      - name: Generate Sponsors 💖
+        uses: JamesIves/github-sponsors-readme-action@v1.5.4
+        with:
+          token: ${{ secrets.PAT }}
+          file: 'README.md'

CHANGELOG.md

@@ -1,7 +1,7 @@
 # Changelog
-
 All notable changes to this project will be documented in this file.
-## [Unreleased]
+
+## [2.1.0] 2024-12-14
 
 ## **Breaking changes**
 - NimBLESecurity class removed.
@@ -57,6 +57,7 @@ All notable changes to this project will be documented in this file.
 - `NimBLEAdvertisedDevice::hasRSSI` removed as redundant, RSSI is always available.
 - `NimBLEAdvertisedDevice::getPayload` now returns `const std::vector<uint8_t>` instead of a pointer to internal memory.
 - `NimBLEAdvertisedDevice` Timestamp removed, if needed then the app should track the time from the callback.
+- `NimBLEAddress` constructor; default value for the `type` parameter removed, caller should know the address type and specify it.
 - `NimBLEAddress::getNative` replaced with `NimBLEAddress::getBase` and now returns a pointer to `const ble_addr_t` instead of a pointer to the address value.
 - `NimBLEAddress::equals` method and `NimBLEAddress::== operator` will now also test if the address types are the same.
 - `NimBLEUUID::getNative` method replaced with `NimBLEUUID::getBase` which returns a read-only pointer to the underlying `ble_uuid_t` struct.

README.md

@@ -1,21 +1,21 @@
-[Latest release ![Release Version](https://img.shields.io/github/release/h2zero/NimBLE-Arduino.svg?style=plastic)
+[![Release Version](https://img.shields.io/github/release/h2zero/NimBLE-Arduino.svg?style=plastic)
 ![Release Date](https://img.shields.io/github/release-date/h2zero/NimBLE-Arduino.svg?style=plastic)](https://github.com/h2zero/NimBLE-Arduino/releases/latest/)
-
-Need help? Have questions or suggestions? Join the [![Gitter](https://badges.gitter.im/NimBLE-Arduino/community.svg)](https://gitter.im/NimBLE-Arduino/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 <br/>
 
 # NimBLE-Arduino
 A fork of the NimBLE stack refactored for compilation in the Arduino IDE.
 
-**As of release 1.4.0 Nordic Semiconductor nRF51 and nRF52 series devices are now supported**
+> [!IMPORTANT]
+> Version 2 is now released!
+> Check out the [1.x to 2.x Migration Guide](docs/1.x_to2.x_migration_guide.md) and [Release Notes](https://github.com/h2zero/NimBLE-Arduino/releases/latest)
 
 ## Supported MCU's
  - Espressif: ESP32, ESP32C3, ESP32S3
  - Nordic: nRF51, nRF52 series (**Requires** using [n-able arduino core](https://github.com/h2zero/n-able-Arduino))
 
 **Note for ESP-IDF users: This repo will not compile correctly in ESP-IDF. An ESP-IDF component version of this library can be [found here.](https://github.com/h2zero/esp-nimble-cpp)**
 
-This library **significantly** reduces resource usage and improves performance for ESP32 BLE applications as compared with the bluedroid based library. The goal is to maintain, as much as reasonable, compatibility with the original library but refactored to use the NimBLE stack. In addition, this library will be more actively developed and maintained to provide improved capabilities and stability over the original.
+This library **significantly** reduces resource usage and improves performance for ESP32 BLE applications as compared with the bluedroid based library. The goal is to maintain, as much as reasonable, compatibility with the original library but but using the NimBLE stack. In addition, this library will be more actively developed and maintained to provide improved capabilities and stability over the original.
 <br/>
 
 For Nordic devices, this library provides access to a completely open source and configurable BLE stack. No softdevice to work around, allowing for full debugging and resource management, continuous updates, with a cross platform API.
@@ -31,17 +31,19 @@ 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@^1.4.0
+h2zero/NimBLE-Arduino@^2.1.0
 ```
 * Build a project, PlatformIO will automatically install dependencies.
 
 # Using
-This library is intended to be compatible with the original ESP32 BLE functions and types with minor changes.
+This library is intended to be compatible with the original ESP32 BLE functions and classes with minor changes.
 
 If you have not used the original Bluedroid library please refer to the [New user guide](docs/New_user_guide.md).
 
 If you are familiar with the original library, see: [The migration guide](docs/Migration_guide.md) for details about breaking changes and migration.
 
+If you already use this library and need to migrate your code to version 2.x see the [1.x to 2.x Migration Guide.](docs/1.x_to2.x_migration_guide.md)
+
 [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).
@@ -60,9 +62,16 @@ such as increasing max connections, default is 3 for the esp32.
 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/>
+
 # Acknowledgments
 * [nkolban](https://github.com/nkolban) and [chegewara](https://github.com/chegewara) for the [original esp32 BLE library](https://github.com/nkolban/esp32-snippets/tree/master/cpp_utils) this project was derived from.
 * [beegee-tokyo](https://github.com/beegee-tokyo) for contributing your time to test/debug and contributing the beacon examples.
 * [Jeroen88](https://github.com/Jeroen88) for the amazing help debugging and improving the client code.
 <br/>
-

docs/index.md

@@ -24,7 +24,7 @@ Call `NimBLEDevice::init` in `setup`.
 * 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@^1.4.0
+h2zero/NimBLE-Arduino@^2.1.0
 ```
 * Build a project, PlatformIO will automatically install dependencies.  
 <br/>
@@ -36,13 +36,13 @@ 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.
 
+If you already use this library and need to migrate your code to version 2.x see the [1.x to 2.x Migration Guide.](docs/1.x_to2.x_migration_guide.md)
+
 For more advanced usage see [Usage tips](Usage_tips.md) for more performance and optimization.  
 <br/>
 
 ## Examples
-See the Refactored_original_examples in the examples folder for highlights of the differences with the original library.
-
-More advanced examples highlighting many available features are in examples/NimBLE_Server, NimBLE_Client.
+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.
 
@@ -55,14 +55,14 @@ As an alternative to changing the configuration in nimconfig.h, Arduino command
 See the command line configuration options available in [Command line config](Command_line_config.md).  
 <br/>
 
-# Need help? Have a question or suggestion?
-Come chat on [gitter](https://gitter.im/NimBLE-Arduino/community?utm_source=share-link&utm_medium=link&utm_campaign=share-link) or open an issue at [NimBLE-Arduino](https://github.com/h2zero/NimBLE-Arduino/issues) or [esp-nimble-cpp](https://github.com/h2zero/esp-nimble-cpp/issues)  
+# Sponsors
+Thank you to all the sponsors who support this project!
+
+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/>
 
 # Acknowledgments
-
 * [nkolban](https://github.com/nkolban) and [chegewara](https://github.com/chegewara) for the [original esp32 BLE library](https://github.com/nkolban/esp32-snippets/tree/master/cpp_utils) this project was derived from.
 * [beegee-tokyo](https://github.com/beegee-tokyo) for contributing your time to test/debug and contributing the beacon examples.
 * [Jeroen88](https://github.com/Jeroen88) for the amazing help debugging and improving the client code.  
 <br/>
-

examples/NimBLE_Client/NimBLE_Client.ino

@@ -11,8 +11,8 @@
 #include <NimBLEDevice.h>
 
 static const NimBLEAdvertisedDevice* advDevice;
-static bool                          doConnect = false;
-static uint32_t                      scanTime  = 5000; /** scan time in milliseconds, 0 = scan forever */
+static bool                          doConnect  = false;
+static uint32_t                      scanTimeMs = 5000; /** scan time in milliseconds, 0 = scan forever */
 
 /**  None of these are required as they will be handled by the library with defaults. **
  **                       Remove as you see fit for your needs                        */
@@ -21,7 +21,7 @@ class ClientCallbacks : public NimBLEClientCallbacks {
 
     void onDisconnect(NimBLEClient* pClient, int reason) override {
         Serial.printf("%s Disconnected, reason = %d - Starting scan\n", pClient->getPeerAddress().toString().c_str(), reason);
-        NimBLEDevice::getScan()->start(scanTime, false, true);
+        NimBLEDevice::getScan()->start(scanTimeMs, false, true);
     }
 
     /********************* Security handled here *********************/
@@ -49,10 +49,10 @@ class ClientCallbacks : public NimBLEClientCallbacks {
             return;
         }
     }
-} clientCB;
+} clientCallbacks;
 
 /** Define a class to handle the callbacks when scan events are received */
-class scanCallbacks : public NimBLEScanCallbacks {
+class ScanCallbacks : public NimBLEScanCallbacks {
     void onResult(const NimBLEAdvertisedDevice* advertisedDevice) override {
         Serial.printf("Advertised Device found: %s\n", advertisedDevice->toString().c_str());
         if (advertisedDevice->isAdvertisingService(NimBLEUUID("DEAD"))) {
@@ -69,9 +69,9 @@ class scanCallbacks : public NimBLEScanCallbacks {
     /** Callback to process the results of the completed scan or restart it */
     void onScanEnd(const NimBLEScanResults& results, int reason) override {
         Serial.printf("Scan Ended, reason: %d, device count: %d; Restarting scan\n", reason, results.getCount());
-        NimBLEDevice::getScan()->start(scanTime, false, true);
+        NimBLEDevice::getScan()->start(scanTimeMs, false, true);
     }
-} scanCB;
+} scanCallbacks;
 
 /** Notification / Indication receiving handler callback */
 void notifyCB(NimBLERemoteCharacteristic* pRemoteCharacteristic, uint8_t* pData, size_t length, bool isNotify) {
@@ -122,7 +122,7 @@ bool connectToServer() {
 
         Serial.printf("New client created\n");
 
-        pClient->setClientCallbacks(&clientCB, false);
+        pClient->setClientCallbacks(&clientCallbacks, false);
         /**
          *  Set initial connection parameters:
          *  These settings are safe for 3 clients to connect reliably, can go faster if you have less
@@ -217,7 +217,9 @@ bool connectToServer() {
                 }
 
                 if (pChr->canRead()) {
-                    Serial.printf("The value of: %s is now: %s\n", pChr->getUUID().toString().c_str(), pChr->readValue().c_str());
+                    Serial.printf("The value of: %s is now: %s\n",
+                                  pChr->getUUID().toString().c_str(),
+                                  pChr->readValue().c_str());
                 }
             }
 
@@ -272,7 +274,7 @@ void setup() {
     NimBLEScan* pScan = NimBLEDevice::getScan();
 
     /** Set the callbacks to call when scan events occur, no duplicates */
-    pScan->setScanCallbacks(&scanCB, false);
+    pScan->setScanCallbacks(&scanCallbacks, false);
 
     /** Set scan interval (how often) and window (how long) in milliseconds */
     pScan->setInterval(100);
@@ -285,7 +287,7 @@ void setup() {
     pScan->setActiveScan(true);
 
     /** Start scanning for advertisers */
-    pScan->start(scanTime);
+    pScan->start(scanTimeMs);
     Serial.printf("Scanning for peripherals\n");
 }
 
@@ -302,6 +304,6 @@ void loop() {
             Serial.printf("Failed to connect, starting scan\n");
         }
 
-        NimBLEDevice::getScan()->start(scanTime, false, true);
+        NimBLEDevice::getScan()->start(scanTimeMs, false, true);
     }
 }

examples/NimBLE_Scan_Continuous/NimBLE_Scan_Continuous.ino

@@ -14,7 +14,7 @@
 #include <Arduino.h>
 #include <NimBLEDevice.h>
 
-static constexpr uint32_t scanTime = 30 * 1000; // 30 seconds scan time.
+static constexpr uint32_t scanTimeMs = 30 * 1000; // 30 seconds scan time.
 
 class scanCallbacks : public NimBLEScanCallbacks {
     /** Initial discovery, advertisement data only. */
@@ -32,7 +32,7 @@ class scanCallbacks : public NimBLEScanCallbacks {
 
     void onScanEnd(const NimBLEScanResults& results, int reason) override {
         printf("Scan ended reason = %d; restarting scan\n", reason);
-        NimBLEDevice::getScan()->start(scanTime, false, true);
+        NimBLEDevice::getScan()->start(scanTimeMs, false, true);
     }
 } scanCallbacks;
 
@@ -42,7 +42,7 @@ void setup() {
     pBLEScan->setScanCallbacks(&scanCallbacks, false); // Set the callback for when devices are discovered, no duplicates.
     pBLEScan->setActiveScan(true);          // Set active scanning, this will get more data from the advertiser.
     pBLEScan->setMaxResults(0);             // Do not store the scan results, use callback only.
-    pBLEScan->start(scanTime, false, true); // duration, not a continuation of last scan, restart to get all devices again.
+    pBLEScan->start(scanTimeMs, false, true); // duration, not a continuation of last scan, restart to get all devices again.
     printf("Scanning...\n");
 }
 

examples/NimBLE_Scan_Whitelist/NimBLE_Scan_whitelist.ino

@@ -8,7 +8,7 @@
 #include <Arduino.h>
 #include <NimBLEDevice.h>
 
-int         scanTime = 5 * 1000; // In milliseconds, 0 = scan forever
+int         scanTimeMs = 5 * 1000; // In milliseconds, 0 = scan forever
 NimBLEScan* pBLEScan;
 
 class ScanCallbacks : public NimBLEScanCallbacks {
@@ -42,7 +42,7 @@ void setup() {
 }
 
 void loop() {
-    NimBLEScanResults foundDevices = pBLEScan->getResults(scanTime, false);
+    NimBLEScanResults foundDevices = pBLEScan->getResults(scanTimeMs, false);
     Serial.print("Devices found: ");
     Serial.println(foundDevices.getCount());
     Serial.println("Scan done!");

library.properties

@@ -1,9 +1,9 @@
 name=NimBLE-Arduino
 version=2.1.0
 author=h2zero
-maintainer=Ryan Powell <powell.rg@gmail.com>
+maintainer=Ryan Powell <ryan@nable-embedded.io>
 sentence=Bluetooth low energy (BLE) library for Arduino based on NimBLE.
-paragraph=This is frequently updated and lower resource alternative to the original bluedroid BLE library for esp32 and Nordic nRF5 devices (must use n-able-Arduino core). Uses 50% less flash space and approximately 100KB less ram with the same functionality. Nearly 100% compatible with existing application code, migration guide included.
+paragraph=A light-weight alternative to the original bluedroid based BLE library for esp32 and Nordic nRF5 devices (must use n-able-Arduino core). Uses 50% less flash space and approximately 100KB less ram with the same functionality. Nearly 100% compatible with existing application code, migration guide included.
 url=https://github.com/h2zero/NimBLE-Arduino
 category=Communication
 architectures=esp32,arm-ble