feedc0de/esp-nimble-cpp
1
0
Fork 0
forked from h2zero/esp-nimble-cpp
Code Pull Requests Activity

Update Documentation.

Browse Source
This commit is contained in:
h2zero
2020-08-22 09:15:53 -06:00
parent d3aa435448
commit f672d04a90
5 changed files with 110 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
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
# control system is used.
PROJECT_NUMBER =
PROJECT_NUMBER = 1.0.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
@ -913,7 +913,9 @@ RECURSIVE = YES
EXCLUDE = ./README.md \
./src/FreeRTOS.h \
./src/FreeRTOS.cpp
./src/FreeRTOS.cpp \
./examples \
./CMakelists.txt
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
# directories that are symbolic links (a Unix file system feature) are excluded

15
docs/Improvements_and_updates.md
View File

@ -1,5 +1,14 @@
# Improvements and updates
Many improvements have been made to this library vs the original, this is a brief overview of the most significant changes.
Refer to the [class documentation](https://h2zero.github.io/esp-nimble-cpp/annotated.html) for futher information on class specifics.
* [Server](#server)
* [Client](#client)
* [General](#general)
<br/>
<a name="server"></a>
# Server
`NimBLECharacteristic::setValue(const T &s)`
@ -51,6 +60,7 @@ it's characteristics / descriptors will remain valid and the service can be re-a
using `NimBLEServer::addService`.
<br/>
<a name="client"></a>
# Client
`NimBLERemoteCharacteristic::readValue(time_t\*, bool)`
@ -96,8 +106,9 @@ These changes allow more control for the user to manage the resources used for t
`NimBLEClient::connect()` can now be called without an address or advertised device parameter. This will connect to the
device with the address previously set when last connected or set with `NimBLEDevice::setPeerAddress()`.
<a name="general"></a>
# General
To reduce resource use all instances of std::map have been replaced with std::vector.
To reduce resource use all instances of `std::map` have been replaced with `std::vector`.
Use of `FreeRTOS::Semaphore` has been removed as it was consuming too much ram, the related files have been left in place to accomodate application use.
@ -110,7 +121,5 @@ Security/pairing operations are now handled in the respective `NimBLEClientCallb
Configuration options have been added to add or remove debugging information, when disabled (default) significatly reduces binary size.
In ESP-IDF the options are in menuconfig: `Main menu -> ESP-NimBLE-cpp configuration`.
For Arduino the options must be commented / uncommented in nimconfig.h.
Many more internal improvements have been made as well, this is a brief overview. Refer to the class docs for futher information on class specifics.
<br/>

115
docs/Migration_guide.md
View File

@ -2,7 +2,7 @@
This guide describes the required changes to existing projects migrating from the original bluedroid API to NimBLE.
The changes listed here are only the **required changes that must be made** and a short overview of options for migrating existing applications.
**The changes listed here are only the required changes that must be made**, and a short overview of options for migrating existing applications.
For more information on the improvements and additions please refer to the [class documentation](https://h2zero.github.io/esp-nimble-cpp/annotated.html) and [Improvements and updates](Improvements_and_updates.md)
@ -11,13 +11,18 @@ For more information on the improvements and additions please refer to the [clas
* [Services](#services)
* [characteristics](#characteristics)
* [descriptors](#descriptors)
* [Security](#server-security)
* [Advertising](#advertising-api)
* [Client](#client-api)
* [Remote Services](#remote-services)
* [Remote characteristics](#remote-characteristics)
* [Security](#security-api)
* [Security](#client-security)
* [General Security](#security-api)
* [Configuration](#arduino-configuration)
<br/>
# General Information {#general-information}
<a name="general-information"></a>
## General Information
### Header Files
All classes are accessible by including `NimBLEDevice.h` in your application, no further headers need to be included.
@ -42,8 +47,8 @@ For example `BLEAddress addr(11:22:33:44:55:66, 1)` will create the address obje
As this paramameter is optional no changes to existing code are needed, it is mentioned here for information.
<br/>
## Server API {#server-api}
<a name="server-api"></a>
## Server API
Creating a `BLEServer` instance is the same as original, no changes required.
For example `BLEDevice::createServer()` will work just as it did before.
@ -51,11 +56,13 @@ For example `BLEDevice::createServer()` will work just as it did before.
**Note:** All callback methods have default implementations which allows the application to implement only the methods applicable.
<br/>
### Services {#services}
<a name="services"></a>
### Services
Creating a `BLEService` (`NimBLEService`) instance is the same as original, no changes required.
For example `BLEServer::createService(SERVICE_UUID)` will work just as it did before.
### Characteristics {#characteristics}
<a name="characteristics"></a>
### Characteristics
`BLEService::createCharacteristic` (`NimBLEService::createCharacteristic`) is used the same way as originally except the properties parameter has changed.
When creating a characteristic the properties are now set with `NIMBLE_PROPERTY::XXXX` instead of `BLECharacteristic::XXXX`.
@ -103,11 +110,32 @@ BLECharacteristic *pCharacteristic = pService->createCharacteristic(
```
<br/>
`BLECharacteristicCallbacks` (`NimBLECharacteristicCallbacks`) has a new method `NimBLECharacteristicCallbacks::onSubscribe` which called when a client subscribes to notifications/indications.
`BLECharacteristicCallbacks` (`NimBLECharacteristicCallbacks`) has a new method `NimBLECharacteristicCallbacks::onSubscribe`
which is called when a client subscribes to notifications/indications.
**Note:** All callback methods have default implementations which allows the application to implement only the methods applicable.
<br/>
### Descriptors {descriptors}
> BLECharacteristic::getData
**Has been removed from the API.**
Originally this returned a `uint8_t*` to the internal data, which is volatile.
To prevent possibly throwing exceptions this has been removed and `NimBLECharacteristic::getValue` should be used
to get a copy of the data first which can then safely be accessed via pointer.
**Example:**
```
std::string value = pCharacteristic->getValue();
uint8_t *pData = (uint8_t*)value.data();
```
Alternatively use the `getValue` template:
```
my_struct_t myStruct = pChr->getValue<my_struct_t>();
```
<br/>
<a name="descriptors"></a>
### Descriptors
The previous method `BLECharacteristic::addDescriptor()` has been removed.
Descriptors are now created using the `NimBLECharacteristic::createDescriptor` method.
@ -158,6 +186,7 @@ p2904 = (NimBLE2904*)pCharacteristic->createDescriptor("2904");
```
<br/>
<a name="server-security"></a>
### Server Security
Security is set on the characteristic or descriptor properties by applying one of the following:
> NIMBLE_PROPERTY::READ_ENC
@ -172,7 +201,18 @@ it will trigger the pairing process. By default the "just-works" pairing will be
This can be changed to use passkey authentication or numeric comparison. See [Security API](#security-api) for details.
<br/>
## Client API {#client-api}
<a name="advertising-api"></a>
## Advertising API
Advertising works the same as the original API except with the removal of:
> BLEAdvertising::setMinPreferred
> BLEAdvertising::setMaxPreferred
These methods were found to not provide useful functionality and consumed valuable advertising space (6 bytes of 31) if used unknowingly.
If you wish to advertise these parameters you can still do so manually via `NimBLEAdvertisementData::addData`.
<br/>
<a name="client-api"></a>
## Client API
Client instances are created just as before with `BLEDevice::createClient` (`NimBLEDevice::createClient`).
@ -205,7 +245,8 @@ the user may not be interested in.
to replace the the removed automatic functionality.
<br/>
### Remote Services {#remote-services}
<a name="remote-services"></a>
### Remote Services
`BLERemoteService` (`NimBLERemoteService`) Methods remain mostly unchanged with the exceptions of:
> BLERemoteService::getCharacteristicsByHandle
@ -220,7 +261,8 @@ the currently known database returned (false : default).
Also now returns a pointer to `std::vector` instead of `std::map`.
<br/>
### Remote Characteristics{#remote-characteristics}
<a name="remote-characteristics"></a>
### Remote Characteristics
`BLERemoteCharacteristic` (`NimBLERemoteCharacteristic`) There have been a few changes to the methods in this class:
> `BLERemoteCharacteristic::writeValue` (`NimBLERemoteCharacteristic::writeValue`)
@ -232,8 +274,8 @@ Now return true or false to indicate success or failure so you can choose to dis
> `BLERemoteCharacteristic::registerForNotify` (`NimBLERemoteCharacteristic::registerForNotify`)
Is now **deprecated**.
> NimBLERemoteCharacteristic::subscribe
> NimBLERemoteCharacteristic::unsubscribe
> `NimBLERemoteCharacteristic::subscribe`
> `NimBLERemoteCharacteristic::unsubscribe`
Are the new methods added to replace it.
<br/>
@ -246,13 +288,15 @@ Are the new methods added to replace it.
Are **deprecated** a template: NimBLERemoteCharacteristic::readValue<type\>(time_t\*, bool) has been added to replace them.
<br/>
> BLERemoteCharacteristic::readRawData
> `BLERemoteCharacteristic::readRawData`
Has been removed from the API as it stored an unnecessary copy of the data.
**Has been removed from the API**
Originally it stored an unnecessary copy of the data and was returning a `uint8_t` pointer to volatile internal data.
The user application should use `NimBLERemoteCharacteristic::readValue` or `NimBLERemoteCharacteristic::getValue`.
Then cast the returned std::string to the type they wish such as:
To obatain a copy of the data, then cast the returned std::string to the type required such as:
```
uint8_t *val = (uint8_t*)pChr->readValue().data();
std::string value = pChr->readValue();
uint8_t *data = (uint8_t*)value.data();
```
Alternatively use the `readValue` template:
```
@ -267,54 +311,67 @@ the currently known database returned (false : default).
Also now returns a pointer to `std::vector` instead of `std::map`.
<br/>
### Client Security {#client-security}
<a name="client-security"></a>
### 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.
<br/>
## Security API {#security-api}
<a name="security-api"></a>
## Security API
Security operations have been moved to `BLEDevice` (`NimBLEDevice`).
Also security callback methods are now incorporated in the NimBLEServerCallbacks / NimBLEClientCallbacks classes.
Also security callback methods are now incorporated in the `NimBLEServerCallbacks` / `NimBLEClientCallbacks` classes.
However backward compatibility with the original `BLESecurity` (`NimBLESecurity`) class is retained to minimize application code changes.
The callback methods are:
> bool onConfirmPIN(uint32_t pin);
> `bool onConfirmPIN(uint32_t pin)`
Receives the pin when using numeric comparison authentication, `return true;` to accept.
<br/>
> uint32_t onPassKeyRequest();
> `uint32_t onPassKeyRequest()`
For server callback; return the passkey expected from the client.
For client callback; return the passkey to send to the server.
<br/>
> void onAuthenticationComplete(ble_gap_conn_desc\* desc);
> `void onAuthenticationComplete(ble_gap_conn_desc\* desc)`
Authentication complete, success or failed information is in `desc`.
<br/>
Security settings and IO capabilities are now set by the following methods of NimBLEDevice.
> NimBLEDevice::setSecurityAuth(bool bonding, bool mitm, bool sc)
> NimBLEDevice::setSecurityAuth(uint8_t auth_req)
> `NimBLEDevice::setSecurityAuth(bool bonding, bool mitm, bool sc)`
> `NimBLEDevice::setSecurityAuth(uint8_t auth_req)`
Sets the authorization mode for this device.
<br/>
> NimBLEDevice::setSecurityIOCap(uint8_t iocap)
> `NimBLEDevice::setSecurityIOCap(uint8_t iocap)`
Sets the Input/Output capabilities of this device.
<br/>
> NimBLEDevice::setSecurityInitKey(uint8_t init_key)
> `NimBLEDevice::setSecurityInitKey(uint8_t init_key)`
If we are the initiator of the security procedure this sets the keys we will distribute.
<br/>
> NimBLEDevice::setSecurityRespKey(uint8_t resp_key)
> `NimBLEDevice::setSecurityRespKey(uint8_t resp_key)`
Sets the keys we are willing to accept from the peer during pairing.
<br/>
<a name="arduino-configuration"></a>
## Arduino Configuration
Unlike the original library pre-packaged in the esp32-arduino, this library has all the configuration
options that are normally set in menuconfig available in the *src/nimconfig.h* file.
This allows Arduino users to fully customize the build, such as increasing max connections
or loading the BLE stack into external PSRAM.
For details on the options, they are fully commented in *nimconfig.h*
<br/>

6
docs/New_user_guide.md
View File

@ -21,7 +21,8 @@ If you're not creating a server or do not want to advertise a name, simply pass
This can be called any time you wish to use BLE functions and does not need to be called from app_main(IDF) or setup(Arduino) but usually is.
<br/>
## Creating a Server {#creating-a-server}
<a name="creating-a-server"></a>
## Creating a Server
BLE servers perform 2 tasks, they advertise their existance for clients to find them and they provide services which contain information for the connecting client.
After initializing the NimBLE stack we create a server by calling `NimBLEDevice::createServer()`, this will create a server instance and return a pointer to it.
@ -136,7 +137,8 @@ Now if you scan with your phone using nRFConnect or any other BLE app you should
For more advanced features and options please see the server examples in the examples folder.
<br/>
## Creating a Client {#creating-a-client}
<a name="creating-a-client"></a>
## Creating a Client
BLE clients perform 2 tasks, they scan for advertising servers and form connections to them to read and write to their characteristics/descriptors.

6
docs/index.md
View File

@ -18,7 +18,7 @@ Download as .zip and extract to Arduino/libraries folder, or in Arduino IDE from
`#include "NimBLEDevice.h"` at the beginning of your sketch.
Tested and working with esp32-arduino v1.0.2 and 1.0.4 in Arduino IDE v1.8.12 and platform IO.
Tested and working with esp32-arduino Arduino IDE and platform IO.
<br/>
# ESP-IDF Installation
@ -44,7 +44,9 @@ Call `NimBLEDevice::init("");` in `app_main`.
# Using
This library is intended to be compatible with the original ESP32 BLE functions and types with minor changes.
See: [The migration guide](Migration_guide.md) for details.
If you have not used the original Bluedroid library please refer to the [New user guide](New_user_guide.md).
If you are familiar with the original library, see: [The migration guide](Migration_guide.md) for details.
Also see [Improvements_and_updates](Improvements_and_updates.md) for information about non-breaking changes.