diff --git a/.github/workflows/sponsors.yml b/.github/workflows/sponsors.yml new file mode 100644 index 0000000..a7d4a53 --- /dev/null +++ b/.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' \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index dca35f1..8aaa265 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,7 @@ # Changelog - All notable changes to this project will be documented in this file. -## [Unreleased] + +## [2.0.0] 2024-12-14 ## **Breaking changes** - 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. diff --git a/README.md b/README.md index 7f37eff..bacf985 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,20 @@ -[Latest release ![Release Version](https://img.shields.io/github/release/h2zero/esp-nimble-cpp.svg?style=plastic) +[![Release Version](https://img.shields.io/github/release/h2zero/esp-nimble-cpp.svg?style=plastic) ![Release Date](https://img.shields.io/github/release-date/h2zero/esp-nimble-cpp.svg?style=plastic)](https://github.com/h2zero/esp-nimble-cpp/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) -
+> [!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/esp-nimble-cpp/releases/latest/) # esp-nimble-cpp -NimBLE CPP library for use with ESP32 that attempts to maintain compatibility with the [nkolban cpp_uitls BLE API](https://github.com/nkolban/esp32-snippets/tree/master/cpp_utils). +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). **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 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 capabilites and stability over the original. +library 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. **Testing shows a nearly 50% reduction in flash use and approx. 100kB less ram consumed vs the original!** *Your results may vary* @@ -35,16 +36,6 @@ Configure settings in `NimBLE Options`. Call `NimBLEDevice::init("");` in `app_main`.
-### ESP-IDF v3.2 & v3.3 -The NimBLE component does not come with these versions of IDF (now included in 3.3.2 and above). -A backport that works in these versions has been created and is [available here](https://github.com/h2zero/esp-nimble-component). -Download or clone that repo into your project/components folder and run menuconfig. -Configure settings in `main menu -> NimBLE Options`. - -`#include "NimBLEDevice.h"` in main.cpp. -Call `NimBLEDevice::init("");` in `app_main`. -
- # Using This library is intended to be compatible with the original ESP32 BLE functions and types with minor changes. @@ -62,6 +53,14 @@ When using this library along with Arduino and compiling with *CMake* you must a in your project/CMakeLists.txt after the line `include($ENV{IDF_PATH}/tools/cmake/project.cmake)` to prevent Arduino from releasing BLE memory.
+# 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. +
+ # 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. diff --git a/docs/index.md b/docs/index.md index 1b729c1..570c018 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,4 @@ # Overview - This is a C++ BLE library for the ESP32 that uses the NimBLE host stack instead of bluedroid. The aim is to maintain, as much as reasonable, the original bluedroid C++ & Arduino BLE API by while adding new features and making improvements in performance, resource use, and stability. @@ -23,16 +22,6 @@ Configure settings in `NimBLE Options`. Call `NimBLEDevice::init` in `app_main`.
-### v3.2 & v3.3 -The NimBLE component does not come with these versions of IDF (now included in 3.3.2 and above). -A backport that works in these versions has been created and is [available here](https://github.com/h2zero/esp-nimble-component). -Download or clone that repo into your project/components folder and run menuconfig. -Configure settings in `main menu -> NimBLE Options`. - -`#include "NimBLEDevice.h"` in main.cpp. -Call `NimBLEDevice::init` in `app_main`. -
- # Using This library is intended to be compatible with the original ESP32 BLE functions and types with minor changes. @@ -43,12 +32,13 @@ If you are familiar with the original library, see: [The migration guide](Migrat For more advanced usage see [Usage tips](Usage_tips.md) for more performance and optimization.
-# 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.
# 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. diff --git a/examples/Bluetooth_5/NimBLE_extended_client/main/main.cpp b/examples/Bluetooth_5/NimBLE_extended_client/main/main.cpp index 5b006ad..9248d94 100644 --- a/examples/Bluetooth_5/NimBLE_extended_client/main/main.cpp +++ b/examples/Bluetooth_5/NimBLE_extended_client/main/main.cpp @@ -14,8 +14,8 @@ #define CHARACTERISTIC_UUID "1234" static const NimBLEAdvertisedDevice* advDevice; -static bool doConnect = false; -static uint32_t scanTime = 10 * 1000; // In milliseconds, 0 = scan forever +static bool doConnect = false; +static uint32_t scanTimeMs = 10 * 1000; // In milliseconds, 0 = scan forever /** Define the PHY's to use when connecting to peer devices, can be 1, 2, or all 3 (default).*/ static uint8_t connectPhys = BLE_GAP_LE_PHY_CODED_MASK | BLE_GAP_LE_PHY_1M_MASK /*| BLE_GAP_LE_PHY_2M_MASK */; @@ -26,7 +26,7 @@ class ClientCallbacks : public NimBLEClientCallbacks { void onDisconnect(NimBLEClient* pClient, int reason) override { printf("%s Disconnected, reason = %d - Starting scan\n", pClient->getPeerAddress().toString().c_str(), reason); - NimBLEDevice::getScan()->start(scanTime); + NimBLEDevice::getScan()->start(scanTimeMs); } } clientCallbacks; @@ -123,7 +123,7 @@ extern "C" void app_main(void) { * Start scanning for advertisers for the scan time specified (in milliseconds) 0 = forever * Optional callback for when scanning stops. */ - pScan->start(scanTime); + pScan->start(scanTimeMs); printf("Scanning for peripherals\n"); @@ -137,7 +137,7 @@ extern "C" void app_main(void) { } doConnect = false; - NimBLEDevice::getScan()->start(scanTime); + NimBLEDevice::getScan()->start(scanTimeMs); } vTaskDelay(pdMS_TO_TICKS(10)); } diff --git a/examples/Bluetooth_5/NimBLE_extended_scan/main/main.cpp b/examples/Bluetooth_5/NimBLE_extended_scan/main/main.cpp index 349afb4..61b0b0c 100644 --- a/examples/Bluetooth_5/NimBLE_extended_scan/main/main.cpp +++ b/examples/Bluetooth_5/NimBLE_extended_scan/main/main.cpp @@ -9,8 +9,8 @@ #include -static uint32_t scanTime = 10 * 1000; // In milliseconds, 0 = scan forever -static NimBLEScan::Phy scanPhy = NimBLEScan::Phy::SCAN_ALL; +static uint32_t scanTimeMs = 10 * 1000; // In milliseconds, 0 = scan forever +static NimBLEScan::Phy scanPhy = NimBLEScan::Phy::SCAN_ALL; /** Define a class to handle the callbacks when advertisements are received */ class ScanCallbacks : public NimBLEScanCallbacks { @@ -43,7 +43,7 @@ class ScanCallbacks : public NimBLEScanCallbacks { NimBLEScan* pScan = NimBLEDevice::getScan(); pScan->setPhy(scanPhy); - pScan->start(scanTime); + pScan->start(scanTimeMs); } } scanCallbacks; @@ -63,7 +63,7 @@ extern "C" void app_main(void) { /** Set the initial PHY's to scan on, default is SCAN_ALL */ pScan->setPhy(scanPhy); - /** Start scanning for scanTime */ - pScan->start(scanTime); + /** Start scanning for scanTimeMs */ + pScan->start(scanTimeMs); printf("Scanning for peripherals\n"); } diff --git a/examples/NimBLE_Client/main/main.cpp b/examples/NimBLE_Client/main/main.cpp index 0385939..ff9acbf 100644 --- a/examples/NimBLE_Client/main/main.cpp +++ b/examples/NimBLE_Client/main/main.cpp @@ -10,8 +10,8 @@ #include 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 */ @@ -20,7 +20,7 @@ class ClientCallbacks : public NimBLEClientCallbacks { void onDisconnect(NimBLEClient* pClient, int reason) override { 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 *********************/ @@ -48,10 +48,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 { printf("Advertised Device found: %s\n", advertisedDevice->toString().c_str()); if (advertisedDevice->isAdvertisingService(NimBLEUUID("DEAD"))) { @@ -68,9 +68,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 { 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) { @@ -121,7 +121,7 @@ bool connectToServer() { 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 @@ -241,8 +241,7 @@ bool connectToServer() { return true; } -extern "C" -void app_main(void) { +extern "C" void app_main(void) { printf("Starting NimBLE Client\n"); /** Initialize NimBLE and set the device name */ NimBLEDevice::init("NimBLE-Client"); @@ -270,7 +269,7 @@ void app_main(void) { 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); @@ -283,7 +282,7 @@ void app_main(void) { pScan->setActiveScan(true); /** Start scanning for advertisers */ - pScan->start(scanTime); + pScan->start(scanTimeMs); printf("Scanning for peripherals\n"); /** Loop here until we find a device we want to connect to */ @@ -299,7 +298,7 @@ void app_main(void) { printf("Failed to connect, starting scan\n"); } - NimBLEDevice::getScan()->start(scanTime, false, true); + NimBLEDevice::getScan()->start(scanTimeMs, false, true); } } } diff --git a/library.json b/library.json index 296bdb2..ac12041 100644 --- a/library.json +++ b/library.json @@ -5,7 +5,6 @@ "keywords": [ "BLE", "espidf", - "arduino", "espressif", "esp32", "nimble"