Adds BLE Characteristic User Description 0x2901 Descriptor (#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_ */