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

Update documentation.

Browse source
This commit is contained in:
h2zero 2020-06-22 20:27:45 -06:00
parent f5541d18de
commit aecf8e268b
2 changed files with 32 additions and 20 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
API_DIFFERENCES.md
View file

@ -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. 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) > NimBLEClient::getServices(bool refresh = false)
> NimBLERemoteService::getCharacteristics(bool refresh = false) > NimBLERemoteService::getCharacteristics(bool refresh = false)
> NimBLERemoteCharacteristic::getDecriptors(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 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 If false(default) it will return the respective vector empty or otherwise with the currently stored attributes.
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. 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. to replace the the former functionality.
@ -145,12 +144,11 @@ to replace the the former functionality.
>getCharacteristic(NimBLEUUID) >getCharacteristic(NimBLEUUID)
>getDescriptor(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. 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: #### Client Security:
The client will automatically initiate security when the peripheral responds that it's required. 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. The default configuration will use "just-works" pairing with no bonding, if you wish to enable bonding see below.

34
README.md
View file

@ -1,5 +1,17 @@
# *** UPDATE *** # *** UPDATES ***
**Breaking change:** Client and scan now use `std::vector` instead of `std::map` for storing the remote attribute database. **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()` 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. 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. 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 # esp-nimble-cpp
NimBLE CPP library for use with ESP32 that attempts to maintain compatibility with the @nkolban cpp_uitls API. 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: # 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. * @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. * @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: # Todo:
1. Code cleanup. 1. Create documentation.
2. Create documentation. 2. Add BLE Mesh code.
3. Expose more NimBLE features. 3. Expose more NimBLE features.
4. Add BLE Mesh code.