- C++ 95.5%
- C 4.2%
- CMake 0.3%
6d5a9be96f
The constructor calls std::reverse_copy on its input, expecting bytes in MSB-first order (Bluedroid's esp_bd_addr_t layout). The previous docstring said "compatibility with bluedroid esp library using native ESP representation," which is correct but ambiguous if the reader doesn't already know the conventions of both stacks. Callers reaching for this constructor with LSB-first bytes (e.g. as they'd come out of NimBLE's own ble_addr_t.val) silently end up with a reversed address — the radio uses val[] directly for HCI commands, so GAP connects target a fictional peer and time out as BLE_HS_ETIMEOUT with no diagnostic. Documentation-only change; behaviour is unchanged. Points readers to NimBLEAddress(ble_addr_t) for LSB-first wire bytes and to NimBLEAddress(const uint64_t&, uint8_t) for hex literals. Refs #423 |
||
|---|---|---|
| .github/workflows | ||
| docs | ||
| examples | ||
| src | ||
| .clang-format | ||
| .gitignore | ||
| CHANGELOG.md | ||
| CMakeLists.txt | ||
| idf_component.yml | ||
| Kconfig | ||
| library.json | ||
| LICENSE | ||
| NOTICE | ||
| README.md | ||
Important
Version 2 is now released! Check out the 1.x to 2.x Migration Guide and Release Notes
esp-nimble-cpp
NimBLE CPP library for use with ESP32 that attempts to maintain compatibility with the nkolban cpp_utils BLE API.
The library is threadsafe, characteristics can be set from any thread.
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 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
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.
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.
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 to ensure the continued updates and maintenance.
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.