Adds BLE Characteristic User Description 0x2901 Descriptor (espressif#9883)

Adds a class for 0x2901 - Characteristic User Descriptor. This Descriptor is usual in BLE and describes with text what each characteristic is about. Improve Notify.ino example by adding the 0x2901 descriptor

Author: SuGlider

CMakeLists.txt

@@ -236,6 +236,7 @@ set(ARDUINO_LIBRARY_WiFiProv_SRCS libraries/WiFiProv/src/WiFiProv.cpp)
 set(ARDUINO_LIBRARY_Wire_SRCS libraries/Wire/src/Wire.cpp)
 
 set(ARDUINO_LIBRARY_BLE_SRCS
+ libraries/BLE/src/BLE2901.cpp
  libraries/BLE/src/BLE2902.cpp
  libraries/BLE/src/BLE2904.cpp
  libraries/BLE/src/BLEAddress.cpp

libraries/BLE/examples/Notify/Notify.ino

@@ -23,9 +23,12 @@
 #include <BLEServer.h>
 #include <BLEUtils.h>
 #include <BLE2902.h>
+#include <BLE2901.h>
 
 BLEServer *pServer = NULL;
 BLECharacteristic *pCharacteristic = NULL;
+BLE2901 *descriptor_2901 = NULL;
+
 bool deviceConnected = false;
 bool oldDeviceConnected = false;
 uint32_t value = 0;
@@ -65,9 +68,13 @@ void setup() {
  BLECharacteristic::PROPERTY_READ | BLECharacteristic::PROPERTY_WRITE | BLECharacteristic::PROPERTY_NOTIFY | BLECharacteristic::PROPERTY_INDICATE
  );
 
- // https://www.bluetooth.com/specifications/gatt/viewer?attributeXmlFile=org.bluetooth.descriptor.gatt.client_characteristic_configuration.xml
- // Create a BLE Descriptor
+ // Creates BLE Descriptor 0x2902: Client Characteristic Configuration Descriptor (CCCD)
  pCharacteristic->addDescriptor(new BLE2902());
+ // Adds also the Characteristic User Description - 0x2901 descriptor
+ descriptor_2901 = new BLE2901();
+ descriptor_2901->setDescription("My own description for this characteristic.");
+ descriptor_2901->setAccessPermissions(ESP_GATT_PERM_READ); // enforce read only - default is Read|Write
+ pCharacteristic->addDescriptor(descriptor_2901);
 
  // Start the service
  pService->start();
@@ -87,7 +94,7 @@ void loop() {
  pCharacteristic->setValue((uint8_t *)&value, 4);
  pCharacteristic->notify();
  value++;
- delay(3); // bluetooth stack will go into congestion, if too many packets are sent, in 6 hours test i was able to go as low as 3ms
+ delay(500);
  }
  // disconnecting
  if (!deviceConnected && oldDeviceConnected) {

libraries/BLE/src/BLE2901.cpp

@@ -0,0 +1,40 @@
+/*
+ BLE2901.h
+
+ GATT Descriptor 0x2901 Characteristic User Description
+
+ The value of this description is a user-readable string
+ describing the characteristic.
+
+ The Characteristic User Description descriptor
+ provides a textual user description for a characteristic
+ value.
+ If the Writable Auxiliary bit of the Characteristics
+ Properties is set then this descriptor is written. Only one
+ User Description descriptor exists in a characteristic
+ definition.
+*/
+
+#include "soc/soc_caps.h"
+#if SOC_BLE_SUPPORTED
+
+#include "sdkconfig.h"
+#if defined(CONFIG_BLUEDROID_ENABLED)
+
+#include "BLE2901.h"
+
+BLE2901::BLE2901() : BLEDescriptor(BLEUUID((uint16_t)0x2901)) {} // BLE2901
+
+/**
+ * @brief Set the Characteristic User Description
+ */
+void BLE2901::setDescription(String userDesc) {
+ if (userDesc.length() > ESP_GATT_MAX_ATTR_LEN) {
+ log_e("Size %d too large, must be no bigger than %d", userDesc.length(), ESP_GATT_MAX_ATTR_LEN);
+ return;
+ }
+ setValue(userDesc);
+}
+
+#endif
+#endif /* SOC_BLE_SUPPORTED */

libraries/BLE/src/BLE2901.h

@@ -0,0 +1,37 @@
+/*
+ BLE2901.h
+
+ GATT Descriptor 0x2901 Characteristic User Description
+
+ The value of this description is a user-readable string
+ describing the characteristic.
+
+ The Characteristic User Description descriptor
+ provides a textual user description for a characteristic
+ value.
+ If the Writable Auxiliary bit of the Characteristics
+ Properties is set then this descriptor is written. Only one
+ User Description descriptor exists in a characteristic
+ definition.
+
+*/
+
+#ifndef COMPONENTS_CPP_UTILS_BLE2901_H_
+#define COMPONENTS_CPP_UTILS_BLE2901_H_
+#include "soc/soc_caps.h"
+#if SOC_BLE_SUPPORTED
+
+#include "sdkconfig.h"
+#if defined(CONFIG_BLUEDROID_ENABLED)
+
+#include "BLEDescriptor.h"
+
+class BLE2901 : public BLEDescriptor {
+public:
+ BLE2901();
+ void setDescription(String desc);
+}; // BLE2901
+
+#endif /* CONFIG_BLUEDROID_ENABLED */
+#endif /* SOC_BLE_SUPPORTED */
+#endif /* COMPONENTS_CPP_UTILS_BLE2901_H_ */