ScStw/esp-nimble-cpp
2
0
Fork 0
mirror of https://github.com/h2zero/esp-nimble-cpp.git synced 2024-11-22 05:00:55 +01:00
Code Issues Projects Releases Packages Wiki Activity

Release 1.1.0

Browse source
This commit is contained in:
h2zero 2021-01-20 15:20:11 -07:00
parent 310c5f7c84
commit 4e24a06645
7 changed files with 51 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
CHANGELOG.md
View file

@ -2,7 +2,7 @@
All notable changes to this project will be documented in this file. All notable changes to this project will be documented in this file.
## [Unreleased] ## [1.1.0] - 2021-01-20
### Added ### Added
- `NimBLEDevice::setOwnAddrType` added to enable the use of random and random-resolvable addresses, by asukiaaa - `NimBLEDevice::setOwnAddrType` added to enable the use of random and random-resolvable addresses, by asukiaaa

6
README.md
View file

@ -1,5 +1,7 @@
[Latest release ![Release Version](https://img.shields.io/github/release/h2zero/esp-nimble-cpp.svg?style=plastic) [Latest release ![Release Version](https://img.shields.io/github/release/h2zero/esp-nimble-cpp.svg?style=plastic)
![Release Date](https://img.shields.io/github/release-date/h2zero/esp-nimble-cpp.svg?style=plastic)](https://github.com/h2zero/esp-nimble-cpp/releases/latest/) ![Release Date](https://img.shields.io/github/release-date/h2zero/esp-nimble-cpp.svg?style=plastic)](https://github.com/h2zero/esp-nimble-cpp/releases/latest/)
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)
<br/> <br/>
# esp-nimble-cpp # esp-nimble-cpp
@ -17,7 +19,7 @@ to provide improved capabilites and stability over the original.
*Your results may vary* *Your results may vary*
<br/> <br/>
### What is NimBLE? # What is NimBLE?
NimBLE is a completely open source Bluetooth Low Energy stack produced by [Apache](https://github.com/apache/mynewt-nimble). 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. It is more suited to resource constrained devices than bluedroid and has now been ported to the ESP32 by Espressif.
<br/> <br/>
@ -34,7 +36,7 @@ Call `NimBLEDevice::init("");` in `app_main`.
<br/> <br/>
### ESP-IDF v3.2 & v3.3 ### ESP-IDF v3.2 & v3.3
The NimBLE component does not come with these versions of IDF. 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](https://github.com/h2zero/esp-nimble-component). 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. Download or clone that repo into your project/components folder and run menuconfig.
Configure settings in `main menu -> NimBLE Options`. Configure settings in `main menu -> NimBLE Options`.

2
docs/Doxyfile
View file

@ -38,7 +38,7 @@ PROJECT_NAME = "esp-nimble-cpp / NimBLE-Arduino"
# could be handy for archiving the generated documentation or if some version # could be handy for archiving the generated documentation or if some version
# control system is used. # control system is used.
PROJECT_NUMBER = 1.0.2 PROJECT_NUMBER = 1.1.0
# Using the PROJECT_BRIEF tag one can provide an optional one line description # Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a # for a project that appears at the top of each page and should give viewer a

38
docs/index.md
View file

@ -1,24 +1,28 @@
# Overview # Overview
This is a C++ BLE library for the ESP32 that uses the NimBLE host stack instead of bluedroid. 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 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. 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!** **Testing shows a nearly 50% reduction in flash use and approx. 100kB less ram consumed vs the original!**
*Your results may vary* *Your results may vary*
<br/> <br/>
### What is NimBLE? # What is NimBLE?
NimBLE is a completely open source Bluetooth Low Energy stack produced by [Apache](https://github.com/apache/mynewt-nimble). 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. It is more suited to resource constrained devices than bluedroid and has now been ported to the ESP32 by Espressif.
<br/> <br/>
# Arduino Installation # Arduino Installation
Download as .zip and extract to Arduino/libraries folder, or in Arduino IDE from Sketch menu -> Include library -> Add .Zip library. **Arduino Library manager:** Go to `sketch` -> `Include Library` -> `Manage Libraries` and search for NimBLE and install.
`#include "NimBLEDevice.h"` at the beginning of your sketch. **Alternatively:** Download as .zip and extract to Arduino/libraries folder, or in Arduino IDE from Sketch menu -> Include library -> Add .Zip library.
Tested and working with esp32-arduino Arduino IDE and platform IO. `#include "NimBLEDevice.h"` at the beginning of your sketch.
Call `NimBLEDevice::init` in `setup`.
Tested and working with esp32-arduino in Arduino IDE and platform IO.
<br/> <br/>
# ESP-IDF Installation # ESP-IDF Installation
@ -28,17 +32,17 @@ Download as .zip and extract or clone into the components folder in your esp-idf
Run menuconfig, go to `Component config->Bluetooth` enable Bluetooth and in `Bluetooth host` NimBLE. Run menuconfig, go to `Component config->Bluetooth` enable Bluetooth and in `Bluetooth host` NimBLE.
Configure settings in `NimBLE Options`. Configure settings in `NimBLE Options`.
`#include "NimBLEDevice.h"` in main.cpp. `#include "NimBLEDevice.h"` in main.cpp.
Call `NimBLEDevice::init("");` in `app_main`. Call `NimBLEDevice::init` in `app_main`.
<br/> <br/>
### v3.2 & v3.3 ### v3.2 & v3.3
The NimBLE component does not come with these versions of IDF. 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](https://github.com/h2zero/esp-nimble-component). 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. Download or clone that repo into your project/components folder and run menuconfig.
Configure settings in `main menu -> NimBLE Options`. Configure settings in `main menu -> NimBLE Options`.
`#include "NimBLEDevice.h"` in main.cpp. `#include "NimBLEDevice.h"` in main.cpp.
Call `NimBLEDevice::init("");` in `app_main`. Call `NimBLEDevice::init` in `app_main`.
<br/> <br/>
# Using # Using
@ -50,7 +54,8 @@ If you are familiar with the original library, see: [The migration guide](Migrat
Also see [Improvements and updates](Improvements_and_updates.md) for information about non-breaking changes. Also see [Improvements and updates](Improvements_and_updates.md) for information about non-breaking changes.
For more advanced usage see [Usage tips](Usage_tips.md) for more performance and optimization. For more advanced usage see [Usage tips](Usage_tips.md) for more performance and optimization.
<br/>
### Arduino specific ### Arduino specific
See the Refactored_original_examples in the examples folder for highlights of the differences with the original library. See the Refactored_original_examples in the examples folder for highlights of the differences with the original library.
@ -60,12 +65,17 @@ More advanced examples highlighting many available features are in examples/NimB
Beacon examples provided by [beegee-tokyo](https://github.com/beegee-tokyo) are in examples/BLE_Beacon_Scanner, BLE_EddystoneTLM_Beacon, BLE_EddystoneURL_Beacon. Beacon examples provided by [beegee-tokyo](https://github.com/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 is 3). Change the settings in the nimconfig.h file to customize NimBLE to your project, such as increasing max connections (default is 3).
<br/> <br/>
### Command line and platformio ### Arduino command line and platformio
As an alternative to changing the configuration in nimconfig.h, Arduino command line and platformio.ini options are available.
See the command line configuration options available in [Command line config](Command_line_config.md). See the command line configuration options available in [Command line config](Command_line_config.md).
<br/> <br/>
# 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/>
# Acknowledgments # 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. * [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.

20
src/NimBLEClient.cpp
View file

@ -378,12 +378,12 @@ int NimBLEClient::disconnect(uint8_t reason) {
/** /**
* @brief Set the connection paramaters to use when connecting to a server. * @brief Set the connection paramaters to use when connecting to a server.
* @param [in] minInterval minimum connection interval in 0.625ms units. * @param [in] minInterval The minimum connection interval in 1.25ms units.
* @param [in] maxInterval maximum connection interval in 0.625ms units. * @param [in] maxInterval The maximum connection interval in 1.25ms units.
* @param [in] latency number of packets allowed to skip (extends max interval) * @param [in] latency The number of packets allowed to skip (extends max interval).
* @param [in] timeout the timeout time in 10ms units before disconnecting * @param [in] timeout The timeout time in 10ms units before disconnecting.
* @param [in] scanInterval the scan interval to use when attempting to connect in 0.625ms units. * @param [in] scanInterval The scan interval to use when attempting to connect in 0.625ms units.
* @param [in] scanWindow the scan window to use when attempting to connect in 0.625ms units. * @param [in] scanWindow The scan window to use when attempting to connect in 0.625ms units.
*/ */
void NimBLEClient::setConnectionParams(uint16_t minInterval, uint16_t maxInterval, void NimBLEClient::setConnectionParams(uint16_t minInterval, uint16_t maxInterval,
uint16_t latency, uint16_t timeout, uint16_t latency, uint16_t timeout,
@ -410,10 +410,10 @@ void NimBLEClient::setConnectionParams(uint16_t minInterval, uint16_t maxInterva
/** /**
* @brief Update the connection parameters: * @brief Update the connection parameters:
* * Can only be used after a connection has been established. * * Can only be used after a connection has been established.
* @param [in] minInterval minimum connection interval in 0.625ms units. * @param [in] minInterval The minimum connection interval in 1.25ms units.
* @param [in] maxInterval maximum connection interval in 0.625ms units. * @param [in] maxInterval The maximum connection interval in 1.25ms units.
* @param [in] latency number of packets allowed to skip (extends max interval) * @param [in] latency The number of packets allowed to skip (extends max interval).
* @param [in] timeout the timeout time in 10ms units before disconnecting * @param [in] timeout The timeout time in 10ms units before disconnecting.
*/ */
void NimBLEClient::updateConnParams(uint16_t minInterval, uint16_t maxInterval, void NimBLEClient::updateConnParams(uint16_t minInterval, uint16_t maxInterval,
uint16_t latency, uint16_t timeout) uint16_t latency, uint16_t timeout)

4
src/NimBLEHIDDevice.h
View file

@ -36,6 +36,10 @@
#define HID_DIGITAL_PEN 0x03C7 #define HID_DIGITAL_PEN 0x03C7
#define HID_BARCODE 0x03C8 #define HID_BARCODE 0x03C8
/**
* @brief A model of a %BLE Human Interface Device.
*/
class NimBLEHIDDevice { class NimBLEHIDDevice {
public: public:
NimBLEHIDDevice(NimBLEServer*); NimBLEHIDDevice(NimBLEServer*);

8
src/NimBLEServer.cpp
View file

@ -621,7 +621,13 @@ uint16_t NimBLEServer::getPeerMTU(uint16_t conn_id) {
/** /**
* Update connection parameters can be called only after connection has been established * @brief Request an Update the connection parameters:
* * Can only be used after a connection has been established.
* @param [in] conn_handle The connection handle of the peer to send the request to.
* @param [in] minInterval The minimum connection interval in 1.25ms units.
* @param [in] maxInterval The maximum connection interval in 1.25ms units.
* @param [in] latency The number of packets allowed to skip (extends max interval).
* @param [in] timeout The timeout time in 10ms units before disconnecting.
*/ */
void NimBLEServer::updateConnParams(uint16_t conn_handle, void NimBLEServer::updateConnParams(uint16_t conn_handle,
uint16_t minInterval, uint16_t maxInterval, uint16_t minInterval, uint16_t maxInterval,