1 /* 2 * Copyright (C) 2024 BlueKitchen GmbH 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions 6 * are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 3. Neither the name of the copyright holders nor the names of 14 * contributors may be used to endorse or promote products derived 15 * from this software without specific prior written permission. 16 * 4. Any redistribution, use, or modification is done solely for 17 * personal benefit and not for any commercial purpose or for 18 * monetary gain. 19 * 20 * THIS SOFTWARE IS PROVIDED BY BLUEKITCHEN GMBH AND CONTRIBUTORS 21 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 23 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BLUEKITCHEN 24 * GMBH OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 25 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 26 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 27 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 28 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF 30 * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31 * SUCH DAMAGE. 32 * 33 * Please inquire about commercial licensing options at 34 * [email protected] 35 * 36 */ 37 38 /** 39 * @title Battery Service Server v1.1 40 * 41 */ 42 43 #ifndef BATTERY_SERVICE_V1_SERVER_H 44 #define BATTERY_SERVICE_V1_SERVER_H 45 46 #include <stdint.h> 47 48 #if defined __cplusplus 49 extern "C" { 50 #endif 51 52 /** 53 * @text The Battery Service allows to query your device's battery level in a standardized way. 54 * 55 * To use with your application, add `#import <battery_service.gatt>` to your .gatt file. 56 * After adding it to your .gatt file, you call *battery_service_server_init(value)* with the 57 * current value of your battery. The valid range for the battery level is 0-100. 58 * 59 * If the battery level changes, you can call *battery_service_server_set_battery_value(value)*. 60 * The service supports sending Notifications if the client enables them. 61 */ 62 63 typedef enum { 64 BAS_CHARACTERISTIC_INDEX_BATTERY_LEVEL = 0, 65 BAS_CHARACTERISTIC_INDEX_BATTERY_LEVEL_STATUS, 66 BAS_CHARACTERISTIC_INDEX_ESTIMATED_SERVICE_DATE, 67 BAS_CHARACTERISTIC_INDEX_BATTERY_CRITCAL_STATUS, 68 BAS_CHARACTERISTIC_INDEX_BATTERY_ENERGY_STATUS, 69 BAS_CHARACTERISTIC_INDEX_BATTERY_TIME_STATUS, 70 BAS_CHARACTERISTIC_INDEX_BATTERY_HEALTH_STATUS, 71 BAS_CHARACTERISTIC_INDEX_BATTERY_HEALTH_INFORMATION, 72 BAS_CHARACTERISTIC_INDEX_BATTERY_INFORMATION, 73 BAS_CHARACTERISTIC_INDEX_MANUFACTURER_NAME_STRING, 74 BAS_CHARACTERISTIC_INDEX_MODEL_NUMBER_STRING, 75 BAS_CHARACTERISTIC_INDEX_SERIAL_NUMBER_STRING, 76 BAS_CHARACTERISTIC_INDEX_NUM 77 } bas_characteristic_index_t; 78 79 // ORG_BLUETOOTH_CHARACTERISTIC_BATTERY_ENERGY_STATUS flags: 80 #define BATTERY_ENERGY_STATUS_BITMASK_EXTERNAL_SOURCE_POWER_PRESENT 0x01 81 #define BATTERY_ENERGY_STATUS_BITMASK_PRESENT_VOLTAGE_PRESENT 0x02 82 #define BATTERY_ENERGY_STATUS_BITMASK_AVAILABLE_ENERGY_PRESENT 0x04 83 #define BATTERY_ENERGY_STATUS_BITMASK_AVAILABLE_BATTERY_CAPACITY_PRESENT 0x08 84 #define BATTERY_ENERGY_STATUS_BITMASK_CHARGE_RATE_PRESENT 0x10 85 #define BATTERY_ENERGY_STATUS_BITMASK_AVAILABLE_ENERGY_AT_LAST_CHARGE_PRESENT 0x20 86 #define BATTERY_ENERGY_STATUS_BITMASK_RFU 0x40 87 88 #define BATTERY_LEVEL_STATUS_BITMASK_IDENTIFIER_PRESENT 0x01 89 #define BATTERY_LEVEL_STATUS_BITMASK_BATTERY_LEVEL_PRESENT 0x02 90 #define BATTERY_LEVEL_STATUS_BITMASK_ADDITIONAL_STATUS_PRESENT 0x04 91 #define BATTERY_LEVEL_STATUS_BITMASK_RFU 0x08 92 93 #define BATTERY_LEVEL_POWER_STATE_BITMASK_EXTERNAL_BATTERY_PRESENT 0x0001 // 0 = No, 1 = Yes 94 #define BATTERY_LEVEL_POWER_STATE_BITMASK_WIRED_EXTERNAL_POWER_SOURCE_CONNECTED 0x0004 // 0 = No, 1 = Yes, 2 = Unknown, 3 = RFU 95 #define BATTERY_LEVEL_POWER_STATE_BITMASK_WIRELESS_EXTERNAL_POWER_SOURCE_CONNECTED 0x0010 // 0 = No, 1 = Yes, 2 = Unknown, 3 = RFU 96 #define BATTERY_LEVEL_POWER_STATE_BITMASK_BATTERY_CHARGE_STATE 0x0040 // 0 = Unknown, 1 = Charging, 2 = Discharging: Active 3 = Discharging: Inactive 97 #define BATTERY_LEVEL_POWER_STATE_BITMASK_BATTERY_CHARGE_LEVEL 0x0100 // 0 = Unknown, 1 = Good, 2 = Low, 3 = Critical 98 #define BATTERY_LEVEL_POWER_STATE_BITMASK_CHARGING_TYPE 0x0400 // 0 = Unknown or Not Charging 1 = Constant Current, 2 = Constant Voltage, 3 = Trickle, 4 = Float, 5–7 = RFU 99 #define BATTERY_LEVEL_POWER_STATE_BITMASK_CHARGING_FAULT_REASON 0x2000 // Bit 12: Battery, Bit 13: External Power source, Bit 14: Other 100 #define BATTERY_LEVEL_POWER_STATE_BITMASK_RFU 0x4000 101 102 #define BATTERY_LEVEL_ADDITIONAL_STATUS_BITMASK_SERVICE_REQUIRED 0x01 // 0 = No, 1 = Yes, 2 = Unknown, 3 = RFU 103 #define BATTERY_LEVEL_ADDITIONAL_STATUS_BITMASK_BATTERY_FAULT 0x02 // 0 = No or Unknown, 1 = Yes 104 #define BATTERY_LEVEL_ADDITIONAL_STATUS_BITMASK_RFU 0x04 105 106 #define BATTERY_CRITCAL_STATUS_BITMASK_CRITICAL_POWER_STATE 0x01 107 #define BATTERY_CRITCAL_STATUS_BITMASK_IMMEDIATE_SERVICE_REQUIRED 0x02 108 #define BATTERY_CRITCAL_STATUS_BITMASK_RFU 0x04 109 110 #define BATTERY_TIME_STATUS_BITMASK_TIME_UNTIL_DISCHARGED_ON_STANDBY_PRESENT 0x01 111 #define BATTERY_TIME_STATUS_BITMASK_TIME_UNTIL_RECHARGED_PRESENT 0x02 112 #define BATTERY_TIME_STATUS_BITMASK_RFU 0x04 113 114 #define BATTERY_HEALTH_STATUS_BITMASK_HEALTH_SUMMARY_PRESENT 0x01 115 #define BATTERY_HEALTH_STATUS_BITMASK_CYCLE_COUNT_PRESENT 0x02 116 #define BATTERY_HEALTH_STATUS_BITMASK_CURRENT_TEMPERATURE_PRESENT 0x04 117 #define BATTERY_HEALTH_STATUS_BITMASK_DEEP_DISCHARGE_COUNT_PRESENT 0x08 118 #define BATTERY_HEALTH_STATUS_BITMASK_RFU 0x10 119 120 #define BATTERY_HEALTH_INFORMATION_BITMASK_CYCLE_COUNT_DESIGNED_LIFETIME_PRESENT 0x01 121 #define BATTERY_HEALTH_INFORMATION_BITMASK_DESIGNED_OPERATING_TEMPERATURE_PRESENT 0x02 122 #define BATTERY_HEALTH_INFORMATION_BITMASK_RFU 0x04 123 124 #define BATTERY_INFORMATION_BITMASK_MANUFACTURE_DATE_PRESENT 0x0001 125 #define BATTERY_INFORMATION_BITMASK_EXPIRATION_DATE_PRESENT 0x0002 126 #define BATTERY_INFORMATION_BITMASK_DESIGNED_CAPACITY_PRESENT 0x0004 127 #define BATTERY_INFORMATION_BITMASK_LOW_ENERGY_PRESENT 0x0008 128 #define BATTERY_INFORMATION_BITMASK_CRITICAL_ENERGY_PRESENT 0x0010 129 #define BATTERY_INFORMATION_BITMASK_CHEMISTRY_PRESENT 0x0020 130 #define BATTERY_INFORMATION_BITMASK_NOMINAL_VOLTAGE_PRESENT 0x0040 131 #define BATTERY_INFORMATION_BITMASK_AGGREGATION_GROUP_PRESENT 0x0080 132 #define BATTERY_INFORMATION_BITMASK_RFU 0x0100 133 134 #define BATTERY_INFROMATION_FEATURE_BITMASK_REPLACEABLE 0x01 135 #define BATTERY_INFROMATION_FEATURE_BITMASK_RECHARGEABLE 0x02 136 #define BATTERY_INFROMATION_FEATURE_BITMASK_RFU 0x04 137 138 struct battery_service_v1; 139 140 typedef struct { 141 uint16_t year; 142 uint8_t month; 143 uint8_t day; 144 } btstack_utc_date_t; 145 146 typedef struct { 147 uint8_t hours; 148 uint8_t minutes; 149 uint8_t seconds; 150 } btstack_utc_time_t; 151 152 typedef struct { 153 hci_con_handle_t con_handle; 154 155 btstack_context_callback_registration_t scheduled_tasks_callback; 156 uint8_t scheduled_tasks; 157 uint16_t configurations[BAS_CHARACTERISTIC_INDEX_NUM]; 158 159 struct battery_service_v1 * service; 160 } battery_service_v1_server_connection_t; 161 162 typedef struct { 163 uint16_t value_handle; 164 uint16_t client_configuration_handle; 165 } bas_characteristic_t; 166 167 typedef struct { 168 uint8_t flags; 169 uint16_t power_state_flags; 170 171 uint16_t identifier; 172 uint8_t battery_level; 173 uint8_t additional_status_flags; 174 } battery_level_status_t; 175 176 typedef struct { 177 uint8_t flags; 178 uint16_t external_source_power_medfloat16; 179 uint16_t present_voltage_medfloat16; 180 uint16_t available_energy_medfloat16; 181 uint16_t available_battery_capacity_medfloat16; 182 uint16_t charge_rate_medfloat16; 183 uint16_t available_energy_at_last_charge_medfloat16; 184 } battery_energy_status_t; 185 186 typedef struct { 187 uint8_t flags; 188 189 // A value of 0xFFFFFF represents: Unknown 190 // A value of 0xFFFFFE represents: Greater than 0xFFFFFD 191 uint32_t time_until_discharged_minutes; 192 uint32_t time_until_discharged_on_standby_minutes; 193 uint32_t time_until_recharged_minutes; 194 } battery_time_status_t; 195 196 typedef struct { 197 uint8_t flags; 198 199 uint8_t summary; // Allowed range is 0 to 100. 200 uint16_t cycle_count; 201 int8_t current_temperature_degree_celsius; 202 uint16_t deep_discharge_count; 203 } battery_health_status_t; 204 205 typedef struct { 206 uint8_t flags; 207 uint16_t cycle_count_designed_lifetime; 208 209 // A raw value of 0x7F represents: Greater than 126. 210 // A raw value of 0x80 represents: Less than -127. 211 int8_t min_designed_operating_temperature_degree_celsius; 212 int8_t max_designed_operating_temperature_degree_celsius; 213 } battery_health_information_t; 214 215 typedef struct { 216 uint16_t flags; 217 uint8_t features; 218 219 uint32_t manufacture_date_days; 220 uint32_t expiration_date_days; 221 222 uint16_t designed_capacity_kWh_medfloat16; 223 uint16_t low_energy_kWh_medfloat16; 224 uint16_t critical_energy_kWh_medfloat16; 225 uint8_t chemistry; 226 uint16_t nominal_voltage_medfloat16; 227 uint8_t aggregation_group; // 0: not in group, 255: RFU 228 } battery_information_t; 229 230 typedef struct battery_service_v1 { 231 btstack_linked_item_t item; 232 233 // service 234 uint16_t start_handle; 235 uint16_t end_handle; 236 uint8_t index; 237 238 att_service_handler_t service_handler; 239 240 bas_characteristic_t characteristics[BAS_CHARACTERISTIC_INDEX_NUM]; 241 242 // ORG_BLUETOOTH_CHARACTERISTIC_BATTERY_LEVEL 243 uint8_t battery_value; 244 245 // ORG_BLUETOOTH_CHARACTERISTIC_BATTERY_LEVEL_STATUS 246 const battery_level_status_t * level_status; 247 248 // ORG_BLUETOOTH_CHARACTERISTIC_ESTIMATED_SERVICE_DATE 249 uint32_t estimated_service_date_days; 250 251 // ORG_BLUETOOTH_CHARACTERISTIC_BATTERY_CRITCAL_STATUS 252 uint8_t battery_critcal_status_flags; 253 254 // ORG_BLUETOOTH_CHARACTERISTIC_BATTERY_ENERGY_STATUS 255 const battery_energy_status_t * energy_status; 256 257 // ORG_BLUETOOTH_CHARACTERISTIC_BATTERY_TIME_STATUS 258 const battery_time_status_t * time_status; 259 260 // ORG_BLUETOOTH_CHARACTERISTIC_BATTERY_HEALTH_STATUS 261 const battery_health_status_t * health_status; 262 263 // ORG_BLUETOOTH_CHARACTERISTIC_BATTERY_HEALTH_INFORMATION 264 const battery_health_information_t * health_information; 265 266 // ORG_BLUETOOTH_CHARACTERISTIC_BATTERY_INFORMATION 267 const battery_information_t * information; 268 269 // ORG_BLUETOOTH_CHARACTERISTIC_MANUFACTURER_NAME_STRING 270 const char * manufacturer_name; 271 272 // ORG_BLUETOOTH_CHARACTERISTIC_MODEL_NUMBER_STRING 273 const char * model_number; 274 275 // ORG_BLUETOOTH_CHARACTERISTIC_SERIAL_NUMBER_STRING 276 const char * serial_number; 277 278 uint8_t connections_max_num; 279 battery_service_v1_server_connection_t * connections; 280 } battery_service_v1_t; 281 282 /* API_START */ 283 284 /** 285 * @brief Init Battery Service Server with ATT DB 286 */ 287 void battery_service_v1_server_init(void); 288 289 void battery_service_v1_server_register(battery_service_v1_t *service, battery_service_v1_server_connection_t *connections, uint8_t connection_max_num); 290 291 void battery_service_v1_server_deregister(battery_service_v1_t *service); 292 /** 293 * @brief Update battery value 294 * @note triggers notifications if subscribed 295 * @param battery_value in range 0-100 296 */ 297 void battery_service_v1_server_set_battery_value(battery_service_v1_t * service, uint8_t value); 298 299 void battery_service_v1_server_deinit(void); 300 301 /* API_END */ 302 303 #if defined __cplusplus 304 } 305 #endif 306 307 #endif 308 309