Mistake on this page?
Report an issue in GitHub or email us
BatteryService.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2013 ARM Limited
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef MBED_BLE_BATTERY_SERVICE_H__
18 #define MBED_BLE_BATTERY_SERVICE_H__
19 
20 #if BLE_FEATURE_GATT_SERVER
21 
22 #include "platform/mbed_assert.h"
23 #include "ble/BLE.h"
24 
25 /**
26  * BLE Battery service.
27  *
28  * @par purpose
29  *
30  * The battery service exposes the charge level of the battery of the device.
31  * This information is exposed as a percentage from 0% to 100%; a value of 0%
32  * represents a fully discharged battery, and a value of 100% represents a
33  * fully charged battery.
34  *
35  * Clients can read the current charge level and subscribe to server initiated
36  * updates of the charge level. The server delivers these updates to the subscribed
37  * client in a notification packet.
38  *
39  * The subscription mechanism is useful to save power; it avoids unecessary data
40  * traffic between the client and the server, which may be induced by polling the
41  * battery level characteristic value.
42  *
43  * @par usage
44  *
45  * When this class is instantiated, it adds a battery service in the GattServer.
46  *
47  * The application code can use the function updateBatteryLevel() to update the
48  * charge level that the service exposes and to notify the subscribed client that the
49  * value changed.
50  *
51  * @note You can find specification of the battery service here:
52  * https://www.bluetooth.com/specifications/gatt
53  *
54  * @attention Multiple instances of this battery service are not supported.
55  */
57 public:
58  /**
59  * Instantiate a battery service.
60  *
61  * The construction of a BatteryService adds a GATT battery service in @p
62  * _ble GattServer and sets the initial charge level of the battery to @p
63  * level.
64  *
65  * @param[in] _ble BLE device which will host the battery service.
66  * @param[in] level Initial charge level of the battery. It is a percentage
67  * where 0% means that the battery is fully discharged and 100% means that
68  * the battery is fully charged.
69  */
70  BatteryService(BLE &_ble, uint8_t level = 100) :
71  ble(_ble),
72  batteryLevel(level),
74  GattCharacteristic::UUID_BATTERY_LEVEL_CHAR,
75  &batteryLevel,
76  GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY
77  )
78  {
79  MBED_ASSERT(level <= 100);
81  GattService batteryService(
83  charTable,
84  sizeof(charTable) / sizeof(GattCharacteristic *)
85  );
86 
87  ble.gattServer().addService(batteryService);
88  }
89 
90  /**
91  * Update the battery charge level that the service exposes.
92  *
93  * The server sends a notification of the new value to clients that have
94  * subscribed to the battery level characteristic updates, and clients
95  * reading the charge level after the update obtain the updated value.
96  *
97  * @param newLevel Charge level of the battery. It is a percentage of the
98  * remaining charge between 0% and 100%.
99  *
100  * @attention This function must be called in the execution context of the
101  * BLE stack.
102  */
103  void updateBatteryLevel(uint8_t newLevel)
104  {
105  MBED_ASSERT(newLevel <= 100);
106  batteryLevel = newLevel;
107  ble.gattServer().write(
109  &batteryLevel,
110  1
111  );
112  }
113 
114 protected:
115  /**
116  * Reference to the underlying BLE instance that this object is attached to.
117  *
118  * The services and characteristics are registered in the GattServer of
119  * this BLE instance.
120  */
122 
123  /**
124  * The current battery level represented as an integer from 0% to 100%.
125  */
126  uint8_t batteryLevel;
127 
128  /**
129  * The GATT characteristic, which exposes the charge level.
130  */
132 };
133 
134 #endif // BLE_FEATURE_GATT_SERVER
135 
136 #endif /* #ifndef MBED_BLE_BATTERY_SERVICE_H__*/
BLE Battery service.
Abstract away BLE-capable radio transceivers or SOCs.
Definition: BLE.h:139
BatteryService(BLE &_ble, uint8_t level=100)
Instantiate a battery service.
uint8_t batteryLevel
The current battery level represented as an integer from 0% to 100%.
#define MBED_ASSERT(expr)
MBED_ASSERT Declare runtime assertions: results in runtime error if condition is false.
Definition: mbed_assert.h:65
Representation of a GattServer characteristic.
GattAttribute::Handle_t getValueHandle(void) const
Get the characteristic&#39;s value attribute handle in the ATT table.
ReadOnlyGattCharacteristic< uint8_t > batteryLevelCharacteristic
The GATT characteristic, which exposes the charge level.
UUID of the Battery service.
Definition: GattService.h:49
Representation of a GattServer service.
Definition: GattService.h:38
Entry namespace for all BLE API definitions.
void updateBatteryLevel(uint8_t newLevel)
Update the battery charge level that the service exposes.
BLE & ble
Reference to the underlying BLE instance that this object is attached to.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.