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 #ifndef GAP_H 39 #define GAP_H 40 41 #if defined __cplusplus 42 extern "C" { 43 #endif 44 45 #include "btstack_defines.h" 46 #include "btstack_util.h" 47 #include "classic/btstack_link_key_db.h" 48 49 typedef enum { 50 51 // MITM protection not required 52 // No encryption required 53 // No user interaction required 54 LEVEL_0 = 0, 55 56 // MITM protection not required 57 // No encryption required 58 // Minimal user interaction desired 59 LEVEL_1, 60 61 // MITM protection not required 62 // Encryption required 63 LEVEL_2, 64 65 // MITM protection required 66 // Encryption required 67 // User interaction acceptable 68 LEVEL_3, 69 70 // MITM protection required 71 // Encryption required 72 // 128-bit equivalent strength for link and encryption keys required (P-192 is not enough) 73 // User interaction acceptable 74 LEVEL_4, 75 } gap_security_level_t; 76 77 typedef enum { 78 GAP_SECURITY_NONE, 79 GAP_SECUIRTY_ENCRYPTED, // SSP: JUST WORKS 80 GAP_SECURITY_AUTHENTICATED, // SSP: numeric comparison, passkey, OOB 81 // GAP_SECURITY_AUTHORIZED 82 } gap_security_state; 83 84 typedef enum { 85 GAP_CONNECTION_INVALID, 86 GAP_CONNECTION_ACL, 87 GAP_CONNECTION_SCO, 88 GAP_CONNECTION_LE 89 } gap_connection_type_t; 90 91 typedef struct le_connection_parameter_range{ 92 uint16_t le_conn_interval_min; 93 uint16_t le_conn_interval_max; 94 uint16_t le_conn_latency_min; 95 uint16_t le_conn_latency_max; 96 uint16_t le_supervision_timeout_min; 97 uint16_t le_supervision_timeout_max; 98 } le_connection_parameter_range_t; 99 100 typedef enum { 101 GAP_RANDOM_ADDRESS_TYPE_OFF = 0, 102 GAP_RANDOM_ADDRESS_TYPE_STATIC, 103 GAP_RANDOM_ADDRESS_NON_RESOLVABLE, 104 GAP_RANDOM_ADDRESS_RESOLVABLE, 105 } gap_random_address_type_t; 106 107 // Authorization state 108 typedef enum { 109 AUTHORIZATION_UNKNOWN, 110 AUTHORIZATION_PENDING, 111 AUTHORIZATION_DECLINED, 112 AUTHORIZATION_GRANTED 113 } authorization_state_t; 114 115 116 /* API_START */ 117 118 // Classic + LE 119 120 /** 121 * @brief Disconnect connection with handle 122 * @param handle 123 */ 124 uint8_t gap_disconnect(hci_con_handle_t handle); 125 126 /** 127 * @brief Get connection type 128 * @param con_handle 129 * @result connection_type 130 */ 131 gap_connection_type_t gap_get_connection_type(hci_con_handle_t connection_handle); 132 133 // Classic 134 135 /** 136 * @brief Sets local name. 137 * @note has to be done before stack starts up 138 * @note Default name is 'BTstack 00:00:00:00:00:00' 139 * @note '00:00:00:00:00:00' in local_name will be replaced with actual bd addr 140 * @param name is not copied, make sure memory is accessible during stack startup 141 */ 142 void gap_set_local_name(const char * local_name); 143 144 /** 145 * @brief Set Extended Inquiry Response data 146 * @note has to be done before stack starts up 147 * @note If not set, local name will be used for EIR data (see gap_set_local_name) 148 * @note '00:00:00:00:00:00' in local_name will be replaced with actual bd addr 149 * @param eir_data size HCI_EXTENDED_INQUIRY_RESPONSE_DATA_LEN (240) bytes, is not copied make sure memory is accessible during stack startup 150 */ 151 void gap_set_extended_inquiry_response(const uint8_t * data); 152 153 /** 154 * @brief Set class of device that will be set during Bluetooth init. 155 * @note has to be done before stack starts up 156 */ 157 void gap_set_class_of_device(uint32_t class_of_device); 158 159 /** 160 * @brief Set default link policy settings for all classic ACL links 161 * @param default_link_policy_settings - see LM_LINK_POLICY_* in bluetooth.h 162 * @note common value: LM_LINK_POLICY_ENABLE_ROLE_SWITCH | LM_LINK_POLICY_ENABLE_SNIFF_MODE to enable role switch and sniff mode 163 * @note has to be done before stack starts up 164 */ 165 void gap_set_default_link_policy_settings(uint16_t default_link_policy_settings); 166 167 /** 168 * @brief Set Allow Role Switch param for outgoing classic ACL links 169 * @param allow_role_switch - true: allow remote device to request role switch, false: stay master 170 */ 171 void gap_set_allow_role_switch(bool allow_role_switch); 172 173 /** 174 * @brief Set link supervision timeout for outgoing classic ACL links 175 * @param default_link_supervision_timeout * 0.625 ms, default 0x7d00 = 20 seconds 176 */ 177 void gap_set_link_supervision_timeout(uint16_t link_supervision_timeout); 178 179 /** 180 * @brief Enable/disable bonding. Default is enabled. 181 * @param enabled 182 */ 183 void gap_set_bondable_mode(int enabled); 184 185 /** 186 * @brief Get bondable mode. 187 * @return 1 if bondable 188 */ 189 int gap_get_bondable_mode(void); 190 191 /** 192 * @brief Set security level for all outgoing and incoming connections. Default: LEVEL_2 193 * @param security_level 194 * @note has to be called before services or profiles are initialized 195 */ 196 void gap_set_security_level(gap_security_level_t security_level); 197 198 /** 199 * @brief Get security level 200 * @return security_level 201 */ 202 gap_security_level_t gap_get_security_level(void); 203 204 /** 205 * @brief Register filter for rejecting classic connections. Callback will return 1 accept connection, 0 on reject. 206 */ 207 void gap_register_classic_connection_filter(int (*accept_callback)(bd_addr_t addr)); 208 209 /* Configure Secure Simple Pairing */ 210 211 /** 212 * @brief Enable will enable SSP during init. 213 */ 214 void gap_ssp_set_enable(int enable); 215 216 /** 217 * @brief Set IO Capability. BTstack will return capability to SSP requests 218 */ 219 void gap_ssp_set_io_capability(int ssp_io_capability); 220 221 /** 222 * @brief Set Authentication Requirements using during SSP 223 */ 224 void gap_ssp_set_authentication_requirement(int authentication_requirement); 225 226 /** 227 * @brief If set, BTstack will confirm a numeric comparison and enter '000000' if requested. 228 */ 229 void gap_ssp_set_auto_accept(int auto_accept); 230 231 /** 232 * @brief Set required encryption key size for GAP Levels 1-3 on ccassic connections. Default: 16 bytes 233 * @param encryption_key_size in bytes. Valid 7..16 234 */ 235 void gap_set_required_encryption_key_size(uint8_t encryption_key_size); 236 237 /** 238 * @brief Start dedicated bonding with device. Disconnect after bonding. 239 * @param device 240 * @param request MITM protection 241 * @return error, if max num acl connections active 242 * @result GAP_DEDICATED_BONDING_COMPLETE 243 */ 244 int gap_dedicated_bonding(bd_addr_t device, int mitm_protection_required); 245 246 gap_security_level_t gap_security_level_for_link_key_type(link_key_type_t link_key_type); 247 248 /** 249 * @brief map link keys to secure connection yes/no 250 */ 251 int gap_secure_connection_for_link_key_type(link_key_type_t link_key_type); 252 253 /** 254 * @brief map link keys to authenticated 255 */ 256 int gap_authenticated_for_link_key_type(link_key_type_t link_key_type); 257 258 gap_security_level_t gap_security_level(hci_con_handle_t con_handle); 259 260 void gap_request_security_level(hci_con_handle_t con_handle, gap_security_level_t level); 261 262 int gap_mitm_protection_required_for_security_level(gap_security_level_t level); 263 264 // LE 265 266 /** 267 * @brief Set parameters for LE Scan 268 */ 269 void gap_set_scan_parameters(uint8_t scan_type, uint16_t scan_interval, uint16_t scan_window); 270 271 /** 272 * @brief Start LE Scan 273 */ 274 void gap_start_scan(void); 275 276 /** 277 * @brief Stop LE Scan 278 */ 279 void gap_stop_scan(void); 280 281 /** 282 * @brief Enable privacy by using random addresses 283 * @param random_address_type to use (incl. OFF) 284 */ 285 void gap_random_address_set_mode(gap_random_address_type_t random_address_type); 286 287 /** 288 * @brief Get privacy mode 289 */ 290 gap_random_address_type_t gap_random_address_get_mode(void); 291 292 /** 293 * @brief Sets update period for random address 294 * @param period_ms in ms 295 */ 296 void gap_random_address_set_update_period(int period_ms); 297 298 /** 299 * @brief Sets a fixed random address for advertising 300 * @param addr 301 * @note Sets random address mode to type off 302 */ 303 void gap_random_address_set(bd_addr_t addr); 304 305 /** 306 * @brief Set Advertisement Data 307 * @param advertising_data_length 308 * @param advertising_data (max 31 octets) 309 * @note data is not copied, pointer has to stay valid 310 * @note '00:00:00:00:00:00' in advertising_data will be replaced with actual bd addr 311 */ 312 void gap_advertisements_set_data(uint8_t advertising_data_length, uint8_t * advertising_data); 313 314 /** 315 * @brief Set Advertisement Paramters 316 * @param adv_int_min 317 * @param adv_int_max 318 * @param adv_type 319 * @param direct_address_type 320 * @param direct_address 321 * @param channel_map 322 * @param filter_policy 323 * @note own_address_type is used from gap_random_address_set_mode 324 */ 325 void gap_advertisements_set_params(uint16_t adv_int_min, uint16_t adv_int_max, uint8_t adv_type, 326 uint8_t direct_address_typ, bd_addr_t direct_address, uint8_t channel_map, uint8_t filter_policy); 327 328 /** 329 * @brief Enable/Disable Advertisements. OFF by default. 330 * @param enabled 331 */ 332 void gap_advertisements_enable(int enabled); 333 334 /** 335 * @brief Set Scan Response Data 336 * 337 * @note For scan response data, scannable undirected advertising (ADV_SCAN_IND) need to be used 338 * 339 * @param advertising_data_length 340 * @param advertising_data (max 31 octets) 341 * @note data is not copied, pointer has to stay valid 342 * @note '00:00:00:00:00:00' in scan_response_data will be replaced with actual bd addr 343 */ 344 void gap_scan_response_set_data(uint8_t scan_response_data_length, uint8_t * scan_response_data); 345 346 /** 347 * @brief Set connection parameters for outgoing connections 348 * @param conn_scan_interval (unit: 0.625 msec), default: 60 ms 349 * @param conn_scan_window (unit: 0.625 msec), default: 30 ms 350 * @param conn_interval_min (unit: 1.25ms), default: 10 ms 351 * @param conn_interval_max (unit: 1.25ms), default: 30 ms 352 * @param conn_latency, default: 4 353 * @param supervision_timeout (unit: 10ms), default: 720 ms 354 * @param min_ce_length (unit: 0.625ms), default: 10 ms 355 * @param max_ce_length (unit: 0.625ms), default: 30 ms 356 */ 357 void gap_set_connection_parameters(uint16_t conn_scan_interval, uint16_t conn_scan_window, 358 uint16_t conn_interval_min, uint16_t conn_interval_max, uint16_t conn_latency, 359 uint16_t supervision_timeout, uint16_t min_ce_length, uint16_t max_ce_length); 360 361 /** 362 * @brief Request an update of the connection parameter for a given LE connection 363 * @param handle 364 * @param conn_interval_min (unit: 1.25ms) 365 * @param conn_interval_max (unit: 1.25ms) 366 * @param conn_latency 367 * @param supervision_timeout (unit: 10ms) 368 * @returns 0 if ok 369 */ 370 int gap_request_connection_parameter_update(hci_con_handle_t con_handle, uint16_t conn_interval_min, 371 uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout); 372 373 /** 374 * @brief Updates the connection parameters for a given LE connection 375 * @param handle 376 * @param conn_interval_min (unit: 1.25ms) 377 * @param conn_interval_max (unit: 1.25ms) 378 * @param conn_latency 379 * @param supervision_timeout (unit: 10ms) 380 * @returns 0 if ok 381 */ 382 int gap_update_connection_parameters(hci_con_handle_t con_handle, uint16_t conn_interval_min, 383 uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout); 384 385 /** 386 * @brief Set accepted connection parameter range 387 * @param range 388 */ 389 void gap_get_connection_parameter_range(le_connection_parameter_range_t * range); 390 391 /** 392 * @brief Get accepted connection parameter range 393 * @param range 394 */ 395 void gap_set_connection_parameter_range(le_connection_parameter_range_t * range); 396 397 /** 398 * @brief Test if connection parameters are inside in existing rage 399 * @param conn_interval_min (unit: 1.25ms) 400 * @param conn_interval_max (unit: 1.25ms) 401 * @param conn_latency 402 * @param supervision_timeout (unit: 10ms) 403 * @returns 1 if included 404 */ 405 int gap_connection_parameter_range_included(le_connection_parameter_range_t * existing_range, uint16_t le_conn_interval_min, uint16_t le_conn_interval_max, uint16_t le_conn_latency, uint16_t le_supervision_timeout); 406 407 /** 408 * @brief Set max number of connections in LE Peripheral role (if Bluetooth Controller supports it) 409 * @note: default: 1 410 * @param max_peripheral_connections 411 */ 412 void gap_set_max_number_peripheral_connections(int max_peripheral_connections); 413 414 /** 415 * @brief Connect to remote LE device 416 */ 417 uint8_t gap_connect(bd_addr_t addr, bd_addr_type_t addr_type); 418 419 /** 420 * @brief Cancel connection process initiated by gap_connect 421 */ 422 uint8_t gap_connect_cancel(void); 423 424 /** 425 * @brief Auto Connection Establishment - Start Connecting to device 426 * @param address_typ 427 * @param address 428 * @returns 0 if ok 429 */ 430 int gap_auto_connection_start(bd_addr_type_t address_typ, bd_addr_t address); 431 432 /** 433 * @brief Auto Connection Establishment - Stop Connecting to device 434 * @param address_typ 435 * @param address 436 * @returns 0 if ok 437 */ 438 int gap_auto_connection_stop(bd_addr_type_t address_typ, bd_addr_t address); 439 440 /** 441 * @brief Auto Connection Establishment - Stop everything 442 * @note Convenience function to stop all active auto connection attempts 443 */ 444 void gap_auto_connection_stop_all(void); 445 446 /** 447 * @brief Set LE PHY 448 * @param con_handle 449 * @param all_phys 0 = set rx/tx, 1 = set only rx, 2 = set only tx 450 * @param tx_phys 1 = 1M, 2 = 2M, 4 = Coded 451 * @param rx_phys 1 = 1M, 2 = 2M, 4 = Coded 452 * @param phy_options 0 = no preferred coding for Coded, 1 = S=2 coding (500 kbit), 2 = S=8 coding (125 kbit) 453 * @returns 0 if ok 454 */ 455 uint8_t gap_le_set_phy(hci_con_handle_t con_handle, uint8_t all_phys, uint8_t tx_phys, uint8_t rx_phys, uint8_t phy_options); 456 457 /** 458 * @brief Get connection interval 459 * @return connection interval, otherwise 0 if error 460 */ 461 uint16_t gap_le_connection_interval(hci_con_handle_t connection_handle); 462 463 /** 464 * 465 * @brief Get encryption key size. 466 * @param con_handle 467 * @return 0 if not encrypted, 7-16 otherwise 468 */ 469 int gap_encryption_key_size(hci_con_handle_t con_handle); 470 471 /** 472 * @brief Get authentication property. 473 * @param con_handle 474 * @return 1 if bonded with OOB/Passkey (AND MITM protection) 475 */ 476 int gap_authenticated(hci_con_handle_t con_handle); 477 478 /** 479 * @brief Get secure connection property 480 * @param con_handle 481 * @return 1 if bonded usiung LE Secure Connections 482 */ 483 int gap_secure_connection(hci_con_handle_t con_handle); 484 485 /** 486 * @brief Queries authorization state. 487 * @param con_handle 488 * @return authorization_state for the current session 489 */ 490 authorization_state_t gap_authorization_state(hci_con_handle_t con_handle); 491 492 // Classic 493 494 /** 495 * @brief Override page scan mode. Page scan mode enabled by l2cap when services are registered 496 * @note Might be used to reduce power consumption while Bluetooth module stays powered but no (new) 497 * connections are expected 498 */ 499 void gap_connectable_control(uint8_t enable); 500 501 /** 502 * @brief Allows to control if device is discoverable. OFF by default. 503 */ 504 void gap_discoverable_control(uint8_t enable); 505 506 /** 507 * @brief Gets local address. 508 */ 509 void gap_local_bd_addr(bd_addr_t address_buffer); 510 511 /** 512 * @brief Deletes link key for remote device with baseband address. 513 * @param addr 514 */ 515 void gap_drop_link_key_for_bd_addr(bd_addr_t addr); 516 517 /** 518 * @brief Delete all stored link keys 519 */ 520 void gap_delete_all_link_keys(void); 521 522 /** 523 * @brief Store link key for remote device with baseband address 524 * @param addr 525 * @param link_key 526 * @param link_key_type 527 */ 528 void gap_store_link_key_for_bd_addr(bd_addr_t addr, link_key_t link_key, link_key_type_t type); 529 530 /** 531 * @brief Setup Link Key iterator 532 * @param it 533 * @returns 1 on success 534 */ 535 int gap_link_key_iterator_init(btstack_link_key_iterator_t * it); 536 537 /** 538 * @brief Get next Link Key 539 * @param it 540 * @brief addr 541 * @brief link_key 542 * @brief type of link key 543 * @returns 1, if valid link key found 544 */ 545 int gap_link_key_iterator_get_next(btstack_link_key_iterator_t * it, bd_addr_t bd_addr, link_key_t link_key, link_key_type_t * type); 546 547 /** 548 * @brief Frees resources allocated by iterator_init 549 * @note Must be called after iteration to free resources 550 * @param it 551 */ 552 void gap_link_key_iterator_done(btstack_link_key_iterator_t * it); 553 554 /** 555 * @brief Start GAP Classic Inquiry 556 * @param duration in 1.28s units 557 * @return 0 if ok 558 * @events: GAP_EVENT_INQUIRY_RESULT, GAP_EVENT_INQUIRY_COMPLETE 559 */ 560 int gap_inquiry_start(uint8_t duration_in_1280ms_units); 561 562 /** 563 * @brief Stop GAP Classic Inquiry 564 * @brief Stop GAP Classic Inquiry 565 * @returns 0 if ok 566 * @events: GAP_EVENT_INQUIRY_COMPLETE 567 */ 568 int gap_inquiry_stop(void); 569 570 /** 571 * @brief Remote Name Request 572 * @param addr 573 * @param page_scan_repetition_mode 574 * @param clock_offset only used when bit 15 is set - pass 0 if not known 575 * @events: HCI_EVENT_REMOTE_NAME_REQUEST_COMPLETE 576 */ 577 int gap_remote_name_request(bd_addr_t addr, uint8_t page_scan_repetition_mode, uint16_t clock_offset); 578 579 /** 580 * @brief Read RSSI 581 * @param con_handle 582 * @events: GAP_EVENT_RSSI_MEASUREMENT 583 */ 584 int gap_read_rssi(hci_con_handle_t con_handle); 585 586 /** 587 * @brief Legacy Pairing Pin Code Response 588 * @param addr 589 * @param pin 590 * @return 0 if ok 591 */ 592 int gap_pin_code_response(bd_addr_t addr, const char * pin); 593 594 /** 595 * @brief Abort Legacy Pairing 596 * @param addr 597 * @param pin 598 * @return 0 if ok 599 */ 600 int gap_pin_code_negative(bd_addr_t addr); 601 602 /** 603 * @brief SSP Passkey Response 604 * @param addr 605 * @param passkey [0..999999] 606 * @return 0 if ok 607 */ 608 int gap_ssp_passkey_response(bd_addr_t addr, uint32_t passkey); 609 610 /** 611 * @brief Abort SSP Passkey Entry/Pairing 612 * @param addr 613 * @param pin 614 * @return 0 if ok 615 */ 616 int gap_ssp_passkey_negative(bd_addr_t addr); 617 618 /** 619 * @brief Accept SSP Numeric Comparison 620 * @param addr 621 * @param passkey 622 * @return 0 if ok 623 */ 624 int gap_ssp_confirmation_response(bd_addr_t addr); 625 626 /** 627 * @brief Abort SSP Numeric Comparison/Pairing 628 * @param addr 629 * @param pin 630 * @return 0 if ok 631 */ 632 int gap_ssp_confirmation_negative(bd_addr_t addr); 633 634 /** 635 * @brief Enter Sniff mode 636 * @param con_handle 637 * @param sniff_min_interval range: 0x0002 to 0xFFFE; only even values are valid, Time = N * 0.625 ms 638 * @param sniff_max_interval range: 0x0002 to 0xFFFE; only even values are valid, Time = N * 0.625 ms 639 * @param sniff_attempt Number of Baseband receive slots for sniff attempt. 640 * @param sniff_timeout Number of Baseband receive slots for sniff timeout. 641 @ @return 0 if ok 642 */ 643 uint8_t gap_sniff_mode_enter(hci_con_handle_t con_handle, uint16_t sniff_min_interval, uint16_t sniff_max_interval, uint16_t sniff_attempt, uint16_t sniff_timeout); 644 645 /** 646 * @brief Exit Sniff mode 647 * @param con_handle 648 @ @return 0 if ok 649 */ 650 uint8_t gap_sniff_mode_exit(hci_con_handle_t con_handle); 651 652 // LE 653 654 /** 655 * @brief Get own addr type and address used for LE 656 */ 657 void gap_le_get_own_address(uint8_t * addr_type, bd_addr_t addr); 658 659 660 /** 661 * @brief Get state of connection re-encryptiong for bonded devices when in central role 662 * @note used by gatt_client and att_server to wait for re-encryption 663 * @param con_handle 664 * @return 1 if security setup is active 665 */ 666 int gap_reconnect_security_setup_active(hci_con_handle_t con_handle); 667 668 669 /* API_END*/ 670 671 #if defined __cplusplus 672 } 673 #endif 674 675 #endif // GAP_H 676