Refactor attributes to reduce code duplication and improve maintainability.
* Add attribute base classes to provide common code.
* Add const where possible to functions and parameters.
* `NimBLECharacteristic::notify` no longer takes a `bool is_notification` parameter, instead `indicate()` should be called to send indications.
* `NimBLECharacteristic::indicate` now takes the same parameters as `notify`.
* `NimBLECharacteristicCallbacks` and `NimBLEDescriptorCallbacks` methods now take `const NimBLEConnInfo&` instead of non-const.
* `NimBLECharacteristic::onNotify` callback removed as unnecessary, the library does not call notify without app input.
* `NimBLERemoteCharacteristic::getRemoteService` now returns a `const NimBLERemoteService*` instead of non-const.
* Add NimBLEUUID constructor that takes a reference to `ble_uuid_any_t`.
* `NimBLERemoteService::getCharacteristics` now returns a `const std::vector<NimBLERemoteCharacteristic*>&` instead of non-const `std::vector<NimBLERemoteCharacteristic*>*`
* `NimBLERemoteService::getValue` now returns `NimBLEAttValue` instead of `std::string`
* `NimBLEService::getCharacteristics` now returns a `const std::vector<NimBLECharacteristic*>&` instead of a copy of std::vector<NimBLECharacteristic *>.
* Remove const requirement for NimBLEConnInfo parameter in callbacks.
Const is unnecessary as the data can't be changed by application code.
* Change NimBLERemoteCharacteristic::getRemoteService to return const pointer.
* msbFirst parameter has been removed from constructor as it was unnecessary,
caller should reverse the data first or call the new `reverseByteOrder` method after.
* `getNative` method replaced with `getBase` which returns a read-only pointer to the UUID size underlying.
* Added `reverseByteOrder` method, this will reverse the bytes of the UUID, which can be useful for advertising/logging.
* Added `getValue` method, which returns a read-only `uint8_t` pointer to the UUID value.
* Removed `m_valueSet` member variable, `bitSize()` can be used as a replacement.
* General code cleanup.
Removes the response parameter from remote characterisitc subscrible/unsubscribe functions
as a response is always required for this operation as per BLE specs.
Removes the deprecated functions from remote characteristic/desriptor.
* Update examples/docs.
As per Bluetooth core specification we must write to 0x2902 descriptors with response request.
This change ensures the correct procedure is used.
Todo: Remove the "response" parameter from related functions.
When retrieving attribute handles using the 128bit base version of a 16 bit UUID some devices will
report "not found". This will attempt to convert the UUID to the 16bit version and try again.
* Adds `to16()` method to NimBLEUUID.
This is a specialized container class to hold BLE attribute values.
- Removes the use of std::string previously used to store the values.
- Allows for setting/getting/notifying values from std::string, std::vector<uint8_t>, Arduino String, const char*, and uint8_t buffers.
- Has operators retrieve the value as std::string, Arduino String, std::vector<uint8_t>, uint8_t* or char pointers.
- Includes iterators and subscript/random access operator.
- Introduces a max length parameter to the creation of server characteristics/descriptors to limit the size of the memory footprint.
- Nearly Seamless integration with existing code.
- Adds a config option to enable/disable timestamp storage when the value is updated.
- Adds a config option to specify the initial size of the value container if not specified in the constructor.
This causes task blocking to fail in client operations leading to exceptions and crashing.
This is a workaround for this situation and will need to be reworked properly in the future.
* Sets macros to allow compiling when Central role is enabled and Observer disabled, or Peripheral enabled and Broadcaster disabled.
* Adds a macro definition for CONFIG_NIMBLE_CPP_IDF to enable different include paths/functionality for IDF / Arduino.
Previously we used the service end handle or, if available, the handle of the next characteristic in the service
as the end handle when retrieving the descriptors of a characteristic. This process would fail when connecting to some
devices if the characteristics were retrieved individually instead of all together. The cause of failure was requesting
a handle range that is out of characteristic scope which is also out of line with BLE
specifications.
The fix included in this is to set the end handles of the characteristics either after retrieving all the characteristics
in a service by using the next charactertistic definition handle or, if the characteristic was retrieved separately,
we retrieve the next characteristic just before retrieving the descriptors.
On some devices, searching for descriptors using the service end handle would return an invalid error.
This patch instead uses the handle of the next characteristic as the end handle (if available).
* Some peripherals will advertise 16/32bit UUIDs but when queried for their handles
they do not convert the UUID to 128 bit locally and will return attribute not found.
This patch will query the peripheral a second time with a 128bit converted UUID.
- This changes NimBLERemoteCharacteristic::subscribe and NimBLERemoteCharacteristic::registerForNotify functionality
such that the notification callback will always be set.
Additionally these methods will always return true unless the descriptor write fails.
This allows for notifications to trigger the callback when a peer device sends them and does not have a CCCD.
Also it should not be flagged as a failure if the CCCD does not exist.
It should only be flagged when an acutal write operation fails.
* Fix for random notify crash in ISR context
Tested for stability over 30 minutes with a daisy chain of 3 esp32
Co-authored-by: h2zero <powellperalta@gmail.com>
* Replace all semaphores with task notifications.
* use critical sections to prevent concurrent data access.
* Ensure scan stop has been called before connecting.
* Optimize and cleanup
* Add template casting to NimBLERemoteDescriptor::readValue()
* Removed storage of the descriptor value read as it did not serve any purpose.
* Add subscribe() and unsubscribe() methods to replace registerForNotify() in NimBLERemoteCharacteristic.
* registerForNotify() remains as a (depreciated) method.
* Make remote attribute delete functions public.
* Rename clear...() functions to delete...(), with ... equals Service(-s), Characteristic(-s) or Descriptor(-s), depending on what the function actually deletes
Previously getRawData() made an unnecessary copy of the remote characteristic value data in order to return a uint8_t*. The resources used for this was unjustified by the value it provided as templates to retrieve such data have been added. Also the application writer could cast the std::string result of readValue() and/or getValue() however they choose using the data() method on the container if desired.
getDataLength() is also an unnecessary function as the length can be retrieved by the returned std::string from readValue() and/or getValue() with the length() method.
The value returned by reading a remote characteristic or by getting a notification for it is kept in the class instance of the NimBLERemoteCharacteristic. This value can be accessed as a std::string type using the getValue() function.
This adds templates to read the value in the type used by the peripheral. The same functionality is implemented for getting the manufacturer data or the service data of an advertised device.
* Add NimBLERemoteCharacteristic::getValue(time_t *timestamp = nullptr) to get the latest remote characteristic and (optionally) it's timestamp.
* Added a timestamp to NimBLEAdvertisedDevice for the moment a device was scanned
Instead of discovering the peripheral database on connection and consuming
the associated resources this will give the user more control over the
discovery operation.
* Adds void NimBLEClient::discoverAtrributes() for the user to discover all
the peripheral attributes as a replacement for the former functionality.
* getServices(), getCharacteristics(), getDescriptors() now take an
optional bool parameter (default false).
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.
* getService(NimBLEUUID), getCharacteristic(NimBLEUUID), getDescriptor(NimBLEUUID)
will now check the respective vectors for the attribute object and, if not
found, will retrieve (only) the specified attribute from the peripheral.
Add iterators for NimBLEScan: NimBLEadvertisedDevice, NimBLEClient: NimBLERemoteService, NimBLERemoteService: NimBLERemoteCharacteristic and NimBLERemoteCharacteristic: NimBLERemoteDescriptor
This is handy e.g. for showing every address of the advertised devices from a scan. To do so, first get a new scan and next:
```
for(auto pAdvertisedDevice: pBLEScan->getResults()) {
Serial.printf("Address is %s\n", std::string(pAdvertisedDevice->getAddress()).c_str());
}
```
Of course any other property of the advertised device can be shown (or looked up, if that is your use case)
Also this is handy e.g. for showing every UUID in a peripheral. To do so, first connect to a peripheral and next:
```
for(auto pService: *pClient) {
Serial.printf("Service UUID is %s\n", std::string(pService->getUUID()).c_str());
for(auto pCharacteristic: *pService) {
Serial.printf("Characteristic UUID is %s\n", std::string(pCharacteristic->getUUID()).c_str());
for(auto pDescriptor: *pCharacteristic) {
Serial.printf("Descriptor UUID is %s\n", std::string(pDescriptor->getUUID()).c_str());
}
}
}
```
Again of course any other property can be shown, or looked up.
* Exchange map for vector, saving 1,076 bytes of program memory and 5,024 bytes of heap for a small device (LYWSD03MMC)
* Removing m_characteristicMapByHandle (using the handles form m_characteristicVector instead) saving in total (compared to the current master) 1,508 bytes of program memory and 6,500 bytes of heap for a small device (LYWSD03MMC)
* Change NimBLEScan container from std::map to std::vector
* Add function to get advertised device by address
* Update documentation
This allows NimBLE options in menuconfig to reduce code size based on
the roles selected (scan/advertising/central/peripheral).
Significant code space can be saved by removing unnecessary roles for the application.
