From 423cd23ec0791283fdf6866e04421f008b333522 Mon Sep 17 00:00:00 2001 From: Vincent Coubard Date: Thu, 9 Nov 2017 18:08:32 +0000 Subject: [PATCH] BLE: Update BatteryService documentation. --- .../FEATURE_BLE/ble/services/BatteryService.h | 109 +++++++++++++----- 1 file changed, 82 insertions(+), 27 deletions(-) diff --git a/features/FEATURE_BLE/ble/services/BatteryService.h b/features/FEATURE_BLE/ble/services/BatteryService.h index 5aa419a469..3aaad9d171 100644 --- a/features/FEATURE_BLE/ble/services/BatteryService.h +++ b/features/FEATURE_BLE/ble/services/BatteryService.h @@ -14,64 +14,119 @@ * limitations under the License. */ -#ifndef __BLE_BATTERY_SERVICE_H__ -#define __BLE_BATTERY_SERVICE_H__ +#ifndef MBED_BLE_BATTERY_SERVICE_H__ +#define MBED_BLE_BATTERY_SERVICE_H__ +#include "platform/mbed_assert.h" #include "ble/BLE.h" /** -* @class BatteryService -* @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 -* Battery Level Char: https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.battery_level.xml -*/ + * BLE Battery service. + * + * @par purpose + * + * 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 - * BLE object for the underlying controller. - * @param[in] level - * 8bit batterly level. Usually used to represent percentage of batterly charge remaining. + * Instantiate a battery service. + * + * The construction of a BatteryService adds a GATT battery service in @p + * _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) { - - GattCharacteristic *charTable[] = {&batteryLevelCharacteristic}; - GattService batteryService(GattService::UUID_BATTERY_SERVICE, charTable, sizeof(charTable) / sizeof(GattCharacteristic *)); + batteryLevelCharacteristic( + GattCharacteristic::UUID_BATTERY_LEVEL_CHAR, + &batteryLevel, + 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, - * anything outside this range will be ignored. + * Update the battery charge level exposed by the service. * - * @param newLevel - * Update to battery level. + * The server will send a notification of the new value to clients that have + * 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. - * The services and characteristics will be registered in this BLE instance. + * Reference to the underlying BLE instance that this object is attached to. + * + * The services and characteristics will be registered in the GattServer of + * this BLE instance. */ BLE &ble; /** * The current battery level represented as an integer from 0% to 100%. */ - uint8_t batteryLevel; + uint8_t batteryLevel; + /** - * A ReadOnlyGattCharacteristic that allows access to the peer device to the - * batteryLevel value through BLE. + * The GATT characteristic which expose the charge level. */ ReadOnlyGattCharacteristic batteryLevelCharacteristic; }; -#endif /* #ifndef __BLE_BATTERY_SERVICE_H__*/ +#endif /* #ifndef MBED_BLE_BATTERY_SERVICE_H__*/