From aecf8e268b68684c133a490a53a8e0135a6e835a Mon Sep 17 00:00:00 2001 From: h2zero Date: Mon, 22 Jun 2020 20:27:45 -0600 Subject: [PATCH] Update documentation. --- API_DIFFERENCES.md | 18 ++++++++---------- README.md | 34 ++++++++++++++++++++++++---------- 2 files changed, 32 insertions(+), 20 deletions(-) diff --git a/API_DIFFERENCES.md b/API_DIFFERENCES.md index 32bf4a2..91b0fd7 100644 --- a/API_DIFFERENCES.md +++ b/API_DIFFERENCES.md @@ -122,21 +122,20 @@ Has been removed from the API as it is no longer maintained in the library. The last two above changes reduce the heap usage significantly with minimal application code adjustments. -**NEW** on May 23, 2020 +**UPDATED** on June 21, 2020 > ``` > NimBLEClient::getServices(bool refresh = false) > NimBLERemoteService::getCharacteristics(bool refresh = false) > NimBLERemoteCharacteristic::getDecriptors(bool refresh = false) >``` -> These methods now take an optional (bool) parameter. +These methods now take an optional (bool) parameter. If true it will clear the respective vector and retrieve all the respective attributes from the peripheral. -If false it will retrieve the attributes only if the vector is empty, otherwise the vector is returned -with the currently stored attributes. +If false(default) it will return the respective vector empty or otherwise with the currently stored attributes. -> Removed the automatic discovery of all peripheral attributes as they consumed time and resources for data +**Removed:** the automatic discovery of all peripheral attributes as they consumed time and resources for data the user may not be interested in. -> Added `NimBLEClient::discoverAtrributes()` for the user to discover all the peripheral attributes +**Added:** `NimBLEClient::discoverAtrributes()` for the user to discover all the peripheral attributes to replace the the former functionality. @@ -145,12 +144,11 @@ to replace the the former functionality. >getCharacteristic(NimBLEUUID) >getDescriptor(NimBLEUUID) >``` ->These methods will now check the respective vectors for the attribute object and, if not found, will retrieve (only) +These methods will now check the respective vectors for the attribute object and, if not found, will retrieve (only) the specified attribute from the peripheral. -> These changes allow more control for the user to manage the resources used for the attributes. - - +These changes allow more control for the user to manage the resources used for the attributes. +*** #### Client Security: The client will automatically initiate security when the peripheral responds that it's required. The default configuration will use "just-works" pairing with no bonding, if you wish to enable bonding see below. diff --git a/README.md b/README.md index d25cfa4..f914937 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,17 @@ -# *** UPDATE *** -**Breaking change:** Client and scan now use `std::vector` instead of `std::map` for storing the remote attribute database. +# *** UPDATES *** +**Breaking changes:** +**NEW** on June 21, 2020 +> ``` +> NimBLEClient::getServices(bool refresh = false) +> NimBLERemoteService::getCharacteristics(bool refresh = false) +> NimBLERemoteCharacteristic::getDecriptors(bool refresh = false) +>``` +These methods now take an optional (bool) parameter. +If true it will clear the respective vector and retrieve all the respective attributes from the peripheral. +If false(default) it will return the respective vector empty or otherwise with the currently stored attributes. + +**NEW** on May 23, 2020 +Client and scan now use `std::vector` instead of `std::map` for storing the remote attribute database. This change will affect your application code if you use `NimBLEClient::getServices()` or `NimBLERemoteService::getCharacteristics()` in your application as they now return a pointer to `std::vector` of the respective attributes. @@ -8,14 +20,17 @@ In addition `NimBLERemoteService::getCharacteristicsByHandle()` has been removed These changes were necessary due to the amount of resources required to use `std::map`, it was not justifed by any benfit it provided. -It is expected that there will be minimal impact on most applications, if you need help adjusting your code please create an issue. +It is expected that there will be minimal impact on most applications, if you need help adjusting your code please create an issue. # esp-nimble-cpp NimBLE CPP library for use with ESP32 that attempts to maintain compatibility with the @nkolban cpp_uitls API. -Why? Because the Bluedroid library is too bulky. +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 +to provide improved capabilites and stability over the original. -Initial client code testing has resulted in code size reduction of ~115k and reduced ram consumption of ~37k. +**Testing shows a nearly 50% reduction in flash use and approx. 100kB less ram consumed vs the original!** # Installation: @@ -38,11 +53,10 @@ Check [API_DIFFERENCES](https://github.com/h2zero/esp-nimble-cpp/blob/master/API * @nkolban and @chegewara for the [original esp32 BLE library](https://github.com/nkolban/esp32-snippets) this project was derived from. * @beegee-tokyo for contributing your time to test/debug and contributing the beacon examples. - +* @Jeroen88 for the amazing help debugging and improving the client code. # Todo: -1. Code cleanup. -2. Create documentation. -3. Expose more NimBLE features. -4. Add BLE Mesh code. \ No newline at end of file +1. Create documentation. +2. Add BLE Mesh code. +3. Expose more NimBLE features. \ No newline at end of file