Line data Source code
1 0 : /*
2 : * Copyright (c) 2024 Demant A/S
3 : * Copyright (c) 2018 Nordic Semiconductor ASA
4 : * Copyright (c) 2016 Intel Corporation
5 : *
6 : * SPDX-License-Identifier: Apache-2.0
7 : */
8 :
9 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_BAS_H_
10 : #define ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_BAS_H_
11 :
12 : /**
13 : * @brief Battery Service (BAS)
14 : * @defgroup bt_bas Battery Service (BAS)
15 : * @ingroup bluetooth
16 : * @{
17 : *
18 : * [Experimental] Users should note that the APIs can change
19 : * as a part of ongoing development.
20 : */
21 :
22 : #include <stdint.h>
23 : #include <zephyr/sys/util.h>
24 :
25 : #ifdef __cplusplus
26 : extern "C" {
27 : #endif
28 :
29 : /**
30 : * @brief Battery Critical Status Characteristic flags.
31 : *
32 : * Enumeration for the flags indicating the presence
33 : * of various fields in the Battery Critical Status characteristic.
34 : */
35 1 : enum bt_bas_bcs_flags {
36 : /** Battery Critical Status Bit 0: Critical Power State */
37 : BT_BAS_BCS_BATTERY_CRITICAL_STATE = BIT(0),
38 :
39 : /** Battery Critical Status Bit 1: Immediate Service Required */
40 : BT_BAS_BCS_IMMEDIATE_SERVICE_REQUIRED = BIT(1),
41 : };
42 :
43 : /**
44 : * @brief Battery Level Status Characteristic flags.
45 : *
46 : * Enumeration for the flags indicating the presence
47 : * of various fields in the Battery Level Status characteristic.
48 : */
49 1 : enum bt_bas_bls_flags {
50 : /** Bit indicating that the Battery Level Status identifier is present. */
51 : BT_BAS_BLS_FLAG_IDENTIFIER_PRESENT = BIT(0),
52 :
53 : /** Bit indicating that the Battery Level is present. */
54 : BT_BAS_BLS_FLAG_BATTERY_LEVEL_PRESENT = BIT(1),
55 :
56 : /** Bit indicating that additional status information is present. */
57 : BT_BAS_BLS_FLAG_ADDITIONAL_STATUS_PRESENT = BIT(2),
58 : };
59 :
60 : /** @brief Battery Present Status
61 : *
62 : * Enumeration for the presence of the battery.
63 : */
64 1 : enum bt_bas_bls_battery_present {
65 : /** Battery is not present. */
66 : BT_BAS_BLS_BATTERY_NOT_PRESENT = 0,
67 :
68 : /** Battery is present. */
69 : BT_BAS_BLS_BATTERY_PRESENT = 1
70 : };
71 :
72 : /** @brief Wired External Power Source Status
73 : *
74 : * Enumeration for the status of the wired external power source.
75 : */
76 1 : enum bt_bas_bls_wired_power_source {
77 : /** Wired external power source is not connected. */
78 : BT_BAS_BLS_WIRED_POWER_NOT_CONNECTED = 0,
79 :
80 : /** Wired external power source is connected. */
81 : BT_BAS_BLS_WIRED_POWER_CONNECTED = 1,
82 :
83 : /** Wired external power source status is unknown. */
84 : BT_BAS_BLS_WIRED_POWER_UNKNOWN = 2
85 : };
86 :
87 : /** @brief Wireless External Power Source Status
88 : *
89 : * Enumeration for the status of the wireless external power source.
90 : */
91 1 : enum bt_bas_bls_wireless_power_source {
92 : /** Wireless external power source is not connected. */
93 : BT_BAS_BLS_WIRELESS_POWER_NOT_CONNECTED = 0,
94 :
95 : /** Wireless external power source is connected. */
96 : BT_BAS_BLS_WIRELESS_POWER_CONNECTED = 1,
97 :
98 : /** Wireless external power source status is unknown. */
99 : BT_BAS_BLS_WIRELESS_POWER_UNKNOWN = 2
100 : };
101 :
102 : /** @brief Battery Charge State
103 : *
104 : * Enumeration for the charge state of the battery.
105 : */
106 1 : enum bt_bas_bls_battery_charge_state {
107 : /** Battery charge state is unknown. */
108 : BT_BAS_BLS_CHARGE_STATE_UNKNOWN = 0,
109 :
110 : /** Battery is currently charging. */
111 : BT_BAS_BLS_CHARGE_STATE_CHARGING = 1,
112 :
113 : /** Battery is discharging actively. */
114 : BT_BAS_BLS_CHARGE_STATE_DISCHARGING_ACTIVE = 2,
115 :
116 : /** Battery is discharging but inactive. */
117 : BT_BAS_BLS_CHARGE_STATE_DISCHARGING_INACTIVE = 3
118 : };
119 :
120 : /** @brief Battery Charge Level
121 : *
122 : * Enumeration for the level of charge in the battery.
123 : */
124 1 : enum bt_bas_bls_battery_charge_level {
125 : /** Battery charge level is unknown. */
126 : BT_BAS_BLS_CHARGE_LEVEL_UNKNOWN = 0,
127 :
128 : /** Battery charge level is good. */
129 : BT_BAS_BLS_CHARGE_LEVEL_GOOD = 1,
130 :
131 : /** Battery charge level is low. */
132 : BT_BAS_BLS_CHARGE_LEVEL_LOW = 2,
133 :
134 : /** Battery charge level is critical. */
135 : BT_BAS_BLS_CHARGE_LEVEL_CRITICAL = 3
136 : };
137 :
138 : /** @brief Battery Charge Type
139 : *
140 : * Enumeration for the type of charging applied to the battery.
141 : */
142 1 : enum bt_bas_bls_battery_charge_type {
143 : /** Battery charge type is unknown or not charging. */
144 : BT_BAS_BLS_CHARGE_TYPE_UNKNOWN = 0,
145 :
146 : /** Battery is charged using constant current. */
147 : BT_BAS_BLS_CHARGE_TYPE_CONSTANT_CURRENT = 1,
148 :
149 : /** Battery is charged using constant voltage. */
150 : BT_BAS_BLS_CHARGE_TYPE_CONSTANT_VOLTAGE = 2,
151 :
152 : /** Battery is charged using trickle charge. */
153 : BT_BAS_BLS_CHARGE_TYPE_TRICKLE = 3,
154 :
155 : /** Battery is charged using float charge. */
156 : BT_BAS_BLS_CHARGE_TYPE_FLOAT = 4
157 : };
158 :
159 : /** @brief Charging Fault Reason
160 : *
161 : * Enumeration for the reasons of charging faults.
162 : */
163 1 : enum bt_bas_bls_charging_fault_reason {
164 : /** No charging fault. */
165 : BT_BAS_BLS_FAULT_REASON_NONE = 0,
166 :
167 : /** Charging fault due to battery issue. */
168 : BT_BAS_BLS_FAULT_REASON_BATTERY = BIT(0),
169 :
170 : /** Charging fault due to external power source issue. */
171 : BT_BAS_BLS_FAULT_REASON_EXTERNAL_POWER = BIT(1),
172 :
173 : /** Charging fault for other reasons. */
174 : BT_BAS_BLS_FAULT_REASON_OTHER = BIT(2)
175 : };
176 :
177 : /** @brief Service Required Status
178 : *
179 : * Enumeration for whether the service is required.
180 : */
181 1 : enum bt_bas_bls_service_required {
182 : /** Service is not required. */
183 : BT_BAS_BLS_SERVICE_REQUIRED_FALSE = 0,
184 :
185 : /** Service is required. */
186 : BT_BAS_BLS_SERVICE_REQUIRED_TRUE = 1,
187 :
188 : /** Service requirement is unknown. */
189 : BT_BAS_BLS_SERVICE_REQUIRED_UNKNOWN = 2
190 : };
191 :
192 : /** @brief Battery Fault Status
193 : *
194 : * Enumeration for the fault status of the battery.
195 : */
196 1 : enum bt_bas_bls_battery_fault {
197 : /** No battery fault. */
198 : BT_BAS_BLS_BATTERY_FAULT_NO = 0,
199 :
200 : /** Battery fault present. */
201 : BT_BAS_BLS_BATTERY_FAULT_YES = 1
202 : };
203 :
204 : /** @brief Read battery level value.
205 : *
206 : * Read the characteristic value of the battery level
207 : *
208 : * @return The battery level in percent.
209 : */
210 1 : uint8_t bt_bas_get_battery_level(void);
211 :
212 : /** @brief Update battery level value.
213 : *
214 : * Update the characteristic value of the battery level
215 : * This will send a GATT notification to all current subscribers.
216 : *
217 : * @param level The battery level in percent.
218 : *
219 : * @return Zero in case of success and error code in case of error.
220 : */
221 1 : int bt_bas_set_battery_level(uint8_t level);
222 :
223 : /**
224 : * @brief Set the battery present status.
225 : *
226 : * @param present The battery present status to set.
227 : */
228 1 : void bt_bas_bls_set_battery_present(enum bt_bas_bls_battery_present present);
229 :
230 : /**
231 : * @brief Set the wired external power source status.
232 : *
233 : * @param source The wired external power source status to set.
234 : */
235 1 : void bt_bas_bls_set_wired_external_power_source(enum bt_bas_bls_wired_power_source source);
236 :
237 : /**
238 : * @brief Set the wireless external power source status.
239 : *
240 : * @param source The wireless external power source status to set.
241 : */
242 1 : void bt_bas_bls_set_wireless_external_power_source(enum bt_bas_bls_wireless_power_source source);
243 :
244 : /**
245 : * @brief Set the battery charge state.
246 : *
247 : * @param state The battery charge state to set.
248 : */
249 1 : void bt_bas_bls_set_battery_charge_state(enum bt_bas_bls_battery_charge_state state);
250 :
251 : /**
252 : * @brief Set the battery charge level.
253 : *
254 : * @param level The battery charge level to set.
255 : */
256 1 : void bt_bas_bls_set_battery_charge_level(enum bt_bas_bls_battery_charge_level level);
257 :
258 : /**
259 : * @brief Set the battery charge type.
260 : *
261 : * @param type The battery charge type to set.
262 : */
263 1 : void bt_bas_bls_set_battery_charge_type(enum bt_bas_bls_battery_charge_type type);
264 :
265 : /**
266 : * @brief Set the charging fault reason.
267 : *
268 : * @param reason The charging fault reason to set.
269 : */
270 1 : void bt_bas_bls_set_charging_fault_reason(enum bt_bas_bls_charging_fault_reason reason);
271 :
272 : /**
273 : * @brief Set the identifier of the battery.
274 : *
275 : * @kconfig_dep{CONFIG_BT_BAS_BLS_IDENTIFIER_PRESENT}
276 : *
277 : * @param identifier Identifier to set.
278 : */
279 1 : void bt_bas_bls_set_identifier(uint16_t identifier);
280 :
281 : /**
282 : * @brief Set the service required status.
283 : *
284 : * @kconfig_dep{CONFIG_BT_BAS_BLS_ADDITIONAL_STATUS_PRESENT}
285 : *
286 : * @param value Service required status to set.
287 : */
288 1 : void bt_bas_bls_set_service_required(enum bt_bas_bls_service_required value);
289 :
290 : /**
291 : * @brief Set the battery fault status.
292 : *
293 : * @kconfig_dep{CONFIG_BT_BAS_BLS_ADDITIONAL_STATUS_PRESENT}
294 : *
295 : * @param value Battery fault status to set.
296 : */
297 1 : void bt_bas_bls_set_battery_fault(enum bt_bas_bls_battery_fault value);
298 :
299 : #ifdef __cplusplus
300 : }
301 : #endif
302 :
303 : /**
304 : * @}
305 : */
306 :
307 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_BAS_H_ */
|
