Skip to content

Commit a76fe21

Browse files
h2zeroh2zero
committed
Update Documentation.
1 parent 493e47e commit a76fe21

File tree

5 files changed

+318
-7
lines changed

5 files changed

+318
-7
lines changed

‎README.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -37,14 +37,16 @@ Download as .zip and extract to Arduino/libraries folder, or in Arduino IDE from
3737

3838
`#include "NimBLEDevice.h"` at the beginning of your sketch.
3939

40-
Tested and working with esp32-arduino v1.0.2 and 1.0.4 in Arduino IDE v1.8.12 and platform IO.
40+
Tested and working with esp32-arduino in Arduino IDE and platform IO.
4141
<br/>
4242

4343
# Using
4444
This library is intended to be compatible with the original ESP32 BLE functions and types with minor changes.
45-
See: [Breaking API Changes vs Original](docs/BREAKING_API_CHANGES.md) for changes that might required to adapt your exisiting projects.
45+
See: [The migration guide](docs/Migration_guide.md) for details.
4646

47-
Also see [Improvements_and_updates](docs/Improvements_and_updates.md) for information about non-breaking changes.
47+
Also see [Improvements_and_updates](docs/Improvements_and_updates.md) for information about non-breaking changes.
48+
49+
[Full API documentation and class list can be found here.](h2zero.github.io/esp-nimble-cpp)
4850

4951
Check the Refactored_original_examples in the examples folder for highlights of the differences with the original library.
5052

‎docs/BREAKING_API_CHANGES.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ NimBLE automatically creates the 0x2902 descriptor if a characteristic has a not
4444
**Note** Attempting to create a 0x2902 descriptor will trigger an assert to notify the error,
4545
allowing the creation of it would cause a fault in the NimBLE stack.
4646

47-
All other desctiptors are now created just as characteristics are by using the `NimBLECharacteristic::createDescriptor` methods (except 0x2904, see below).
47+
All other descriptors are now created just as characteristics are by using the `NimBLECharacteristic::createDescriptor` methods (except 0x2904, see below).
4848
Which are defined as:
4949
```
5050
NimBLEDescriptor* createDescriptor(const char* uuid,

‎docs/Improvements_and_updates.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -83,8 +83,14 @@ get the last updated value any time.
8383
In addition NimBLERemoteCharacteristic::readValue and NimBLERemoteCharacteristic::getValue take an optional timestamp parameter which will update it's value with
8484
the time the last value was recieved.
8585

86-
NimBLEClient::getService will now retrieve only the service specified and not the full database, this preserves resources
87-
otherwise wasted retrieving and allocating attributes the user application is not interested in.
86+
> NimBLEClient::getService
87+
> NimBLERemoteService::getCharacteristic
88+
> NimBLERemoteCharacteristic::getDescriptor
89+
90+
These methods will now check the respective vectors for the attribute object and, if not found, will retrieve (only)
91+
the specified attribute from the peripheral.
92+
93+
These changes allow more control for the user to manage the resources used for the attributes.
8894
<br/>
8995

9096
NimBLEClient::connect() can now be called without an address or advertised device parameter. This will connect to the

‎docs/Migration_guide.md‎

Lines changed: 303 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,303 @@
1+
# Migrating from Bluedroid to NimBLE
2+
3+
This guide describes the required changes to existing projects migrating from the original bluedroid API to NimBLE.
4+
5+
The changes listed here are only some of the many that have been made, this is a short overview for migrating existing applications.
6+
7+
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](docs/Improvements_and_updates.md)
8+
<br/>
9+
10+
# General Information
11+
12+
### Header Files
13+
All classes are accessible by including `NimBLEDevice.h` in your application, no further headers need to be included.
14+
15+
You may choose to include `NimBLELog.h` in your appplication if you want to use the `NIMBLE_LOGx` macros for debugging.
16+
These macros are used the same way as the `ESP_LOGx` macros.
17+
<br/>
18+
19+
### Class Names
20+
Class names remain the same as the original with the addition of a "Nim" prefix.
21+
For example `BLEDevice` is now `NimBLEDevice` and `BLEServer` is now `NimBLEServer` etc.
22+
23+
For convienience definitions have been added to allow applications to use either name for all classes
24+
this means **no class names need to be changed in existing code** and makes migrating easier.
25+
<br/>
26+
27+
### BLE Addresses
28+
`BLEAddress` (`NimBLEAddress`) When constructing an address the constructor now takes an *optional* `uint8_t type` paramameter
29+
to specify the address type. Default is (0) Public static address.
30+
31+
For example `BLEAddress addr(11:22:33:44:55:66, 1)` will create the address object with an address type of: 1 (Random).
32+
33+
As this paramameter is optional no changes to existing code are needed, it is mentioned here for information.
34+
<br/>
35+
36+
# Server API
37+
Creating a `BLEServer` instance is the same as original, no changes required.
38+
For example `BLEDevice::createServer()` will work just as it did before.
39+
40+
`BLEServerCallbacks` (`NimBLEServerCallbacks`) has new methods for handling security operations.
41+
**Note:** All callback methods have default implementations which allows the application to implement only the methods applicable.
42+
<br/>
43+
44+
### Services
45+
Creating a `BLEService` (`NimBLEService`) instance is the same as original, no changes required.
46+
For example `BLEServer::createService(SERVICE_UUID)` will work just as it did before.
47+
48+
### Characteristics
49+
`BLEService::createCharacteristic` (`NimBLEService::createCharacteristic`) is used the same way as originally except the properties parameter has changed.
50+
51+
When creating a characteristic the properties are now set with `NIMBLE_PROPERTY::XXXX` instead of `BLECharacteristic::XXXX`.
52+
53+
#### Originally
54+
> BLECharacteristic::PROPERTY_READ |
55+
> BLECharacteristic::PROPERTY_WRITE
56+
57+
#### Is Now
58+
> NIMBLE_PROPERTY::READ |
59+
> NIMBLE_PROPERTY::WRITE
60+
<br/>
61+
62+
#### The full list of properties
63+
> NIMBLE_PROPERTY::READ
64+
> NIMBLE_PROPERTY::READ_ENC
65+
> NIMBLE_PROPERTY::READ_AUTHEN
66+
> NIMBLE_PROPERTY::READ_AUTHOR
67+
> NIMBLE_PROPERTY::WRITE
68+
> NIMBLE_PROPERTY::WRITE_NR
69+
> NIMBLE_PROPERTY::WRITE_ENC
70+
> NIMBLE_PROPERTY::WRITE_AUTHEN
71+
> NIMBLE_PROPERTY::WRITE_AUTHOR
72+
> NIMBLE_PROPERTY::BROADCAST
73+
> NIMBLE_PROPERTY::NOTIFY
74+
> NIMBLE_PROPERTY::INDICATE
75+
<br/>
76+
77+
**Example:**
78+
```
79+
BLECharacteristic *pCharacteristic = pService->createCharacteristic(
80+
CHARACTERISTIC_UUID,
81+
BLECharacteristic::PROPERTY_READ |
82+
BLECharacteristic::PROPERTY_WRITE
83+
);
84+
85+
```
86+
Needs to be changed to:
87+
```
88+
BLECharacteristic *pCharacteristic = pService->createCharacteristic(
89+
CHARACTERISTIC_UUID,
90+
NIMBLE_PROPERTY::READ |
91+
NIMBLE_PROPERTY::WRITE
92+
);
93+
```
94+
<br/>
95+
96+
`BLECharacteristicCallbacks` (`NimBLECharacteristicCallbacks`) has a new method `NimBLECharacteristicCallbacks::onSubscribe` which called when a client subscribes to notifications/indications.
97+
**Note:** All callback methods have default implementations which allows the application to implement only the methods applicable.
98+
<br/>
99+
100+
### Descriptors
101+
The previous method `BLECharacteristic::addDescriptor()` has been removed.
102+
103+
Descriptors are now created using the `NimBLECharacteristic::createDescriptor` method.
104+
105+
BLE2902 or NimBLE2902 class has been removed.
106+
NimBLE automatically creates the 0x2902 descriptor if a characteristic has a notification or indication property assigned to it.
107+
108+
It was no longer useful to have a class for the 0x2902 descriptor as a new callback `NimBLECharacteristicCallbacks::onSubscribe` was added
109+
to handle callback functionality and the client subscription status is handled internally.
110+
111+
**Note:** Attempting to create a 0x2902 descriptor will trigger an assert to notify the error,
112+
allowing the creation of it would cause a fault in the NimBLE stack.
113+
114+
All other descriptors are now created just as characteristics are by using the `NimBLECharacteristic::createDescriptor` method (except 0x2904, see below).
115+
Which are defined as:
116+
```
117+
NimBLEDescriptor* createDescriptor(const char* uuid,
118+
uint32_t properties =
119+
NIMBLE_PROPERTY::READ |
120+
NIMBLE_PROPERTY::WRITE,
121+
uint16_t max_len = 100);
122+
123+
NimBLEDescriptor* createDescriptor(NimBLEUUID uuid,
124+
uint32_t properties =
125+
NIMBLE_PROPERTY::READ |
126+
NIMBLE_PROPERTY::WRITE,
127+
uint16_t max_len = 100);
128+
```
129+
##### Example
130+
```
131+
pDescriptor = pCharacteristic->createDescriptor("ABCD",
132+
NIMBLE_PROPERTY::READ |
133+
NIMBLE_PROPERTY::WRITE |
134+
NIMBLE_PROPERTY::WRITE_ENC,
135+
25);
136+
```
137+
Would create a descriptor with the UUID 0xABCD, publicly readable but only writable if paired/bonded (encrypted) and has a max value length of 25 bytes.
138+
<br/>
139+
140+
For the 0x2904, there is a special class that is created when you call `createDescriptor("2904").
141+
142+
The pointer returned is of the base class `NimBLEDescriptor` but the call will create the derived class of `NimBLE2904` so you must cast the returned pointer to
143+
`NimBLE2904` to access the specific class methods.
144+
145+
##### Example
146+
```
147+
p2904 = (NimBLE2904*)pCharacteristic->createDescriptor("2904");
148+
```
149+
<br/>
150+
151+
### Server Security
152+
Security is set on the characteristic or descriptor properties by applying one of the following:
153+
> NIMBLE_PROPERTY::READ_ENC
154+
> NIMBLE_PROPERTY::READ_AUTHEN
155+
> NIMBLE_PROPERTY::READ_AUTHOR
156+
> NIMBLE_PROPERTY::WRITE_ENC
157+
> NIMBLE_PROPERTY::WRITE_AUTHEN
158+
> NIMBLE_PROPERTY::WRITE_AUTHOR
159+
160+
When a peer wants to read or write a characteristic or descriptor with any of these properties applied
161+
it will trigger the pairing process. By default the "just-works" pairing will be performed automatically.
162+
This can be changed to use passkey authentication or numeric comparison. See [Security Differences](#security-differences) for details.
163+
<br/>
164+
165+
# Client API
166+
167+
Client instances are created just as before with `BLEDevice::createClient` (`NimBLEDevice::createClient`).
168+
169+
Multiple client instances can be created, up to the maximum number of connections set in the config file (default: 3).
170+
To delete a client instance you must use `NimBLEDevice::deleteClient`.
171+
172+
`BLEClient::connect`(`NimBLEClient::connect`) Has had it's parameters altered.
173+
Defined as:
174+
> NimBLEClient::connect(bool deleteServices = true);
175+
> NimBLEClient::connect(NimBLEAdvertisedDevice\* device, bool deleteServices = true);
176+
> NimBLEClient::connect(NimBLEAddress address, bool deleteServices = true);
177+
178+
The type parameter has been removed and a new bool parameter has been added to indicate if the client should
179+
delete the attribute database previously retrieved (if applicable) for the peripheral, default value is true.
180+
If set to false the client will use the attribute database it retrieved from the peripheral when previously connected.
181+
This allows for faster connections and power saving if the devices dropped connection and are reconnecting.
182+
<br/>
183+
184+
> `BLEClient::getServices` (`NimBLEClient::getServices`)
185+
186+
This method now takes an optional (bool) parameter to indicate if the services should be retrieved from the server (true) or
187+
the currently known database returned (false : default).
188+
Also now returns a pointer to `std::vector` instead of `std::map`.
189+
<br/>
190+
191+
**Removed:** the automatic discovery of all peripheral attributes as they consumed time and resources for data
192+
the user may not be interested in.
193+
194+
**Added:** `NimBLEClient::discoverAttributes` for the user to discover all the peripheral attributes
195+
to replace the the removed automatic functionality.
196+
<br/>
197+
198+
### Remote Services
199+
`BLERemoteService` (`NimBLERemoteService`) Methods remain mostly unchanged with the exceptions of:
200+
> BLERemoteService::getCharacteristicsByHandle
201+
This method has been removed.
202+
<br/>
203+
204+
> `BLERemoteService::getCharacteristics` (`NimBLERemoteService::getCharacteristics`)
205+
This method now takes an optional (bool) parameter to indicate if the characteristics should be retrieved from the server (true) or
206+
the currently known database returned (false : default).
207+
Also now returns a pointer to `std::vector` instead of `std::map`.
208+
<br/>
209+
210+
### Remote Characteristics
211+
`BLERemoteCharacteristic` (`NimBLERemoteCharacteristic`) There have been a few changes to the methods in this class:
212+
213+
> `BLERemoteCharacteristic::writeValue` (`NimBLERemoteCharacteristic::writeValue`)
214+
> `BLERemoteCharacteristic::registerForNotify` (`NimBLERemoteCharacteristic::registerForNotify`)
215+
216+
Now return true or false to indicate success or failure so you can choose to disconnect or try again.
217+
<br/>
218+
219+
> `BLERemoteCharacteristic::registerForNotify` (`NimBLERemoteCharacteristic::registerForNotify`)
220+
221+
Is now **deprecated**.
222+
> NimBLERemoteCharacteristic::subscribe
223+
> NimBLERemoteCharacteristic::unsubscribe
224+
225+
Are the new methods added to replace it.
226+
<br/>
227+
228+
> `BLERemoteCharacteristic::readUInt8` (`NimBLERemoteCharacteristic::readUInt8`)
229+
> `BLERemoteCharacteristic::readUInt16` (`NimBLERemoteCharacteristic::readUInt16`)
230+
> `BLERemoteCharacteristic::readUInt32` (`NimBLERemoteCharacteristic::readUInt32`)
231+
> `BLERemoteCharacteristic::readFloat` (`NimBLERemoteCharacteristic::readFloat`)
232+
233+
Are **deprecated** a template: NimBLERemoteCharacteristic::readValue<type\>(time_t\*, bool) has been added to replace them.
234+
<br/>
235+
236+
> BLERemoteCharacteristic::readRawData
237+
238+
Has been removed from the API as it stored an unnecessary copy of the data.
239+
The user application should use `NimBLERemoteCharacteristic::readValue` or `NimBLERemoteCharacteristic::getValue`.
240+
Then cast the returned std::string to the type they wish such as:
241+
```
242+
uint8_t *val = (uint8_t*)pChr->readValue().data();
243+
```
244+
<br/>
245+
246+
> `BLERemoteCharacteristic::getDescriptors` (`NimBLERemoteCharacteristic::getDescriptors`)
247+
248+
This method now takes an optional (bool) parameter to indicate if the descriptors should be retrieved from the server (true) or
249+
the currently known database returned (false : default).
250+
Also now returns a pointer to `std::vector` instead of `std::map`.
251+
<br/>
252+
253+
### Client Security
254+
The client will automatically initiate security when the peripheral responds that it's required.
255+
The default configuration will use "just-works" pairing with no bonding, if you wish to enable bonding see below.
256+
<br/>
257+
258+
# Security API
259+
Security operations have been moved to `BLEDevice` (`NimBLEDevice`).
260+
261+
Also security callback methods are now incorporated in the NimBLEServerCallbacks / NimBLEClientCallbacks classes.
262+
However backward compatibility with the original `BLESecurity` (`NimBLESecurity`) class is retained to minimize app code changes.
263+
264+
The callback methods are:
265+
266+
> bool onConfirmPIN(uint32_t pin);
267+
268+
Receives the pin when using numeric comparison authentication, `return true;` to accept.
269+
<br/>
270+
271+
> uint32_t onPassKeyRequest();
272+
273+
For server callback; return the passkey expected from the client.
274+
For client callback; return the passkey to send to the server.
275+
<br/>
276+
277+
> void onAuthenticationComplete(ble_gap_conn_desc\* desc);
278+
279+
Authentication complete, success or failed information is in `desc`.
280+
<br/>
281+
282+
Security settings and IO capabilities are now set by the following methods of NimBLEDevice.
283+
> NimBLEDevice::setSecurityAuth(bool bonding, bool mitm, bool sc)
284+
> NimBLEDevice::setSecurityAuth(uint8_t auth_req)
285+
286+
Sets the authorization mode for this device.
287+
<br/>
288+
289+
> NimBLEDevice::setSecurityIOCap(uint8_t iocap)
290+
291+
Sets the Input/Output capabilities of this device.
292+
<br/>
293+
294+
> NimBLEDevice::setSecurityInitKey(uint8_t init_key)
295+
296+
If we are the initiator of the security procedure this sets the keys we will distribute.
297+
<br/>
298+
299+
> NimBLEDevice::setSecurityRespKey(uint8_t resp_key)
300+
301+
Sets the keys we are willing to accept from the peer during pairing.
302+
<br/>
303+

‎docs/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ Call `NimBLEDevice::init("");` in `app_main`.
4444
# Using
4545
This library is intended to be compatible with the original ESP32 BLE functions and types with minor changes.
4646

47-
See: [Breaking API Changes vs Original](docs/BREAKING_API_CHANGES.md) for details.
47+
See: [The migration guide](docs/Migration_guide.md) for details.
4848

4949
Also see [Improvements_and_updates](docs/Improvements_and_updates.md) for information about non-breaking changes.
5050

0 commit comments

Comments
 (0)