BLE: Update BatteryService documentation.

features/FEATURE_BLE/ble/services/BatteryService.h

@@ -14,52 +14,107 @@
  * limitations under the License.
  */
 
-#ifndef __BLE_BATTERY_SERVICE_H__
+#ifndef MBED_BLE_BATTERY_SERVICE_H__
-#define __BLE_BATTERY_SERVICE_H__
+#define MBED_BLE_BATTERY_SERVICE_H__
 
+#include "platform/mbed_assert.h"
 #include "ble/BLE.h"
 
 /**
-* @class BatteryService
+ * BLE Battery service.
-* @brief BLE Battery Service. This service displays the battery level from 0% to 100%, represented as an 8bit number.
+ *
-* Service:  https://developer.bluetooth.org/gatt/services/Pages/ServiceViewer.aspx?u=org.bluetooth.service.battery_service.xml
+ * @par purpose
-* Battery Level Char:  https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.battery_level.xml
+ *
-*/
+ * The battery service exposes the charge level of the battery of the device.
+ * This information is exposed as a percentage from 0% to 100%; a value of 0%
+ * represents a fully discharged battery while a value of 100% represents a
+ * fully charged battery.
+ *
+ * Clients can read the current charge level and subscribe for server initiated
+ * updates of the charge level. The server delivers these updates to subscribed
+ * client in a notification packet.
+ *
+ * The subscription mechanism is usefull to save power; it avoids unecessary data
+ * traffic between the client and the server which may be induced by polling the
+ * battery level characteristic value.
+ *
+ * @par usage
+ *
+ * When this class is instantiated it adds a Battery service in the GattServer.
+ *
+ * The application code can use the function updateBatteryLevel() to update the
+ * charge level exposed by the service and notify subscribed client that the
+ * value changed.
+ *
+ * @note Specification of the Battery service can be found here:
+ * https://www.bluetooth.com/specifications/gatt
+ *
+ * @important Multiple instances of this Battery service are not supported.
+ */
 class BatteryService {
 public:
     /**
-     * @param[in] _ble
+     * Instantiate a battery service.
-     *               BLE object for the underlying controller.
+     *
-     * @param[in] level
+     * The construction of a BatteryService adds a GATT battery service in @p
-     *               8bit batterly level. Usually used to represent percentage of batterly charge remaining.
+     * _ble GattServer and sets the initial charge level of the battery to @p
+     * level.
+     *
+     * @param[in] _ble BLE device which will host the battery service.
+     * @param[in] level Initial charge level of the battery. It is a percentage
+     * where 0% means that the battery is fully discharged and 100% means that
+     * the battery is fully charged.
      */
     BatteryService(BLE &_ble, uint8_t level = 100) :
         ble(_ble),
         batteryLevel(level),
-        batteryLevelCharacteristic(GattCharacteristic::UUID_BATTERY_LEVEL_CHAR, &batteryLevel, GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY) {
+        batteryLevelCharacteristic(
-
+            GattCharacteristic::UUID_BATTERY_LEVEL_CHAR,
-        GattCharacteristic *charTable[] = {&batteryLevelCharacteristic};
+            &batteryLevel,
-        GattService         batteryService(GattService::UUID_BATTERY_SERVICE, charTable, sizeof(charTable) / sizeof(GattCharacteristic *));
+            GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY
+        )
+    {
+        MBED_ASSERT(level <= 100);
+        GattCharacteristic *charTable[] = { &batteryLevelCharacteristic };
+        GattService batteryService(
+            GattService::UUID_BATTERY_SERVICE,
+            charTable,
+            sizeof(charTable) / sizeof(GattCharacteristic *)
+        );
 
         ble.addService(batteryService);
     }
 
     /**
-     * @brief Update the battery level with a new value. Valid values lie between 0 and 100,
+     * Update the battery charge level exposed by the service.
-     * anything outside this range will be ignored.
      *
-     * @param newLevel
+     * The server will send a notification of the new value to clients that have
-     *              Update to battery level.
+     * subscribed to the battery level characteristic updates and clients
+     * reading the charge level after the update will obtain the updated value.
+     *
+     * @param newLevel Charge level of the battery. It is a percentage of the
+     * remaining charge between 0% and 100%.
+     *
+     * @important This function must be called in the execution context of the
+     * BLE stack.
      */
-    void updateBatteryLevel(uint8_t newLevel) {
+    void updateBatteryLevel(uint8_t newLevel)
+    {
+        MBED_ASSERT(level <= 100);
         batteryLevel = newLevel;
-        ble.gattServer().write(batteryLevelCharacteristic.getValueHandle(), &batteryLevel, 1);
+        ble.gattServer().write(
+            batteryLevelCharacteristic.getValueHandle(),
+            &batteryLevel,
+            1
+        );
     }
 
 protected:
     /**
-     * A reference to the underlying BLE instance that this object is attached to.
+     * Reference to the underlying BLE instance that this object is attached to.
-     * The services and characteristics will be registered in this BLE instance.
+     *
+     * The services and characteristics will be registered in the GattServer of
+     * this BLE instance.
      */
     BLE &ble;
 
@@ -67,11 +122,11 @@ protected:
      * The current battery level represented as an integer from 0% to 100%.
      */
     uint8_t batteryLevel;
+
     /**
-     * A ReadOnlyGattCharacteristic that allows access to the peer device to the
+     * The GATT characteristic which expose the charge level.
-     * batteryLevel value through BLE.
      */
     ReadOnlyGattCharacteristic<uint8_t> batteryLevelCharacteristic;
 };
 
-#endif /* #ifndef __BLE_BATTERY_SERVICE_H__*/
+#endif /* #ifndef MBED_BLE_BATTERY_SERVICE_H__*/