Server: Add onSubscribe() callback for characteristics. (#91)

* Server: Add onSubscribe() callback for characteristics.

Adds a new method to NimBLECharacteristicCallbacks that gets called when a client
changes it's subscription status.

* Remove NimBLE2902 class.

As the NimBLE2902 class usefulness was only related to callback functions that were replaced
by the NimBLECharacteristicCallbacks:onSubscribe() method this removes the NimBLE2902 class and
moves all subscription handling to NimBLECharacteristic.

* Update documents and examples to reflect this change.

* Add getSubscribedCount() to get the number of subscribed clients.

Author: h2zero

docs/BREAKING_API_CHANGES.md

@@ -33,15 +33,18 @@ When creating a characteristic the properties are now set with `NIMBLE_PROPERTY:
 ### Descriptors
 Descriptors are now created using the `NimBLECharacteristic::createDescriptor()` method.
 
-The previous method `BLECharacteristic::addDescriptor()` is now a private function in the library.
+The previous method `BLECharacteristic::addDescriptor()` has been removed.  
 
-This was done because the NimBLE host automatically creates a 0x2902 descriptor if a characteristic has NOTIFY or INDICATE properties applied.   
-Due to this fact, the library also creates one automatically for your application.    
-The only reason to manually create this descriptor now is to assign callback functions.   
-If you do not require this functionality you can safely exclude the manual creation of the 0x2902 descriptor.   
+0x2902 Descriptor class: formerly known as BLE2902 or NimBLE2902 has been removed.  
+It was no longer useful as a new callback `NimBLECharacteristicCallbacks::onSubscribe` was added  
+to handle callback functionality and the client subscription status is handled internally.  
 
-For any other descriptor, (except 0x2904, see below) it should now be created just as characteristics are    
-by using the `NimBLECharacteristic::createDescriptor` method.   
+NimBLE automatically creates the 0x2902 descriptor if a characteristic has a notification or indication property assigned to it.  
+
+**Note** Attempting to create a 0x2902 descriptor will trigger an assert to notify the error, 
+allowing the creation of it would cause a fault in the NimBLE stack.
+
+All other desctiptors are now created just as characteristics are by using the `NimBLECharacteristic::createDescriptor` methods (except 0x2904, see below).   
 Which are defined as:
 ```
 NimBLEDescriptor* createDescriptor(const char* uuid,
@@ -67,15 +70,14 @@ pDescriptor = pCharacteristic->createDescriptor("ABCD",
 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.  
 <br/>
 
-For the 0x2904 and 0x2902 descriptor, there is a special class that is created when you call `createDescriptor("2904")`or `createDescriptor("2902")`.
+For the 0x2904, there is a special class that is created when you call `createDescriptor("2904").
 
-The pointer returned is of the base class `NimBLEDescriptor` but the call will create the derived class of `NimBLE2904` or `NimBLE2902` so you must cast the returned pointer to  
-`NimBLE2904` or `NimBLE2902` to access the specific class methods.
+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  
+`NimBLE2904` to access the specific class methods.
 
 ##### Example
 ```
 p2904 = (NimBLE2904*)pCharacteristic->createDescriptor("2904");
-p2902 = (NimBLE2902*)pCharacteristic->createDescriptor("2902");
 ```
 <br/>
 
@@ -91,7 +93,6 @@ Security is set on the characteristic or descriptor properties by applying one o
 When a peer wants to read or write a characteristic or descriptor with any of these properties applied    
 it will trigger the pairing process. By default the "just-works" pairing will be performed automatically.   
 This can be changed to use passkey authentication or numeric comparison. See [Security Differences](#security-differences) for details.  
-
 <br/>
 
 # Client API Differences

examples/NimBLE_Server/NimBLE_Server.ino

@@ -100,26 +100,33 @@ class CharacteristicCallbacks: public NimBLECharacteristicCallbacks {
         str += NimBLEUtils::returnCodeToString(code);
         Serial.println(str);
     };
+
+    void onSubscribe(NimBLECharacteristic* pCharacteristic, ble_gap_conn_desc* desc, uint16_t subValue) {
+        String str = "Client ID: ";
+        str += desc->conn_handle;
+        str += " Address: ";
+        str += std::string(NimBLEAddress(desc->peer_ota_addr)).c_str();
+        if(subValue == 0) {
+            str += " Unsubscribed to ";
+        }else if(subValue == 1) {
+            str += " Subscribed to notfications for ";
+        } else if(subValue == 2) {
+            str += " Subscribed to indications for ";
+        } else if(subValue == 3) {
+            str += " Subscribed to notifications and indications for ";
+        }
+        str += std::string(pCharacteristic->getUUID()).c_str();
+
+        Serial.println(str);
+    };
 };
 
 /** Handler class for descriptor actions */    
 class DescriptorCallbacks : public NimBLEDescriptorCallbacks {
     void onWrite(NimBLEDescriptor* pDescriptor) {
-        if(pDescriptor->getUUID().equals(NimBLEUUID("2902"))) {
-            /** Cast to NimBLE2902 to use the class specific functions. **/
-            NimBLE2902* p2902 = (NimBLE2902*)pDescriptor;
-            if(p2902->getNotifications()) {
-                Serial.println("Client Subscribed to notfications");
-            } else if(p2902->getIndications()) {
-                Serial.println("Client Subscribed to indications");
-            } else {
-                Serial.println("Client Unubscribed");
-            }
-        } else {
-            std::string dscVal((char*)pDescriptor->getValue(), pDescriptor->getLength());
-            Serial.print("Descriptor witten value:");
-            Serial.println(dscVal.c_str());
-        }
+        std::string dscVal((char*)pDescriptor->getValue(), pDescriptor->getLength());
+        Serial.print("Descriptor witten value:");
+        Serial.println(dscVal.c_str());
     };
 
     void onRead(NimBLEDescriptor* pDescriptor) {
@@ -176,9 +183,9 @@ void setup() {
     pBeefCharacteristic->setValue("Burger");
     pBeefCharacteristic->setCallbacks(&chrCallbacks);
 
-    /** 2902 and 2904 descriptors are a special case, when createDescriptor is called with
-     *  either of those uuid's it will create the associated class with the correct properties
-     *  and sizes. However we must cast the returned reference to the correct type as the method
+    /** 2904 descriptors are a special case, when createDescriptor is called with
+     *  0x2904 a NimBLE2904 class is created with the correct properties and sizes.
+     *  However we must cast the returned reference to the correct type as the method
      *  only returns a pointer to the base NimBLEDescriptor class.
      */
     NimBLE2904* pBeef2904 = (NimBLE2904*)pBeefCharacteristic->createDescriptor("2904"); 
@@ -197,6 +204,10 @@ void setup() {
     pFoodCharacteristic->setValue("Fries");
     pFoodCharacteristic->setCallbacks(&chrCallbacks);
 
+    /** Note a 0x2902 descriptor MUST NOT be created as NimBLE will create one automatically
+     *  if notification or indication properties are assigned to a characteristic.
+     */
+
     /** Custom descriptor: Arguments are UUID, Properties, max length in bytes of the value */
     NimBLEDescriptor* pC01Ddsc = pFoodCharacteristic->createDescriptor(
                                                "C01D",
@@ -208,14 +219,6 @@ void setup() {
     pC01Ddsc->setValue("Send it back!");
     pC01Ddsc->setCallbacks(&dscCallbacks);
 
-    /** Note a 2902 descriptor does NOT need to be created as any chactateristic with 
-     *  notification or indication properties will have one created autmatically.
-     *  Manually creating it is only useful if you wish to handle callback functions
-     *  as shown here. Otherwise this can be removed without loss of functionality.
-     */
-    NimBLE2902* pFood2902 = (NimBLE2902*)pFoodCharacteristic->createDescriptor("2902"); 
-    pFood2902->setCallbacks(&dscCallbacks);
-
     /** Start the services when finished creating all Characteristics and Descriptors */  
     pDeadService->start();
     pBaadService->start();
@@ -247,4 +250,4 @@ void loop() {
     }
 
   delay(2000);
-}
+}

examples/Refactored_original_examples/BLE_notify/BLE_notify.ino

@@ -102,16 +102,13 @@ void setup() {
 
   // https://www.bluetooth.com/specifications/gatt/viewer?attributeXmlFile=org.bluetooth.descriptor.gatt.client_characteristic_configuration.xml
   // Create a BLE Descriptor
-  /*********** New createDescriptor method ************   
-   NOTE: There is no need to create the 2902 descriptor 
-   as it will be created automatically if notifications 
+  /***************************************************   
+   NOTE: DO NOT create a 2902 descriptor. 
+   it will be created automatically if notifications 
    or indications are enabled on a characteristic.
    
    pCharacteristic->addDescriptor(new BLE2902());
   ****************************************************/
-  /** Add properties the same way as characteristics now **/
-  
-  pCharacteristic->createDescriptor("2902" /** , NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::WRITE **/);
   // Start the service
   pService->start();
 

examples/Refactored_original_examples/BLE_server_multiconnect/BLE_server_multiconnect.ino

@@ -105,16 +105,13 @@ void setup() {
 
   // https://www.bluetooth.com/specifications/gatt/viewer?attributeXmlFile=org.bluetooth.descriptor.gatt.client_characteristic_configuration.xml
   // Create a BLE Descriptor
-  /*********** New createDescriptor method ************   
-   NOTE: There is no need to create the 2902 descriptor 
-   as it will be created automatically if notifications 
+  /***************************************************   
+   NOTE: DO NOT create a 2902 descriptor 
+   it will be created automatically if notifications 
    or indications are enabled on a characteristic.
    
    pCharacteristic->addDescriptor(new BLE2902());
   ****************************************************/
-  /** Add properties the same way as characteristics now **/
-  
-  pCharacteristic->createDescriptor("2902" /** , NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::WRITE **/);
 
   // Start the service
   pService->start();

examples/Refactored_original_examples/BLE_uart/BLE_uart.ino

@@ -112,15 +112,13 @@ void setup() {
                                         NIMBLE_PROPERTY::NOTIFY
                                        );
 
-  /******* New createDescriptor method ********   
-   NOTE: There is no need to create the 2902 descriptor 
-   as it will be created automatically if notifications or 
-   indications are enabled on a characteristic.
+  /***************************************************   
+   NOTE: DO NOT create a 2902 descriptor 
+   it will be created automatically if notifications 
+   or indications are enabled on a characteristic.
    
-  pCharacteristic->addDescriptor(new BLE2902());
-  ********************************************/
-  /** Add properties the same way as characteristics now **/
-  pTxCharacteristic->createDescriptor("2902" /** , NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::WRITE **/);                      
+   pCharacteristic->addDescriptor(new BLE2902());
+  ****************************************************/                  
 
   BLECharacteristic * pRxCharacteristic = pService->createCharacteristic(
                                             CHARACTERISTIC_UUID_RX,