Nordic Pucks / Puck Featured

A library for easier setup and prototyping of IoT devices (pucks), by collecting everything that is common for all pucks in one place.

Dependencies:   BLE_API nRF51822

Dependents:   ir-puck display-puck ir-puck2 BLE_ScoringDevice ... more

/media/uploads/stiaje/header.jpg

Introduction

Raspberry Pi took the maker community by storm when it launched in 2012. With its internet access it allowed small projects to be internet-of-things enabled. We have created a platform to take this one step further.

Our platform, called the Puck platform, is an internet of things platform for mbed. mbed makes it easy to program embedded hardware for people new to embedded systems. Our platform is built upon the first mbed chip with Bluetooth, the nRF51822 created by Nordic Semiconductor. We hope to create a community around these BLE devices where people contribute to the project, and share their designs with each other. Everything is open-source, of course, with lots of supporting materials.

We make it easy to rapidly prototype and develop Bluetooth LE enabled devices - get up and running in under 10 lines of code.

Tutorials and in-depth documentation is available at the project's GitHub page

Pucks

We've developed a handful of awesome examples to demonstrate the platform. These examples are named 'Pucks'. By talking to the internet through your smartphone, the barrier to creating your own Internet of Things device is lower than ever.

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];