1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 20 #ifndef H_BLE_GAP_ 21 #define H_BLE_GAP_ 22 23 /** 24 * @brief Bluetooth Host Generic Access Profile (GAP) 25 * @defgroup bt_host_gap Bluetooth Host Generic Access Profile (GAP) 26 * @ingroup bt_host 27 * @{ 28 */ 29 30 #include <inttypes.h> 31 #include "host/ble_hs.h" 32 #include "host/ble_hs_adv.h" 33 #include "syscfg/syscfg.h" 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 39 struct hci_le_conn_complete; 40 struct hci_conn_update; 41 42 /** 30 ms. */ 43 #define BLE_GAP_ADV_FAST_INTERVAL1_MIN (30 * 1000 / BLE_HCI_ADV_ITVL) 44 45 /** 60 ms. */ 46 #define BLE_GAP_ADV_FAST_INTERVAL1_MAX (60 * 1000 / BLE_HCI_ADV_ITVL) 47 48 /** 100 ms. */ 49 #define BLE_GAP_ADV_FAST_INTERVAL2_MIN (100 * 1000 / BLE_HCI_ADV_ITVL) 50 51 /** 150 ms. */ 52 #define BLE_GAP_ADV_FAST_INTERVAL2_MAX (150 * 1000 / BLE_HCI_ADV_ITVL) 53 54 /** 30 ms; active scanning. */ 55 #define BLE_GAP_SCAN_FAST_INTERVAL_MIN (30 * 1000 / BLE_HCI_ADV_ITVL) 56 57 /** 60 ms; active scanning. */ 58 #define BLE_GAP_SCAN_FAST_INTERVAL_MAX (60 * 1000 / BLE_HCI_ADV_ITVL) 59 60 /** 11.25 ms; limited discovery interval. */ 61 #define BLE_GAP_LIM_DISC_SCAN_INT (11.25 * 1000 / BLE_HCI_SCAN_ITVL) 62 63 /** 11.25 ms; limited discovery window (not from the spec). */ 64 #define BLE_GAP_LIM_DISC_SCAN_WINDOW (11.25 * 1000 / BLE_HCI_SCAN_ITVL) 65 66 /** 30 ms; active scanning. */ 67 #define BLE_GAP_SCAN_FAST_WINDOW (30 * 1000 / BLE_HCI_SCAN_ITVL) 68 69 /* 30.72 seconds; active scanning. */ 70 #define BLE_GAP_SCAN_FAST_PERIOD (30.72 * 1000) 71 72 /** 1.28 seconds; background scanning. */ 73 #define BLE_GAP_SCAN_SLOW_INTERVAL1 (1280 * 1000 / BLE_HCI_SCAN_ITVL) 74 75 /** 11.25 ms; background scanning. */ 76 #define BLE_GAP_SCAN_SLOW_WINDOW1 (11.25 * 1000 / BLE_HCI_SCAN_ITVL) 77 78 /** 10.24 seconds. */ 79 #define BLE_GAP_DISC_DUR_DFLT (10.24 * 1000) 80 81 /** 30 seconds (not from the spec). */ 82 #define BLE_GAP_CONN_DUR_DFLT (30 * 1000) 83 84 /** 1 second. */ 85 #define BLE_GAP_CONN_PAUSE_CENTRAL (1 * 1000) 86 87 /** 5 seconds. */ 88 #define BLE_GAP_CONN_PAUSE_PERIPHERAL (5 * 1000) 89 90 /* 30 ms. */ 91 #define BLE_GAP_INITIAL_CONN_ITVL_MIN (30 * 1000 / BLE_HCI_CONN_ITVL) 92 93 /* 50 ms. */ 94 #define BLE_GAP_INITIAL_CONN_ITVL_MAX (50 * 1000 / BLE_HCI_CONN_ITVL) 95 96 /** Default channels mask: all three channels are used. */ 97 #define BLE_GAP_ADV_DFLT_CHANNEL_MAP 0x07 98 99 #define BLE_GAP_INITIAL_CONN_LATENCY 0 100 #define BLE_GAP_INITIAL_SUPERVISION_TIMEOUT 0x0100 101 #define BLE_GAP_INITIAL_CONN_MIN_CE_LEN 0x0010 102 #define BLE_GAP_INITIAL_CONN_MAX_CE_LEN 0x0300 103 104 #define BLE_GAP_ROLE_MASTER 0 105 #define BLE_GAP_ROLE_SLAVE 1 106 107 #define BLE_GAP_EVENT_CONNECT 0 108 #define BLE_GAP_EVENT_DISCONNECT 1 109 /* Reserved 2 */ 110 #define BLE_GAP_EVENT_CONN_UPDATE 3 111 #define BLE_GAP_EVENT_CONN_UPDATE_REQ 4 112 #define BLE_GAP_EVENT_L2CAP_UPDATE_REQ 5 113 #define BLE_GAP_EVENT_TERM_FAILURE 6 114 #define BLE_GAP_EVENT_DISC 7 115 #define BLE_GAP_EVENT_DISC_COMPLETE 8 116 #define BLE_GAP_EVENT_ADV_COMPLETE 9 117 #define BLE_GAP_EVENT_ENC_CHANGE 10 118 #define BLE_GAP_EVENT_PASSKEY_ACTION 11 119 #define BLE_GAP_EVENT_NOTIFY_RX 12 120 #define BLE_GAP_EVENT_NOTIFY_TX 13 121 #define BLE_GAP_EVENT_SUBSCRIBE 14 122 #define BLE_GAP_EVENT_MTU 15 123 #define BLE_GAP_EVENT_IDENTITY_RESOLVED 16 124 #define BLE_GAP_EVENT_REPEAT_PAIRING 17 125 #define BLE_GAP_EVENT_PHY_UPDATE_COMPLETE 18 126 #define BLE_GAP_EVENT_EXT_DISC 19 127 128 /*** Reason codes for the subscribe GAP event. */ 129 130 /** Peer's CCCD subscription state changed due to a descriptor write. */ 131 #define BLE_GAP_SUBSCRIBE_REASON_WRITE 1 132 133 /** Peer's CCCD subscription state cleared due to connection termination. */ 134 #define BLE_GAP_SUBSCRIBE_REASON_TERM 2 135 136 /** 137 * Peer's CCCD subscription state changed due to restore from persistence 138 * (bonding restored). 139 */ 140 #define BLE_GAP_SUBSCRIBE_REASON_RESTORE 3 141 142 #define BLE_GAP_REPEAT_PAIRING_RETRY 1 143 #define BLE_GAP_REPEAT_PAIRING_IGNORE 2 144 145 /** Connection security state */ 146 struct ble_gap_sec_state { 147 /** If connection is encrypted */ 148 unsigned encrypted:1; 149 150 /** If connection is authenticated */ 151 unsigned authenticated:1; 152 153 /** If connection is bonded (security information is stored) */ 154 unsigned bonded:1; 155 156 /** Size of a key used for encryption */ 157 unsigned key_size:5; 158 }; 159 160 /** Advertising parameters */ 161 struct ble_gap_adv_params { 162 /** Advertising mode. Can be one of following constants: 163 * - BLE_GAP_CONN_MODE_NON (non-connectable; 3.C.9.3.2). 164 * - BLE_GAP_CONN_MODE_DIR (directed-connectable; 3.C.9.3.3). 165 * - BLE_GAP_CONN_MODE_UND (undirected-connectable; 3.C.9.3.4). 166 */ 167 uint8_t conn_mode; 168 /** Discoverable mode. Can be one of following constants: 169 * - BLE_GAP_DISC_MODE_NON (non-discoverable; 3.C.9.2.2). 170 * - BLE_GAP_DISC_MODE_LTD (limited-discoverable; 3.C.9.2.3). 171 * - BLE_GAP_DISC_MODE_GEN (general-discoverable; 3.C.9.2.4). 172 */ 173 uint8_t disc_mode; 174 175 /** Minimum advertising interval, if 0 stack use sane defaults */ 176 uint16_t itvl_min; 177 /** Maximum advertising interval, if 0 stack use sane defaults */ 178 uint16_t itvl_max; 179 /** Advertising channel map , if 0 stack use sane defaults */ 180 uint8_t channel_map; 181 182 /** Advertising Filter policy */ 183 uint8_t filter_policy; 184 185 /** If do High Duty cycle for Directed Advertising */ 186 uint8_t high_duty_cycle:1; 187 }; 188 189 /** @brief Connection descriptor */ 190 struct ble_gap_conn_desc { 191 /** Connection security state */ 192 struct ble_gap_sec_state sec_state; 193 194 /** Local identity address */ 195 ble_addr_t our_id_addr; 196 197 /** Peer identity address */ 198 ble_addr_t peer_id_addr; 199 200 /** Local over-the-air address */ 201 ble_addr_t our_ota_addr; 202 203 /** Peer over-the-air address */ 204 ble_addr_t peer_ota_addr; 205 206 /** Connection handle */ 207 uint16_t conn_handle; 208 209 /** Connection interval */ 210 uint16_t conn_itvl; 211 212 /** Connection latency */ 213 uint16_t conn_latency; 214 215 /** Connection supervision timeout */ 216 uint16_t supervision_timeout; 217 218 /** Connection Role 219 * Possible values BLE_GAP_ROLE_SLAVE or BLE_GAP_ROLE_MASTER 220 */ 221 uint8_t role; 222 223 /** Master clock accuracy */ 224 uint8_t master_clock_accuracy; 225 }; 226 227 struct ble_gap_conn_params { 228 uint16_t scan_itvl; 229 uint16_t scan_window; 230 uint16_t itvl_min; 231 uint16_t itvl_max; 232 uint16_t latency; 233 uint16_t supervision_timeout; 234 uint16_t min_ce_len; 235 uint16_t max_ce_len; 236 }; 237 238 struct ble_gap_ext_disc_params { 239 uint16_t itvl; 240 uint16_t window; 241 uint8_t passive:1; 242 }; 243 244 struct ble_gap_disc_params { 245 uint16_t itvl; 246 uint16_t window; 247 uint8_t filter_policy; 248 uint8_t limited:1; 249 uint8_t passive:1; 250 uint8_t filter_duplicates:1; 251 }; 252 253 struct ble_gap_upd_params { 254 uint16_t itvl_min; 255 uint16_t itvl_max; 256 uint16_t latency; 257 uint16_t supervision_timeout; 258 uint16_t min_ce_len; 259 uint16_t max_ce_len; 260 }; 261 262 struct ble_gap_passkey_params { 263 uint8_t action; 264 uint32_t numcmp; 265 }; 266 267 #if MYNEWT_VAL(BLE_EXT_ADV) 268 269 #define BLE_GAP_EXT_ADV_DATA_STATUS_COMPLETE 0x00 270 #define BLE_GAP_EXT_ADV_DATA_STATUS_INCOMPLETE 0x01 271 #define BLE_GAP_EXT_ADV_DATA_STATUS_TRUNCATED 0x02 272 273 struct ble_gap_ext_disc_desc { 274 /*** Common fields. */ 275 uint8_t props; 276 uint8_t data_status; 277 uint8_t legacy_event_type; 278 ble_addr_t addr; 279 int8_t rssi; 280 uint8_t tx_power; 281 uint8_t sid; 282 uint8_t prim_phy; 283 uint8_t sec_phy; 284 uint8_t length_data; 285 uint8_t *data; 286 /*** 287 * LE direct advertising report fields; direct_addr is BLE_ADDR_ANY if 288 * direct address fields are not present. 289 */ 290 ble_addr_t direct_addr; 291 }; 292 #endif 293 294 struct ble_gap_disc_desc { 295 /*** Common fields. */ 296 uint8_t event_type; 297 uint8_t length_data; 298 ble_addr_t addr; 299 int8_t rssi; 300 uint8_t *data; 301 302 /*** 303 * LE direct advertising report fields; direct_addr is BLE_ADDR_ANY if 304 * direct address fields are not present. 305 */ 306 ble_addr_t direct_addr; 307 }; 308 309 struct ble_gap_repeat_pairing { 310 /** The handle of the relevant connection. */ 311 uint16_t conn_handle; 312 313 /** Properties of the existing bond. */ 314 uint8_t cur_key_size; 315 uint8_t cur_authenticated:1; 316 uint8_t cur_sc:1; 317 318 /** 319 * Properties of the imminent secure link if the pairing procedure is 320 * allowed to continue. 321 */ 322 uint8_t new_key_size; 323 uint8_t new_authenticated:1; 324 uint8_t new_sc:1; 325 uint8_t new_bonding:1; 326 }; 327 328 /** 329 * Represents a GAP-related event. When such an event occurs, the host 330 * notifies the application by passing an instance of this structure to an 331 * application-specified callback. 332 */ 333 struct ble_gap_event { 334 /** 335 * Indicates the type of GAP event that occurred. This is one of the 336 * BLE_GAP_EVENT codes. 337 */ 338 uint8_t type; 339 340 /** 341 * A discriminated union containing additional details concerning the GAP 342 * event. The 'type' field indicates which member of the union is valid. 343 */ 344 union { 345 /** 346 * Represents a connection attempt. Valid for the following event 347 * types: 348 * o BLE_GAP_EVENT_CONNECT 349 */ 350 struct { 351 /** 352 * The status of the connection attempt; 353 * o 0: the connection was successfully established. 354 * o BLE host error code: the connection attempt failed for 355 * the specified reason. 356 */ 357 int status; 358 359 /** The handle of the relevant connection. */ 360 uint16_t conn_handle; 361 } connect; 362 363 /** 364 * Represents a terminated connection. Valid for the following event 365 * types: 366 * o BLE_GAP_EVENT_DISCONNECT 367 */ 368 struct { 369 /** 370 * A BLE host return code indicating the reason for the 371 * disconnect. 372 */ 373 int reason; 374 375 /** Information about the connection prior to termination. */ 376 struct ble_gap_conn_desc conn; 377 } disconnect; 378 379 /** 380 * Represents an advertising report received during a discovery 381 * procedure. Valid for the following event types: 382 * o BLE_GAP_EVENT_DISC 383 */ 384 struct ble_gap_disc_desc disc; 385 386 #if MYNEWT_VAL(BLE_EXT_ADV) 387 /** 388 * Represents an extended advertising report received during a discovery 389 * procedure. Valid for the following event types: 390 * o BLE_GAP_EVENT_EXT_DISC 391 */ 392 struct ble_gap_ext_disc_desc ext_disc; 393 #endif 394 395 /** 396 * Represents a completed discovery procedure. Valid for the following 397 * event types: 398 * o BLE_GAP_EVENT_DISC_COMPLETE 399 */ 400 struct { 401 /** 402 * The reason the discovery procedure stopped. Typical reason 403 * codes are: 404 * o 0: Duration expired. 405 * o BLE_HS_EPREEMPTED: Host aborted procedure to configure a 406 * peer's identity. 407 */ 408 int reason; 409 } disc_complete; 410 411 /** 412 * Represents a completed advertise procedure. Valid for the following 413 * event types: 414 * o BLE_GAP_EVENT_ADV_COMPLETE 415 */ 416 struct { 417 /** 418 * The reason the advertise procedure stopped. Typical reason 419 * codes are: 420 * o 0: Terminated due to connection. 421 * o BLE_HS_ETIMEOUT: Duration expired. 422 * o BLE_HS_EPREEMPTED: Host aborted procedure to configure a 423 * peer's identity. 424 */ 425 int reason; 426 427 #if MYNEWT_VAL(BLE_EXT_ADV) 428 /** Advertising instance */ 429 uint8_t instance; 430 /** The handle of the relevant connection - valid if reason=0 */ 431 uint16_t conn_handle; 432 /** 433 * Number of completed extended advertising events 434 * 435 * This field is only valid if non-zero max_events was passed to 436 * ble_gap_ext_adv_start() and advertising completed due to duration 437 * timeout or max events transmitted. 438 * */ 439 uint8_t num_ext_adv_events; 440 #endif 441 } adv_complete; 442 443 /** 444 * Represents an attempt to update a connection's parameters. If the 445 * attempt was successful, the connection's descriptor reflects the 446 * updated parameters. 447 * 448 * Valid for the following event types: 449 * o BLE_GAP_EVENT_CONN_UPDATE 450 */ 451 struct { 452 /** 453 * The result of the connection update attempt; 454 * o 0: the connection was successfully updated. 455 * o BLE host error code: the connection update attempt failed 456 * for the specified reason. 457 */ 458 int status; 459 460 /** The handle of the relevant connection. */ 461 uint16_t conn_handle; 462 } conn_update; 463 464 /** 465 * Represents a peer's request to update the connection parameters. 466 * This event is generated when a peer performs any of the following 467 * procedures: 468 * o L2CAP Connection Parameter Update Procedure 469 * o Link-Layer Connection Parameters Request Procedure 470 * 471 * To reject the request, return a non-zero HCI error code. The value 472 * returned is the reject reason given to the controller. 473 * 474 * Valid for the following event types: 475 * o BLE_GAP_EVENT_L2CAP_UPDATE_REQ 476 * o BLE_GAP_EVENT_CONN_UPDATE_REQ 477 */ 478 struct { 479 /** 480 * Indicates the connection parameters that the peer would like to 481 * use. 482 */ 483 const struct ble_gap_upd_params *peer_params; 484 485 /** 486 * Indicates the connection parameters that the local device would 487 * like to use. The application callback should fill this in. By 488 * default, this struct contains the requested parameters (i.e., 489 * it is a copy of 'peer_params'). 490 */ 491 struct ble_gap_upd_params *self_params; 492 493 /** The handle of the relevant connection. */ 494 uint16_t conn_handle; 495 } conn_update_req; 496 497 /** 498 * Represents a failed attempt to terminate an established connection. 499 * Valid for the following event types: 500 * o BLE_GAP_EVENT_TERM_FAILURE 501 */ 502 struct { 503 /** 504 * A BLE host return code indicating the reason for the failure. 505 */ 506 int status; 507 508 /** The handle of the relevant connection. */ 509 uint16_t conn_handle; 510 } term_failure; 511 512 /** 513 * Represents an attempt to change the encrypted state of a 514 * connection. If the attempt was successful, the connection 515 * descriptor reflects the updated encrypted state. 516 * 517 * Valid for the following event types: 518 * o BLE_GAP_EVENT_ENC_CHANGE 519 */ 520 struct { 521 /** 522 * Indicates the result of the encryption state change attempt; 523 * o 0: the encrypted state was successfully updated; 524 * o BLE host error code: the encryption state change attempt 525 * failed for the specified reason. 526 */ 527 int status; 528 529 /** The handle of the relevant connection. */ 530 uint16_t conn_handle; 531 } enc_change; 532 533 /** 534 * Represents a passkey query needed to complete a pairing procedure. 535 * 536 * Valid for the following event types: 537 * o BLE_GAP_EVENT_PASSKEY_ACTION 538 */ 539 struct { 540 /** Contains details about the passkey query. */ 541 struct ble_gap_passkey_params params; 542 543 /** The handle of the relevant connection. */ 544 uint16_t conn_handle; 545 } passkey; 546 547 /** 548 * Represents a received ATT notification or indication. 549 * 550 * Valid for the following event types: 551 * o BLE_GAP_EVENT_NOTIFY_RX 552 */ 553 struct { 554 /** 555 * The contents of the notification or indication. If the 556 * application wishes to retain this mbuf for later use, it must 557 * set this pointer to NULL to prevent the stack from freeing it. 558 */ 559 struct os_mbuf *om; 560 561 /** The handle of the relevant ATT attribute. */ 562 uint16_t attr_handle; 563 564 /** The handle of the relevant connection. */ 565 uint16_t conn_handle; 566 567 /** 568 * Whether the received command is a notification or an 569 * indication; 570 * o 0: Notification; 571 * o 1: Indication. 572 */ 573 uint8_t indication:1; 574 } notify_rx; 575 576 /** 577 * Represents a transmitted ATT notification or indication, or a 578 * completed indication transaction. 579 * 580 * Valid for the following event types: 581 * o BLE_GAP_EVENT_NOTIFY_TX 582 */ 583 struct { 584 /** 585 * The status of the notification or indication transaction; 586 * o 0: Command successfully sent; 587 * o BLE_HS_EDONE: Confirmation (indication ack) received; 588 * o BLE_HS_ETIMEOUT: Confirmation (indication ack) never 589 * received; 590 * o Other return code: Error. 591 */ 592 int status; 593 594 /** The handle of the relevant connection. */ 595 uint16_t conn_handle; 596 597 /** The handle of the relevant characterstic value. */ 598 uint16_t attr_handle; 599 600 /** 601 * Whether the transmitted command is a notification or an 602 * indication; 603 * o 0: Notification; 604 * o 1: Indication. 605 */ 606 uint8_t indication:1; 607 } notify_tx; 608 609 /** 610 * Represents a state change in a peer's subscription status. In this 611 * comment, the term "update" is used to refer to either a notification 612 * or an indication. This event is triggered by any of the following 613 * occurrences: 614 * o Peer enables or disables updates via a CCCD write. 615 * o Connection is about to be terminated and the peer is 616 * subscribed to updates. 617 * o Peer is now subscribed to updates after its state was restored 618 * from persistence. This happens when bonding is restored. 619 * 620 * Valid for the following event types: 621 * o BLE_GAP_EVENT_SUBSCRIBE 622 */ 623 struct { 624 /** The handle of the relevant connection. */ 625 uint16_t conn_handle; 626 627 /** The value handle of the relevant characteristic. */ 628 uint16_t attr_handle; 629 630 /** One of the BLE_GAP_SUBSCRIBE_REASON codes. */ 631 uint8_t reason; 632 633 /** Whether the peer was previously subscribed to notifications. */ 634 uint8_t prev_notify:1; 635 636 /** Whether the peer is currently subscribed to notifications. */ 637 uint8_t cur_notify:1; 638 639 /** Whether the peer was previously subscribed to indications. */ 640 uint8_t prev_indicate:1; 641 642 /** Whether the peer is currently subscribed to indications. */ 643 uint8_t cur_indicate:1; 644 } subscribe; 645 646 /** 647 * Represents a change in an L2CAP channel's MTU. 648 * 649 * Valid for the following event types: 650 * o BLE_GAP_EVENT_MTU 651 */ 652 struct { 653 /** The handle of the relevant connection. */ 654 uint16_t conn_handle; 655 656 /** 657 * Indicates the channel whose MTU has been updated; either 658 * BLE_L2CAP_CID_ATT or the ID of a connection-oriented channel. 659 */ 660 uint16_t channel_id; 661 662 /* The channel's new MTU. */ 663 uint16_t value; 664 } mtu; 665 666 /** 667 * Represents a change in peer's identity. This is issued after 668 * successful pairing when Identity Address Information was received. 669 * 670 * Valid for the following event types: 671 * o BLE_GAP_EVENT_IDENTITY_RESOLVED 672 */ 673 struct { 674 /** The handle of the relevant connection. */ 675 uint16_t conn_handle; 676 } identity_resolved; 677 678 /** 679 * Represents a peer's attempt to pair despite a bond already existing. 680 * The application has two options for handling this event type: 681 * o Retry: Return BLE_GAP_REPEAT_PAIRING_RETRY after deleting the 682 * conflicting bond. The stack will verify the bond has 683 * been deleted and continue the pairing procedure. If 684 * the bond is still present, this event will be reported 685 * again. 686 * o Ignore: Return BLE_GAP_REPEAT_PAIRING_IGNORE. The stack will 687 * silently ignore the pairing request. 688 * 689 * Valid for the following event types: 690 * o BLE_GAP_EVENT_REPEAT_PAIRING 691 */ 692 struct ble_gap_repeat_pairing repeat_pairing; 693 694 /** 695 * Represents a change of PHY. This is issue after successful 696 * change on PHY. 697 */ 698 struct { 699 int status; 700 uint16_t conn_handle; 701 702 /** 703 * Indicates enabled TX/RX PHY. Possible values: 704 * o BLE_GAP_LE_PHY_1M 705 * o BLE_GAP_LE_PHY_2M 706 * o BLE_GAP_LE_PHY_CODED 707 */ 708 uint8_t tx_phy; 709 uint8_t rx_phy; 710 } phy_updated; 711 }; 712 }; 713 714 typedef int ble_gap_event_fn(struct ble_gap_event *event, void *arg); 715 716 #define BLE_GAP_CONN_MODE_NON 0 717 #define BLE_GAP_CONN_MODE_DIR 1 718 #define BLE_GAP_CONN_MODE_UND 2 719 720 #define BLE_GAP_DISC_MODE_NON 0 721 #define BLE_GAP_DISC_MODE_LTD 1 722 #define BLE_GAP_DISC_MODE_GEN 2 723 724 /** 725 * Searches for a connection with the specified handle. If a matching 726 * connection is found, the supplied connection descriptor is filled 727 * correspondingly. 728 * 729 * @param handle The connection handle to search for. 730 * @param out_desc On success, this is populated with information relating to 731 * the matching connection. Pass NULL if you don't need this 732 * information. 733 * 734 * @return 0 on success, BLE_HS_ENOTCONN if no matching connection was 735 * found. 736 */ 737 int ble_gap_conn_find(uint16_t handle, struct ble_gap_conn_desc *out_desc); 738 739 /** 740 * Searches for a connection with a peer with the specified address. 741 * If a matching connection is found, the supplied connection descriptor 742 * is filled correspondingly. 743 * 744 * @param addr The ble address of a connected peer device to search for. 745 * @param out_desc On success, this is populated with information relating to 746 * the matching connection. Pass NULL if you don't need this 747 * information. 748 * 749 * @return 0 on success, BLE_HS_ENOTCONN if no matching connection was 750 * found. 751 */ 752 int ble_gap_conn_find_by_addr(const ble_addr_t *addr, 753 struct ble_gap_conn_desc *out_desc); 754 755 /** 756 * Configures a connection to use the specified GAP event callback. A 757 * connection's GAP event callback is first specified when the connection is 758 * created, either via advertising or initiation. This function replaces the 759 * callback that was last configured. 760 * 761 * @param conn_handle The handle of the connection to configure. 762 * @param cb The callback to associate with the connection. 763 * @param cb_arg An optional argument that the callback receives. 764 * 765 * @return 0 on success, BLE_HS_ENOTCONN if there is no connection 766 * with the specified handle. 767 */ 768 int ble_gap_set_event_cb(uint16_t conn_handle, 769 ble_gap_event_fn *cb, void *cb_arg); 770 771 /** @brief Start advertising 772 * 773 * This function configures and start advertising procedure. 774 * 775 * @param own_addr_type The type of address the stack should use for itself. 776 * Valid values are: 777 * - BLE_OWN_ADDR_PUBLIC 778 * - BLE_OWN_ADDR_RANDOM 779 * - BLE_OWN_ADDR_RPA_PUBLIC_DEFAULT 780 * - BLE_OWN_ADDR_RPA_RANDOM_DEFAULT 781 * @param direct_addr The peer's address for directed advertising. his 782 * parameter shall be non-NULL if directed advertising is 783 * being used. 784 * @param duration_ms The duration of the advertisement procedure. On 785 * expiration, the procedure ends and a 786 * BLE_GAP_EVENT_ADV_COMPLETE event is reported. Units are 787 * milliseconds. Specify BLE_HS_FOREVER for no expiration. 788 * @param adv_params Additional arguments specifying the particulars of the 789 * advertising procedure. 790 * @param cb The callback to associate with this advertising 791 * procedure. If advertising ends, the event is reported 792 * through this callback. If advertising results in a 793 * connection, the connection inherits this callback as its 794 * event-reporting mechanism. 795 * @param cb_arg The optional argument to pass to the callback function. 796 * 797 * @return 0 on success, error code on failure. 798 */ 799 int ble_gap_adv_start(uint8_t own_addr_type, const ble_addr_t *direct_addr, 800 int32_t duration_ms, 801 const struct ble_gap_adv_params *adv_params, 802 ble_gap_event_fn *cb, void *cb_arg); 803 804 /** 805 * Stops the currently-active advertising procedure. A success return 806 * code indicates that advertising has been fully aborted and a new advertising 807 * procedure can be initiated immediately. 808 * 809 * NOTE: If the caller is running in the same task as the NimBLE host, or if it 810 * is running in a higher priority task than that of the host, care must be 811 * taken when restarting advertising. Under these conditions, the following is 812 * *not* a reliable method to restart advertising: 813 * ble_gap_adv_stop() 814 * ble_gap_adv_start() 815 * 816 * Instead, the call to `ble_gap_adv_start()` must be made in a separate event 817 * context. That is, `ble_gap_adv_start()` must be called asynchronously by 818 * enqueueing an event on the current task's event queue. See 819 * https://github.com/apache/mynewt-nimble/pull/211 for more information. 820 * 821 * @return 0 on success, BLE_HS_EALREADY if there is no active advertising 822 * procedure, other error code on failure. 823 */ 824 int ble_gap_adv_stop(void); 825 826 /** 827 * Indicates whether an advertisement procedure is currently in progress. 828 * 829 * @return 0 if no advertisement procedure in progress, 1 otherwise. 830 */ 831 int ble_gap_adv_active(void); 832 833 /** 834 * Configures the data to include in subsequent advertisements. 835 * 836 * @param data Buffer containing the advertising data. 837 * @param data_len The size of the advertising data, in bytes. 838 * 839 * @return 0 on succes, BLE_HS_EBUSY if advertising is in progress, 840 * other error code on failure. 841 */ 842 int ble_gap_adv_set_data(const uint8_t *data, int data_len); 843 844 /** 845 * Configures the data to include in subsequent scan responses. 846 * 847 * @param data Buffer containing the scan response data. 848 * @param data_len The size of the response data, in bytes. 849 * 850 * @return 0 on succes, BLE_HS_EBUSY if advertising is in progress, 851 * other error code on failure. 852 */ 853 int ble_gap_adv_rsp_set_data(const uint8_t *data, int data_len); 854 855 /** 856 * Configures the fields to include in subsequent advertisements. This is a 857 * convenience wrapper for ble_gap_adv_set_data(). 858 * 859 * @param adv_fields Specifies the advertisement data. 860 * 861 * @return 0 on success, 862 * BLE_HS_EBUSY if advertising is in progress, 863 * BLE_HS_EMSGSIZE if the specified data is too large to 864 * fit in an advertisement, 865 * other error code on failure. 866 */ 867 int ble_gap_adv_set_fields(const struct ble_hs_adv_fields *rsp_fields); 868 869 /** 870 * Configures the fields to include in subsequent scan responses. This is a 871 * convenience wrapper for ble_gap_adv_rsp_set_data(). 872 * 873 * @param adv_fields Specifies the scan response data. 874 * 875 * @return 0 on success, 876 * BLE_HS_EBUSY if advertising is in progress, 877 * BLE_HS_EMSGSIZE if the specified data is too large to 878 * fit in a scan response, 879 * other error code on failure. 880 */ 881 int ble_gap_adv_rsp_set_fields(const struct ble_hs_adv_fields *rsp_fields); 882 883 #if MYNEWT_VAL(BLE_EXT_ADV) 884 struct ble_gap_ext_adv_params { 885 unsigned int connectable:1; 886 unsigned int scannable:1; 887 unsigned int directed:1; 888 unsigned int high_duty_directed:1; 889 unsigned int legacy_pdu:1; 890 unsigned int anonymous:1; 891 unsigned int include_tx_power:1; 892 unsigned int scan_req_notif:1; 893 894 uint32_t itvl_min; 895 uint32_t itvl_max; 896 uint8_t channel_map; 897 uint8_t own_addr_type; 898 ble_addr_t peer; 899 uint8_t filter_policy; 900 uint8_t primary_phy; 901 uint8_t secondary_phy; 902 int8_t tx_power; 903 uint8_t sid; 904 }; 905 906 int ble_gap_ext_adv_configure(uint8_t instance, 907 const struct ble_gap_ext_adv_params *params, 908 int8_t *selected_tx_power, 909 ble_gap_event_fn *cb, void *cb_arg); 910 int ble_gap_ext_adv_set_addr(uint8_t instance, const ble_addr_t *addr); 911 int ble_gap_ext_adv_start(uint8_t instance, int duration, int max_events); 912 int ble_gap_ext_adv_stop(uint8_t instance); 913 int ble_gap_ext_adv_set_data(uint8_t instance, struct os_mbuf *data); 914 int ble_gap_ext_adv_rsp_set_data(uint8_t instance, struct os_mbuf *data); 915 int ble_gap_ext_adv_remove(uint8_t instance); 916 #endif 917 918 /** 919 * Performs the Limited or General Discovery Procedures. 920 * 921 * @param own_addr_type The type of address the stack should use for 922 * itself when sending scan requests. Valid 923 * values are: 924 * - BLE_ADDR_TYPE_PUBLIC 925 * - BLE_ADDR_TYPE_RANDOM 926 * - BLE_ADDR_TYPE_RPA_PUB_DEFAULT 927 * - BLE_ADDR_TYPE_RPA_RND_DEFAULT 928 * This parameter is ignored unless active 929 * scanning is being used. 930 * @param duration_ms The duration of the discovery procedure. 931 * On expiration, the procedure ends and a 932 * BLE_GAP_EVENT_DISC_COMPLETE event is 933 * reported. Units are milliseconds. Specify 934 * BLE_HS_FOREVER for no expiration. 935 * @param disc_params Additional arguments specifying the particulars 936 * of the discovery procedure. 937 * @param cb The callback to associate with this discovery 938 * procedure. Advertising reports and 939 * discovery termination events are reported 940 * through this callback. 941 * @param cb_arg The optional argument to pass to the callback 942 * function. 943 * 944 * @return 0 on success; nonzero on failure. 945 */ 946 int ble_gap_disc(uint8_t own_addr_type, int32_t duration_ms, 947 const struct ble_gap_disc_params *disc_params, 948 ble_gap_event_fn *cb, void *cb_arg); 949 950 int ble_gap_ext_disc(uint8_t own_addr_type, uint16_t duration, uint16_t period, 951 uint8_t filter_duplicates, uint8_t filter_policy, 952 uint8_t limited, 953 const struct ble_gap_ext_disc_params *uncoded_params, 954 const struct ble_gap_ext_disc_params *coded_params, 955 ble_gap_event_fn *cb, void *cb_arg); 956 957 /** 958 * Cancels the discovery procedure currently in progress. A success return 959 * code indicates that scanning has been fully aborted; a new discovery or 960 * connect procedure can be initiated immediately. 961 * 962 * @return 0 on success; 963 * BLE_HS_EALREADY if there is no discovery 964 * procedure to cancel; 965 * Other nonzero on unexpected error. 966 */ 967 int ble_gap_disc_cancel(void); 968 969 /** 970 * Indicates whether a discovery procedure is currently in progress. 971 * 972 * @return 0: No discovery procedure in progress; 973 * 1: Discovery procedure in progress. 974 */ 975 int ble_gap_disc_active(void); 976 977 /** 978 * Initiates a connect procedure. 979 * 980 * @param own_addr_type The type of address the stack should use for 981 * itself during connection establishment. 982 * - BLE_OWN_ADDR_PUBLIC 983 * - BLE_OWN_ADDR_RANDOM 984 * - BLE_OWN_ADDR_RPA_PUBLIC_DEFAULT 985 * - BLE_OWN_ADDR_RPA_RANDOM_DEFAULT 986 * @param peer_addr The address of the peer to connect to. 987 * If this parameter is NULL, the white list 988 * is used. 989 * @param duration_ms The duration of the discovery procedure. 990 * On expiration, the procedure ends and a 991 * BLE_GAP_EVENT_DISC_COMPLETE event is 992 * reported. Units are milliseconds. 993 * @param conn_params Additional arguments specifying the particulars 994 * of the connect procedure. Specify null for 995 * default values. 996 * @param cb The callback to associate with this connect 997 * procedure. When the connect procedure 998 * completes, the result is reported through 999 * this callback. If the connect procedure 1000 * succeeds, the connection inherits this 1001 * callback as its event-reporting mechanism. 1002 * @param cb_arg The optional argument to pass to the callback 1003 * function. 1004 * 1005 * @return 0 on success; 1006 * BLE_HS_EALREADY if a connection attempt is 1007 * already in progress; 1008 * BLE_HS_EBUSY if initiating a connection is not 1009 * possible because scanning is in progress; 1010 * BLE_HS_EDONE if the specified peer is already 1011 * connected; 1012 * Other nonzero on error. 1013 */ 1014 int ble_gap_connect(uint8_t own_addr_type, const ble_addr_t *peer_addr, 1015 int32_t duration_ms, 1016 const struct ble_gap_conn_params *params, 1017 ble_gap_event_fn *cb, void *cb_arg); 1018 1019 /** 1020 * Initiates an extended connect procedure. 1021 * 1022 * @param own_addr_type The type of address the stack should use for 1023 * itself during connection establishment. 1024 * - BLE_OWN_ADDR_PUBLIC 1025 * - BLE_OWN_ADDR_RANDOM 1026 * - BLE_OWN_ADDR_RPA_PUBLIC_DEFAULT 1027 * - BLE_OWN_ADDR_RPA_RANDOM_DEFAULT 1028 * @param peer_addr The address of the peer to connect to. 1029 * If this parameter is NULL, the white list 1030 * is used. 1031 * @param duration_ms The duration of the discovery procedure. 1032 * On expiration, the procedure ends and a 1033 * BLE_GAP_EVENT_DISC_COMPLETE event is 1034 * reported. Units are milliseconds. 1035 * @param phy_mask Define on which PHYs connection attempt should 1036 * be done 1037 * @param phy_1m_conn_params Additional arguments specifying the 1038 * particulars of the connect procedure. When 1039 * BLE_GAP_LE_PHY_1M_MASK is set in phy_mask 1040 * this parameter can be specify to null for 1041 * default values. 1042 * @param phy_2m_conn_params Additional arguments specifying the 1043 * particulars of the connect procedure. When 1044 * BLE_GAP_LE_PHY_2M_MASK is set in phy_mask 1045 * this parameter can be specify to null for 1046 * default values. 1047 * @param phy_coded_conn_params Additional arguments specifying the 1048 * particulars of the connect procedure. When 1049 * BLE_GAP_LE_PHY_CODED_MASK is set in 1050 * phy_mask this parameter can be specify to 1051 * null for default values. 1052 * @param cb The callback to associate with this connect 1053 * procedure. When the connect procedure 1054 * completes, the result is reported through 1055 * this callback. If the connect procedure 1056 * succeeds, the connection inherits this 1057 * callback as its event-reporting mechanism. 1058 * @param cb_arg The optional argument to pass to the callback 1059 * function. 1060 * 1061 * @return 0 on success; 1062 * BLE_HS_EALREADY if a connection attempt is 1063 * already in progress; 1064 * BLE_HS_EBUSY if initiating a connection is not 1065 * possible because scanning is in progress; 1066 * BLE_HS_EDONE if the specified peer is already 1067 * connected; 1068 * Other nonzero on error. 1069 */ 1070 int ble_gap_ext_connect(uint8_t own_addr_type, const ble_addr_t *peer_addr, 1071 int32_t duration_ms, uint8_t phy_mask, 1072 const struct ble_gap_conn_params *phy_1m_conn_params, 1073 const struct ble_gap_conn_params *phy_2m_conn_params, 1074 const struct ble_gap_conn_params *phy_coded_conn_params, 1075 ble_gap_event_fn *cb, void *cb_arg); 1076 1077 /** 1078 * Aborts a connect procedure in progress. 1079 * 1080 * @return 0 on success; 1081 * BLE_HS_EALREADY if there is no active connect 1082 * procedure. 1083 * Other nonzero on error. 1084 */ 1085 int ble_gap_conn_cancel(void); 1086 1087 /** 1088 * Indicates whether a connect procedure is currently in progress. 1089 * 1090 * @return 0: No connect procedure in progress; 1091 * 1: Connect procedure in progress. 1092 */ 1093 int ble_gap_conn_active(void); 1094 1095 /** 1096 * Terminates an established connection. 1097 * 1098 * @param conn_handle The handle corresponding to the connection to 1099 * terminate. 1100 * @param hci_reason The HCI error code to indicate as the reason 1101 * for termination. 1102 * 1103 * @return 0 on success; 1104 * BLE_HS_ENOTCONN if there is no connection with 1105 * the specified handle; 1106 * Other nonzero on failure. 1107 */ 1108 int ble_gap_terminate(uint16_t conn_handle, uint8_t hci_reason); 1109 1110 /** 1111 * Overwrites the controller's white list with the specified contents. 1112 * 1113 * @param addrs The entries to write to the white list. 1114 * @param white_list_count The number of entries in the white list. 1115 * 1116 * @return 0 on success; nonzero on failure. 1117 */ 1118 int ble_gap_wl_set(const ble_addr_t *addrs, uint8_t white_list_count); 1119 1120 /** 1121 * Initiates a connection parameter update procedure. 1122 * 1123 * @param conn_handle The handle corresponding to the connection to 1124 * update. 1125 * @param params The connection parameters to attempt to update 1126 * to. 1127 * 1128 * @return 0 on success; 1129 * BLE_HS_ENOTCONN if the there is no connection 1130 * with the specified handle; 1131 * BLE_HS_EALREADY if a connection update 1132 * procedure for this connection is already in 1133 * progress; 1134 * BLE_HS_EINVAL if requested parameters are 1135 * invalid; 1136 * Other nonzero on error. 1137 */ 1138 int ble_gap_update_params(uint16_t conn_handle, 1139 const struct ble_gap_upd_params *params); 1140 1141 /** 1142 * Initiates the GAP security procedure. 1143 * 1144 * Depending on connection role and stored security information this function 1145 * will start appropriate security procedure (pairing or encryption). 1146 * 1147 * @param conn_handle The handle corresponding to the connection to 1148 * secure. 1149 * 1150 * @return 0 on success; 1151 * BLE_HS_ENOTCONN if the there is no connection 1152 * with the specified handle; 1153 * BLE_HS_EALREADY if an security procedure for 1154 * this connection is already in progress; 1155 * Other nonzero on error. 1156 */ 1157 int ble_gap_security_initiate(uint16_t conn_handle); 1158 1159 /** 1160 * Initiates the GAP pairing procedure as a master. This is for testing only and 1161 * should not be used by application. Use ble_gap_security_initiate() instead. 1162 * 1163 * @param conn_handle The handle corresponding to the connection to 1164 * start pairing on. 1165 * 1166 * @return 0 on success; 1167 * BLE_HS_ENOTCONN if the there is no connection 1168 * with the specified handle; 1169 * BLE_HS_EALREADY if an pairing procedure for 1170 * this connection is already in progress; 1171 * Other nonzero on error. 1172 */ 1173 int ble_gap_pair_initiate(uint16_t conn_handle); 1174 1175 /** 1176 * Initiates the GAP encryption procedure as a master. This is for testing only 1177 * and should not be used by application. Use ble_gap_security_initiate() 1178 * instead. 1179 * 1180 * @param conn_handle The handle corresponding to the connection to 1181 * start encryption. 1182 * @param ltk Long Term Key to be used for encryption. 1183 * @param udiv Encryption Diversifier for LTK 1184 * @param rand_val Random Value for EDIV and LTK 1185 * @param auth If LTK provided is authenticated. 1186 * 1187 * @return 0 on success; 1188 * BLE_HS_ENOTCONN if the there is no connection 1189 * with the specified handle; 1190 * BLE_HS_EALREADY if an encryption procedure for 1191 * this connection is already in progress; 1192 * Other nonzero on error. 1193 */ 1194 int ble_gap_encryption_initiate(uint16_t conn_handle, const uint8_t *ltk, 1195 uint16_t ediv, uint64_t rand_val, int auth); 1196 1197 /** 1198 * Retrieves the most-recently measured RSSI for the specified connection. A 1199 * connection's RSSI is updated whenever a data channel PDU is received. 1200 * 1201 * @param conn_handle Specifies the connection to query. 1202 * @param out_rssi On success, the retrieved RSSI is written here. 1203 * 1204 * @return 0 on success; 1205 * A BLE host HCI return code if the controller 1206 * rejected the request; 1207 * A BLE host core return code on unexpected 1208 * error. 1209 */ 1210 int ble_gap_conn_rssi(uint16_t conn_handle, int8_t *out_rssi); 1211 1212 /** 1213 * Unpairs a device with the specified address. The keys related to that peer 1214 * device are removed from storage and peer address is removed from the resolve 1215 * list from the controller. If a peer is connected, the connection is terminated. 1216 * 1217 * @param peer_addr Address of the device to be unpaired 1218 * 1219 * @return 0 on success; 1220 * A BLE host HCI return code if the controller 1221 * rejected the request; 1222 * A BLE host core return code on unexpected 1223 * error. 1224 */ 1225 int ble_gap_unpair(const ble_addr_t *peer_addr); 1226 1227 /** 1228 * Unpairs the oldest bonded peer device. The keys related to that peer 1229 * device are removed from storage and peer address is removed from the resolve 1230 * list from the controller. If a peer is connected, the connection is terminated. 1231 * 1232 * @return 0 on success; 1233 * A BLE host HCI return code if the controller 1234 * rejected the request; 1235 * A BLE host core return code on unexpected 1236 * error. 1237 */ 1238 int ble_gap_unpair_oldest_peer(void); 1239 1240 #define BLE_GAP_PRIVATE_MODE_NETWORK 0 1241 #define BLE_GAP_PRIVATE_MODE_DEVICE 1 1242 int ble_gap_set_priv_mode(const ble_addr_t *peer_addr, uint8_t priv_mode); 1243 1244 #define BLE_GAP_LE_PHY_1M 1 1245 #define BLE_GAP_LE_PHY_2M 2 1246 #define BLE_GAP_LE_PHY_CODED 3 1247 int ble_gap_read_le_phy(uint16_t conn_handle, uint8_t *tx_phy, uint8_t *rx_phy); 1248 1249 #define BLE_GAP_LE_PHY_1M_MASK 0x01 1250 #define BLE_GAP_LE_PHY_2M_MASK 0x02 1251 #define BLE_GAP_LE_PHY_CODED_MASK 0x04 1252 #define BLE_GAP_LE_PHY_ANY_MASK 0x0F 1253 int ble_gap_set_prefered_default_le_phy(uint8_t tx_phys_mask, 1254 uint8_t rx_phys_mask); 1255 1256 #define BLE_GAP_LE_PHY_CODED_ANY 0 1257 #define BLE_GAP_LE_PHY_CODED_S2 1 1258 #define BLE_GAP_LE_PHY_CODED_S8 2 1259 int ble_gap_set_prefered_le_phy(uint16_t conn_handle, uint8_t tx_phys_mask, 1260 uint8_t rx_phys_mask, uint16_t phy_opts); 1261 1262 /** 1263 * Event listener structure 1264 * 1265 * This should be used as an opaque structure and not modified manually. 1266 */ 1267 struct ble_gap_event_listener { 1268 ble_gap_event_fn *fn; 1269 void *arg; 1270 SLIST_ENTRY(ble_gap_event_listener) link; 1271 }; 1272 1273 /** 1274 * Registers listener for GAP events 1275 * 1276 * On success listener structure will be initialized automatically and does not 1277 * need to be initialized prior to calling this function. To change callback 1278 * and/or argument unregister listener first and register it again. 1279 * 1280 * @param listener Listener structure 1281 * @param fn Callback function 1282 * @param arg Callback argument 1283 * 1284 * @return 0 on success 1285 * BLE_HS_EINVAL if no callback is specified 1286 * BLE_HS_EALREADY if listener is already registered 1287 */ 1288 int ble_gap_event_listener_register(struct ble_gap_event_listener *listener, 1289 ble_gap_event_fn *fn, void *arg); 1290 1291 /** 1292 * Unregisters listener for GAP events 1293 * 1294 * @param listener Listener structure 1295 * 1296 * @return 0 on success 1297 * BLE_HS_ENOENT if listener was not registered 1298 */ 1299 int ble_gap_event_listener_unregister(struct ble_gap_event_listener *listener); 1300 1301 #if MYNEWT_VAL(BLE_MESH) 1302 int ble_gap_mesh_cb_register(ble_gap_event_fn *cb, void *cb_arg); 1303 #endif 1304 1305 #ifdef __cplusplus 1306 } 1307 #endif 1308 1309 /** 1310 * @} 1311 */ 1312 1313 #endif 1314