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 #include "platform/mbed_assert.h"
00021 #include "ble/BLE.h"
00022 
00023 /**
00024  * BLE Battery service.
00025  *
00026  * @par purpose
00027  *
00028  * The battery service exposes the charge level of the battery of the device.
00029  * This information is exposed as a percentage from 0% to 100%; a value of 0%
00030  * represents a fully discharged battery, and a value of 100% represents a
00031  * fully charged battery.
00032  *
00033  * Clients can read the current charge level and subscribe to server initiated
00034  * updates of the charge level. The server delivers these updates to the subscribed
00035  * client in a notification packet.
00036  *
00037  * The subscription mechanism is useful to save power; it avoids unecessary data
00038  * traffic between the client and the server, which may be induced by polling the
00039  * battery level characteristic value.
00040  *
00041  * @par usage
00042  *
00043  * When this class is instantiated, it adds a battery service in the GattServer.
00044  *
00045  * The application code can use the function updateBatteryLevel() to update the
00046  * charge level that the service exposes and to notify the subscribed client that the
00047  * value changed.
00048  *
00049  * @note You can find specification of the battery service here:
00050  * https://www.bluetooth.com/specifications/gatt
00051  *
00052  * @attention Multiple instances of this battery service are not supported.
00053  */
00054 class BatteryService {
00055 public:
00056     /**
00057      * Instantiate a battery service.
00058      *
00059      * The construction of a BatteryService adds a GATT battery service in @p
00060      * _ble GattServer and sets the initial charge level of the battery to @p
00061      * level.
00062      *
00063      * @param[in] _ble BLE device which will host the battery service.
00064      * @param[in] level Initial charge level of the battery. It is a percentage
00065      * where 0% means that the battery is fully discharged and 100% means that
00066      * the battery is fully charged.
00067      */
00068     BatteryService(BLE &_ble, uint8_t level = 100) :
00069         ble(_ble),
00070         batteryLevel(level),
00071         batteryLevelCharacteristic(
00072             GattCharacteristic::UUID_BATTERY_LEVEL_CHAR,
00073             &batteryLevel,
00074             GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY
00075         )
00076     {
00077         MBED_ASSERT(level <= 100);
00078         GattCharacteristic *charTable[] = { &batteryLevelCharacteristic };
00079         GattService batteryService(
00080             GattService::UUID_BATTERY_SERVICE,
00081             charTable,
00082             sizeof(charTable) / sizeof(GattCharacteristic *)
00083         );
00084 
00085         ble.addService(batteryService);
00086     }
00087 
00088     /**
00089      * Update the battery charge level that the service exposes.
00090      *
00091      * The server sends a notification of the new value to clients that have
00092      * subscribed to the battery level characteristic updates, and clients
00093      * reading the charge level after the update obtain the updated value.
00094      *
00095      * @param newLevel Charge level of the battery. It is a percentage of the
00096      * remaining charge between 0% and 100%.
00097      *
00098      * @attention This function must be called in the execution context of the
00099      * BLE stack.
00100      */
00101     void updateBatteryLevel(uint8_t newLevel)
00102     {
00103         MBED_ASSERT(newLevel <= 100);
00104         batteryLevel = newLevel;
00105         ble.gattServer().write(
00106             batteryLevelCharacteristic.getValueHandle(),
00107             &batteryLevel,
00108             1
00109         );
00110     }
00111 
00112 protected:
00113     /**
00114      * Reference to the underlying BLE instance that this object is attached to.
00115      *
00116      * The services and characteristics are registered in the GattServer of
00117      * this BLE instance.
00118      */
00119     BLE &ble;
00120 
00121     /**
00122      * The current battery level represented as an integer from 0% to 100%.
00123      */
00124     uint8_t batteryLevel;
00125 
00126     /**
00127      * The GATT characteristic, which exposes the charge level.
00128      */
00129     ReadOnlyGattCharacteristic<uint8_t>  batteryLevelCharacteristic;
00130 };
00131 
00132 #endif /* #ifndef MBED_BLE_BATTERY_SERVICE_H__*/