Tasmota/lib/libesp32_div/NimBLE-Arduino/README.md

92 lines
4.6 KiB
Markdown
Raw Normal View History

2020-09-15 09:45:24 +01:00
[Latest release ![Release Version](https://img.shields.io/github/release/h2zero/NimBLE-Arduino.svg?style=plastic)
![Release Date](https://img.shields.io/github/release-date/h2zero/NimBLE-Arduino.svg?style=plastic)](https://github.com/h2zero/NimBLE-Arduino/releases/latest/)
2021-01-21 16:41:41 +00:00
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)
2020-09-15 09:45:24 +01:00
<br/>
2020-04-21 09:11:30 +01:00
# NimBLE-Arduino
2020-09-15 09:45:24 +01:00
A fork of the NimBLE stack restructured for compilation in the Ardruino IDE with a CPP library for use with ESP32.
**Note for IDF users: This repo will not compile correctly in ESP-IDF. An ESP-IDF component version of this library can be [found here.](https://github.com/h2zero/esp-nimble-cpp)**
2020-04-21 09:11:30 +01:00
2020-07-06 19:09:32 +01:00
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
2020-09-15 09:45:24 +01:00
to provide improved capabilites and stability over the original.
<br/>
2020-04-21 09:11:30 +01:00
2020-09-15 09:45:24 +01:00
## Resource use improvement
2020-04-21 09:11:30 +01:00
2020-07-06 19:09:32 +01:00
### (Original) BLE_client example comparison (Debug):
#### Arduino BLE Library
Sketch uses **1216377** bytes (58%) of program storage space.
Memory after connection: Free Heap: **171548**
2020-04-21 09:11:30 +01:00
#### NimBLE-Arduino library
2020-07-06 19:09:32 +01:00
Sketch uses **617256** bytes (29%) of program storage space.
Memory after connection: Free Heap: **270336**
***
### (Original) BLE_notify example comparison (Debug):
#### Arduino BLE Library
Sketch uses **1208409** bytes (57%) of program storage space.
Memory after connection: Free Heap: **173300**
#### NimBLE-Arduino library
Sketch uses **603432** bytes (28%) of program storage space.
Memory after connection: Free Heap: **269792**
2020-09-15 09:45:24 +01:00
**As shown: there is nearly a 50% reduction in flash use and approx. 100kB less ram consumed!**
<br/>
# Installation
**Arduino Library manager:** Go to `sketch` -> `Include Library` -> `Manage Libraries` and search for NimBLE and install.
2020-04-21 09:11:30 +01:00
2020-09-15 09:45:24 +01:00
**Alternatively:** Download as .zip and extract to Arduino/libraries folder, or in Arduino IDE from Sketch menu -> Include library -> Add .Zip library.
2020-04-21 09:11:30 +01:00
`#include "NimBLEDevice.h"` at the beginning of your sketch.
2020-09-15 09:45:24 +01:00
Tested and working with esp32-arduino in Arduino IDE and platform IO.
<br/>
# Using
This library is intended to be compatible with the original ESP32 BLE functions and types with minor changes.
2020-04-21 09:11:30 +01:00
2020-09-15 09:45:24 +01:00
If you have not used the original Bluedroid library please refer to the [New user guide](docs/New_user_guide.md).
2020-04-21 09:11:30 +01:00
2020-09-15 09:45:24 +01:00
If you are familiar with the original library, see: [The migration guide](docs/Migration_guide.md) for details about breaking changes and migration.
2020-04-21 09:11:30 +01:00
2020-09-15 09:45:24 +01:00
Also see [Improvements_and_updates](docs/Improvements_and_updates.md) for information about non-breaking changes.
[Full API documentation and class list can be found here.](https://h2zero.github.io/esp-nimble-cpp/)
2020-04-21 09:11:30 +01:00
2021-01-21 16:41:41 +00:00
For added performance and optimizations see [Usage tips](docs/Usage_tips.md).
2020-04-21 09:11:30 +01:00
Check 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.
2020-09-15 09:45:24 +01:00
Change the settings in the `src/nimconfig.h` file to customize NimBLE to your project,
such as increasing max connections, default is 3, absolute maximum connections is 9.
<br/>
2020-04-21 09:11:30 +01:00
2020-09-15 09:45:24 +01:00
# Development Status
This Library is tracking the esp-nimble repo, nimble-1.2.0-idf master branch, currently [@f4ae049.](https://github.com/espressif/esp-nimble)
2020-04-21 09:11:30 +01:00
Also tracking the NimBLE related changes in ESP-IDF, master branch, currently [@3caa969.](https://github.com/espressif/esp-idf/tree/master/components/bt/host/nimble)
2020-09-15 09:45:24 +01:00
<br/>
2020-07-06 19:09:32 +01:00
2020-09-15 09:45:24 +01: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/>
2020-04-21 09:11:30 +01:00
2020-09-15 09:45:24 +01:00
# Todo
- Improve host reset handler
- Implement random address handling
- Implement bond management
- Add Bluetooth Mesh
<br/>