1 /* 2 * Copyright (C) 2014 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 MATTHIAS 24 * RINGWALD 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 #ifndef btstack_gatt_client_h 40 #define btstack_gatt_client_h 41 42 #include "hci.h" 43 44 #if defined __cplusplus 45 extern "C" { 46 #endif 47 48 typedef struct le_event { 49 uint8_t type; 50 uint16_t handle; 51 } le_event_t; 52 53 typedef enum { 54 P_READY, 55 P_W2_SEND_SERVICE_QUERY, 56 P_W4_SERVICE_QUERY_RESULT, 57 P_W2_SEND_SERVICE_WITH_UUID_QUERY, 58 P_W4_SERVICE_WITH_UUID_RESULT, 59 60 P_W2_SEND_ALL_CHARACTERISTICS_OF_SERVICE_QUERY, 61 P_W4_ALL_CHARACTERISTICS_OF_SERVICE_QUERY_RESULT, 62 P_W2_SEND_CHARACTERISTIC_WITH_UUID_QUERY, 63 P_W4_CHARACTERISTIC_WITH_UUID_QUERY_RESULT, 64 65 P_W2_SEND_ALL_CHARACTERISTIC_DESCRIPTORS_QUERY, 66 P_W4_ALL_CHARACTERISTIC_DESCRIPTORS_QUERY_RESULT, 67 68 P_W2_SEND_INCLUDED_SERVICE_QUERY, 69 P_W4_INCLUDED_SERVICE_QUERY_RESULT, 70 P_W2_SEND_INCLUDED_SERVICE_WITH_UUID_QUERY, 71 P_W4_INCLUDED_SERVICE_UUID_WITH_QUERY_RESULT, 72 73 P_W2_SEND_READ_CHARACTERISTIC_VALUE_QUERY, 74 P_W4_READ_CHARACTERISTIC_VALUE_RESULT, 75 76 P_W2_SEND_READ_BLOB_QUERY, 77 P_W4_READ_BLOB_RESULT, 78 79 P_W2_SEND_READ_BY_TYPE_REQUEST, 80 P_W4_READ_BY_TYPE_RESPONSE, 81 82 P_W2_SEND_READ_MULTIPLE_REQUEST, 83 P_W4_READ_MULTIPLE_RESPONSE, 84 85 P_W2_SEND_WRITE_CHARACTERISTIC_VALUE, 86 P_W4_WRITE_CHARACTERISTIC_VALUE_RESULT, 87 88 P_W2_PREPARE_WRITE, 89 P_W4_PREPARE_WRITE_RESULT, 90 P_W2_PREPARE_RELIABLE_WRITE, 91 P_W4_PREPARE_RELIABLE_WRITE_RESULT, 92 93 P_W2_EXECUTE_PREPARED_WRITE, 94 P_W4_EXECUTE_PREPARED_WRITE_RESULT, 95 P_W2_CANCEL_PREPARED_WRITE, 96 P_W4_CANCEL_PREPARED_WRITE_RESULT, 97 P_W2_CANCEL_PREPARED_WRITE_DATA_MISMATCH, 98 P_W4_CANCEL_PREPARED_WRITE_DATA_MISMATCH_RESULT, 99 100 P_W2_SEND_READ_CLIENT_CHARACTERISTIC_CONFIGURATION_QUERY, 101 P_W4_READ_CLIENT_CHARACTERISTIC_CONFIGURATION_QUERY_RESULT, 102 P_W2_WRITE_CLIENT_CHARACTERISTIC_CONFIGURATION, 103 P_W4_CLIENT_CHARACTERISTIC_CONFIGURATION_RESULT, 104 105 P_W2_SEND_READ_CHARACTERISTIC_DESCRIPTOR_QUERY, 106 P_W4_READ_CHARACTERISTIC_DESCRIPTOR_RESULT, 107 108 P_W2_SEND_READ_BLOB_CHARACTERISTIC_DESCRIPTOR_QUERY, 109 P_W4_READ_BLOB_CHARACTERISTIC_DESCRIPTOR_RESULT, 110 111 P_W2_SEND_WRITE_CHARACTERISTIC_DESCRIPTOR, 112 P_W4_WRITE_CHARACTERISTIC_DESCRIPTOR_RESULT, 113 114 // all long writes use this 115 P_W2_PREPARE_WRITE_CHARACTERISTIC_DESCRIPTOR, 116 P_W4_PREPARE_WRITE_CHARACTERISTIC_DESCRIPTOR_RESULT, 117 P_W2_EXECUTE_PREPARED_WRITE_CHARACTERISTIC_DESCRIPTOR, 118 P_W4_EXECUTE_PREPARED_WRITE_CHARACTERISTIC_DESCRIPTOR_RESULT, 119 120 // gatt reliable write API use this (manual version of the above) 121 P_W2_PREPARE_WRITE_SINGLE, 122 P_W4_PREPARE_WRITE_SINGLE_RESULT, 123 124 P_W4_CMAC_READY, 125 P_W4_CMAC_RESULT, 126 P_W2_SEND_SIGNED_WRITE, 127 P_W4_SEND_SINGED_WRITE_DONE, 128 } gatt_client_state_t; 129 130 131 typedef enum{ 132 SEND_MTU_EXCHANGE, 133 SENT_MTU_EXCHANGE, 134 MTU_EXCHANGED 135 } gatt_client_mtu_t; 136 137 typedef struct gatt_client{ 138 btstack_linked_item_t item; 139 // TODO: rename gatt_client_state -> state 140 gatt_client_state_t gatt_client_state; 141 142 // subclient 143 uint16_t subclient_id; 144 145 uint16_t handle; 146 147 uint8_t address_type; 148 bd_addr_t address; 149 uint16_t mtu; 150 gatt_client_mtu_t mtu_state; 151 152 uint16_t uuid16; 153 uint8_t uuid128[16]; 154 155 uint16_t start_group_handle; 156 uint16_t end_group_handle; 157 158 uint16_t query_start_handle; 159 uint16_t query_end_handle; 160 161 uint8_t characteristic_properties; 162 uint16_t characteristic_start_handle; 163 164 uint16_t attribute_handle; 165 uint16_t attribute_offset; 166 uint16_t attribute_length; 167 uint8_t* attribute_value; 168 169 // read multiple characteristic values 170 uint16_t read_multiple_handle_count; 171 uint16_t * read_multiple_handles; 172 173 uint16_t client_characteristic_configuration_handle; 174 uint8_t client_characteristic_configuration_value[2]; 175 176 uint8_t filter_with_uuid; 177 uint8_t send_confirmation; 178 179 int le_device_index; 180 uint8_t cmac[8]; 181 182 btstack_timer_source_t gc_timeout; 183 } gatt_client_t; 184 185 typedef struct gatt_subclient { 186 btstack_linked_item_t item; 187 uint16_t id; 188 btstack_packet_handler_t callback; 189 } gatt_subclient_t; 190 191 /* API_START */ 192 193 typedef struct le_service{ 194 uint16_t start_group_handle; 195 uint16_t end_group_handle; 196 uint16_t uuid16; 197 uint8_t uuid128[16]; 198 } le_service_t; 199 200 typedef struct le_characteristic{ 201 uint16_t start_handle; 202 uint16_t value_handle; 203 uint16_t end_handle; 204 uint16_t properties; 205 uint16_t uuid16; 206 uint8_t uuid128[16]; 207 } le_characteristic_t; 208 209 typedef struct le_characteristic_descriptor{ 210 uint16_t handle; 211 uint16_t uuid16; 212 uint8_t uuid128[16]; 213 } le_characteristic_descriptor_t; 214 215 /** 216 * @brief Set up GATT client. 217 */ 218 void gatt_client_init(void); 219 220 /** 221 * @brief Register callback (packet handler) for GATT client. Returns GATT client ID. 222 */ 223 uint16_t gatt_client_register_packet_handler (btstack_packet_handler_t callback); 224 225 /** 226 * @brief Unregister callback (packet handler) for GATT client. 227 */ 228 void gatt_client_unregister_packet_handler(uint16_t gatt_client_id); 229 230 /** 231 * @brief MTU is available after the first query has completed. If status is equal to 0, it returns the real value, otherwise the default value of 23. 232 */ 233 uint8_t gatt_client_get_mtu(uint16_t handle, uint16_t * mtu); 234 235 /** 236 * @brief Returns if the GATT client is ready to receive a query. It is used with daemon. 237 */ 238 int gatt_client_is_ready(uint16_t handle); 239 240 /** 241 * @brief Discovers all primary services. For each found service, an le_service_event_t with type set to GATT_EVENT_SERVICE_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t, with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of discovery. 242 */ 243 uint8_t gatt_client_discover_primary_services(uint16_t gatt_client_id, uint16_t con_handle); 244 245 /** 246 * @brief Discovers a specific primary service given its UUID. This service may exist multiple times. For each found service, an le_service_event_t with type set to GATT_EVENT_SERVICE_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t, with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of discovery. 247 */ 248 uint8_t gatt_client_discover_primary_services_by_uuid16(uint16_t gatt_client_id, uint16_t con_handle, uint16_t uuid16); 249 uint8_t gatt_client_discover_primary_services_by_uuid128(uint16_t gatt_client_id, uint16_t con_handle, const uint8_t * uuid); 250 251 /** 252 * @brief Finds included services within the specified service. For each found included service, an le_service_event_t with type set to GATT_EVENT_INCLUDED_SERVICE_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of discovery. Information about included service type (primary/secondary) can be retrieved either by sending an ATT find information request for the returned start group handle (returning the handle and the UUID for primary or secondary service) or by comparing the service to the list of all primary services. 253 */ 254 uint8_t gatt_client_find_included_services_for_service(uint16_t gatt_client_id, uint16_t con_handle, le_service_t *service); 255 256 /** 257 * @brief Discovers all characteristics within the specified service. For each found characteristic, an le_characteristics_event_t with type set to GATT_EVENT_CHARACTERISTIC_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of discovery. 258 */ 259 uint8_t gatt_client_discover_characteristics_for_service(uint16_t gatt_client_id, uint16_t con_handle, le_service_t *service); 260 261 /** 262 * @brief The following four functions are used to discover all characteristics within the specified service or handle range, and return those that match the given UUID. For each found characteristic, an le_characteristic_event_t with type set to GATT_EVENT_CHARACTERISTIC_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of discovery. 263 */ 264 uint8_t gatt_client_discover_characteristics_for_handle_range_by_uuid16(uint16_t gatt_client_id, uint16_t con_handle, uint16_t start_handle, uint16_t end_handle, uint16_t uuid16); 265 uint8_t gatt_client_discover_characteristics_for_handle_range_by_uuid128(uint16_t gatt_client_id, uint16_t con_handle, uint16_t start_handle, uint16_t end_handle, uint8_t * uuid); 266 uint8_t gatt_client_discover_characteristics_for_service_by_uuid16 (uint16_t gatt_client_id, uint16_t con_handle, le_service_t *service, uint16_t uuid16); 267 uint8_t gatt_client_discover_characteristics_for_service_by_uuid128(uint16_t gatt_client_id, uint16_t con_handle, le_service_t *service, uint8_t * uuid128); 268 269 /** 270 * @brief Discovers attribute handle and UUID of a characteristic descriptor within the specified characteristic. For each found descriptor, an le_characteristic_descriptor_event_t with type set to GATT_EVENT_ALL_CHARACTERISTIC_DESCRIPTORS_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of discovery. 271 */ 272 uint8_t gatt_client_discover_characteristic_descriptors(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_t *characteristic); 273 274 /** 275 * @brief Reads the characteristic value using the characteristic's value handle. If the characteristic value is found, an le_characteristic_value_event_t with type set to GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of read. 276 */ 277 uint8_t gatt_client_read_value_of_characteristic(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_t *characteristic); 278 uint8_t gatt_client_read_value_of_characteristic_using_value_handle(uint16_t gatt_client_id, uint16_t con_handle, uint16_t characteristic_value_handle); 279 280 /** 281 * @brief Reads the characteric value of all characteristics with the uuid. For each found, an le_characteristic_value_event_t with type set to GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of read. 282 */ 283 uint8_t gatt_client_read_value_of_characteristics_by_uuid16(uint16_t gatt_client_id, uint16_t con_handle, uint16_t start_handle, uint16_t end_handle, uint16_t uuid16); 284 uint8_t gatt_client_read_value_of_characteristics_by_uuid128(uint16_t gatt_client_id, uint16_t con_handle, uint16_t start_handle, uint16_t end_handle, uint8_t * uuid128); 285 286 /** 287 * @brief Reads the long characteristic value using the characteristic's value handle. The value will be returned in several blobs. For each blob, an le_characteristic_value_event_t with type set to GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT and updated value offset will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, mark the end of read. 288 */ 289 uint8_t gatt_client_read_long_value_of_characteristic(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_t *characteristic); 290 uint8_t gatt_client_read_long_value_of_characteristic_using_value_handle(uint16_t gatt_client_id, uint16_t con_handle, uint16_t characteristic_value_handle); 291 uint8_t gatt_client_read_long_value_of_characteristic_using_value_handle_with_offset(uint16_t gatt_client_id, uint16_t con_handle, uint16_t characteristic_value_handle, uint16_t offset); 292 293 /* 294 * @brief Read multiple characteristic values 295 * @param number handles 296 * @param list_of_handles list of handles 297 */ 298 uint8_t gatt_client_read_multiple_characteristic_values(uint16_t gatt_client_id, uint16_t con_handle, int num_value_handles, uint16_t * value_handles); 299 300 /** 301 * @brief Writes the characteristic value using the characteristic's value handle without an acknowledgment that the write was successfully performed. 302 */ 303 uint8_t gatt_client_write_value_of_characteristic_without_response(uint16_t gatt_client_id, uint16_t con_handle, uint16_t characteristic_value_handle, uint16_t length, uint8_t * data); 304 305 /** 306 * @brief Writes the authenticated characteristic value using the characteristic's value handle without an acknowledgment that the write was successfully performed. 307 */ 308 uint8_t gatt_client_signed_write_without_response(uint16_t gatt_client_id, uint16_t con_handle, uint16_t handle, uint16_t message_len, uint8_t * message); 309 310 /** 311 * @brief Writes the characteristic value using the characteristic's value handle. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of write. The write is successfully performed, if the event's status field is set to 0. 312 */ 313 uint8_t gatt_client_write_value_of_characteristic(uint16_t gatt_client_id, uint16_t con_handle, uint16_t characteristic_value_handle, uint16_t length, uint8_t * data); 314 uint8_t gatt_client_write_long_value_of_characteristic(uint16_t gatt_client_id, uint16_t con_handle, uint16_t characteristic_value_handle, uint16_t length, uint8_t * data); 315 uint8_t gatt_client_write_long_value_of_characteristic_with_offset(uint16_t gatt_client_id, uint16_t con_handle, uint16_t characteristic_value_handle, uint16_t offset, uint16_t length, uint8_t * data); 316 317 /** 318 * @brief Writes of the long characteristic value using the characteristic's value handle. It uses server response to validate that the write was correctly received. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE marks the end of write. The write is successfully performed, if the event's status field is set to 0. 319 */ 320 uint8_t gatt_client_reliable_write_long_value_of_characteristic(uint16_t gatt_client_id, uint16_t con_handle, uint16_t characteristic_value_handle, uint16_t length, uint8_t * data); 321 322 /** 323 * @brief Reads the characteristic descriptor using its handle. If the characteristic descriptor is found, an le_characteristic_descriptor_event_t with type set to GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of read. 324 */ 325 uint8_t gatt_client_read_characteristic_descriptor(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_descriptor_t * descriptor); 326 uint8_t gatt_client_read_characteristic_descriptor_using_descriptor_handle(uint16_t gatt_client_id, uint16_t con_handle, uint16_t descriptor_handle); 327 328 /** 329 * @brief Reads the long characteristic descriptor using its handle. It will be returned in several blobs. For each blob, an le_characteristic_descriptor_event_t with type set to GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of read. 330 */ 331 uint8_t gatt_client_read_long_characteristic_descriptor(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_descriptor_t * descriptor); 332 uint8_t gatt_client_read_long_characteristic_descriptor_using_descriptor_handle(uint16_t gatt_client_id, uint16_t con_handle, uint16_t descriptor_handle); 333 uint8_t gatt_client_read_long_characteristic_descriptor_using_descriptor_handle_with_offset(uint16_t gatt_client_id, uint16_t con_handle, uint16_t descriptor_handle, uint16_t offset); 334 335 /** 336 * @brief Writes the characteristic descriptor using its handle. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of write. The write is successfully performed, if the event's status field is set to 0. 337 */ 338 uint8_t gatt_client_write_characteristic_descriptor(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_descriptor_t * descriptor, uint16_t length, uint8_t * data); 339 uint8_t gatt_client_write_characteristic_descriptor_using_descriptor_handle(uint16_t gatt_client_id, uint16_t con_handle, uint16_t descriptor_handle, uint16_t length, uint8_t * data); 340 uint8_t gatt_client_write_long_characteristic_descriptor(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_descriptor_t * descriptor, uint16_t length, uint8_t * data); 341 uint8_t gatt_client_write_long_characteristic_descriptor_using_descriptor_handle(uint16_t gatt_client_id, uint16_t con_handle, uint16_t descriptor_handle, uint16_t length, uint8_t * data); 342 uint8_t gatt_client_write_long_characteristic_descriptor_using_descriptor_handle_with_offset(uint16_t gatt_client_id, uint16_t con_handle, uint16_t descriptor_handle, uint16_t offset, uint16_t length, uint8_t * data); 343 344 /** 345 * @brief Writes the client characteristic configuration of the specified characteristic. It is used to subscribe for notifications or indications of the characteristic value. For notifications or indications specify: GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_NOTIFICATION resp. GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_INDICATION as configuration value. 346 */ 347 uint8_t gatt_client_write_client_characteristic_configuration(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_t * characteristic, uint16_t configuration); 348 349 /** 350 * @brief -> gatt complete event 351 */ 352 uint8_t gatt_client_prepare_write(uint16_t gatt_client_id, uint16_t con_handle, uint16_t attribute_handle, uint16_t offset, uint16_t length, uint8_t * data); 353 354 /** 355 * @brief -> gatt complete event 356 */ 357 uint8_t gatt_client_execute_write(uint16_t gatt_client_id, uint16_t con_handle); 358 359 /** 360 * @brief -> gatt complete event 361 */ 362 uint8_t gatt_client_cancel_write(uint16_t gatt_client_id, uint16_t con_handle); 363 364 365 /* API_END */ 366 367 // only used for testing 368 void gatt_client_pts_suppress_mtu_exchange(void); 369 370 #if defined __cplusplus 371 } 372 #endif 373 374 #endif 375