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