236bd8d139
* General code cleanup. * Added new method, `NimBLEAdvertising::setPreferredParams` that takes the min and max preferred connection parameters as an alternative for `setMinPreferred` and `setMaxPreferred`. * Added new method, `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` payload is now stored in `std::vector<uint8_t>` instead of `std::string`. * `NimBLEAdvertisementData::getPayload` now returns `std::vector<uint8_t>` instead of `std::string`. * `NimBLEAdvertisementData::addData` now takes either a `std::vector<uint8_t>` or `uint8_t* + length` instead of `std::string` or `char + length`. * `NimBLEAdvertisementData::setName` now takes an optional `bool` parameter to indicate if the name is complete or incomplete, default = complete. * `NimBLEAdvertising::start` No longer takes a callback pointer parameter, instead the new method `NimBLEAdvertising::setAdvertisingCompleteCallback` should be used. * `NimBLEAdvertising::setAdvertisementType` has been renamed to `NimBLEAdvertising::setConnectableMode` to better reflect it's function. * Added new method, `NimBLEAdvertising::setDiscoverableMode` to allow applications to control the discoverability of the advertiser. * Advertising the name and TX power of the device will no longer happen by default and should be set manually by the application. * Added overload for `NimBLEAdvertising::setManufacturerData` that takes a `const uint8_t*` and , size_t` paramter. * Added overload for `NimBLEAdvertising::setServiceData` that takes `const NimBLEUUID& uuid`, ` const uint8_t* data`, ` size_t length` as parameters. * Added overload for `NimBLEAdvertising::setServiceData` that takes `const NimBLEUUID& uuid`, `const std::vector<uint8_t>&` as parameters. * All `NimBLEAdvertisementData` functions that change data values now return `bool`, true = success. * All `NimBLEAdvertising` functions that change data values now return `bool`, true = success. * `NimBLEAdvertising::setMinPreferred` and `NimBLEAdvertising::setMaxPreferred` have been removed, use `NimBLEAdvertising::setPreferredParams` instead. * All advertising data is now stored in instances of `NimBLEAdvertisingData` and vectors removed from `NimBLEAdvertising`. * `NimBLEAdvertising::setAdvertisementData` and `NimBLEAdvertising::setScanResponseData` now return `bool`, true = success. * Added new method, `NimBLEAdvertisementData::removeData`, which takes a parameter `uint8_t type`, the data type to remove. * Added new method, `NimBLEAdvertisementData::toString`, which will print the data in hex. * Added new method, `NimBLEAdvertising::getAdvertisementData`, which returns a reference to the currently set advertisement data. * Added new method, `NimBLEAdvertising::getScanData`, which returns a reference to the currently set scan response data. * Added overloads for `NimBLEAdvertising::removeServiceUUID` and `NimBLEAdvertisementData::removeServiceUUID` to accept a `const char*` |
||
|---|---|---|
| .github/workflows | ||
| docs | ||
| examples | ||
| src | ||
| .clang-format | ||
| .gitignore | ||
| CHANGELOG.md | ||
| CMakeLists.txt | ||
| CMakeLists.txt_idf3 | ||
| component.mk | ||
| idf_component.yml | ||
| Kconfig | ||
| LICENSE | ||
| package.json | ||
| README.md | ||
Need help? Have questions or suggestions? Join the 
esp-nimble-cpp
NimBLE CPP library for use with ESP32 that attempts to maintain compatibility with the nkolban cpp_uitls BLE API.
An Arduino version of this library, including NimBLE, can be found here.
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.
Testing shows a nearly 50% reduction in flash use and approx. 100kB less ram consumed vs the original!
Your results may vary
What is NimBLE?
NimBLE is a completely open source Bluetooth Low Energy stack produced by Apache.
It is more suited to resource constrained devices than bluedroid and has now been ported to the ESP32 by Espressif.
Installation
ESP-IDF v4.0+
Download as .zip and extract or clone into the components folder in your esp-idf project.
Run menuconfig, go to Component config->Bluetooth enable Bluetooth and in Bluetooth host NimBLE.
Configure settings in NimBLE Options.
#include "NimBLEDevice.h" in main.cpp.
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.
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.
If you have not used the original Bluedroid library please refer to the New user guide.
If you are familiar with the original library, see: The migration guide for details about breaking changes and migration.
Also see Improvements_and_updates for information about non-breaking changes.
Full API documentation and class list can be found here.
Using with Arduino as an IDF component and CMake
When using this library along with Arduino and compiling with CMake you must add add_compile_definitions(ARDUINO_ARCH_ESP32=1)
in your project/CMakeLists.txt after the line include($ENV{IDF_PATH}/tools/cmake/project.cmake) to prevent Arduino from releasing BLE memory.
Acknowledgments
- nkolban and chegewara for the original esp32 BLE library this project was derived from.
- beegee-tokyo for contributing your time to test/debug and contributing the beacon examples.
- Jeroen88 for the amazing help debugging and improving the client code.