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 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 Genral Access Profile (GAP) 40 * 41 */ 42 43 #ifndef GAP_H 44 #define GAP_H 45 46 #if defined __cplusplus 47 extern "C" { 48 #endif 49 50 #include "btstack_defines.h" 51 #include "btstack_util.h" 52 53 #ifdef ENABLE_CLASSIC 54 #include "classic/btstack_link_key_db.h" 55 #endif 56 57 typedef enum { 58 59 // MITM protection not required 60 // No encryption required 61 // No user interaction required 62 LEVEL_0 = 0, 63 64 // MITM protection not required 65 // No encryption required 66 // Minimal user interaction desired 67 LEVEL_1, 68 69 // MITM protection not required 70 // Encryption required 71 LEVEL_2, 72 73 // MITM protection required 74 // Encryption required 75 // User interaction acceptable 76 LEVEL_3, 77 78 // MITM protection required 79 // Encryption required 80 // 128-bit equivalent strength for link and encryption keys required (P-192 is not enough) 81 // User interaction acceptable 82 LEVEL_4, 83 } gap_security_level_t; 84 85 86 typedef enum { 87 // non-secure 88 GAP_SECURITY_MODE_1 = 1, 89 90 // service level enforced security 91 GAP_SECURITY_MODE_2, 92 93 // link level enforced security 94 GAP_SECURITY_MODE_3, 95 96 // service level enforced security 97 GAP_SECURITY_MODE_4 98 } gap_security_mode_t; 99 100 typedef enum { 101 GAP_SECURITY_NONE, 102 GAP_SECURITY_ENCRYPTED, // SSP: JUST WORKS 103 GAP_SECURITY_AUTHENTICATED, // SSP: numeric comparison, passkey, OOB 104 // GAP_SECURITY_AUTHORIZED 105 } gap_security_state; 106 107 typedef enum { 108 GAP_CONNECTION_INVALID, 109 GAP_CONNECTION_ACL, 110 GAP_CONNECTION_SCO, 111 GAP_CONNECTION_LE 112 } gap_connection_type_t; 113 114 typedef struct le_connection_parameter_range{ 115 uint16_t le_conn_interval_min; 116 uint16_t le_conn_interval_max; 117 uint16_t le_conn_latency_min; 118 uint16_t le_conn_latency_max; 119 uint16_t le_supervision_timeout_min; 120 uint16_t le_supervision_timeout_max; 121 } le_connection_parameter_range_t; 122 123 typedef enum { 124 GAP_RANDOM_ADDRESS_TYPE_OFF = 0, 125 GAP_RANDOM_ADDRESS_TYPE_STATIC, 126 GAP_RANDOM_ADDRESS_NON_RESOLVABLE, 127 GAP_RANDOM_ADDRESS_RESOLVABLE, 128 } gap_random_address_type_t; 129 130 // Authorization state 131 typedef enum { 132 AUTHORIZATION_UNKNOWN, 133 AUTHORIZATION_PENDING, 134 AUTHORIZATION_DECLINED, 135 AUTHORIZATION_GRANTED 136 } authorization_state_t; 137 138 // Extended Advertising Parameters 139 typedef struct { 140 uint16_t advertising_event_properties; 141 uint16_t primary_advertising_interval_min; 142 uint16_t primary_advertising_interval_max; 143 uint8_t primary_advertising_channel_map; 144 bd_addr_type_t own_address_type; 145 bd_addr_type_t peer_address_type; 146 bd_addr_t peer_address; 147 uint8_t advertising_filter_policy; 148 int8_t advertising_tx_power; 149 uint8_t primary_advertising_phy; 150 uint8_t secondary_advertising_max_skip; 151 uint8_t secondary_advertising_phy; 152 uint8_t advertising_sid; 153 uint8_t scan_request_notification_enable; 154 } le_extended_advertising_parameters_t; 155 156 typedef struct { 157 uint16_t periodic_advertising_interval_min; 158 uint16_t periodic_advertising_interval_max; 159 uint16_t periodic_advertising_properties; 160 } le_periodic_advertising_parameters_t; 161 162 // Extended Advertising Set State 163 typedef struct { 164 btstack_linked_item_t item; 165 le_extended_advertising_parameters_t extended_params; 166 le_periodic_advertising_parameters_t periodic_params; 167 bd_addr_t random_address; 168 const uint8_t * adv_data; 169 const uint8_t * scan_data; 170 const uint8_t * periodic_data; 171 uint16_t adv_data_len; 172 uint16_t scan_data_len; 173 uint16_t periodic_data_len; 174 uint16_t adv_data_pos; 175 uint16_t scan_data_pos; 176 uint16_t periodic_data_pos; 177 uint16_t enable_timeout; 178 uint8_t advertising_handle; 179 uint8_t enable_max_scan_events; 180 bool periodic_include_adi; 181 uint8_t state; 182 uint8_t tasks; 183 } le_advertising_set_t; 184 185 /* API_START */ 186 187 // Classic + LE 188 189 /** 190 * @brief Read RSSI 191 * @param con_handle 192 * @events: GAP_EVENT_RSSI_MEASUREMENT 193 */ 194 int gap_read_rssi(hci_con_handle_t con_handle); 195 196 197 /** 198 * @brief Gets local address. 199 */ 200 void gap_local_bd_addr(bd_addr_t address_buffer); 201 202 /** 203 * @brief Disconnect connection with handle 204 * @param handle 205 */ 206 uint8_t gap_disconnect(hci_con_handle_t handle); 207 208 /** 209 * @brief Get connection type 210 * @param con_handle 211 * @result connection_type 212 */ 213 gap_connection_type_t gap_get_connection_type(hci_con_handle_t connection_handle); 214 215 /** 216 * @brief Get HCI connection role 217 * @param con_handle 218 * @result hci_role_t HCI_ROLE_MASTER / HCI_ROLE_SLAVE / HCI_ROLE_INVALID (if connection does not exist) 219 */ 220 hci_role_t gap_get_role(hci_con_handle_t connection_handle); 221 222 // Classic 223 224 /** 225 * @brief Request role switch 226 * @note this only requests the role switch. A HCI_EVENT_ROLE_CHANGE is emitted and its status field will indicate if the switch was succesful 227 * @param addr 228 * @param hci_role_t HCI_ROLE_MASTER / HCI_ROLE_SLAVE 229 * @result status 230 */ 231 uint8_t gap_request_role(const bd_addr_t addr, hci_role_t role); 232 233 /** 234 * @brief Sets local name. 235 * @note Default name is 'BTstack 00:00:00:00:00:00' 236 * @note '00:00:00:00:00:00' in local_name will be replaced with actual bd addr 237 * @param name is not copied, make sure memory stays valid 238 */ 239 void gap_set_local_name(const char * local_name); 240 241 /** 242 * @brief Set Extended Inquiry Response data 243 * @note If not set, local name will be used for EIR data (see gap_set_local_name) 244 * @note '00:00:00:00:00:00' in local_name will be replaced with actual bd addr 245 * @param eir_data size HCI_EXTENDED_INQUIRY_RESPONSE_DATA_LEN (240) bytes, is not copied make sure memory stays valid 246 */ 247 void gap_set_extended_inquiry_response(const uint8_t * data); 248 249 /** 250 * @brief Set class of device 251 */ 252 void gap_set_class_of_device(uint32_t class_of_device); 253 254 /** 255 * @brief Set default link policy settings for all classic ACL links 256 * @param default_link_policy_settings - see LM_LINK_POLICY_* in bluetooth.h 257 * @note common value: LM_LINK_POLICY_ENABLE_ROLE_SWITCH | LM_LINK_POLICY_ENABLE_SNIFF_MODE to enable role switch and sniff mode 258 */ 259 void gap_set_default_link_policy_settings(uint16_t default_link_policy_settings); 260 261 /** 262 * @brief Set Allow Role Switch param for outgoing classic ACL links 263 * @param allow_role_switch - true: allow remote device to request role switch, false: stay master 264 */ 265 void gap_set_allow_role_switch(bool allow_role_switch); 266 267 /** 268 * @brief Set link supervision timeout for outgoing classic ACL links 269 * @param default_link_supervision_timeout * 0.625 ms, default 0x7d00 = 20 seconds, 0 = no link supervision timeout 270 */ 271 void gap_set_link_supervision_timeout(uint16_t link_supervision_timeout); 272 273 /** 274 * @brief Enable link watchdog. If no ACL packet is sent within timeout_ms, the link will get disconnected 275 * note: current implementation uses the automatic flush timeout controller feature with a max timeout of 1.28s 276 * @param timeout_ms 277 */ 278 void gap_enable_link_watchdog(uint16_t timeout_ms); 279 280 /** 281 * @brief Enable/disable bonding. Default is enabled. 282 * @param enabled 283 */ 284 void gap_set_bondable_mode(int enabled); 285 286 /** 287 * @brief Get bondable mode. 288 * @return 1 if bondable 289 */ 290 int gap_get_bondable_mode(void); 291 292 /** 293 * @brief Set security mode for all outgoing and incoming connections. Default: GAP_SECURITY_MODE_4 294 * @param security_mode is GAP_SECURITY_MODE_2 or GAP_SECURITY_MODE_4 295 * @return status ERROR_CODE_SUCCESS or ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE 296 */ 297 uint8_t gap_set_security_mode(gap_security_mode_t security_mode); 298 299 /** 300 * @brief Get security mode 301 * @return security_mode 302 */ 303 gap_security_mode_t gap_get_security_mode(void); 304 305 /** 306 * @brief Set security level for all outgoing and incoming connections. Default: LEVEL_2 307 * @param security_level 308 * @note has to be called before services or profiles are initialized 309 */ 310 void gap_set_security_level(gap_security_level_t security_level); 311 312 /** 313 * @brief Get security level 314 * @return security_level 315 */ 316 gap_security_level_t gap_get_security_level(void); 317 318 /** 319 * @brief Set Secure Connections Only Mode for BR/EDR (Classic) Default: false 320 * @param enable 321 */ 322 void gap_set_secure_connections_only_mode(bool enable); 323 324 /** 325 * @breif Get Secure Connections Only Mode 326 * @param enabled 327 */ 328 bool gap_get_secure_connections_only_mode(void); 329 330 /** 331 * @brief Set minimal security level for registered services 332 * @param security_level 333 * @note Called by L2CAP based on registered services 334 */ 335 void gap_set_minimal_service_security_level(gap_security_level_t security_level); 336 337 /** 338 * @brief Register filter for rejecting classic connections. Callback will return 1 accept connection, 0 on reject. 339 */ 340 void gap_register_classic_connection_filter(int (*accept_callback)(bd_addr_t addr, hci_link_type_t link_type)); 341 342 /* Configure Secure Simple Pairing */ 343 344 /** 345 * @brief Enable will enable SSP during init. Default: true 346 */ 347 void gap_ssp_set_enable(int enable); 348 349 /** 350 * @brief Set IO Capability. BTstack will return capability to SSP requests 351 */ 352 void gap_ssp_set_io_capability(int ssp_io_capability); 353 354 /** 355 * @brief Set Authentication Requirements using during SSP 356 */ 357 void gap_ssp_set_authentication_requirement(int authentication_requirement); 358 359 /** 360 * @brief Enable/disable Secure Connections. Default: true if supported by Controller 361 */ 362 void gap_secure_connections_enable(bool enable); 363 364 /** 365 * @brief Query if Secure Connections can be used for Classic connections. 366 * @note Requires gap_secure_connections_enable == true and Controller to support it 367 */ 368 bool gap_secure_connections_active(void); 369 370 /** 371 * @brief If set, BTstack will confirm a numeric comparison and enter '000000' if requested. 372 */ 373 void gap_ssp_set_auto_accept(int auto_accept); 374 375 /** 376 * @brief Set required encryption key size for GAP Levels 1-3 on ccassic connections. Default: 16 bytes 377 * @param encryption_key_size in bytes. Valid 7..16 378 */ 379 void gap_set_required_encryption_key_size(uint8_t encryption_key_size); 380 381 /** 382 * @brief Start dedicated bonding with device. Disconnect after bonding. 383 * @param device 384 * @param request MITM protection 385 * @return error, if max num acl connections active 386 * @result GAP_DEDICATED_BONDING_COMPLETE 387 */ 388 int gap_dedicated_bonding(bd_addr_t device, int mitm_protection_required); 389 390 gap_security_level_t gap_security_level_for_link_key_type(link_key_type_t link_key_type); 391 392 /** 393 * @brief map link keys to secure connection yes/no 394 */ 395 bool gap_secure_connection_for_link_key_type(link_key_type_t link_key_type); 396 397 /** 398 * @brief map link keys to authenticated 399 */ 400 bool gap_authenticated_for_link_key_type(link_key_type_t link_key_type); 401 402 gap_security_level_t gap_security_level(hci_con_handle_t con_handle); 403 404 void gap_request_security_level(hci_con_handle_t con_handle, gap_security_level_t level); 405 406 bool gap_mitm_protection_required_for_security_level(gap_security_level_t level); 407 408 /** 409 * @brief Set Page Scan Type 410 * @param page_scan_interval * 0.625 ms, range: 0x0012..0x1000, default: 0x0800 411 * @param page_scan_windows * 0.625 ms, range: 0x0011..page_scan_interval, default: 0x0012 412 */ 413 void gap_set_page_scan_activity(uint16_t page_scan_interval, uint16_t page_scan_window); 414 415 /** 416 * @brief Set Page Scan Type 417 * @param page_scan_mode 418 */ 419 void gap_set_page_scan_type(page_scan_type_t page_scan_type); 420 421 /** 422 * @brief Set Page Timeout 423 * @param page_timeout * 0.625 ms, range: 0x0001..0xffff, default: 0x6000 (ca 15 seconds) 424 */ 425 void gap_set_page_timeout(uint16_t page_timeout); 426 427 // LE 428 429 /** 430 * @brief Set parameters for LE Scan 431 * @param scan_type 0 = passive, 1 = active 432 * @param scan_interval range 0x0004..0x4000, unit 0.625 ms 433 * @param scan_window range 0x0004..0x4000, unit 0.625 ms 434 * @param scanning_filter_policy 0 = all devices, 1 = all from whitelist 435 */ 436 void gap_set_scan_params(uint8_t scan_type, uint16_t scan_interval, uint16_t scan_window, uint8_t scanning_filter_policy); 437 438 /** 439 * @brief Set parameters for LE Scan 440 * @deprecated Use gap_set_scan_params instead 441 */ 442 void gap_set_scan_parameters(uint8_t scan_type, uint16_t scan_interval, uint16_t scan_window); 443 444 /** 445 * @brief Start LE Scan 446 */ 447 void gap_start_scan(void); 448 449 /** 450 * @brief Stop LE Scan 451 */ 452 void gap_stop_scan(void); 453 454 /** 455 * @brief Enable privacy by using random addresses 456 * @param random_address_type to use (incl. OFF) 457 */ 458 void gap_random_address_set_mode(gap_random_address_type_t random_address_type); 459 460 /** 461 * @brief Get privacy mode 462 */ 463 gap_random_address_type_t gap_random_address_get_mode(void); 464 465 /** 466 * @brief Sets update period for random address 467 * @param period_ms in ms 468 */ 469 void gap_random_address_set_update_period(int period_ms); 470 471 /** 472 * @brief Sets a fixed random address for advertising 473 * @param addr 474 * @note Sets random address mode to type off 475 */ 476 void gap_random_address_set(const bd_addr_t addr); 477 478 /** 479 * @brief Set Advertisement Data 480 * @param advertising_data_length 481 * @param advertising_data (max 31 octets) 482 * @note data is not copied, pointer has to stay valid 483 * @note '00:00:00:00:00:00' in advertising_data will be replaced with actual bd addr 484 */ 485 void gap_advertisements_set_data(uint8_t advertising_data_length, uint8_t * advertising_data); 486 487 /** 488 * @brief Set Advertisement Parameters 489 * @param adv_int_min 490 * @param adv_int_max 491 * @param adv_type 492 * @param direct_address_type 493 * @param direct_address 494 * @param channel_map 495 * @param filter_policy 496 * @note own_address_type is used from gap_random_address_set_mode 497 */ 498 void gap_advertisements_set_params(uint16_t adv_int_min, uint16_t adv_int_max, uint8_t adv_type, 499 uint8_t direct_address_typ, bd_addr_t direct_address, uint8_t channel_map, uint8_t filter_policy); 500 501 /** 502 * @brief Enable/Disable Advertisements. OFF by default. 503 * @param enabled 504 */ 505 void gap_advertisements_enable(int enabled); 506 507 /** 508 * @brief Set Scan Response Data 509 * 510 * @note For scan response data, scannable undirected advertising (ADV_SCAN_IND) need to be used 511 * 512 * @param advertising_data_length 513 * @param advertising_data (max 31 octets) 514 * @note data is not copied, pointer has to stay valid 515 * @note '00:00:00:00:00:00' in scan_response_data will be replaced with actual bd addr 516 */ 517 void gap_scan_response_set_data(uint8_t scan_response_data_length, uint8_t * scan_response_data); 518 519 /** 520 * @brief Provide storage for new advertising set and setup on Controller 521 * @param storage to use by stack, needs to stay valid until adv set is removed with gap_extended_advertising_remove 522 * @param advertising_parameters 523 * @param out_advertising_handle to use with other adv config commands 524 * @return status 525 * @events: GAP_SUBEVENT_ADVERTISING_SET_INSTALLED 526 */ 527 uint8_t gap_extended_advertising_setup(le_advertising_set_t * storage, const le_extended_advertising_parameters_t * advertising_parameters, uint8_t * out_advertising_handle); 528 529 /** 530 * @param Set advertising params for advertising set 531 * @param advertising_handle 532 * @param advertising_parameters 533 * @return status 534 */ 535 uint8_t gap_extended_advertising_set_params(uint8_t advertising_handle, const le_extended_advertising_parameters_t * advertising_parameters); 536 537 /** 538 * @param Get advertising params for advertising set, e.g. to update params 539 * @param advertising_handle 540 * @param advertising_parameters 541 * @return status 542 */ 543 uint8_t gap_extended_advertising_get_params(uint8_t advertising_handle, le_extended_advertising_parameters_t * advertising_parameters); 544 545 /** 546 * @param Set periodic advertising params for advertising set 547 * @param advertising_handle 548 * @param advertising_parameters 549 * @return status 550 */ 551 uint8_t gap_periodic_advertising_set_params(uint8_t advertising_handle, const le_periodic_advertising_parameters_t * advertising_parameters); 552 553 /** 554 * @param Get params for periodic advertising set, e.g. to update params 555 * @param advertising_handle 556 * @param advertising_parameters 557 * @return status 558 */ 559 uint8_t gap_periodic_advertising_get_params(uint8_t advertising_handle, le_periodic_advertising_parameters_t * advertising_parameters); 560 561 /** 562 * @param Set random addrress for advertising set 563 * @param advertising_handle 564 * @param random_address 565 * @return status 566 */ 567 uint8_t gap_extended_advertising_set_random_address(uint8_t advertising_handle, bd_addr_t random_address); 568 569 /** 570 * @brief Set Advertising Data for a advertisement set 571 * @param advertising_handle 572 * @param advertising_data_length 573 * @param advertising_data 574 * @return status 575 */ 576 uint8_t gap_extended_advertising_set_adv_data(uint8_t advertising_handle, uint16_t advertising_data_length, const uint8_t * advertising_data); 577 578 /** 579 * @brief Set Scan Response Data for a advertisement set 580 * @param advertising_handle 581 * @param scan_response_data_length 582 * @param scan_response_data 583 * @return status 584 */ 585 uint8_t gap_extended_advertising_set_scan_response_data(uint8_t advertising_handle, uint16_t scan_response_data_length, const uint8_t * scan_response_data); 586 587 /** 588 * @brief Set data for periodic advertisement set 589 * @param advertising_handle 590 * @param periodic_data_length 591 * @param periodic_data 592 * @return status 593 */ 594 uint8_t gap_periodic_advertising_set_data(uint8_t advertising_handle, uint16_t periodic_data_length, const uint8_t * periodic_data); 595 596 /** 597 * @brief Start advertising advertising set 598 * @param advertising_handle 599 * @param timeout in 10ms, or 0 == no timeout 600 * @param num_extended_advertising_events Controller shall send, or 0 == no max number 601 * @return status 602 */ 603 uint8_t gap_extended_advertising_start(uint8_t advertising_handle, uint16_t timeout, uint8_t num_extended_advertising_events); 604 605 /** 606 * @brief Stop advertising 607 * @param advertising_handle 608 * @return status 609 */ 610 uint8_t gap_extended_advertising_stop(uint8_t advertising_handle); 611 612 /** 613 * @brief Start periodic advertising for given advertising set 614 * @param advertising_handle 615 * @param include_adi 616 * @return status 617 */ 618 uint8_t gap_periodic_advertising_start(uint8_t advertising_handle, bool include_adi); 619 620 /** 621 * @brief Stop periodic advertising for given advertising set 622 * @param advertising_handle 623 * @return status 624 */ 625 uint8_t gap_periodic_advertising_stop(uint8_t advertising_handle); 626 627 /** 628 * @brief Remove advertising set from Controller 629 * @param advertising_handle 630 * @return status 631 * @events: GAP_SUBEVENT_ADVERTISING_SET_REMOVED 632 */ 633 uint8_t gap_extended_advertising_remove(uint8_t advertising_handle); 634 635 /** 636 * @brief Set connection parameters for outgoing connections 637 * @param conn_scan_interval (unit: 0.625 msec), default: 60 ms 638 * @param conn_scan_window (unit: 0.625 msec), default: 30 ms 639 * @param conn_interval_min (unit: 1.25ms), default: 10 ms 640 * @param conn_interval_max (unit: 1.25ms), default: 30 ms 641 * @param conn_latency, default: 4 642 * @param supervision_timeout (unit: 10ms), default: 720 ms 643 * @param min_ce_length (unit: 0.625ms), default: 10 ms 644 * @param max_ce_length (unit: 0.625ms), default: 30 ms 645 */ 646 void gap_set_connection_parameters(uint16_t conn_scan_interval, uint16_t conn_scan_window, 647 uint16_t conn_interval_min, uint16_t conn_interval_max, uint16_t conn_latency, 648 uint16_t supervision_timeout, uint16_t min_ce_length, uint16_t max_ce_length); 649 650 /** 651 * @brief Request an update of the connection parameter for a given LE connection 652 * @param handle 653 * @param conn_interval_min (unit: 1.25ms) 654 * @param conn_interval_max (unit: 1.25ms) 655 * @param conn_latency 656 * @param supervision_timeout (unit: 10ms) 657 * @return 0 if ok 658 */ 659 int gap_request_connection_parameter_update(hci_con_handle_t con_handle, uint16_t conn_interval_min, 660 uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout); 661 662 /** 663 * @brief Updates the connection parameters for a given LE connection 664 * @param handle 665 * @param conn_interval_min (unit: 1.25ms) 666 * @param conn_interval_max (unit: 1.25ms) 667 * @param conn_latency 668 * @param supervision_timeout (unit: 10ms) 669 * @return 0 if ok 670 */ 671 int gap_update_connection_parameters(hci_con_handle_t con_handle, uint16_t conn_interval_min, 672 uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout); 673 674 /** 675 * @brief Set accepted connection parameter range 676 * @param range 677 */ 678 void gap_get_connection_parameter_range(le_connection_parameter_range_t * range); 679 680 /** 681 * @brief Get accepted connection parameter range 682 * @param range 683 */ 684 void gap_set_connection_parameter_range(le_connection_parameter_range_t * range); 685 686 /** 687 * @brief Test if connection parameters are inside in existing rage 688 * @param conn_interval_min (unit: 1.25ms) 689 * @param conn_interval_max (unit: 1.25ms) 690 * @param conn_latency 691 * @param supervision_timeout (unit: 10ms) 692 * @return 1 if included 693 */ 694 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); 695 696 /** 697 * @brief Set max number of connections in LE Peripheral role (if Bluetooth Controller supports it) 698 * @note: default: 1 699 * @param max_peripheral_connections 700 */ 701 void gap_set_max_number_peripheral_connections(int max_peripheral_connections); 702 703 /** 704 * @brief Add Device to Whitelist 705 * @param address_typ 706 * @param address 707 * @return 0 if ok 708 */ 709 uint8_t gap_whitelist_add(bd_addr_type_t address_type, const bd_addr_t address); 710 711 /** 712 * @brief Remove Device from Whitelist 713 * @param address_typ 714 * @param address 715 * @return 0 if ok 716 */ 717 uint8_t gap_whitelist_remove(bd_addr_type_t address_type, const bd_addr_t address); 718 719 /** 720 * @brief Clear Whitelist 721 * @return 0 if ok 722 */ 723 uint8_t gap_whitelist_clear(void); 724 725 /** 726 * @brief Connect to remote LE device 727 */ 728 uint8_t gap_connect(const bd_addr_t addr, bd_addr_type_t addr_type); 729 730 /** 731 * @brief Connect with Whitelist 732 * @note Explicit whitelist management and this connect with whitelist replace deprecated gap_auto_connection_* functions 733 * @return - if ok 734 */ 735 uint8_t gap_connect_with_whitelist(void); 736 737 /** 738 * @brief Cancel connection process initiated by gap_connect 739 */ 740 uint8_t gap_connect_cancel(void); 741 742 /** 743 * @brief Auto Connection Establishment - Start Connecting to device 744 * @deprecated Please setup Whitelist with gap_whitelist_* and start connecting with gap_connect_with_whitelist 745 * @param address_type 746 * @param address 747 * @return 0 if ok 748 */ 749 uint8_t gap_auto_connection_start(bd_addr_type_t address_type, const bd_addr_t address); 750 751 /** 752 * @brief Auto Connection Establishment - Stop Connecting to device 753 * @deprecated Please setup Whitelist with gap_whitelist_* and start connecting with gap_connect_with_whitelist 754 * @param address_type 755 * @param address 756 * @return 0 if ok 757 */ 758 uint8_t gap_auto_connection_stop(bd_addr_type_t address_type, const bd_addr_t address); 759 760 /** 761 * @brief Auto Connection Establishment - Stop everything 762 * @deprecated Please setup Whitelist with gap_whitelist_* and start connecting with gap_connect_with_whitelist 763 * @note Convenience function to stop all active auto connection attempts 764 */ 765 uint8_t gap_auto_connection_stop_all(void); 766 767 /** 768 * @brief Set LE PHY 769 * @param con_handle 770 * @param all_phys 0 = set rx/tx, 1 = set only rx, 2 = set only tx 771 * @param tx_phys 1 = 1M, 2 = 2M, 4 = Coded 772 * @param rx_phys 1 = 1M, 2 = 2M, 4 = Coded 773 * @param phy_options 0 = no preferred coding for Coded, 1 = S=2 coding (500 kbit), 2 = S=8 coding (125 kbit) 774 * @return 0 if ok 775 */ 776 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); 777 778 /** 779 * @brief Get connection interval 780 * @param con_handle 781 * @return connection interval, otherwise 0 if error 782 */ 783 uint16_t gap_le_connection_interval(hci_con_handle_t con_handle); 784 785 /** 786 * 787 * @brief Get encryption key size. 788 * @param con_handle 789 * @return 0 if not encrypted, 7-16 otherwise 790 */ 791 uint8_t gap_encryption_key_size(hci_con_handle_t con_handle); 792 793 /** 794 * @brief Get authentication property. 795 * @param con_handle 796 * @return 1 if bonded with OOB/Passkey (AND MITM protection) 797 */ 798 bool gap_authenticated(hci_con_handle_t con_handle); 799 800 /** 801 * @brief Get secure connection property 802 * @param con_handle 803 * @return 1 if bonded usiung LE Secure Connections 804 */ 805 bool gap_secure_connection(hci_con_handle_t con_handle); 806 807 /** 808 * @brief Queries authorization state. 809 * @param con_handle 810 * @return authorization_state for the current session 811 */ 812 authorization_state_t gap_authorization_state(hci_con_handle_t con_handle); 813 814 /** 815 * @brief Get bonded property (BR/EDR/LE) 816 * @note LE: has to be called after identity resolving is complete 817 * @param con_handle 818 * @return true if bonded 819 */ 820 bool gap_bonded(hci_con_handle_t con_handle); 821 822 // Classic 823 #ifdef ENABLE_CLASSIC 824 825 /** 826 * @brief Override page scan mode. Page scan mode enabled by l2cap when services are registered 827 * @note Might be used to reduce power consumption while Bluetooth module stays powered but no (new) 828 * connections are expected 829 */ 830 void gap_connectable_control(uint8_t enable); 831 832 /** 833 * @brief Allows to control if device is discoverable. OFF by default. 834 */ 835 void gap_discoverable_control(uint8_t enable); 836 837 /** 838 * @brief Deletes link key for remote device with baseband address. 839 * @param addr 840 * @note On most desktop ports, the Link Key DB uses a TLV and there is one TLV storage per 841 * Controller resp. its Bluetooth Address. As the Bluetooth Address is retrieved during 842 * power up, this function only works, when the stack is in working state for these ports. 843 */ 844 void gap_drop_link_key_for_bd_addr(bd_addr_t addr); 845 846 /** 847 * @brief Delete all stored link keys 848 * @note On most desktop ports, the Link Key DB uses a TLV and there is one TLV storage per 849 * Controller resp. its Bluetooth Address. As the Bluetooth Address is retrieved during 850 * power up, this function only works, when the stack is in working state for these ports. 851 */ 852 void gap_delete_all_link_keys(void); 853 854 /** 855 * @brief Store link key for remote device with baseband address 856 * @param addr 857 * @param link_key 858 * @param link_key_type 859 * @note On most desktop ports, the Link Key DB uses a TLV and there is one TLV storage per 860 * Controller resp. its Bluetooth Address. As the Bluetooth Address is retrieved during 861 * power up, this function only works, when the stack is in working state for these ports. 862 */ 863 void gap_store_link_key_for_bd_addr(bd_addr_t addr, link_key_t link_key, link_key_type_t type); 864 865 /** 866 * @brief Get link for remote device with basband address 867 * @param addr 868 * @param link_key (out) is stored here 869 * @param link_key_type (out) is stored here 870 * @note On most desktop ports, the Link Key DB uses a TLV and there is one TLV storage per 871 * Controller resp. its Bluetooth Address. As the Bluetooth Address is retrieved during 872 * power up, this function only works, when the stack is in working state for these ports. 873 */ 874 bool gap_get_link_key_for_bd_addr(bd_addr_t addr, link_key_t link_key, link_key_type_t * type); 875 876 /** 877 * @brief Setup Link Key iterator 878 * @param it 879 * @return 1 on success 880 * @note On most desktop ports, the Link Key DB uses a TLV and there is one TLV storage per 881 * Controller resp. its Bluetooth Address. As the Bluetooth Address is retrieved during 882 * power up, this function only works, when the stack is in working state for these ports. 883 */ 884 int gap_link_key_iterator_init(btstack_link_key_iterator_t * it); 885 886 /** 887 * @brief Get next Link Key 888 * @param it 889 * @brief addr 890 * @brief link_key 891 * @brief type of link key 892 * @return 1, if valid link key found 893 * @see note on gap_link_key_iterator_init 894 */ 895 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); 896 897 /** 898 * @brief Frees resources allocated by iterator_init 899 * @note Must be called after iteration to free resources 900 * @param it 901 * @see note on gap_link_key_iterator_init 902 */ 903 void gap_link_key_iterator_done(btstack_link_key_iterator_t * it); 904 905 /** 906 * @brief Start GAP Classic Inquiry 907 * @param duration in 1.28s units 908 * @return 0 if ok 909 * @events: GAP_EVENT_INQUIRY_RESULT, GAP_EVENT_INQUIRY_COMPLETE 910 */ 911 int gap_inquiry_start(uint8_t duration_in_1280ms_units); 912 913 /** 914 * @brief Start GAP Classic Periodic Inquiry 915 * @param duration in 1.28s units 916 * @param max_period_length between consecutive inquiries in 1.28s units 917 * @param min_period_length between consecutive inquiries in 1.28s units 918 * @return 0 if ok 919 * @events: GAP_EVENT_INQUIRY_RESULT, GAP_EVENT_INQUIRY_COMPLETE 920 */ 921 uint8_t gap_inquiry_periodic_start(uint8_t duration, uint16_t max_period_length, uint16_t min_period_length); 922 923 /** 924 * @brief Stop GAP Classic Inquiry (regular or periodic) 925 * @return 0 if ok 926 * @events: GAP_EVENT_INQUIRY_COMPLETE 927 */ 928 int gap_inquiry_stop(void); 929 930 /** 931 * @brief Set LAP for GAP Classic Inquiry 932 * @param lap GAP_IAC_GENERAL_INQUIRY (default), GAP_IAC_LIMITED_INQUIRY 933 */ 934 void gap_inquiry_set_lap(uint32_t lap); 935 936 /** 937 * @brief Set Inquiry Scan Activity 938 * @param inquiry_scan_interval range: 0x0012 to 0x1000; only even values are valid, Time = N * 0.625 ms 939 * @param inquiry_scan_window range: 0x0011 to 0x1000; Time = N * 0.625 ms 940 */ 941 void gap_inquiry_set_scan_activity(uint16_t inquiry_scan_interval, uint16_t inquiry_scan_window); 942 943 /** 944 * @brief Remote Name Request 945 * @param addr 946 * @param page_scan_repetition_mode 947 * @param clock_offset only used when bit 15 is set - pass 0 if not known 948 * @events: HCI_EVENT_REMOTE_NAME_REQUEST_COMPLETE 949 */ 950 int gap_remote_name_request(const bd_addr_t addr, uint8_t page_scan_repetition_mode, uint16_t clock_offset); 951 952 /** 953 * @brief Legacy Pairing Pin Code Response 954 * @note data is not copied, pointer has to stay valid 955 * @param addr 956 * @param pin 957 * @return 0 if ok 958 */ 959 int gap_pin_code_response(const bd_addr_t addr, const char * pin); 960 961 /** 962 * @brief Legacy Pairing Pin Code Response for binary data / non-strings 963 * @note data is not copied, pointer has to stay valid 964 * @param addr 965 * @param pin_data 966 * @param pin_len 967 * @return 0 if ok 968 */ 969 int gap_pin_code_response_binary(const bd_addr_t addr, const uint8_t * pin_data, uint8_t pin_len); 970 971 /** 972 * @brief Abort Legacy Pairing 973 * @param addr 974 * @param pin 975 * @return 0 if ok 976 */ 977 int gap_pin_code_negative(bd_addr_t addr); 978 979 /** 980 * @brief SSP Passkey Response 981 * @param addr 982 * @param passkey [0..999999] 983 * @return 0 if ok 984 */ 985 int gap_ssp_passkey_response(const bd_addr_t addr, uint32_t passkey); 986 987 /** 988 * @brief Abort SSP Passkey Entry/Pairing 989 * @param addr 990 * @param pin 991 * @return 0 if ok 992 */ 993 int gap_ssp_passkey_negative(const bd_addr_t addr); 994 995 /** 996 * @brief Accept SSP Numeric Comparison 997 * @param addr 998 * @param passkey 999 * @return 0 if ok 1000 */ 1001 int gap_ssp_confirmation_response(const bd_addr_t addr); 1002 1003 /** 1004 * @brief Abort SSP Numeric Comparison/Pairing 1005 * @param addr 1006 * @param pin 1007 * @return 0 if ok 1008 */ 1009 int gap_ssp_confirmation_negative(const bd_addr_t addr); 1010 1011 /** 1012 * @brief Generate new OOB data 1013 * @note OOB data will be provided in GAP_EVENT_LOCAL_OOB_DATA and be used in future pairing procedures 1014 */ 1015 void gap_ssp_generate_oob_data(void); 1016 1017 /** 1018 * @brief Report Remote OOB Data 1019 * @note Pairing Hash and Randomizer are expected in big-endian byte format 1020 * @param bd_addr 1021 * @param c_192 Simple Pairing Hash C derived from P-192 public key 1022 * @param r_192 Simple Pairing Randomizer derived from P-192 public key 1023 * @param c_256 Simple Pairing Hash C derived from P-256 public key 1024 * @param r_256 Simple Pairing Randomizer derived from P-256 public key 1025 */ 1026 uint8_t gap_ssp_remote_oob_data(const bd_addr_t addr, const uint8_t * c_192, const uint8_t * r_192, const uint8_t * c_256, const uint8_t * r_256); 1027 1028 /** 1029 * Send SSP IO Capabilities Reply 1030 * @note IO Capabilities (Negative) Reply is sent automatically unless ENABLE_EXPLICIT_IO_CAPABILITIES_REPLY 1031 * @param addr 1032 * @return 0 if ok 1033 */ 1034 uint8_t gap_ssp_io_capabilities_response(const bd_addr_t addr); 1035 1036 /** 1037 * Send SSP IO Capabilities Negative Reply 1038 * @note IO Capabilities (Negative) Reply is sent automatically unless ENABLE_EXPLICIT_IO_CAPABILITIES_REPLY 1039 * @param addr 1040 * @return 0 if ok 1041 */ 1042 uint8_t gap_ssp_io_capabilities_negative(const bd_addr_t addr); 1043 1044 /** 1045 * Send Link Key Reponse 1046 * @note Link Key (Negative) Reply is sent automatically unless ENABLE_EXPLICIT_LINK_KEY_RESPONSE 1047 * @param addr 1048 * @param link_key 1049 * @param type or INVALID_LINK_KEY if link key not available 1050 * @return 0 if ok 1051 */ 1052 uint8_t gap_send_link_key_response(const bd_addr_t addr, link_key_t link_key, link_key_type_t type); 1053 1054 /** 1055 * @brief Enter Sniff mode 1056 * @param con_handle 1057 * @param sniff_min_interval range: 0x0002 to 0xFFFE; only even values are valid, Time = N * 0.625 ms 1058 * @param sniff_max_interval range: 0x0002 to 0xFFFE; only even values are valid, Time = N * 0.625 ms 1059 * @param sniff_attempt Number of Baseband receive slots for sniff attempt. 1060 * @param sniff_timeout Number of Baseband receive slots for sniff timeout. 1061 @ @return 0 if ok 1062 */ 1063 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); 1064 1065 /** 1066 * @brief Exit Sniff mode 1067 * @param con_handle 1068 @ @return 0 if ok 1069 */ 1070 uint8_t gap_sniff_mode_exit(hci_con_handle_t con_handle); 1071 1072 /** 1073 * @brief Configure Sniff Subrating 1074 * @param con_handle 1075 * @param max_latency range: 0x0002 to 0xFFFE; Time = N * 0.625 ms 1076 * @param min_remote_timeout range: 0x0002 to 0xFFFE; Time = N * 0.625 ms 1077 * @param min_local_timeout range: 0x0002 to 0xFFFE; Time = N * 0.625 ms 1078 @ @return 0 if ok 1079 */ 1080 uint8_t gap_sniff_subrating_configure(hci_con_handle_t con_handle, uint16_t max_latency, uint16_t min_remote_timeout, uint16_t min_local_timeout); 1081 1082 /** 1083 * @Brief Set QoS 1084 * @param con_handle 1085 * @param service_type 1086 * @param token_rate 1087 * @param peak_bandwidth 1088 * @param latency 1089 * @param delay_variation 1090 @ @return 0 if ok 1091 */ 1092 uint8_t gap_qos_set(hci_con_handle_t con_handle, hci_service_type_t service_type, uint32_t token_rate, uint32_t peak_bandwidth, uint32_t latency, uint32_t delay_variation); 1093 1094 #endif 1095 1096 // LE 1097 1098 /** 1099 * @brief Get own addr type and address used for LE for next scan/advertisement/connect operation 1100 */ 1101 void gap_le_get_own_address(uint8_t * addr_type, bd_addr_t addr); 1102 1103 /** 1104 * @brief Get own addr type and address used for LE advertisements (Peripheral) 1105 */ 1106 void gap_le_get_own_advertisements_address(uint8_t * addr_type, bd_addr_t addr); 1107 1108 /** 1109 * @brief Get own addr type and address used for LE connections (Central) 1110 */ 1111 void gap_le_get_own_connection_address(uint8_t * addr_type, bd_addr_t addr); 1112 1113 /** 1114 * @brief Get state of connection re-encryption for bonded devices when in central role 1115 * @note used by gatt_client and att_server to wait for re-encryption 1116 * @param con_handle 1117 * @return 1 if security setup is active 1118 */ 1119 int gap_reconnect_security_setup_active(hci_con_handle_t con_handle); 1120 1121 /** 1122 * @brief Delete bonding information for remote device 1123 * @note On most desktop ports, the LE Device DB uses a TLV and there is one TLV storage per 1124 * Controller resp. its Bluetooth Address. As the Bluetooth Address is retrieved during 1125 * power up, this function only works, when the stack is in working state for these ports. 1126 * @param address_type 1127 * @param address 1128 */ 1129 void gap_delete_bonding(bd_addr_type_t address_type, bd_addr_t address); 1130 1131 /** 1132 * LE Privacy 1.2 - requires support by Controller and ENABLE_LE_RESOLVING_LIST to be defined 1133 */ 1134 1135 /** 1136 * @brief Load LE Device DB entries into Controller Resolving List to allow filtering on 1137 * bonded devies with resolvable private addresses 1138 * @return EROOR_CODE_SUCCESS if supported by Controller 1139 */ 1140 uint8_t gap_load_resolving_list_from_le_device_db(void); 1141 1142 /** 1143 * @brief Get local persistent IRK 1144 */ 1145 const uint8_t * gap_get_persistent_irk(void); 1146 1147 /* API_END*/ 1148 1149 #if defined __cplusplus 1150 } 1151 #endif 1152 1153 #endif // GAP_H 1154