Diff: bricks/characteristic.h

Revision:

23:677689000369

Child:

24:0f08f68579bd

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/bricks/characteristic.h	Fri Jan 06 15:28:18 2017 +0000
@@ -0,0 +1,248 @@
+// characteristic.h - an easy to use overloaded characteristic class
+//
+// Synopsis:
+//
+//    Characteristic<type>   myCharacteristic(col,uuid,mode);
+//    Characteristic<type>   myCharacteristic(col,uuid,mode,name);
+//    Characteristic<type>   myCharacteristic(col,uuid,mode,name,inidata);
+//    Characteristic<type>   myCharacteristic(col,uuid,mode,inidata);
+//
+// Declaration of a characteristic, specifying value type, UUID and access mode,
+// optionally providing a name (user descriptor) and initial data.
+//
+//    col:     Collection, to which the constructed characteristic is automati-
+//             cally added. After construction and adding all characteristics to 
+//             a collection this collection is passed to a service constructor,
+//             which gets thus knowledge about all characteristics which have to
+//             be involved in the service
+//
+//    uuid:    A unique universal ID which identifies the characteristic
+//
+//    mode:    A string comprising zero or more access mode characters which 
+//             define the possible access modes of the characteristic.  
+//
+//                ""       no access
+//                "b"      broadcast
+//                "r"      read access
+//                "s"      send & pray (write without response)
+//                "w"      write access (with feedback)
+//                "n"      notification (no client confirmation)
+//                "i"      indication (with client confirmation)
+//                "a"      authentication signed write
+//                "x"      extended access
+//
+//    name:    An optional name provided in terms of a user descriptor. If this
+//             argument is omitted the user descriptor is not created.
+//
+//    inidata: A pointer to a variable containing initializing data for the
+//             characteristic. If the inidata argument is not provided, an
+//             implicit initialization is performed which clears the characte-
+//             ristic (all bytes set to 0). As a concluding remark it needs to
+//             be noted that the implicite initialozation works only for 
+//             sizeof(Type) <= SIZE_INIBUFFER (defined in "bricks/types.h")
+//
+//
+// Example 1: A protocol might be declared as a class as follows
+//
+//    Collection col;                            // collection used during setup
+//
+//    Characteristic<ObjectId>   id(col,0x2AC3,"rw","ID");
+//    Characteristic<ObjectName> name(col,0x2ABE,"rw","Name");
+//    Characteristic<Digital>    presence(col,0x2A56,"r","Presence");
+//
+//    Service presenceDetection(col,0xA001);     // instantiate service
+//
+//    onSetup(Blob &blue)
+//    {
+//       blue.service(presenceDetection);        // add service    
+//    }
+//
+// Example 2: service definition by means of a service definition class
+//
+//   class PresenceDetector
+//   {
+//      public:
+//         Collection col;                       // collection used during setup 
+//
+//         Characteristic<ObjectId> id;          // ID of presence detector
+//         Characteristic<ObjectName> name;      // name of presence detector
+//         Characteristic<Digital> presence;     // digital presence value
+//         Characteristic<DateTime> timestamp;   // last detection change's time
+//         Characteristic<ObjectName> layout;    // name of model railway layout
+//
+//         Service presenceDetection;            // the service
+//
+//      public:
+//         PresenceDetector(Blob &blue, cost UUID uuid) :
+//            list;                              // init service list
+//            id(list,0x2AC3,"rw","ID"),         // instantiate characteristic
+//            name(list,0x2ABE,"rw","Name"),     // instantiate characteristic
+//            presence(list,0x2A56,"r","Presence"),// instantiate characteristic
+//            timestamp(list,0x2A08,"r","Timestamp"),// instantiate characteristic
+//            layout(list,0x2ABE,"rw","Layout"), // instantiate characteristic
+//            presenceDetection(list,uuid)       // instantiate service
+//         {
+//            blue.service(presenceDetection);   // add service    
+//         }
+//   };       
+//
+#ifndef _CHARACTERISTIC_H_
+#define _CHARACTERISTIC_H_
+
+#include "ble/BLE.h"
+#include "ble/Gap.h"
+#include "bricks/types.h"
+#include "bricks/collection.h"
+
+//==============================================================================
+// UserDescriptor Class - Create a User Descriptor
+//==============================================================================
+
+   class UserDescriptor : public GattAttribute
+   {
+       private:
+          typedef GattAttribute *GattAttributePtr;
+       
+       public:
+          GattAttributePtr plist[1];
+          
+          UserDescriptor(const char *name) :
+             GattAttribute(0x2901,(uint8_t*)name,strlen(name),strlen(name))
+          {
+              plist[0] = this;
+          }
+   };
+
+//==============================================================================
+// Characteristic Class - derived GattCharacteristic, auto-adds to service list
+//==============================================================================
+//
+// Synopsis: 
+//             Characteristic(list,uuid,mode)
+//             Characteristic(list,uuid,mode,description)
+// 
+// Parameter mode is a string combination of the following characters:
+//    ""       BLE_GATT_CHAR_PROPERTIES_NONE (0x00)
+//    "b"      BLE_GATT_CHAR_PROPERTIES_BROADCAST (0x01)
+//    "r"      BLE_GATT_CHAR_PROPERTIES_READ (0x02)
+//    "s"      BLE_GATT_CHAR_PROPERTIES_WRITE_WITHOUT_RESPONSE (0x04) (send&pray)
+//    "w"      BLE_GATT_CHAR_PROPERTIES_WRITE (0x08)
+//    "n"      BLE_GATT_CHAR_PROPERTIES_NOTIFY (0x10)
+//    "i"      BLE_GATT_CHAR_PROPERTIES_INDICATE (0x20)
+//    "a"      BLE_GATT_CHAR_PROPERTIES_AUTHENTICATED_SIGNED_WRITES (0x40)
+//    "x"      BLE_GATT_CHAR_PROPERTIES_EXTENDED_PROPERTIES (0x80)
+//
+// Example:
+//    ServiceList list;
+//
+//    Characteristic<ObjectId>   id(list,0x2AC3,"rw","ID");
+//    Characteristic<ObjectName> name(list,0x2ABE,"rw","Name");
+//    Characteristic<Digital>    presence(list,0x2A56,"rn","Presence");
+//
+// 
+   static IniBuffer inidata;             // to initialize a characteristic
+
+   static void init()                    // initialize inibuffer
+   {
+      static int initialized = 0;
+      
+      if (!initialized)                  // clear init data buffer
+      {  initialized = 1;
+         memset(inidata,0,sizeof(IniBuffer));
+      }
+   }
+
+   template <typename Type>
+   class Characteristic : public GattCharacteristic
+   {
+      private:
+         UserDescriptor descriptor;      // characteristic's user descriptor
+         
+         uint8_t getmask(const char *pmask)
+         {
+            uint8_t mask = 0;
+            
+            for(;*pmask;pmask++)
+            {  switch (*pmask)
+               {
+                  case 'b':  // broad cast
+                     mask = mask | BLE_GATT_CHAR_PROPERTIES_BROADCAST;
+                     break;
+                  case 'r':  // read
+                     mask = mask | BLE_GATT_CHAR_PROPERTIES_READ;
+                     break; 
+                  case 's':  // send (& pray)
+                     mask = mask | BLE_GATT_CHAR_PROPERTIES_WRITE_WITHOUT_RESPONSE;
+                     break; 
+                  case 'w':  // write
+                     mask = mask | BLE_GATT_CHAR_PROPERTIES_WRITE;
+                     break; 
+                  case 'n':  // notify
+                     mask = mask | BLE_GATT_CHAR_PROPERTIES_NOTIFY;
+                     break; 
+                  case 'i':  // indicate
+                     mask = mask | BLE_GATT_CHAR_PROPERTIES_INDICATE;
+                     break; 
+                  case 'a':  // authenticated signed write
+                     mask = mask | BLE_GATT_CHAR_PROPERTIES_AUTHENTICATED_SIGNED_WRITES;
+                     break; 
+                  case 'x':  // extended properties
+                     mask = mask | BLE_GATT_CHAR_PROPERTIES_EXTENDED_PROPERTIES;
+                     break;
+               } 
+            }
+            return mask;
+         }
+         
+      public:
+         Characteristic<Type> (Collection &list, UUID uuid, const char *mode,
+                               Type *valuePtr = (Type*)&inidata) : 
+            GattCharacteristic(uuid, 
+                               reinterpret_cast<uint8_t*> (valuePtr),
+                               sizeof(Type),
+                               sizeof(Type),
+                               getmask(mode),
+                               NULL,             // descriptor list
+                               0,                // number of descriptors
+                               false),
+         {
+            init();                              // assure initializing
+            
+               // there is a potential danger that we use implicite initializing
+               // with sizeof(Type) > sizeof(inibuffer). This must be prevented!
+               
+            int feasible = (sizeof(Type) <= sizeof(inibuffer)); 
+            if (feasible || valuePtr != (Type*)&inidata)
+            {
+               list.add(this);                   // add to setup list
+            }                                    // otherwise just ignore!
+         }
+
+      public:
+         Characteristic<Type> (Collection &list, UUID uuid, const char *mode,
+                               const char *name, Type *valuePtr = (Type*)&inidata) : 
+            GattCharacteristic(uuid, 
+                               reinterpret_cast<uint8_t*> (valuePtr),
+                               sizeof(Type),
+                               sizeof(Type),
+                               getmask(mode),
+                               descriptor.plist, // descriptor list
+                               1,                // number of descriptors
+                               false),
+            descriptor(name)                     // construct descriptor
+         {
+            init();                              // assure initializing
+            
+               // there is a potential danger that we use implicite initializing
+               // with sizeof(Type) > sizeof(inibuffer). This must be prevented!
+               
+            int feasible = (sizeof(Type) <= sizeof(IniBuffer)); 
+            if (feasible || valuePtr != (Type*)&inidata)
+            {
+               list.add(this);                   // add to setup list
+            }                                    // otherwise just ignore!
+         }
+   };
+
+
+#endif // _CHARACTERISTIC_H_
\ No newline at end of file