BatteryService.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef MBED_BLE_BATTERY_SERVICE_H__
00018 #define MBED_BLE_BATTERY_SERVICE_H__
00019 
00020 #if BLE_FEATURE_GATT_SERVER
00021 
00022 #include "platform/mbed_assert.h"
00023 #include "ble/BLE.h"
00024 
00025 /**
00026  * BLE Battery service.
00027  *
00028  * @par purpose
00029  *
00030  * The battery service exposes the charge level of the battery of the device.
00031  * This information is exposed as a percentage from 0% to 100%; a value of 0%
00032  * represents a fully discharged battery, and a value of 100% represents a
00033  * fully charged battery.
00034  *
00035  * Clients can read the current charge level and subscribe to server initiated
00036  * updates of the charge level. The server delivers these updates to the subscribed
00037  * client in a notification packet.
00038  *
00039  * The subscription mechanism is useful to save power; it avoids unecessary data
00040  * traffic between the client and the server, which may be induced by polling the
00041  * battery level characteristic value.
00042  *
00043  * @par usage
00044  *
00045  * When this class is instantiated, it adds a battery service in the GattServer.
00046  *
00047  * The application code can use the function updateBatteryLevel() to update the
00048  * charge level that the service exposes and to notify the subscribed client that the
00049  * value changed.
00050  *
00051  * @note You can find specification of the battery service here:
00052  * https://www.bluetooth.com/specifications/gatt
00053  *
00054  * @attention Multiple instances of this battery service are not supported.
00055  */
00056 class BatteryService {
00057 public:
00058     /**
00059      * Instantiate a battery service.
00060      *
00061      * The construction of a BatteryService adds a GATT battery service in @p
00062      * _ble GattServer and sets the initial charge level of the battery to @p
00063      * level.
00064      *
00065      * @param[in] _ble BLE device which will host the battery service.
00066      * @param[in] level Initial charge level of the battery. It is a percentage
00067      * where 0% means that the battery is fully discharged and 100% means that
00068      * the battery is fully charged.
00069      */
00070     BatteryService(BLE &_ble, uint8_t level = 100) :
00071         ble(_ble),
00072         batteryLevel(level),
00073         batteryLevelCharacteristic(
00074             GattCharacteristic::UUID_BATTERY_LEVEL_CHAR,
00075             &batteryLevel,
00076             GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY
00077         )
00078     {
00079         MBED_ASSERT(level <= 100);
00080         GattCharacteristic *charTable[] = { &batteryLevelCharacteristic };
00081         GattService batteryService(
00082             GattService::UUID_BATTERY_SERVICE,
00083             charTable,
00084             sizeof(charTable) / sizeof(GattCharacteristic *)
00085         );
00086 
00087         ble.gattServer().addService(batteryService);
00088     }
00089 
00090     /**
00091      * Update the battery charge level that the service exposes.
00092      *
00093      * The server sends a notification of the new value to clients that have
00094      * subscribed to the battery level characteristic updates, and clients
00095      * reading the charge level after the update obtain the updated value.
00096      *
00097      * @param newLevel Charge level of the battery. It is a percentage of the
00098      * remaining charge between 0% and 100%.
00099      *
00100      * @attention This function must be called in the execution context of the
00101      * BLE stack.
00102      */
00103     void updateBatteryLevel(uint8_t newLevel)
00104     {
00105         MBED_ASSERT(newLevel <= 100);
00106         batteryLevel = newLevel;
00107         ble.gattServer().write(
00108             batteryLevelCharacteristic.getValueHandle(),
00109             &batteryLevel,
00110             1
00111         );
00112     }
00113 
00114 protected:
00115     /**
00116      * Reference to the underlying BLE instance that this object is attached to.
00117      *
00118      * The services and characteristics are registered in the GattServer of
00119      * this BLE instance.
00120      */
00121     BLE &ble;
00122 
00123     /**
00124      * The current battery level represented as an integer from 0% to 100%.
00125      */
00126     uint8_t batteryLevel;
00127 
00128     /**
00129      * The GATT characteristic, which exposes the charge level.
00130      */
00131     ReadOnlyGattCharacteristic<uint8_t>  batteryLevelCharacteristic;
00132 };
00133 
00134 #endif // BLE_FEATURE_GATT_SERVER
00135 
00136 #endif /* #ifndef MBED_BLE_BATTERY_SERVICE_H__*/