ScStw/esp-nimble-cpp
2
0
Fork 0
mirror of https://github.com/h2zero/esp-nimble-cpp.git synced 2024-11-22 13:10:55 +01:00
Code Issues Projects Releases Packages Wiki Activity
esp-nimble-cpp/docs/index.md
h2zero f672d04a90 Update Documentation.
2020-08-22 09:15:53 -06:00

3.8 KiB
Raw Blame History

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++ API while adding new features
and making improvements in performance, resource use and stability.

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.

Arduino Installation

Download as .zip and extract to Arduino/libraries folder, or in Arduino IDE from Sketch menu -> Include library -> Add .Zip library.

#include "NimBLEDevice.h" at the beginning of your sketch.

Tested and working with esp32-arduino Arduino IDE and platform IO.

ESP-IDF Installation

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.

v3.2 & v3.3

The NimBLE component does not come with these versions of IDF.
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.

Also see Improvements_and_updates for information about non-breaking changes.

Arduino specific:

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.

Beacon examples provided by beegee-tokyo are in examples/BLE_Beacon_Scanner, BLE_EddystoneTLM_Beacon, BLE_EddystoneURL_Beacon.

Change the settings in the nimconfig.h file to customize NimBLE to your project, such as increasing max connections (default == 3).

Note To increase max connections in Arduino it is also required to change the controller max connections defined in sdkconfig.h.

This is located in your Arduino/hardware/espressif/esp32/tools/sdk/include/config folder.

The values in sdkconfig.h you will need to change are:

#define CONFIG_BTDM_CONTROLLER_BLE_MAX_CONN 3  
#define CONFIG_BTDM_CONTROLLER_BLE_MAX_CONN_EFF 3

In nimconfig.h the value is:

#define CONFIG_BT_NIMBLE_MAX_CONNECTIONS 3

Espressif has stated the hard maximum connections is 9.

Acknowledgments