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 void (*gatt_client_callback_t)(uint8_t packet_type, uint8_t *packet, uint16_t size); 54 55 typedef enum { 56 P_READY, 57 P_W2_SEND_SERVICE_QUERY, 58 P_W4_SERVICE_QUERY_RESULT, 59 P_W2_SEND_SERVICE_WITH_UUID_QUERY, 60 P_W4_SERVICE_WITH_UUID_RESULT, 61 62 P_W2_SEND_ALL_CHARACTERISTICS_OF_SERVICE_QUERY, 63 P_W4_ALL_CHARACTERISTICS_OF_SERVICE_QUERY_RESULT, 64 P_W2_SEND_CHARACTERISTIC_WITH_UUID_QUERY, 65 P_W4_CHARACTERISTIC_WITH_UUID_QUERY_RESULT, 66 67 P_W2_SEND_ALL_CHARACTERISTIC_DESCRIPTORS_QUERY, 68 P_W4_ALL_CHARACTERISTIC_DESCRIPTORS_QUERY_RESULT, 69 70 P_W2_SEND_INCLUDED_SERVICE_QUERY, 71 P_W4_INCLUDED_SERVICE_QUERY_RESULT, 72 P_W2_SEND_INCLUDED_SERVICE_WITH_UUID_QUERY, 73 P_W4_INCLUDED_SERVICE_UUID_WITH_QUERY_RESULT, 74 75 P_W2_SEND_READ_CHARACTERISTIC_VALUE_QUERY, 76 P_W4_READ_CHARACTERISTIC_VALUE_RESULT, 77 78 P_W2_SEND_READ_BLOB_QUERY, 79 P_W4_READ_BLOB_RESULT, 80 81 P_W2_SEND_READ_BY_TYPE_REQUEST, 82 P_W4_READ_BY_TYPE_RESPONSE, 83 84 P_W2_SEND_READ_MULTIPLE_REQUEST, 85 P_W4_READ_MULTIPLE_RESPONSE, 86 87 P_W2_SEND_WRITE_CHARACTERISTIC_VALUE, 88 P_W4_WRITE_CHARACTERISTIC_VALUE_RESULT, 89 90 P_W2_PREPARE_WRITE, 91 P_W4_PREPARE_WRITE_RESULT, 92 P_W2_PREPARE_RELIABLE_WRITE, 93 P_W4_PREPARE_RELIABLE_WRITE_RESULT, 94 95 P_W2_EXECUTE_PREPARED_WRITE, 96 P_W4_EXECUTE_PREPARED_WRITE_RESULT, 97 P_W2_CANCEL_PREPARED_WRITE, 98 P_W4_CANCEL_PREPARED_WRITE_RESULT, 99 P_W2_CANCEL_PREPARED_WRITE_DATA_MISMATCH, 100 P_W4_CANCEL_PREPARED_WRITE_DATA_MISMATCH_RESULT, 101 102 P_W2_SEND_READ_CLIENT_CHARACTERISTIC_CONFIGURATION_QUERY, 103 P_W4_READ_CLIENT_CHARACTERISTIC_CONFIGURATION_QUERY_RESULT, 104 P_W2_WRITE_CLIENT_CHARACTERISTIC_CONFIGURATION, 105 P_W4_CLIENT_CHARACTERISTIC_CONFIGURATION_RESULT, 106 107 P_W2_SEND_READ_CHARACTERISTIC_DESCRIPTOR_QUERY, 108 P_W4_READ_CHARACTERISTIC_DESCRIPTOR_RESULT, 109 110 P_W2_SEND_READ_BLOB_CHARACTERISTIC_DESCRIPTOR_QUERY, 111 P_W4_READ_BLOB_CHARACTERISTIC_DESCRIPTOR_RESULT, 112 113 P_W2_SEND_WRITE_CHARACTERISTIC_DESCRIPTOR, 114 P_W4_WRITE_CHARACTERISTIC_DESCRIPTOR_RESULT, 115 116 // all long writes use this 117 P_W2_PREPARE_WRITE_CHARACTERISTIC_DESCRIPTOR, 118 P_W4_PREPARE_WRITE_CHARACTERISTIC_DESCRIPTOR_RESULT, 119 P_W2_EXECUTE_PREPARED_WRITE_CHARACTERISTIC_DESCRIPTOR, 120 P_W4_EXECUTE_PREPARED_WRITE_CHARACTERISTIC_DESCRIPTOR_RESULT, 121 122 // gatt reliable write API use this (manual version of the above) 123 P_W2_PREPARE_WRITE_SINGLE, 124 P_W4_PREPARE_WRITE_SINGLE_RESULT, 125 126 P_W4_CMAC_READY, 127 P_W4_CMAC_RESULT, 128 P_W2_SEND_SIGNED_WRITE, 129 P_W4_SEND_SINGED_WRITE_DONE, 130 } gatt_client_state_t; 131 132 133 typedef enum{ 134 SEND_MTU_EXCHANGE, 135 SENT_MTU_EXCHANGE, 136 MTU_EXCHANGED 137 } gatt_client_mtu_t; 138 139 typedef struct gatt_client{ 140 btstack_linked_item_t item; 141 // TODO: rename gatt_client_state -> state 142 gatt_client_state_t gatt_client_state; 143 144 // subclient 145 uint16_t subclient_id; 146 147 uint16_t handle; 148 149 uint8_t address_type; 150 bd_addr_t address; 151 uint16_t mtu; 152 gatt_client_mtu_t mtu_state; 153 154 uint16_t uuid16; 155 uint8_t uuid128[16]; 156 157 uint16_t start_group_handle; 158 uint16_t end_group_handle; 159 160 uint16_t query_start_handle; 161 uint16_t query_end_handle; 162 163 uint8_t characteristic_properties; 164 uint16_t characteristic_start_handle; 165 166 uint16_t attribute_handle; 167 uint16_t attribute_offset; 168 uint16_t attribute_length; 169 uint8_t* attribute_value; 170 171 // read multiple characteristic values 172 uint16_t read_multiple_handle_count; 173 uint16_t * read_multiple_handles; 174 175 uint16_t client_characteristic_configuration_handle; 176 uint8_t client_characteristic_configuration_value[2]; 177 178 uint8_t filter_with_uuid; 179 uint8_t send_confirmation; 180 181 int le_device_index; 182 uint8_t cmac[8]; 183 184 btstack_timer_source_t gc_timeout; 185 } gatt_client_t; 186 187 typedef struct gatt_subclient { 188 btstack_linked_item_t item; 189 uint16_t id; 190 gatt_client_callback_t callback; 191 } gatt_subclient_t; 192 193 /* API_START */ 194 195 typedef struct le_service{ 196 uint16_t start_group_handle; 197 uint16_t end_group_handle; 198 uint16_t uuid16; 199 uint8_t uuid128[16]; 200 } le_service_t; 201 202 typedef struct le_characteristic{ 203 uint16_t start_handle; 204 uint16_t value_handle; 205 uint16_t end_handle; 206 uint16_t properties; 207 uint16_t uuid16; 208 uint8_t uuid128[16]; 209 } le_characteristic_t; 210 211 typedef struct le_characteristic_descriptor{ 212 uint16_t handle; 213 uint16_t uuid16; 214 uint8_t uuid128[16]; 215 } le_characteristic_descriptor_t; 216 217 /** 218 * @brief Set up GATT client. 219 */ 220 void gatt_client_init(void); 221 222 /** 223 * @brief Register callback (packet handler) for GATT client. Returns GATT client ID. 224 */ 225 uint16_t gatt_client_register_packet_handler (gatt_client_callback_t callback); 226 227 /** 228 * @brief Unregister callback (packet handler) for GATT client. 229 */ 230 void gatt_client_unregister_packet_handler(uint16_t gatt_client_id); 231 232 /** 233 * @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. 234 */ 235 uint8_t gatt_client_get_mtu(uint16_t handle, uint16_t * mtu); 236 237 /** 238 * @brief Returns if the GATT client is ready to receive a query. It is used with daemon. 239 */ 240 int gatt_client_is_ready(uint16_t handle); 241 242 /** 243 * @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. 244 */ 245 uint8_t gatt_client_discover_primary_services(uint16_t gatt_client_id, uint16_t con_handle); 246 247 /** 248 * @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. 249 */ 250 uint8_t gatt_client_discover_primary_services_by_uuid16(uint16_t gatt_client_id, uint16_t con_handle, uint16_t uuid16); 251 uint8_t gatt_client_discover_primary_services_by_uuid128(uint16_t gatt_client_id, uint16_t con_handle, const uint8_t * uuid); 252 253 /** 254 * @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. 255 */ 256 uint8_t gatt_client_find_included_services_for_service(uint16_t gatt_client_id, uint16_t con_handle, le_service_t *service); 257 258 /** 259 * @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. 260 */ 261 uint8_t gatt_client_discover_characteristics_for_service(uint16_t gatt_client_id, uint16_t con_handle, le_service_t *service); 262 263 /** 264 * @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. 265 */ 266 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); 267 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); 268 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); 269 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); 270 271 /** 272 * @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. 273 */ 274 uint8_t gatt_client_discover_characteristic_descriptors(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_t *characteristic); 275 276 /** 277 * @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. 278 */ 279 uint8_t gatt_client_read_value_of_characteristic(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_t *characteristic); 280 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); 281 282 /** 283 * @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. 284 */ 285 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); 286 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); 287 288 /** 289 * @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. 290 */ 291 uint8_t gatt_client_read_long_value_of_characteristic(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_t *characteristic); 292 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); 293 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); 294 295 /* 296 * @brief Read multiple characteristic values 297 * @param number handles 298 * @param list_of_handles list of handles 299 */ 300 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); 301 302 /** 303 * @brief Writes the characteristic value using the characteristic's value handle without an acknowledgment that the write was successfully performed. 304 */ 305 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); 306 307 /** 308 * @brief Writes the authenticated characteristic value using the characteristic's value handle without an acknowledgment that the write was successfully performed. 309 */ 310 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); 311 312 /** 313 * @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. 314 */ 315 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); 316 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); 317 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); 318 319 /** 320 * @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. 321 */ 322 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); 323 324 /** 325 * @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. 326 */ 327 uint8_t gatt_client_read_characteristic_descriptor(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_descriptor_t * descriptor); 328 uint8_t gatt_client_read_characteristic_descriptor_using_descriptor_handle(uint16_t gatt_client_id, uint16_t con_handle, uint16_t descriptor_handle); 329 330 /** 331 * @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. 332 */ 333 uint8_t gatt_client_read_long_characteristic_descriptor(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_descriptor_t * descriptor); 334 uint8_t gatt_client_read_long_characteristic_descriptor_using_descriptor_handle(uint16_t gatt_client_id, uint16_t con_handle, uint16_t descriptor_handle); 335 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); 336 337 /** 338 * @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. 339 */ 340 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); 341 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); 342 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); 343 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); 344 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); 345 346 /** 347 * @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. 348 */ 349 uint8_t gatt_client_write_client_characteristic_configuration(uint16_t gatt_client_id, uint16_t con_handle, le_characteristic_t * characteristic, uint16_t configuration); 350 351 /** 352 * @brief -> gatt complete event 353 */ 354 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); 355 356 /** 357 * @brief -> gatt complete event 358 */ 359 uint8_t gatt_client_execute_write(uint16_t gatt_client_id, uint16_t con_handle); 360 361 /** 362 * @brief -> gatt complete event 363 */ 364 uint8_t gatt_client_cancel_write(uint16_t gatt_client_id, uint16_t con_handle); 365 366 367 /* API_END */ 368 369 // only used for testing 370 void gatt_client_pts_suppress_mtu_exchange(void); 371 372 #if defined __cplusplus 373 } 374 #endif 375 376 #endif 377