diff --git a/CHANGELOG.md b/CHANGELOG.md index 128d3c9..e763a3c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ All notable changes to this project will be documented in this file. -## [Unreleased] +## [1.1.0] - 2021-01-20 ### Added - `NimBLEDevice::setOwnAddrType` added to enable the use of random and random-resolvable addresses, by asukiaaa diff --git a/README.md b/README.md index d88c933..db3b1ea 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ [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/) + +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)
# esp-nimble-cpp @@ -17,7 +19,7 @@ to provide improved capabilites and stability over the original. *Your results may vary*
-### 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). It is more suited to resource constrained devices than bluedroid and has now been ported to the ESP32 by Espressif.
@@ -34,7 +36,7 @@ Call `NimBLEDevice::init("");` in `app_main`.
### 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). Download or clone that repo into your project/components folder and run menuconfig. Configure settings in `main menu -> NimBLE Options`. diff --git a/docs/Doxyfile b/docs/Doxyfile index c328bb5..71d4482 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -38,7 +38,7 @@ PROJECT_NAME = "esp-nimble-cpp / NimBLE-Arduino" # could be handy for archiving the generated documentation or if some version # 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 # for a project that appears at the top of each page and should give viewer a diff --git a/docs/index.md b/docs/index.md index 4bfbd24..bcf892b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,24 +1,28 @@ # 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. +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. **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* +
-### 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). 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. +**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.
# 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. Configure settings in `NimBLE Options`. `#include "NimBLEDevice.h"` in main.cpp. -Call `NimBLEDevice::init("");` in `app_main`. +Call `NimBLEDevice::init` in `app_main`.
### 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). 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`. +Call `NimBLEDevice::init` in `app_main`.
# 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. -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. +
### Arduino specific 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. Change the settings in the nimconfig.h file to customize NimBLE to your project, such as increasing max connections (default is 3). -
+
-### 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).
+# 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) +
+ # 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. diff --git a/src/NimBLEClient.cpp b/src/NimBLEClient.cpp index 072f663..ddeb1de 100644 --- a/src/NimBLEClient.cpp +++ b/src/NimBLEClient.cpp @@ -378,12 +378,12 @@ int NimBLEClient::disconnect(uint8_t reason) { /** * @brief Set the connection paramaters to use when connecting to a server. - * @param [in] minInterval minimum connection interval in 0.625ms units. - * @param [in] maxInterval maximum connection interval in 0.625ms units. - * @param [in] latency number of packets allowed to skip (extends max interval) - * @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] scanWindow the scan window to use when attempting to connect in 0.625ms units. + * @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. + * @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. */ void NimBLEClient::setConnectionParams(uint16_t minInterval, uint16_t maxInterval, uint16_t latency, uint16_t timeout, @@ -410,10 +410,10 @@ void NimBLEClient::setConnectionParams(uint16_t minInterval, uint16_t maxInterva /** * @brief Update the connection parameters: * * Can only be used after a connection has been established. - * @param [in] minInterval minimum connection interval in 0.625ms units. - * @param [in] maxInterval maximum connection interval in 0.625ms units. - * @param [in] latency number of packets allowed to skip (extends max interval) - * @param [in] timeout the timeout time in 10ms units before disconnecting + * @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 NimBLEClient::updateConnParams(uint16_t minInterval, uint16_t maxInterval, uint16_t latency, uint16_t timeout) diff --git a/src/NimBLEHIDDevice.h b/src/NimBLEHIDDevice.h index 3e7a6f7..6ed7c2b 100644 --- a/src/NimBLEHIDDevice.h +++ b/src/NimBLEHIDDevice.h @@ -36,6 +36,10 @@ #define HID_DIGITAL_PEN 0x03C7 #define HID_BARCODE 0x03C8 + +/** + * @brief A model of a %BLE Human Interface Device. + */ class NimBLEHIDDevice { public: NimBLEHIDDevice(NimBLEServer*); diff --git a/src/NimBLEServer.cpp b/src/NimBLEServer.cpp index 655511a..fd5d826 100644 --- a/src/NimBLEServer.cpp +++ b/src/NimBLEServer.cpp @@ -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, uint16_t minInterval, uint16_t maxInterval,