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