2020-07-09 03:27:26 +02:00
# Overview
This is a C++ BLE library for the ESP32 that uses the NimBLE host stack instead of bluedroid.
2021-01-20 23:20:11 +01:00
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.
2020-07-09 03:27:26 +02:00
**Testing shows a nearly 50% reduction in flash use and approx. 100kB less ram consumed vs the original!**
2021-01-20 23:20:11 +01:00
*Your results may vary*
< br / >
2020-07-09 03:27:26 +02:00
2021-01-20 23:20:11 +01:00
# What is NimBLE?
2020-07-09 03:27:26 +02:00
NimBLE is a completely open source Bluetooth Low Energy stack produced by [Apache ](https://github.com/apache/mynewt-nimble ).
It is more suited to resource constrained devices than bluedroid and has now been ported to the ESP32 by Espressif.
< br / >
# Arduino Installation
2021-01-20 23:20:11 +01:00
**Arduino Library manager:** Go to `sketch` -> `Include Library` -> `Manage Libraries` and search for NimBLE and install.
**Alternatively:** Download as .zip and extract to Arduino/libraries folder, or in Arduino IDE from Sketch menu -> Include library -> Add .Zip library.
2020-07-09 03:27:26 +02:00
2021-01-20 23:20:11 +01:00
`#include "NimBLEDevice.h"` at the beginning of your sketch.
2020-07-09 03:27:26 +02:00
2021-01-20 23:20:11 +01:00
Call `NimBLEDevice::init` in `setup` .
Tested and working with esp32-arduino in Arduino IDE and platform IO.
2020-07-09 03:27:26 +02:00
< br / >
# 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.
2021-01-20 23:20:11 +01:00
Call `NimBLEDevice::init` in `app_main` .
2020-07-09 03:27:26 +02:00
< br / >
### v3.2 & v3.3
2021-01-20 23:20:11 +01:00
The NimBLE component does not come with these versions of IDF (now included in 3.3.2 and above).
2020-07-09 03:27:26 +02:00
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.
2021-01-20 23:20:11 +01:00
Call `NimBLEDevice::init` in `app_main` .
2020-07-09 03:27:26 +02:00
< br / >
# Using
This library is intended to be compatible with the original ESP32 BLE functions and types with minor changes.
2020-08-22 17:15:53 +02:00
If you have not used the original Bluedroid library please refer to the [New user guide ](New_user_guide.md ).
If you are familiar with the original library, see: [The migration guide ](Migration_guide.md ) for details.
2020-07-09 03:27:26 +02:00
2021-01-17 18:19:58 +01:00
Also see [Improvements and updates ](Improvements_and_updates.md ) for information about non-breaking changes.
2021-01-20 23:20:11 +01:00
For more advanced usage see [Usage tips ](Usage_tips.md ) for more performance and optimization.
< br / >
2020-07-09 03:27:26 +02:00
2021-01-16 05:51:49 +01:00
### Arduino specific
2020-08-08 15:29:45 +02:00
See the Refactored_original_examples in the examples folder for highlights of the differences with the original library.
2020-07-09 03:27:26 +02:00
2020-08-08 15:29:45 +02:00
More advanced examples highlighting many available features are in examples/NimBLE_Server, NimBLE_Client.
2020-07-09 03:27:26 +02:00
2020-08-08 15:29:45 +02:00
Beacon examples provided by [beegee-tokyo ](https://github.com/beegee-tokyo ) are in examples/BLE_Beacon_Scanner, BLE_EddystoneTLM_Beacon, BLE_EddystoneURL_Beacon.
2020-07-09 03:27:26 +02:00
2021-01-16 05:51:49 +01:00
Change the settings in the nimconfig.h file to customize NimBLE to your project, such as increasing max connections (default is 3).
2021-01-20 23:20:11 +01:00
< br / >
2020-08-08 15:29:45 +02:00
2021-01-20 23:20:11 +01:00
### Arduino command line and platformio
As an alternative to changing the configuration in nimconfig.h, Arduino command line and platformio.ini options are available.
2021-01-17 18:19:58 +01:00
See the command line configuration options available in [Command line config ](Command_line_config.md ).
2020-07-09 03:27:26 +02:00
< br / >
2021-01-20 23:20:11 +01:00
# 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 )
< br / >
2020-07-09 03:27:26 +02:00
# 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 / >