Diff: Puck.h

Revision:

16:fb8678ee25b0

Parent:

10:67e4694f2d74

Child:

17:23a05bd2fe2b

--- a/Puck.h	Fri Aug 01 07:46:52 2014 +0000
+++ b/Puck.h	Fri Aug 01 13:31:46 2014 +0000
@@ -21,7 +21,9 @@
      std::vector<CharacteristicWriteCallback>* callbacks;
 } CharacteristicWriteCallbacks;
   
- 
+/** Puck class. Abstracts away much 
+ *
+ */ 
 class Puck {
     private:
         Puck() {}
@@ -60,6 +62,11 @@
         uint8_t* getCharacteristicValue(const UUID uuid);
 };
 
+/**
+ *  @brief Returns singleton instance of puck object.
+ *
+ *  @return singleton instance of puck object.
+ */
 Puck &Puck::getPuck() {
     static Puck _puckSingletonInstance;
     return _puckSingletonInstance;
@@ -95,6 +102,10 @@
     return true;
 }
 
+/**
+ * @brief Returns UUID representation of a 16-character string.
+ *
+ */
 const UUID stringToUUID(const char* str) {
     uint8_t array[16];
     for(int i = 0; i < 16; i++) {
@@ -107,6 +118,10 @@
     ble.disconnect();    
 }
 
+/**
+ *  @brief Approximates malloc-able heap space. Do not use in production code, as it may crash.
+ *
+ */
 int Puck::countFreeMemory() {
     int blocksize = 256;
     int amount = 0;
@@ -132,6 +147,14 @@
     this->state = state;    
 }
 
+/**
+ *  @brief  Call after finishing configuring puck (adding services, characteristics, callbacks).
+            Starts advertising over bluetooth le. 
+ *
+ *  @parameter  minor
+ *              Minor number to use for iBeacon identifier.
+ *
+ */
 void Puck::init(uint16_t minor) {
         /*
      * The Beacon payload (encapsulated within the MSD advertising data structure)
@@ -203,7 +226,24 @@
     }
 }
 
-
+/** 
+ *  @brief  Extends the given gatt service with the given gatt characteristic.
+ *          If the service doesn't exist, it is created.
+ *
+ *  @param  serviceUuid
+            UUID of the gatt service to be extended.
+ *
+ *  @param  characteristicUuid
+ *          UUID to use for this characteristic.
+ *
+ *  @param  bytes
+ *          Length in bytes of this characteristic's value.
+ *
+ *  @param  properties
+ *          8-bit bit field containing the characteristic's properties. See @ref ble_gatt_char_properties_t.
+ *
+ *  @return Void.
+ */
 void Puck::addCharacteristic(const UUID serviceUuid, const UUID characteristicUuid, int bytes, int properties) {
     MBED_ASSERT(bytes <= 20);
     uint16_t size = sizeof(uint8_t) * bytes;
@@ -255,7 +295,20 @@
     LOG_DEBUG("Added characteristic.\n");
 }
 
-
+/** 
+ *  @brief  Update the value of the given gatt characteristic.
+ *
+ *  @param  uuid
+            UUID of the gatt characteristic to be updated.
+ *
+ *  @param  value
+ *          New value of the characteristic.
+ *
+ *  @param  length
+ *          Length in bytes of the characteristic's value.
+ *
+ *  @return Void.
+ */
 void Puck::updateCharacteristicValue(const UUID uuid, uint8_t* value, int length) {
     GattCharacteristic* characteristic = NULL;
     for( int i = 0; i < characteristics.size(); i++) {
@@ -272,6 +325,19 @@
     }
 }
 
+/** 
+ *  @brief Pass control to the bluetooth stack, executing pending callbacks afterwards. Should be used inside a while condition loop.
+ *
+ *  Example:
+ *  @code
+ *  while (puck->drive) {
+ *      // Do stuff
+ *  }
+ *  @endcode
+ *
+ * @return true.
+ *
+ */
 bool Puck::drive() {
     ble.waitForEvent();
     if(state == DISCONNECTED) {
@@ -285,7 +351,18 @@
     return true;
 }
 
-
+/** 
+ *  @brief Register callback to be triggered on characteristic write.
+ *
+ *  @parameter  uuid
+ *              UUID of the gatt characteristic to bind callback to.
+ *
+ *  @parameter  callback
+ *              CharacteristicWriteCallback to be executed on characteristic write.
+ *
+ *  @return Void.
+ *
+ */
 void Puck::onCharacteristicWrite(const UUID* uuid, CharacteristicWriteCallback callback) {
     CharacteristicWriteCallbacks* cb = NULL;
     for(int i = 0; i< writeCallbacks.size(); i++) {
@@ -307,7 +384,10 @@
     LOG_VERBOSE("Bound characteristic write callback (uuid: %x, callback: %x)\n", uuid, callback);
 }
 
-
+/**
+ *  @brief Returns current value of provided gatt characteristic.
+ *
+ */
 uint8_t* Puck::getCharacteristicValue(const UUID uuid) {
     LOG_VERBOSE("Reading characteristic value for UUID %x\n", uuid);
     for(int i = 0; i < characteristics.size(); i++) {
@@ -320,7 +400,10 @@
     return NULL;
 }
 
-
+/**
+ * @brief For internal use only. Exposed to hack around mbed framework limitation.
+ *
+ */
 void Puck::onDataWritten(uint16_t handle) {
     for (int i = 0; i < characteristics.size(); i++) {
         GattCharacteristic* characteristic = characteristics[i];