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

Update documentation

Browse Source 
Co-authored-by: wakwak-koba <wakwak-koba@users.noreply.github.com>
This commit is contained in:
h2zero
2020-07-30 20:16:58 -06:00
committed by h2zero
parent 97832d4d95
commit a460eca1ef
6 changed files with 32 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
docs/BREAKING_API_CHANGES.md
View File

@@ -99,15 +99,17 @@ This can be changed to use passkey authentication or numeric comparison. See [Se
The `NimBLEAdvertisedDeviceCallbacks::onResult()` method now receives a pointer to the
`NimBLEAdvertisedDevice` object instead of a copy.
`NimBLEClient::connect()` now takes an extra parameter to indicate if the client should download the services
database from the peripheral, default value is true.
`NimBLEClient::connect()` Has had it's parameters altered.
Defined as:
> NimBLEClient::connect(bool refreshServices = true);
> NimBLEClient::connect(NimBLEAdvertisedDevice\* device, bool refreshServices = true);
> NimBLEClient::connect(NimBLEAddress address, uint8_t type = BLE_ADDR_PUBLIC, bool refreshServices = true);
> NimBLEClient::connect(NimBLEAddress address, bool refreshServices = true);
<br/>
If set to false the client will use the services database it retrieved from the peripheral last time it connected.
This allows for faster connections and power saving if the devices just dropped connection and want to reconnect.
The type parameter has been removed and a new bool parameter has been added to indicate if the client should
delete the attribute database previously retrieved (if applicable) for the peripheral, default value is true.
If set to false the client will use the attribute database it retrieved from the peripheral when previously connected.
This allows for faster connections and power saving if the devices dropped connection and are reconnecting.
<br/>
> NimBLERemoteCharacteristic::writeValue();
@@ -117,6 +119,7 @@ Now return true or false to indicate success or failure so you can choose to dis
<br/>
> NimBLERemoteCharacteristic::registerForNotify();
Is now **deprecated**.
> NimBLERemoteCharacteristic::subscribe()
> NimBLERemoteCharacteristic::unsubscribe()
@@ -129,7 +132,7 @@ Are the new methods added to replace it.
> NimBLERemoteCharacteristic::readUInt32()
> NimBLERemoteCharacteristic::readFloat()
Are **deprecated** and NimBLERemoteCharacteristic::readValue(time_t\*, bool) template added to replace them.
Are **deprecated** and NimBLERemoteCharacteristic::readValue<type\>(time_t\*, bool) template added to replace them.
<br/>
> NimBLERemoteService::getCharacteristicsByHandle()
@@ -152,8 +155,9 @@ uint8_t *val = (uint8_t*)pChr->readValue().data();
> NimBLERemoteService::getCharacteristics(bool refresh = false)
These methods now take an optional (bool) parameter and return a pointer to `std::vector` instead of `std::map`.
If passed 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 with the currently stored attributes.
If passed 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 with the currently stored attributes.
<br/>
**Removed:** the automatic discovery of all peripheral attributes as they consumed time and resources for data
the user may not be interested in.
@@ -177,6 +181,17 @@ The client will automatically initiate security when the peripheral responds tha
The default configuration will use "just-works" pairing with no bonding, if you wish to enable bonding see below.
<br/>
# General Differences
`NimBLEAddress()` When constructing an address the constructor now takes an optional `uint8_t type` paramameter
to specify the address type. Default is (0) Public static address.
Defined as:
> NimBLEAddress(ble_addr_t address);
> NimBLEAddress(uint8_t address[6], uint8_t type = BLE_ADDR_PUBLIC);
> NimBLEAddress(const std::string &stringAddress, uint8_t type = BLE_ADDR_PUBLIC);
> NimBLEAddress(const uint64_t &address, uint8_t type = BLE_ADDR_PUBLIC);
<br/>
# Security Differences
Security callback functions are now incorporated in the NimBLEServerCallbacks / NimBLEClientCallbacks classes.
However backward compatibility with the original `BLESecurity` class is retained to minimize app code changes.

9
docs/Improvements_and_updates.md
View File

@@ -45,16 +45,12 @@ A new method `NimBLEServer::advertiseOnDisconnect(bool)` has been implemented to
`NimBLEServer::removeService` takes an additional parameter `bool deleteSvc` that if true will delete the service
and all characteristics / descriptors belonging to it and invalidating any pointers to them.
If false the service is only removed from visibility by clients. The pointers to the service and
it's characteristics / descriptors will remain valid and the service can be re-added in the future
using `NimBLEServer::addService`.
<br/>
New characteristic read/write callbacks added to NimBLECharacteristicCallbacks that receive a pointer to the connection
description of the client reading/writing.
This is useful when connected to multiple clients to discern which client is performing the operation.
<br/>
# Client
NimBLERemoteCharacteristic::readValue(time_t\*, bool)
@@ -91,6 +87,9 @@ NimBLEClient::getService will now retrieve only the service specified and not th
otherwise wasted retrieving and allocating attributes the user application is not interested in.
<br/>
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().
# General
To reduce resource use all instances of std::map have been replaced with std::vector.