1 /** 2 **************************************************************************************** 3 * 4 * @file gap.h 5 * 6 * @brief Header file - GAP. 7 * 8 * Copyright (C) RivieraWaves 2009-2016 9 * 10 * 11 **************************************************************************************** 12 */ 13 #ifndef GAP_H_ 14 #define GAP_H_ 15 /** 16 **************************************************************************************** 17 * @addtogroup HOST 18 * @ingroup ROOT 19 * @brief Bluetooth Low Energy Host 20 * 21 * The HOST layer of the stack contains the higher layer protocols (@ref ATT "ATT", 22 * @ref SMP "SMP") and transport module (@ref L2C "L2C"). It also includes the Generic 23 * Access Profile (@ref GAP "GAP"), used for scanning/connection operations. 24 **************************************************************************************** 25 */ 26 /** 27 **************************************************************************************** 28 * @addtogroup GAP Generic Access Profile 29 * @ingroup HOST 30 * @brief Generic Access Profile. 31 * 32 * The GAP module is responsible for providing an API to the application in order to 33 * configure the device in the desired mode (discoverable, connectable, etc.) and perform 34 * required actions (scanning, connection, pairing, etc.). To achieve this, the GAP 35 * interfaces with both the @ref SMP "SMP", @ref L2C "L2C" and the @ref CONTROLLER "CONTROLLER" 36 * 37 * @{ 38 **************************************************************************************** 39 */ 40 41 #include <stdint.h> 42 #include "ble_arch.h" 43 //#include "compiler.h" 44 #include "att.h" 45 46 /* 47 * DEFINES 48 **************************************************************************************** 49 */ 50 51 /// BD address length 52 #define GAP_BD_ADDR_LEN (6) 53 /// LE Channel map length 54 #define GAP_LE_CHNL_MAP_LEN (0x05) 55 /// LE Feature Flags Length 56 #define GAP_LE_FEATS_LEN (0x08) 57 /// ADV Data and Scan Response length 58 #define GAP_ADV_DATA_LEN (0x1F) 59 #define GAP_SCAN_RSP_DATA_LEN (0x1F) 60 /// Random number length 61 #define GAP_RAND_NB_LEN (0x08) 62 /// Key length 63 #define GAP_KEY_LEN (16) 64 /// P256 Key Len 65 #define GAP_P256_KEY_LEN (0x20) 66 67 68 ///***** AD Type Flag - Bit set *******/ 69 /// Limited discovery flag - AD Flag 70 #define GAP_LE_LIM_DISCOVERABLE_FLG 0x01 71 /// General discovery flag - AD Flag 72 #define GAP_LE_GEN_DISCOVERABLE_FLG 0x02 73 /// Legacy BT not supported - AD Flag 74 #define GAP_BR_EDR_NOT_SUPPORTED 0x04 75 /// Dual mode for controller supported (BR/EDR/LE) - AD Flag 76 #define GAP_SIMUL_BR_EDR_LE_CONTROLLER 0x08 77 /// Dual mode for host supported (BR/EDR/LE) - AD Flag 78 #define GAP_SIMUL_BR_EDR_LE_HOST 0x10 79 80 /*********** GAP Miscellaneous Defines *************/ 81 /// Invalid connection index 82 #define GAP_INVALID_CONIDX 0xFF 83 84 /// Invalid connection handle 85 #define GAP_INVALID_CONHDL 0xFFFF 86 87 /// Connection interval min (N*1.250ms) 88 #define GAP_CNX_INTERVAL_MIN 6 //(0x06) 89 /// Connection interval Max (N*1.250ms) 90 #define GAP_CNX_INTERVAL_MAX 3200 //(0xC80) 91 /// Connection latency min (N*cnx evt) 92 #define GAP_CNX_LATENCY_MIN 0 //(0x00) 93 /// Connection latency Max (N*cnx evt 94 #define GAP_CNX_LATENCY_MAX 499 //(0x1F3) 95 /// Supervision TO min (N*10ms) 96 #define GAP_CNX_SUP_TO_MIN 10 //(0x0A) 97 /// Supervision TO Max (N*10ms) 98 #define GAP_CNX_SUP_TO_MAX 3200 //(0xC80) 99 100 101 102 /// Length of resolvable random address prand part 103 #define GAP_ADDR_PRAND_LEN (3) 104 /// Length of resolvable random address hash part 105 #define GAP_ADDR_HASH_LEN (3) 106 107 108 /* 109 * DEFINES - Optional for BLE application usage 110 **************************************************************************************** 111 */ 112 113 /// Central idle timer 114 /// TGAP(conn_pause_central) 115 /// recommended value: 1 s: (100 for ke timer) 116 #define GAP_TMR_CONN_PAUSE_CT 0x0064 117 118 /// Minimum time upon connection establishment before the peripheral 119 /// starts a connection update procedure: TGAP(conn_pause_peripheral) 120 /// recommended value: 5 s: (500 for ke timer) 121 #define GAP_TMR_CONN_PAUSE_PH 0x01F4 122 123 /// Minimum time to perform scanning when user initiated 124 /// TGAP(scan_fast_period) 125 /// recommended value: 30.72 s: (3072 for ke timer) 126 #define GAP_TMR_SCAN_FAST_PERIOD 0x0C00 127 128 /// Minimum time to perform advertising when user initiated 129 /// TGAP(adv_fast_period) 130 /// recommended value: 30 s: (3000 for ke timer) 131 #define GAP_TMR_ADV_FAST_PERIOD 0x0BB8 132 133 /// Scan interval used during Link Layer Scanning State when 134 /// performing the Limited Discovery procedure 135 /// TGAP(lim_disc_scan_int) 136 /// recommended value: 11.25ms; (18 decimal) 137 #define GAP_LIM_DISC_SCAN_INT 0x0012 138 139 /// Scan interval in any discovery or connection establishment 140 /// procedure when user initiated: TGAP(scan_fast_interval) 141 /// recommended value: 30 to 60 ms; N * 0.625 142 #define GAP_SCAN_FAST_INTV 0x0030 143 144 /// Scan window in any discovery or connection establishment 145 /// procedure when user initiated: TGAP(scan_fast_window) 146 /// recommended value: 30 ms; N * 0.625 147 #define GAP_SCAN_FAST_WIND 0x0030 148 149 /// Scan interval in any discovery or connection establishment 150 /// procedure when background scanning: TGAP(scan_slow_interval1) 151 /// recommended value: 1.28 s : 0x00CD (205); N * 0.625 152 #define GAP_SCAN_SLOW_INTV1 0x00CD 153 154 /// Scan interval in any discovery or connection establishment 155 /// procedure when background scanning: TGAP(scan_slow_interval2) 156 /// recommended value: 2.56 s : 0x019A (410); N * 0.625 157 #define GAP_SCAN_SLOW_INTV2 0x019A 158 159 /// Scan window in any discovery or connection establishment 160 /// procedure when background scanning: TGAP(scan_slow_window1) 161 /// recommended value: 11.25 ms : 0x0012 (18); N * 0.625 162 #define GAP_SCAN_SLOW_WIND1 0x0012 163 164 /// Scan window in any discovery or connection establishment 165 /// procedure when background scanning: TGAP(scan_slow_window2) 166 /// recommended value: 22.5 ms : 0x0024 (36); N * 0.625 167 #define GAP_SCAN_SLOW_WIND2 0x0024 168 169 /// Minimum to maximum advertisement interval in any discoverable 170 /// or connectable mode when user initiated: TGAP(adv_fast_interval1) 171 /// recommended value: 30 to 60 ms; N * 0.625 172 #define GAP_ADV_FAST_INTV1 0x0030 173 174 /// Minimum to maximum advertisement interval in any discoverable 175 /// or connectable mode when user initiated: TGAP(adv_fast_interval2) 176 /// recommended value: 100 to 150 ms; N * 0.625 177 #define GAP_ADV_FAST_INTV2 0x0064 178 179 /// Minimum to maximum advertisement interval in any discoverable or 180 /// connectable mode when background advertising: TGAP(adv_slow_interval) 181 /// recommended value: 1 to 1.2 s : 0x00B0 (176); N * 0.625 182 #define GAP_ADV_SLOW_INTV 0x00B0 183 184 /// Minimum to maximum connection interval upon any connection 185 /// establishment: TGAP(initial_conn_interval) 186 /// recommended value: 30 to 50 ms ; N * 1.25 ms 187 #define GAP_INIT_CONN_MIN_INTV 0x0018 188 #define GAP_INIT_CONN_MAX_INTV 0x0028 189 190 /// RW Defines 191 #define GAP_INQ_SCAN_INTV 0x0012 192 #define GAP_INQ_SCAN_WIND 0x0012 193 194 /// Connection supervision timeout 195 /// recommended value: 20s 196 #define GAP_CONN_SUPERV_TIMEOUT 0x07D0 197 198 /// Minimum connection event 199 /// default value: 0x0000 200 #define GAP_CONN_MIN_CE 0x0000 201 202 /// Maximum connection event 203 /// default value: 0xFFFF 204 #define GAP_CONN_MAX_CE 0xFFFF 205 206 /// Connection latency 207 /// default value: 0x0000 208 #define GAP_CONN_LATENCY 0x0000 209 210 /// GAP Device name Characteristic 211 /// Default device name 212 #define GAP_DEV_NAME "RIVIERAWAVES-BLE" 213 214 /// GAP Appearance or Icon Characteristic - 2 octets 215 /// Current appearance value is 0x0000 (unknown appearance) 216 /// Description: 217 /// http://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.gap.appearance.xml 218 #define GAP_APPEARANCE 0x0000 219 220 ///GAP Peripheral Preferred Connection Parameter - 8 octets 221 #define GAP_PPCP_CONN_INTV_MAX 0x0064 222 #define GAP_PPCP_CONN_INTV_MIN 0x00C8 223 #define GAP_PPCP_SLAVE_LATENCY 0x0000 224 #define GAP_PPCP_STO_MULT 0x07D0 225 226 227 /* 228 * Enumerations 229 **************************************************************************************** 230 */ 231 /// GAP Advertising Flags 232 enum gap_ad_type 233 { 234 /// Flag 235 GAP_AD_TYPE_FLAGS = 0x01, 236 /// Use of more than 16 bits UUID 237 GAP_AD_TYPE_MORE_16_BIT_UUID = 0x02, 238 /// Complete list of 16 bit UUID 239 GAP_AD_TYPE_COMPLETE_LIST_16_BIT_UUID = 0x03, 240 /// Use of more than 32 bit UUD 241 GAP_AD_TYPE_MORE_32_BIT_UUID = 0x04, 242 /// Complete list of 32 bit UUID 243 GAP_AD_TYPE_COMPLETE_LIST_32_BIT_UUID = 0x05, 244 /// Use of more than 128 bit UUID 245 GAP_AD_TYPE_MORE_128_BIT_UUID = 0x06, 246 /// Complete list of 128 bit UUID 247 GAP_AD_TYPE_COMPLETE_LIST_128_BIT_UUID = 0x07, 248 /// Shortened device name 249 GAP_AD_TYPE_SHORTENED_NAME = 0x08, 250 /// Complete device name 251 GAP_AD_TYPE_COMPLETE_NAME = 0x09, 252 /// Transmit power 253 GAP_AD_TYPE_TRANSMIT_POWER = 0x0A, 254 /// Class of device 255 GAP_AD_TYPE_CLASS_OF_DEVICE = 0x0D, 256 /// Simple Pairing Hash C 257 GAP_AD_TYPE_SP_HASH_C = 0x0E, 258 /// Simple Pairing Randomizer 259 GAP_AD_TYPE_SP_RANDOMIZER_R = 0x0F, 260 /// Temporary key value 261 GAP_AD_TYPE_TK_VALUE = 0x10, 262 /// Out of Band Flag 263 GAP_AD_TYPE_OOB_FLAGS = 0x11, 264 /// Slave connection interval range 265 GAP_AD_TYPE_SLAVE_CONN_INT_RANGE = 0x12, 266 /// Require 16 bit service UUID 267 GAP_AD_TYPE_RQRD_16_BIT_SVC_UUID = 0x14, 268 /// Require 32 bit service UUID 269 GAP_AD_TYPE_RQRD_32_BIT_SVC_UUID = 0x1F, 270 /// Require 128 bit service UUID 271 GAP_AD_TYPE_RQRD_128_BIT_SVC_UUID = 0x15, 272 /// Service data 16-bit UUID 273 GAP_AD_TYPE_SERVICE_16_BIT_DATA = 0x16, 274 /// Service data 32-bit UUID 275 GAP_AD_TYPE_SERVICE_32_BIT_DATA = 0x20, 276 /// Service data 128-bit UUID 277 GAP_AD_TYPE_SERVICE_128_BIT_DATA = 0x21, 278 /// Public Target Address 279 GAP_AD_TYPE_PUB_TGT_ADDR = 0x17, 280 /// Random Target Address 281 GAP_AD_TYPE_RAND_TGT_ADDR = 0x18, 282 /// Appearance 283 GAP_AD_TYPE_APPEARANCE = 0x19, 284 /// Advertising Interval 285 GAP_AD_TYPE_ADV_INTV = 0x1A, 286 /// LE Bluetooth Device Address 287 GAP_AD_TYPE_LE_BT_ADDR = 0x1B, 288 /// LE Role 289 GAP_AD_TYPE_LE_ROLE = 0x1C, 290 /// Simple Pairing Hash C-256 291 GAP_AD_TYPE_SPAIR_HASH = 0x1D, 292 /// Simple Pairing Randomizer R-256 293 GAP_AD_TYPE_SPAIR_RAND = 0x1E, 294 /// 3D Information Data 295 GAP_AD_TYPE_3D_INFO = 0x3D, 296 297 /// Manufacturer specific data 298 GAP_AD_TYPE_MANU_SPECIFIC_DATA = 0xFF, 299 }; 300 301 302 /// Random Address type 303 enum gap_rnd_addr_type 304 { 305 /// Static random address - 11 (MSB->LSB) 306 GAP_STATIC_ADDR = 0xC0, 307 /// Private non resolvable address - 01 (MSB->LSB) 308 GAP_NON_RSLV_ADDR = 0x00, 309 /// Private resolvable address - 01 (MSB->LSB) 310 GAP_RSLV_ADDR = 0x40, 311 }; 312 313 /// Boolean value set 314 enum 315 { 316 /// Disable 317 GAP_DISABLE = 0x00, 318 /// Enable 319 GAP_ENABLE 320 }; 321 322 323 /// GAP Attribute database handles 324 /// Generic Access Profile Service 325 enum 326 { 327 GAP_IDX_PRIM_SVC, 328 GAP_IDX_CHAR_DEVNAME, 329 GAP_IDX_DEVNAME, 330 GAP_IDX_CHAR_ICON, 331 GAP_IDX_ICON, 332 GAP_IDX_CHAR_SLAVE_PREF_PARAM, 333 GAP_IDX_SLAVE_PREF_PARAM, 334 GAP_IDX_CHAR_CNT_ADDR_RESOL, 335 GAP_IDX_CNT_ADDR_RESOL, 336 GAP_IDX_NUMBER 337 }; 338 339 340 341 /****************** GAP Role **********************/ 342 enum gap_role 343 { 344 /// No role set yet 345 GAP_ROLE_NONE = 0x00, 346 347 /// Observer role 348 GAP_ROLE_OBSERVER = 0x01, 349 350 /// Broadcaster role 351 GAP_ROLE_BROADCASTER = 0x02, 352 353 /// Master/Central role 354 GAP_ROLE_CENTRAL = (0x04 | GAP_ROLE_OBSERVER), 355 356 /// Peripheral/Slave role 357 GAP_ROLE_PERIPHERAL = (0x08 | GAP_ROLE_BROADCASTER), 358 359 /// Device has all role, both peripheral and central 360 GAP_ROLE_ALL = (GAP_ROLE_CENTRAL | GAP_ROLE_PERIPHERAL), 361 362 /// Debug mode used to force LL configuration on BLE 4.0 363 GAP_ROLE_DBG_LE_4_0 = 0x80, 364 }; 365 366 /// Advertising mode 367 enum gap_adv_mode 368 { 369 /// Mode in non-discoverable 370 GAP_NON_DISCOVERABLE, 371 /// Mode in general discoverable 372 GAP_GEN_DISCOVERABLE, 373 /// Mode in limited discoverable 374 GAP_LIM_DISCOVERABLE, 375 /// Broadcaster mode which is a non discoverable and non connectable mode. 376 GAP_BROADCASTER_MODE 377 }; 378 379 /// Scan mode 380 enum gap_scan_mode 381 { 382 /// Mode in general discovery 383 GAP_GEN_DISCOVERY, 384 /// Mode in limited discovery 385 GAP_LIM_DISCOVERY, 386 /// Observer mode 387 GAP_OBSERVER_MODE, 388 /// Invalid mode 389 GAP_INVALID_MODE 390 }; 391 392 393 394 /// IO Capability Values 395 enum gap_io_cap 396 { 397 /// Display Only 398 GAP_IO_CAP_DISPLAY_ONLY = 0x00, 399 /// Display Yes No 400 GAP_IO_CAP_DISPLAY_YES_NO, 401 /// Keyboard Only 402 GAP_IO_CAP_KB_ONLY, 403 /// No Input No Output 404 GAP_IO_CAP_NO_INPUT_NO_OUTPUT, 405 /// Keyboard Display 406 GAP_IO_CAP_KB_DISPLAY, 407 GAP_IO_CAP_LAST 408 }; 409 410 /// TK Type 411 enum gap_tk_type 412 { 413 /// TK get from out of band method 414 GAP_TK_OOB = 0x00, 415 /// TK generated and shall be displayed by local device 416 GAP_TK_DISPLAY, 417 /// TK shall be entered by user using device keyboard 418 GAP_TK_KEY_ENTRY 419 }; 420 421 /// OOB Data Present Flag Values 422 enum gap_oob 423 { 424 /// OOB Data not present 425 GAP_OOB_AUTH_DATA_NOT_PRESENT = 0x00, 426 /// OOB data present 427 GAP_OOB_AUTH_DATA_PRESENT, 428 GAP_OOB_AUTH_DATA_LAST 429 }; 430 431 /// Authentication mask 432 enum gap_auth_mask 433 { 434 /// No Flag set 435 GAP_AUTH_NONE = 0, 436 /// Bond authentication 437 GAP_AUTH_BOND = (1 << 0), 438 /// Man In the middle protection 439 GAP_AUTH_MITM = (1 << 2), 440 /// Secure Connection 441 GAP_AUTH_SEC_CON = (1 << 3), 442 /// Key Notification 443 GAP_AUTH_KEY_NOTIF = (1 << 4) 444 }; 445 446 /// Security Link Level 447 enum gap_lk_sec_lvl 448 { 449 /// No authentication 450 GAP_LK_NO_AUTH = 0, 451 /// Unauthenticated link 452 GAP_LK_UNAUTH, 453 /// Authenticated link 454 GAP_LK_AUTH, 455 /// Secure Connection link 456 GAP_LK_SEC_CON, 457 }; 458 459 /// Authentication Requirements 460 enum gap_auth 461 { 462 /// No MITM No Bonding 463 GAP_AUTH_REQ_NO_MITM_NO_BOND = (GAP_AUTH_NONE), 464 /// No MITM Bonding 465 GAP_AUTH_REQ_NO_MITM_BOND = (GAP_AUTH_BOND), 466 /// MITM No Bonding 467 GAP_AUTH_REQ_MITM_NO_BOND = (GAP_AUTH_MITM), 468 /// MITM and Bonding 469 GAP_AUTH_REQ_MITM_BOND = (GAP_AUTH_MITM | GAP_AUTH_BOND), 470 /// SEC_CON and No Bonding 471 GAP_AUTH_REQ_SEC_CON_NO_BOND = (GAP_AUTH_SEC_CON), 472 /// SEC_CON and Bonding 473 GAP_AUTH_REQ_SEC_CON_BOND = (GAP_AUTH_SEC_CON | GAP_AUTH_BOND), 474 475 GAP_AUTH_REQ_LAST, 476 477 /// Mask of authentication features without reserved flag 478 GAP_AUTH_REQ_MASK = 0x1F, 479 }; 480 481 /// Key Distribution Flags 482 enum gap_kdist 483 { 484 /// No Keys to distribute 485 GAP_KDIST_NONE = 0x00, 486 /// Encryption key in distribution 487 GAP_KDIST_ENCKEY = (1 << 0), 488 /// IRK (ID key)in distribution 489 GAP_KDIST_IDKEY = (1 << 1), 490 /// CSRK(Signature key) in distribution 491 GAP_KDIST_SIGNKEY= (1 << 2), 492 /// LTK in distribution 493 GAP_KDIST_LINKKEY= (1 << 3), 494 495 GAP_KDIST_LAST = (1 << 4) 496 }; 497 498 /// Security Defines 499 enum gap_sec_req 500 { 501 /// No security (no authentication and encryption) 502 GAP_NO_SEC = 0x00, 503 /// Unauthenticated pairing with encryption 504 GAP_SEC1_NOAUTH_PAIR_ENC, 505 /// Authenticated pairing with encryption 506 GAP_SEC1_AUTH_PAIR_ENC, 507 /// Unauthenticated pairing with data signing 508 GAP_SEC2_NOAUTH_DATA_SGN, 509 /// Authentication pairing with data signing 510 GAP_SEC2_AUTH_DATA_SGN, 511 /// Secure Connection pairing with encryption 512 GAP_SEC1_SEC_CON_PAIR_ENC, 513 }; 514 515 /// device name 516 struct gap_dev_name 517 { 518 /// name length 519 uint16_t length; 520 /// name value 521 uint8_t value[__ARRAY_EMPTY]; 522 }; 523 524 /// Slave preferred connection parameters 525 struct gap_slv_pref 526 { 527 /// Connection interval minimum 528 uint16_t con_intv_min; 529 /// Connection interval maximum 530 uint16_t con_intv_max; 531 /// Slave latency 532 uint16_t slave_latency; 533 /// Connection supervision timeout multiplier 534 uint16_t conn_timeout; 535 }; 536 537 538 539 540 541 /*************** GAP Structures ********************/ 542 543 ///BD Address structure 544 typedef struct 545 { 546 ///6-byte array address value 547 uint8_t addr[GAP_BD_ADDR_LEN]; 548 } bd_addr_t; 549 550 ///Channel map structure 551 typedef struct 552 { 553 ///5-byte channel map array 554 uint8_t map[GAP_LE_CHNL_MAP_LEN]; 555 } le_chnl_map_t; 556 557 558 ///Random number structure 559 typedef struct 560 { 561 ///8-byte array for random number 562 uint8_t nb[GAP_RAND_NB_LEN]; 563 } rand_nb_t; 564 565 ///Advertising report structure 566 typedef struct 567 { 568 ///Event type: 569 /// - ADV_CONN_UNDIR: Connectable Undirected advertising 570 /// - ADV_CONN_DIR: Connectable directed advertising 571 /// - ADV_DISC_UNDIR: Discoverable undirected advertising 572 /// - ADV_NONCONN_UNDIR: Non-connectable undirected advertising 573 uint8_t evt_type; 574 ///Advertising address type: public/random 575 uint8_t adv_addr_type; 576 ///Advertising address value 577 bd_addr_t adv_addr; 578 ///Data length in advertising packet 579 uint8_t data_len; 580 ///Data of advertising packet 581 uint8_t data[GAP_ADV_DATA_LEN]; 582 ///RSSI value for advertising packet 583 uint8_t rssi; 584 } adv_report_t; 585 586 587 /// P256 Public key data format 588 typedef struct 589 { 590 /// X Coordinate of the key 591 uint8_t x[GAP_P256_KEY_LEN]; 592 /// X Coordinate of the key 593 uint8_t y[GAP_P256_KEY_LEN]; 594 } public_key_t; 595 596 /// Address information about a device address 597 struct gap_bdaddr 598 { 599 /// BD Address of device 600 bd_addr_t addr; 601 /// Address type of the device 0=public/1=private random 602 uint8_t addr_type; 603 }; 604 605 /// Resolving list device information 606 struct gap_ral_dev_info 607 { 608 /// Address type of the device 0=public/1=private random 609 uint8_t addr_type; 610 /// BD Address of device 611 bd_addr_t addr; 612 /// Peer IRK 613 uint8_t peer_irk[GAP_KEY_LEN]; 614 /// Local IRK 615 uint8_t local_irk[GAP_KEY_LEN]; 616 }; 617 618 /// Generic Security key structure 619 struct gap_sec_key 620 { 621 /// Key value MSB -> LSB 622 uint8_t key[GAP_KEY_LEN]; 623 }; 624 625 626 627 /// @} GAP 628 #endif // GAP_H_ 629