1 /* 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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_ */ 308
