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 /* MBED_DEPRECATED */
20 #warning "These services are deprecated and will be removed. Please see services.md for details about replacement services."
21 
22 #ifndef MBED_BLE_BATTERY_SERVICE_H__
23 #define MBED_BLE_BATTERY_SERVICE_H__
24 
25 #if BLE_FEATURE_GATT_SERVER
26 
27 #include "platform/mbed_assert.h"
28 
29 #include "ble/BLE.h"
30 #include "ble/Gap.h"
31 #include "ble/GattServer.h"
32 
33 /**
34  * BLE Battery service.
35  *
36  * @par purpose
37  *
38  * The battery service exposes the charge level of the battery of the device.
39  * This information is exposed as a percentage from 0% to 100%; a value of 0%
40  * represents a fully discharged battery, and a value of 100% represents a
41  * fully charged battery.
42  *
43  * Clients can read the current charge level and subscribe to server initiated
44  * updates of the charge level. The server delivers these updates to the subscribed
45  * client in a notification packet.
46  *
47  * The subscription mechanism is useful to save power; it avoids unecessary data
48  * traffic between the client and the server, which may be induced by polling the
49  * battery level characteristic value.
50  *
51  * @par usage
52  *
53  * When this class is instantiated, it adds a battery service in the GattServer.
54  *
55  * The application code can use the function updateBatteryLevel() to update the
56  * charge level that the service exposes and to notify the subscribed client that the
57  * value changed.
58  *
59  * @note You can find specification of the battery service here:
60  * https://www.bluetooth.com/specifications/gatt
61  *
62  * @attention Multiple instances of this battery service are not supported.
63  */
65 public:
66  /**
67  * Instantiate a battery service.
68  *
69  * The construction of a BatteryService adds a GATT battery service in @p
70  * _ble GattServer and sets the initial charge level of the battery to @p
71  * level.
72  *
73  * @param[in] _ble BLE device which will host the battery service.
74  * @param[in] level Initial charge level of the battery. It is a percentage
75  * where 0% means that the battery is fully discharged and 100% means that
76  * the battery is fully charged.
77  */
78  BatteryService(BLE &_ble, uint8_t level = 100) :
79  ble(_ble),
80  batteryLevel(level),
82  GattCharacteristic::UUID_BATTERY_LEVEL_CHAR,
83  &batteryLevel,
84  GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_NOTIFY
85  )
86  {
87  MBED_ASSERT(level <= 100);
89  GattService batteryService(
91  charTable,
92  sizeof(charTable) / sizeof(charTable[0])
93  );
94 
95  ble.gattServer().addService(batteryService);
96  }
97 
98  /**
99  * Update the battery charge level that the service exposes.
100  *
101  * The server sends a notification of the new value to clients that have
102  * subscribed to the battery level characteristic updates, and clients
103  * reading the charge level after the update obtain the updated value.
104  *
105  * @param newLevel Charge level of the battery. It is a percentage of the
106  * remaining charge between 0% and 100%.
107  *
108  * @attention This function must be called in the execution context of the
109  * BLE stack.
110  */
111  void updateBatteryLevel(uint8_t newLevel)
112  {
113  MBED_ASSERT(newLevel <= 100);
114  batteryLevel = newLevel;
115  ble.gattServer().write(
117  &batteryLevel,
118  1
119  );
120  }
121 
122 protected:
123  /**
124  * Reference to the underlying BLE instance that this object is attached to.
125  *
126  * The services and characteristics are registered in the GattServer of
127  * this BLE instance.
128  */
130 
131  /**
132  * The current battery level represented as an integer from 0% to 100%.
133  */
134  uint8_t batteryLevel;
135 
136  /**
137  * The GATT characteristic, which exposes the charge level.
138  */
140 };
141 
142 #endif // BLE_FEATURE_GATT_SERVER
143 
144 #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.
uint8_t batteryLevel
The current battery level represented as an integer from 0% to 100%.
UUID of the Battery service.
#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.