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 #define BATTERY_SERVICE_MAX_STRING_LEN 32 63 64 typedef enum { 65 BAS_CHARACTERISTIC_INDEX_BATTERY_LEVEL = 0, 66 BAS_CHARACTERISTIC_INDEX_BATTERY_LEVEL_STATUS, 67 BAS_CHARACTERISTIC_INDEX_ESTIMATED_SERVICE_DATE, 68 BAS_CHARACTERISTIC_INDEX_BATTERY_CRITCAL_STATUS, 69 BAS_CHARACTERISTIC_INDEX_BATTERY_ENERGY_STATUS, 70 BAS_CHARACTERISTIC_INDEX_BATTERY_TIME_STATUS, 71 BAS_CHARACTERISTIC_INDEX_BATTERY_HEALTH_STATUS, 72 BAS_CHARACTERISTIC_INDEX_BATTERY_HEALTH_INFORMATION, 73 BAS_CHARACTERISTIC_INDEX_BATTERY_INFORMATION, 74 BAS_CHARACTERISTIC_INDEX_MANUFACTURER_NAME_STRING, 75 BAS_CHARACTERISTIC_INDEX_MODEL_NUMBER_STRING, 76 BAS_CHARACTERISTIC_INDEX_SERIAL_NUMBER_STRING, 77 BAS_CHARACTERISTIC_INDEX_NUM 78 } bas_characteristic_index_t; 79 80 // ORG_BLUETOOTH_CHARACTERISTIC_BATTERY_ENERGY_STATUS flags: 81 #define BATTERY_ENERGY_STATUS_BITMASK_EXTERNAL_SOURCE_POWER_PRESENT 0x01 82 #define BATTERY_ENERGY_STATUS_BITMASK_PRESENT_VOLTAGE_PRESENT 0x02 83 #define BATTERY_ENERGY_STATUS_BITMASK_AVAILABLE_ENERGY_PRESENT 0x04 84 #define BATTERY_ENERGY_STATUS_BITMASK_AVAILABLE_BATTERY_CAPACITY_PRESENT 0x08 85 #define BATTERY_ENERGY_STATUS_BITMASK_CHARGE_RATE_PRESENT 0x10 86 #define BATTERY_ENERGY_STATUS_BITMASK_AVAILABLE_ENERGY_AT_LAST_CHARGE_PRESENT 0x20 87 #define BATTERY_ENERGY_STATUS_BITMASK_RFU 0x40 88 89 #define BATTERY_LEVEL_STATUS_BITMASK_IDENTIFIER_PRESENT 0x01 90 #define BATTERY_LEVEL_STATUS_BITMASK_BATTERY_LEVEL_PRESENT 0x02 91 #define BATTERY_LEVEL_STATUS_BITMASK_ADDITIONAL_STATUS_PRESENT 0x04 92 #define BATTERY_LEVEL_STATUS_BITMASK_RFU 0x08 93 94 #define BATTERY_LEVEL_POWER_STATE_BITMASK_EXTERNAL_BATTERY_PRESENT 0x0001 // 0 = No, 1 = Yes 95 #define BATTERY_LEVEL_POWER_STATE_BITMASK_WIRED_EXTERNAL_POWER_SOURCE_CONNECTED 0x0004 // 0 = No, 1 = Yes, 2 = Unknown, 3 = RFU 96 #define BATTERY_LEVEL_POWER_STATE_BITMASK_WIRELESS_EXTERNAL_POWER_SOURCE_CONNECTED 0x0010 // 0 = No, 1 = Yes, 2 = Unknown, 3 = RFU 97 #define BATTERY_LEVEL_POWER_STATE_BITMASK_BATTERY_CHARGE_STATE 0x0040 // 0 = Unknown, 1 = Charging, 2 = Discharging: Active 3 = Discharging: Inactive 98 #define BATTERY_LEVEL_POWER_STATE_BITMASK_BATTERY_CHARGE_LEVEL 0x0100 // 0 = Unknown, 1 = Good, 2 = Low, 3 = Critical 99 #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 100 #define BATTERY_LEVEL_POWER_STATE_BITMASK_CHARGING_FAULT_REASON 0x2000 // Bit 12: Battery, Bit 13: External Power source, Bit 14: Other 101 #define BATTERY_LEVEL_POWER_STATE_BITMASK_RFU 0x4000 102 103 #define BATTERY_LEVEL_ADDITIONAL_STATUS_BITMASK_SERVICE_REQUIRED 0x01 // 0 = No, 1 = Yes, 2 = Unknown, 3 = RFU 104 #define BATTERY_LEVEL_ADDITIONAL_STATUS_BITMASK_BATTERY_FAULT 0x02 // 0 = No or Unknown, 1 = Yes 105 #define BATTERY_LEVEL_ADDITIONAL_STATUS_BITMASK_RFU 0x04 106 107 #define BATTERY_CRITCAL_STATUS_BITMASK_CRITICAL_POWER_STATE 0x01 108 #define BATTERY_CRITCAL_STATUS_BITMASK_IMMEDIATE_SERVICE_REQUIRED 0x02 109 #define BATTERY_CRITCAL_STATUS_BITMASK_RFU 0x04 110 111 #define BATTERY_TIME_STATUS_BITMASK_TIME_UNTIL_DISCHARGED_ON_STANDBY_PRESENT 0x01 112 #define BATTERY_TIME_STATUS_BITMASK_TIME_UNTIL_RECHARGED_PRESENT 0x02 113 #define BATTERY_TIME_STATUS_BITMASK_RFU 0x04 114 115 #define BATTERY_HEALTH_STATUS_BITMASK_HEALTH_SUMMARY_PRESENT 0x01 116 #define BATTERY_HEALTH_STATUS_BITMASK_CYCLE_COUNT_PRESENT 0x02 117 #define BATTERY_HEALTH_STATUS_BITMASK_CURRENT_TEMPERATURE_PRESENT 0x04 118 #define BATTERY_HEALTH_STATUS_BITMASK_DEEP_DISCHARGE_COUNT_PRESENT 0x08 119 #define BATTERY_HEALTH_STATUS_BITMASK_RFU 0x10 120 121 #define BATTERY_HEALTH_INFORMATION_BITMASK_CYCLE_COUNT_DESIGNED_LIFETIME_PRESENT 0x01 122 #define BATTERY_HEALTH_INFORMATION_BITMASK_DESIGNED_OPERATING_TEMPERATURE_PRESENT 0x02 123 #define BATTERY_HEALTH_INFORMATION_BITMASK_RFU 0x04 124 125 #define BATTERY_INFORMATION_BITMASK_MANUFACTURE_DATE_PRESENT 0x0001 126 #define BATTERY_INFORMATION_BITMASK_EXPIRATION_DATE_PRESENT 0x0002 127 #define BATTERY_INFORMATION_BITMASK_DESIGNED_CAPACITY_PRESENT 0x0004 128 #define BATTERY_INFORMATION_BITMASK_LOW_ENERGY_PRESENT 0x0008 129 #define BATTERY_INFORMATION_BITMASK_CRITICAL_ENERGY_PRESENT 0x0010 130 #define BATTERY_INFORMATION_BITMASK_CHEMISTRY_PRESENT 0x0020 131 #define BATTERY_INFORMATION_BITMASK_NOMINAL_VOLTAGE_PRESENT 0x0040 132 #define BATTERY_INFORMATION_BITMASK_AGGREGATION_GROUP_PRESENT 0x0080 133 #define BATTERY_INFORMATION_BITMASK_RFU 0x0100 134 135 #define BATTERY_INFROMATION_FEATURE_BITMASK_REPLACEABLE 0x01 136 #define BATTERY_INFROMATION_FEATURE_BITMASK_RECHARGEABLE 0x02 137 #define BATTERY_INFROMATION_FEATURE_BITMASK_RFU 0x04 138 139 struct battery_service_v1; 140 141 typedef struct { 142 uint16_t year; 143 uint8_t month; 144 uint8_t day; 145 } btstack_utc_date_t; 146 147 typedef struct { 148 uint8_t hours; 149 uint8_t minutes; 150 uint8_t seconds; 151 } btstack_utc_time_t; 152 153 typedef struct { 154 hci_con_handle_t con_handle; 155 156 btstack_context_callback_registration_t scheduled_tasks_callback; 157 uint8_t scheduled_tasks; 158 uint16_t configurations[BAS_CHARACTERISTIC_INDEX_NUM]; 159 160 struct battery_service_v1 * service; 161 } battery_service_v1_server_connection_t; 162 163 typedef struct { 164 uint16_t value_handle; 165 uint16_t client_configuration_handle; 166 } bas_characteristic_t; 167 168 169 typedef struct battery_service_v1 { 170 btstack_linked_item_t item; 171 172 // service 173 uint16_t start_handle; 174 uint16_t end_handle; 175 uint8_t index; 176 177 att_service_handler_t service_handler; 178 179 bas_characteristic_t characteristics[BAS_CHARACTERISTIC_INDEX_NUM]; 180 181 // ORG_BLUETOOTH_CHARACTERISTIC_BATTERY_LEVEL 182 uint8_t battery_value; 183 184 // ORG_BLUETOOTH_CHARACTERISTIC_BATTERY_LEVEL_STATUS 185 struct { 186 uint8_t flags; 187 uint16_t power_state_flags; 188 189 uint16_t identifier; 190 uint8_t battery_level; 191 uint8_t additional_status_flags; 192 } battery_level; 193 194 // ORG_BLUETOOTH_CHARACTERISTIC_ESTIMATED_SERVICE_DATE 195 uint32_t estimated_service_date_days; 196 197 // ORG_BLUETOOTH_CHARACTERISTIC_BATTERY_CRITCAL_STATUS 198 uint8_t battery_critcal_status_flags; 199 200 // ORG_BLUETOOTH_CHARACTERISTIC_BATTERY_ENERGY_STATUS 201 struct { 202 uint8_t flags; 203 uint16_t external_source_power_medfloat16; 204 uint16_t present_voltage_medfloat16; 205 uint16_t available_energy_medfloat16; 206 uint16_t available_battery_capacity_medfloat16; 207 uint16_t charge_rate_medfloat16; 208 uint16_t available_energy_at_last_charge_medfloat16; 209 } energy_status; 210 211 // ORG_BLUETOOTH_CHARACTERISTIC_BATTERY_TIME_STATUS 212 struct { 213 uint8_t flags; 214 215 // A value of 0xFFFFFF represents: Unknown 216 // A value of 0xFFFFFE represents: Greater than 0xFFFFFD 217 uint32_t time_until_discharged_minutes; 218 uint32_t time_until_discharged_on_standby_minutes; 219 uint32_t time_until_recharged_minutes; 220 } time_status; 221 222 // ORG_BLUETOOTH_CHARACTERISTIC_BATTERY_HEALTH_STATUS 223 struct { 224 uint8_t flags; 225 uint8_t summary; // Allowed range is 0 to 100. 226 uint16_t cycle_count; 227 int8_t current_temperature_degree_celsius; 228 uint16_t deep_discharge_count; 229 } health_status; 230 231 // ORG_BLUETOOTH_CHARACTERISTIC_BATTERY_HEALTH_INFORMATION 232 struct { 233 uint8_t flags; 234 uint16_t cycle_count_designed_lifetime; 235 236 // A raw value of 0x7F represents: Greater than 126. 237 // A raw value of 0x80 represents: Less than -127. 238 int8_t min_designed_operating_temperature_degree_celsius; 239 int8_t max_designed_operating_temperature_degree_celsius; 240 } health_information; 241 242 // ORG_BLUETOOTH_CHARACTERISTIC_BATTERY_INFORMATION 243 struct { 244 uint16_t flags; 245 uint8_t features; 246 247 uint32_t manufacture_date_days; 248 uint32_t expiration_date_days; 249 250 uint16_t designed_capacity_kWh_medfloat16; 251 uint16_t low_energy_kWh_medfloat16; 252 uint16_t critical_energy_kWh_medfloat16; 253 uint8_t chemistry; 254 uint16_t nominal_voltage_medfloat16; 255 uint8_t aggregation_group; // 0: not in group, 255: RFU 256 } information; 257 258 // ORG_BLUETOOTH_CHARACTERISTIC_MANUFACTURER_NAME_STRING 259 uint8_t manufacturer_name[BATTERY_SERVICE_MAX_STRING_LEN]; 260 uint8_t manufacturer_name_len; 261 262 // ORG_BLUETOOTH_CHARACTERISTIC_MODEL_NUMBER_STRING 263 uint8_t model_number[BATTERY_SERVICE_MAX_STRING_LEN]; 264 uint8_t model_number_len; 265 266 // ORG_BLUETOOTH_CHARACTERISTIC_SERIAL_NUMBER_STRING 267 uint8_t serial_number[BATTERY_SERVICE_MAX_STRING_LEN]; 268 uint8_t serial_number_len; 269 270 uint8_t connections_max_num; 271 battery_service_v1_server_connection_t * connections; 272 } battery_service_v1_t; 273 274 /* API_START */ 275 276 /** 277 * @brief Init Battery Service Server with ATT DB 278 */ 279 void battery_service_v1_server_init(void); 280 281 void battery_service_v1_server_register(battery_service_v1_t *service, battery_service_v1_server_connection_t *connections, uint8_t connection_max_num); 282 283 void battery_service_v1_server_deregister(battery_service_v1_t *service); 284 /** 285 * @brief Update battery value 286 * @note triggers notifications if subscribed 287 * @param battery_value in range 0-100 288 */ 289 void battery_service_v1_server_set_battery_value(battery_service_v1_t * service, uint8_t value); 290 291 void battery_service_v1_server_deinit(void); 292 293 /* API_END */ 294 295 #if defined __cplusplus 296 } 297 #endif 298 299 #endif 300 301