1 /** 2 **************************************************************************************** 3 * 4 * @file ble_gapc.h 5 * 6 * @brief BLE GAPC API 7 * 8 **************************************************************************************** 9 * @attention 10 #####Copyright (c) 2019 GOODIX 11 All rights reserved. 12 13 Redistribution and use in source and binary forms, with or without 14 modification, are permitted provided that the following conditions are met: 15 * Redistributions of source code must retain the above copyright 16 notice, this list of conditions and the following disclaimer. 17 * Redistributions in binary form must reproduce the above copyright 18 notice, this list of conditions and the following disclaimer in the 19 documentation and/or other materials provided with the distribution. 20 * Neither the name of GOODIX nor the names of its contributors may be used 21 to endorse or promote products derived from this software without 22 specific prior written permission. 23 24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 25 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27 ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE 28 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34 POSSIBILITY OF SUCH DAMAGE. 35 ***************************************************************************************** 36 */ 37 38 /** 39 * @addtogroup BLE 40 * @{ 41 * @brief Definitions and prototypes for the BLE SDK interface. 42 */ 43 44 /** 45 * @addtogroup BLE_GAP Generic Access Profile (GAP) 46 * @{ 47 * @brief Definitions and prototypes for the GAP interface. 48 */ 49 50 /** 51 * @defgroup BLE_GAPC Generic Access Profile (GAP) Connection Control 52 * @{ 53 * @brief Definitions and prototypes for the GAP Connection Control interface. 54 */ 55 #ifndef __BLE_GAPC_H__ 56 #define __BLE_GAPC_H__ 57 58 #include <stdint.h> // Standard Integer 59 #include <stdbool.h> 60 #include "gr55xx_sys_cfg.h" 61 62 /** 63 * @defgroup BLE_GAPC_DEFINES Defines 64 * @{ 65 */ 66 #define GAP_CHNL_MAP_LEN 0x05 /**< The length of channel map. */ 67 #define GAP_FEATS_LEN 0x08 /**< The length of features. */ 68 #define GAP_ADDR_LEN 0x06 /**< The length of address. */ 69 #define GAP_INVALID_CONN_INDEX 0xFF /**< Invalid connection index. */ 70 71 /**@defgroup BLE_GAP_ADDR_TYPES GAP Address types 72 * @{ */ 73 #define BLE_GAP_ADDR_TYPE_PUBLIC 0x00 /**< Public (identity) address.*/ 74 #define BLE_GAP_ADDR_TYPE_RANDOM_STATIC 0x01 /**< Random static (identity) address. */ 75 /**@} */ 76 77 /**@defgroup BLE_GAP_PHY_OPTIONS GAP PHY OPTIONS (bitmask) 78 * @{ */ 79 #define PHY_OPT_NO_CODING 0x00 /**< The Host has no preferred coding when transmitting on the LE Coded PHY. */ 80 #define PHY_OPT_S2_CODING 0x01 /**< The Host prefers that S=2 coding be used when transmitting on the LE Coded PHY. */ 81 #define PHY_OPT_S8_CODING 0x02 /**< The Host prefers that S=8 coding be used when transmitting on the LE Coded PHY. */ 82 /**@} */ 83 84 /** @} */ 85 86 /** 87 * @defgroup BLE_SDK_GAP_ENUM Enumerations 88 * @{ 89 */ 90 /** @brief The operation code used to get connection info */ 91 typedef enum { 92 GAP_GET_CON_RSSI = 0, /**< Get connection RSSI info. */ 93 GAP_GET_CON_CHANNEL_MAP, /**< Get connection channel map. */ 94 GAP_GET_PHY, /**< Get connection PHY. */ 95 GAP_GET_CHAN_SEL_ALGO /**< Get selection algorithm for connection channel. */ 96 } gap_get_conn_info_op_t; 97 98 /**@brief The operation code used to get peer device info. */ 99 typedef enum { 100 GAP_GET_PEER_VERSION = 0, /**< Get peer device version info. */ 101 GAP_GET_PEER_FEATURES /**< Get peer device features info. */ 102 } gap_get_peer_info_op_t; 103 104 /** @brief Advertising report type. */ 105 typedef enum { 106 GAP_REPORT_TYPE_ADV_EXT = 0, /**< Extended advertising report. */ 107 GAP_REPORT_TYPE_ADV_LEG, /**< Legacy advertising report. */ 108 GAP_REPORT_TYPE_SCAN_RSP_EXT, /**< Extended scan response report. */ 109 GAP_REPORT_TYPE_SCAN_RSP_LEG, /**< Legacy scan response report. */ 110 GAP_REPORT_TYPE_PER_ADV, /**< Periodic advertising report. */ 111 } gap_adv_report_type_t; 112 113 /** @brief Advertising report information. */ 114 typedef enum { 115 GAP_REPORT_INFO_COMPLETE_BIT = (1 << 0), /**< Report is complete. */ 116 GAP_REPORT_INFO_CONN_ADV_BIT = (1 << 1), /**< Connectable advertising. */ 117 GAP_REPORT_INFO_SCAN_ADV_BIT = (1 << 2), /**< Scannable advertising. */ 118 GAP_REPORT_INFO_DIR_ADV_BIT = (1 << 3), /**< Directed advertising. */ 119 } gap_adv_report_info_t; 120 121 /** @brief Stop reason code. */ 122 typedef enum { 123 GAP_STOPPED_REASON_TIMEOUT = 0, /**< Stop with timeout. */ 124 GAP_STOPPED_REASON_ON_USER, /**< Stop with user stopping it actively. */ 125 GAP_STOPPED_REASON_CONN_EST /**< Stop with connection established. */ 126 } gap_stopped_reason_t; 127 128 /** @brief Device role of LL layer type */ 129 typedef enum { 130 GAP_LL_ROLE_MASTER = 0, /**< Master role. */ 131 GAP_LL_ROLE_SLAVE = 1, /**< Slave role. */ 132 } gap_ll_role_type_t; 133 134 /** 135 * @brief Operation code used to set param(s). 136 */ 137 typedef enum { 138 GAP_OPCODE_CHNL_MAP_SET, /**< Set Channel Map. */ 139 GAP_OPCODE_WHITELIST_SET, /**< Set white list. */ 140 GAP_OPCODE_PER_ADV_LIST_SET, /**< Set periodic advertising list. */ 141 GAP_OPCODE_PRIVACY_MODE_SET, /**< Set privacy mode for peer device. */ 142 } gap_param_set_op_id_t; 143 144 /** 145 * @brief Operation code used to read resolvable address. 146 */ 147 typedef enum { 148 GAP_OPCODE_LOCAL_RSLV_ADDR_READ, /**< Local resolvable address operation. */ 149 GAP_OPCODE_PEER_RSLV_ADDR_READ, /**< Peer resolvable address operation. */ 150 } gap_rslv_addr_read_op_id_t; 151 152 /** 153 * @brief Operation code used for LEPSM manager. 154 */ 155 typedef enum { 156 GAP_OPCODE_LEPSM_REGISTER, /**< LEPSM register operation. */ 157 GAP_OPCODE_LEPSM_UNREGISTER, /**< LEPSM unregister operation. */ 158 } gap_psm_manager_op_id_t; 159 160 /** 161 * @brief The specified reason for terminating a connection. 162 */ 163 typedef enum { 164 GAP_HCI_AUTHENTICATION_FAILURE = 0x05, /**< Authentication Failure. */ 165 GAP_HCI_REMOTE_USER_TERMINATED_CONNECTION = 0x13, /**< Remote User Terminated Connection. */ 166 GAP_HCI_REMOTE_DEV_TERMINATION_DUE_TO_LOW_RESOURCES = 0x14, /**< Remote Device Terminated Connection due to 167 Low Resources . */ 168 GAP_HCI_REMOTE_DEV_TERMINATION_DUE_TO_POWER_OFF = 0x15, /**< Remote Device Terminated Connection due to 169 Power Off. */ 170 GAP_HCI_UNSUPPORTED_REMOTE_FEATURE = 0x1A, /**< Unsupported Remote Feature. */ 171 GAP_HCI_PAIRING_WITH_UNIT_KEY_UNSUPPORTED = 0X29, /**< Pairing With Unit Key Not Supported. */ 172 GAP_HCI_CONN_INTERVAL_UNACCEPTABLE = 0x3B, /**< Unacceptable Connection Parameters. */ 173 } gap_disconn_reason_t; 174 175 /** @} */ 176 177 /** 178 * @defgroup BLE_GAPC_STRUCT Structures 179 * @{ 180 */ 181 182 /** @brief The struct of device version. */ 183 typedef struct { 184 uint8_t hci_ver; /**< HCI version. */ 185 uint8_t lmp_ver; /**< LMP version. */ 186 uint8_t host_ver; /**< Host version. */ 187 uint16_t hci_subver; /**< HCI subversion. */ 188 uint16_t lmp_subver; /**< LMP subversion. */ 189 uint16_t host_subver; /**< Host subversion. */ 190 uint16_t manuf_name; /**< Manufacturer name. */ 191 } gap_dev_version_ind_t; 192 193 /** @brief The struct of address. */ 194 typedef struct { 195 uint8_t addr[GAP_ADDR_LEN]; /**< 6-byte array address value. */ 196 } gap_addr_t; 197 198 /** @brief The struct of broadcast address with broadcast type. */ 199 typedef struct { 200 gap_addr_t gap_addr; /**< Device BD Address. */ 201 uint8_t addr_type; /**< Address type of the device: 0=public/1=random. please @ref BLE_GAP_ADDR_TYPES. */ 202 } gap_bdaddr_t; 203 204 /** @brief Get broadcast address struct. */ 205 typedef struct { 206 uint8_t index; /**< Advertsing index. The valid range is: 0 - 4. */ 207 gap_bdaddr_t bd_addr; /**< BD address. */ 208 } gap_get_bd_addr_t; 209 210 /** @brief TX power info struct. */ 211 typedef struct { 212 int8_t power_lvl; /**< Advertising channel TX power level. Range: -20 to 10. Unit: dBm. Accuracy: +/-4dB. */ 213 } gap_dev_adv_tx_power_t; 214 215 /** @brief TX power info struct. */ 216 typedef struct { 217 int8_t min_tx_pwr; /**< MIN of TX power. Size: 1 octet (signed integer). Range: -127 to +126. Unit: dBm. */ 218 int8_t max_tx_pwr; /**< MAX of TX power. Size: 1 octet (signed integer). Range: -127 to +126. Unit: dBm. */ 219 } gap_dev_tx_power_t; 220 221 /** @brief Max data length info struct. */ 222 typedef struct { 223 uint16_t suppted_max_tx_octets; /**< Maximum number of payload octets that the local Controller supports 224 for transmission of a single Link Layer packet on a data connection. 225 Range: 0x001B-0x00FB (all other values reserved for future use). */ 226 uint16_t suppted_max_tx_time; /**< Maximum time, in microseconds, that the local Controller supports 227 for transmission of a single Link Layer packet on a data connection. 228 Range: 0x0148-0x4290 (all other values reserved for future use). */ 229 uint16_t suppted_max_rx_octets; /**< Maximum number of payload octets that the local Controller supports 230 for reception of a single Link Layer packet on a data connection. 231 Range: 0x001B-0x00FB (all other values reserved for future use). */ 232 uint16_t suppted_max_rx_time; /**< Maximum time, in microseconds, that the local Controller supports 233 for reception of a single Link Layer packet on a data connection. 234 Range: 0x0148-0x4290 (all other values reserved for future use). */ 235 } gap_max_data_len_t; 236 237 /** @brief Suggested default data length info. */ 238 typedef struct { 239 uint16_t suggted_max_tx_octets; /**< The Host's suggested value for the Controller's maximum transmitted number of 240 payload octets to be used for new connections. 241 Range: 0x001B-0x00FB (all other values reserved for future use), 242 default: 0x001B */ 243 uint16_t suggted_max_tx_time; /**< The Host's suggested value for the Controller's maximum packet 244 transmissiontime to be used for new connections. 245 Range: 0x0148-0x4290 (all other values reserved for future use), 246 default: 0x0148 */ 247 } gap_sugg_dflt_data_len_t; 248 249 /** @brief Number of available advertising sets info. */ 250 typedef struct { 251 uint8_t nb_adv_sets; /**< Number of available advertising sets. */ 252 } gap_nb_adv_sets_t; 253 254 /** @brief Maximum advertising data length info. */ 255 typedef struct { 256 uint16_t length; /**< Maximum advertising data length supported by controller. */ 257 } gap_max_adv_data_len_ind_t; 258 259 /** @brief RF path compensation values info. */ 260 typedef struct { 261 uint16_t tx_path_comp; /**< RF TX path compensation. */ 262 uint16_t rx_path_comp; /**< RF RX path compensation. */ 263 } gap_dev_rf_path_comp_ind_t; 264 265 /** @brief Device info. */ 266 typedef union { 267 gap_dev_version_ind_t dev_version; /**< Version info. */ 268 gap_get_bd_addr_t get_bd_addr; /**< Device BD address info. */ 269 gap_dev_adv_tx_power_t adv_tx_power; /**< Advertising TX power info. */ 270 gap_sugg_dflt_data_len_t sugg_dflt_data_len; /**< Suggested default data length info. */ 271 gap_max_data_len_t max_data_len; /**< Suggested MAX data length info. */ 272 gap_nb_adv_sets_t nb_adv_sets; /**< Number of available advertising sets. */ 273 gap_max_adv_data_len_ind_t max_adv_data_len; /**< Maximum advertising data length info. */ 274 gap_dev_tx_power_t dev_tx_power; /**< Device TX power info. */ 275 gap_dev_rf_path_comp_ind_t dev_rf_path_comp; /**< RF path compensation values. */ 276 } gap_dev_info_t; 277 278 /** @brief Get device info operation struct. */ 279 typedef struct { 280 uint8_t operation; /**< Operation code. @see enum gap_dev_info_get_type_t. */ 281 gap_dev_info_t dev_info; /**< Device info. */ 282 } gap_dev_info_get_t; 283 284 /** @brief Read resolvable address info struct. */ 285 typedef struct { 286 uint8_t op_code; /**< Operation code. @see enum gap_rslv_addr_read_op_id_t. */ 287 gap_addr_t gap_addr; /**< Resolvable address info. */ 288 } gap_rslv_addr_read_t; 289 290 /** @brief Sync established indication. */ 291 typedef struct { 292 uint8_t phy; /**< PHY on which synchronization has been established. @see gap_phy_type. */ 293 uint16_t intv; /**< Periodic advertising interval (in unit of 1.25ms, min is 7.5ms). */ 294 uint8_t adv_sid; /**< Advertising SID. */ 295 uint8_t clk_acc; /**< Advertiser clock accuracy. @see enum gapm_clk_acc. */ 296 gap_bdaddr_t bd_addr; /**< Advertiser address. */ 297 uint16_t sync_hdl; /**< Sync handle. */ 298 } gap_sync_established_ind_t; 299 300 /** @brief APP receives the extended advertising report indication info struct. */ 301 typedef struct { 302 uint8_t adv_type; /**< Advertising type. @see enum gap_adv_report_type_t. */ 303 uint8_t adv_info; /**< Bit field providing information about the received report. 304 @see enum gap_adv_report_info_t. */ 305 gap_bdaddr_t broadcaster_addr; /**< Broadcaster device address. */ 306 gap_bdaddr_t direct_addr; /**< Target address (in case of a directed advertising report). */ 307 int8_t tx_pwr; /**< TX power (in dBm). */ 308 int8_t rssi; /**< RSSI (between -127 and +20 dBm). */ 309 uint8_t phy_prim; /**< Primary PHY on which advertising report has been received. */ 310 uint8_t phy_second; /**< Secondary PHY on which advertising report has been received. */ 311 uint8_t adv_sid; /**< Advertising SID , valid only for periodic advertising report. */ 312 uint16_t period_adv_intv; /**< Periodic advertising interval (in unit of 1.25ms, min is 7.5ms), 313 valid only for periodic advertising report. */ 314 uint8_t per_sync_idx; /**< Periodic syncronization index, 315 valid only for periodic advertising report. */ 316 uint16_t length; /**< Report length. */ 317 uint8_t data[__ARRAY_EMPTY]; /**< Report. */ 318 } gap_ext_adv_report_ind_t; 319 320 /** @brief Name of peer device indication. */ 321 typedef struct { 322 gap_addr_t peer_addr; /**< Peer device bd address. */ 323 uint8_t addr_type; /**< Peer device address type. */ 324 uint8_t name_len; /**< Peer device name length. */ 325 uint8_t name[__ARRAY_EMPTY]; /**< Peer device name. */ 326 } gap_peer_name_ind_t; 327 328 /** @brief Connection parameter used to update connection parameters. */ 329 typedef struct { 330 uint16_t interval; /**< Connection interval. Range: 0x0006 to 0x0C80. 331 Unit: 1.25 ms. Time range: 7.5 ms to 4 s. */ 332 uint16_t latency; /**< Latency for the connection in number of connection events. 333 Range: 0x0000 to 0x01F3. */ 334 uint16_t sup_timeout; /**< Supervision timeout for the LE link. Range: 0x000A to 0x0C80, 335 unit: 10 ms, time range: 100 ms to 32 s. */ 336 } gap_conn_update_cmp_t; 337 338 /** @brief The parameter of connection. */ 339 typedef struct { 340 uint16_t interval_min; /**< Minimum value for the connection interval. 341 This shall be less than or equal to Conn_Interval_Max. 342 Range: 0x0006 to 0x0C80, unit: 1.25 ms, time range: 7.5 ms to 4 s */ 343 uint16_t interval_max; /**< Maximum value for the connection interval. 344 This shall be greater than or equal to Conn_Interval_Min. 345 Range: 0x0006 to 0x0C80, unit: 1.25 ms, time range: 7.5 ms to 4 s. */ 346 uint16_t slave_latency; /**< Slave latency for the connection in number of connection events. 347 Range: 0x0000 to 0x01F3. */ 348 uint16_t sup_timeout; /**< Supervision timeout for the LE link. Range: 0x000A to 0x0C80, 349 unit: 10 ms, time range: 100 ms to 32 s. */ 350 } gap_conn_param_t; 351 352 /** @brief The parameter of update connection. */ 353 typedef struct { 354 uint16_t interval_min; /**< Minimum value for the connection interval. 355 This shall be less than or equal to Conn_Interval_Max. 356 Range: 0x0006 to 0x0C80, unit: 1.25 ms, time range: 7.5 ms to 4 s */ 357 uint16_t interval_max; /**< Maximum value for the connection interval. 358 This shall be greater than or equal to Conn_Interval_Min. 359 Range: 0x0006 to 0x0C80, unit: 1.25 ms, time range: 7.5 ms to 4 s. */ 360 uint16_t slave_latency; /**< Slave latency for the connection in number of connection events. 361 Range: 0x0000 to 0x01F3. */ 362 uint16_t sup_timeout; /**< Supervision timeout for the LE link. range: 0x000A to 0x0C80, 363 unit: 10 ms, Time range: 100 ms to 32 s. */ 364 uint16_t ce_len; /**< The length of connection event needed for this LE connection. 365 Range: 0x0002 to 0xFFFF, unit: 0.625 ms, time Range: 1.25 ms to 40.9 s. 366 recommended value: 0x0002 for 1M phy, 0x0006 for coded phy */ 367 } gap_conn_update_param_t; 368 369 /** @brief Connection complete info. */ 370 typedef struct { 371 uint16_t 372 conhdl; /**< Connection_Handle. Range: 0x0000-0x0EFF (all other values reserved for future use). */ 373 uint16_t 374 con_interval; /**< Connection interval. Range: 0x0006 to 0x0C80, unit: 1.25 ms, time range: 7.5 ms to 4 s. */ 375 uint16_t 376 con_latency; /**< Latency for the connection in number of connection events. Range: 0x0000 to 0x01F3. */ 377 uint16_t 378 sup_to; /**< Connection supervision timeout. Range: 0x000A to 0x0C80, 379 unit: 10 ms, time range: 100 ms to 32 s. */ 380 uint8_t 381 clk_accuracy; /**< Clock accuracy (0x00: 500 ppm, 0x01: 250 ppm, 0x02: 150 ppm, 0x03: 100 ppm, 0x04: 75 ppm, 382 0x05:50 ppm, 0x06:30 ppm, 0x07:20 ppm, others: reserved for future use). */ 383 uint8_t 384 peer_addr_type; /**< Peer address type(0x00: Public Device Address, 0x01 : Random Device Address, 385 others: reserved for future use). */ 386 gap_addr_t peer_addr; /**< Peer BT address. */ 387 gap_ll_role_type_t ll_role; /**< Device Role of LL Layer. */ 388 } gap_conn_cmp_t; 389 390 /** @brief Channel map structure. */ 391 typedef struct { 392 uint8_t map[GAP_CHNL_MAP_LEN]; /**< This parameter contains 37 1-bit fields. 393 The nth bit (n is in the range of 0 to 36) contains the value for 394 the link layer channel index n. 395 Channel n is unused = 0, channel n is used = 1. 396 The most significant bits are reserved for future use. */ 397 } gap_chnl_map_t; 398 399 /** @brief PHY info. */ 400 typedef struct { 401 uint8_t tx_phy; /**< LE PHY for data transmission. @see BLE_GAP_PHYS. */ 402 uint8_t rx_phy; /**< LE PHY for data reception. @see BLE_GAP_PHYS. */ 403 } gap_le_phy_ind_t; 404 405 /** @brief Connection info. */ 406 typedef union { 407 int8_t rssi; /**< RSSI. */ 408 gap_chnl_map_t chnl_map; /**< channel map. */ 409 gap_le_phy_ind_t phy; /**< PHY indicaiton. */ 410 uint8_t chan_sel_algo; /**< Chanel Selection algorithm, 0x00: LE Channel Selection Algorithm #1 is used. 411 0x01: LE Channel Selection Algorithm #2 is used.\n 0x02-0xFF: reserved. */ 412 } gap_conn_info_t; 413 414 /** @brief The info of connecting operation. */ 415 typedef struct { 416 uint8_t opcode; /**< Operation code. See @ref gap_get_conn_info_op_t. */ 417 gap_conn_info_t info; /**< Connection info. */ 418 } gap_conn_info_param_t; 419 420 /** @brief Peer version info. */ 421 typedef struct { 422 uint16_t compid; /**<Manufacturer name. */ 423 uint16_t lmp_subvers; /**< LMP subversion. */ 424 uint8_t lmp_vers; /**< LMP version. */ 425 } gap_peer_version_ind_t; 426 427 /** @brief LE features info. */ 428 typedef struct { 429 uint8_t features[GAP_FEATS_LEN]; /**< 8-byte array for LE features\n 430 Feature Setting field's bit mapping to Controller Features 431 (0: not support, 1: support) \n 432 |Bit position | Link Layer Feature| 433 |-------------|-----------------| 434 |0 | LE Encryption| 435 |1 |Connection Parameters Request Procedure| 436 |2 |Extended Reject Indication| 437 |3 | Slave-initiated Features Exchange | 438 |4 |LE Ping | 439 |5 |LE Data Packet Length Extension | 440 |6 |LL Privacy | 441 |7 |Extended Scanner Filter Policies | 442 |8 |LE 2M PHY| 443 |9 | Stable Modulation Index - Transmitter | 444 |10 | Stable Modulation Index - Receiver | 445 |11 |LE Coded PHY | 446 |12 |LE Extended Advertising| 447 |13 | LE Periodic Advertising| 448 |14 | Channel Selection Algorithm #2| 449 |15 |LE Power Class 1| 450 |16 |Minimum Number of Used Channels Procedure| 451 |All other values |Reserved for Future Use| */ 452 } gap_peer_features_ind_t; 453 454 /** @brief LE peer info. */ 455 typedef union { 456 gap_peer_version_ind_t peer_version; /**< Version info. */ 457 gap_peer_features_ind_t peer_features; /**< Features info. */ 458 } gap_peer_info_t; 459 460 /** @brief Get peer info operation struct. */ 461 typedef struct { 462 uint8_t opcode; /**< Operation code. See @ref gap_get_peer_info_op_t. */ 463 gap_peer_info_t peer_info; /**< Peer info. */ 464 } gap_peer_info_param_t; 465 466 /** @brief Supported data length size Indication. */ 467 typedef struct { 468 uint16_t max_tx_octets; /**< The maximum number of payload octets in TX. */ 469 uint16_t max_tx_time; /**< The maximum time that the local Controller will take to TX. */ 470 uint16_t max_rx_octets; /**< The maximum number of payload octets in RX. */ 471 uint16_t max_rx_time; /**< The maximum time that the local Controller will take to RX. */ 472 } gap_le_pkt_size_ind_t; 473 474 /**@brief The Structure for BLE Connection Arrangement. */ 475 typedef struct { 476 uint16_t conn_idx; /**< Connection Index. */ 477 uint32_t interval; /**< Connection Interval (in 625us). */ 478 uint32_t offset; /**< Connection Offset (in 625us). */ 479 uint32_t duration; /**< Connection Duration (in 625us). */ 480 } gap_con_plan_tag_t; 481 482 /** @brief Set preference slave event duration */ 483 typedef struct { 484 uint16_t duration; /**< Preferred event duration. */ 485 uint8_t single_tx; /**< Slave transmits a single packet per connection event (False/True). */ 486 } gap_set_pref_slave_evt_dur_param_t; 487 488 /** @brief BLE initialization completed callback function for application. */ 489 typedef void (*app_ble_init_cmp_cb_t)(void); 490 491 /** @brief The gap callback function struct. */ 492 typedef struct { 493 // ---------------------------------------------------------------------------------- 494 // ------------------------- Common Callbacks ------------------------------------ 495 // ---------------------------------------------------------------------------------- 496 497 /** 498 **************************************************************************************** 499 * @brief This callback function will be called when the param(s) setting operation has been completed. 500 * @param[in] status: The status of set param operation. 501 * @param[in] set_param_op: The operation of setting. @see gap_param_set_op_id_t. 502 * @retval void 503 **************************************************************************************** 504 */ 505 void (*app_gap_param_set_cb)(uint8_t status, const gap_param_set_op_id_t set_param_op); 506 507 /** 508 **************************************************************************************** 509 * @brief This callback function will be called when the PSM register/unregister operation has been completed. 510 * @param[in] status: The status of PSM manager operations. 511 * @param[in] psm_op: The operation of register/unregister PSM. @see gap_psm_op_id_t 512 * @retval void 513 **************************************************************************************** 514 */ 515 void (*app_gap_psm_manager_cb)(uint8_t status, const gap_psm_manager_op_id_t psm_op); 516 517 /** 518 **************************************************************************************** 519 * @brief This callback function will be called when update PHY completed. 520 * @param[in] conn_idx: The index of connections. 521 * @param[in] status: The status of udpate PHY operation. 522 * @param[in] phy: Pointer to the PHY info. 523 * @retval void 524 **************************************************************************************** 525 */ 526 void (*app_gap_phy_update_cb)(uint8_t conn_idx, uint8_t status, const gap_le_phy_ind_t *p_phy); 527 528 /** 529 **************************************************************************************** 530 * @brief This callback function will be called once the requested parameters has been available. 531 * @param[in] status: GAP operation status. 532 * @param[in] p_dev_info: Pointer to the device info. See @ref gap_dev_info_get_t. 533 * @retval void 534 **************************************************************************************** 535 */ 536 void (*app_gap_dev_info_get_cb)(uint8_t status, const gap_dev_info_get_t* p_dev_info); 537 538 // ---------------------------------------------------------------------------------- 539 // ------------------------- Advertising Callbacks ---------------------------------- 540 // ---------------------------------------------------------------------------------- 541 542 /** 543 **************************************************************************************** 544 * @brief This callback function will be called when the adv has started. 545 * @param[in] inst_idx: The advertising index. Valid range is: 0 - 4. 546 * @param[in] status: The status of starting a advertiser. 547 * @retval void 548 **************************************************************************************** 549 */ 550 void (*app_gap_adv_start_cb)(uint8_t inst_idx, uint8_t status); 551 552 /** 553 **************************************************************************************** 554 * @brief This callback function will be called when the adv has stopped. 555 * @param[in] inst_idx: The advertising index. Valid range is: 0 - 4. 556 * @param[in] status: The status of stopping a advertiser. If status is not success, adv_stop_reason is invalid. 557 * @param[in] adv_stop_reason: The stop reason. See @ref gap_stopped_reason_t. 558 * @retval void 559 **************************************************************************************** 560 */ 561 void (*app_gap_adv_stop_cb)(uint8_t inst_idx, uint8_t status, gap_stopped_reason_t adv_stop_reason); 562 563 /** 564 **************************************************************************************** 565 * @brief This callback function will be called when app has received the scan request. 566 * @param[in] inst_idx: The advertising index. Valid range is: 0 - 4. 567 * @param[in] p_scanner_addr: Pointer to the BD address. See @ref gap_bdaddr_t. 568 * @retval void 569 **************************************************************************************** 570 */ 571 void (*app_gap_scan_req_ind_cb)(uint8_t inst_idx, const gap_bdaddr_t *p_scanner_addr); 572 573 /** 574 **************************************************************************************** 575 * @brief This callback function will be called when update adv data completed. 576 * @param[in] inst_idx: The advertising index. Valid range is: 0 - 4. 577 * @param[in] status: The status of udpate PHY operation. 578 * @retval void 579 **************************************************************************************** 580 */ 581 void (*app_gap_adv_data_update_cb)(uint8_t inst_idx, uint8_t status); 582 583 // ---------------------------------------------------------------------------------- 584 // -------------------- Scanning/Periodic Synchronization Callbacks ------------------------ 585 // ---------------------------------------------------------------------------------- 586 587 /** 588 **************************************************************************************** 589 * @brief This callback function will be called when the scan has started. 590 * @param[in] status: The status of starting a scanner. 591 * @retval void 592 **************************************************************************************** 593 */ 594 void (*app_gap_scan_start_cb)(uint8_t status); 595 596 /** 597 **************************************************************************************** 598 * @brief This callback function will be called once the scanning activi-ty has been stopped. 599 * @param[in] status: The status of stopping a scanner. 600 * @param[in] scan_stop_reason: The stop reason. See @ref gap_stopped_reason_t. 601 * @retval void 602 **************************************************************************************** 603 */ 604 void (*app_gap_scan_stop_cb)(uint8_t status, gap_stopped_reason_t scan_stop_reason); 605 606 /** 607 **************************************************************************************** 608 * @brief This callback function will be called once the advertising report has been received. 609 * @param[in] p_adv_report: Pointer to the extended advertising report. See @ref gap_ext_adv_report_ind_t. 610 * @retval void 611 **************************************************************************************** 612 */ 613 void (*app_gap_adv_report_ind_cb)(const gap_ext_adv_report_ind_t *p_adv_report); 614 615 /** 616 **************************************************************************************** 617 * @brief This callback function will be called once the periodic advertising synchronization has been established. 618 * @param[in] status: The status of sync. 619 * @param[in] inst_idx: The periodic syncronization index. Valid range is: 0 - 4. 620 * @param[in] p_sync_established_info: Pointer to the established ind info. See @ref gap_sync_established_ind_t. 621 * @retval void 622 **************************************************************************************** 623 */ 624 void (*app_gap_sync_establish_cb)(uint8_t inst_idx, uint8_t status, 625 const gap_sync_established_ind_t *p_sync_established_info); 626 627 /** 628 **************************************************************************************** 629 * @brief This callback function will be called when sync has stopped. 630 * @param[in] status: The status of stopping sync. 631 * @param[in] inst_idx: The periodic syncronization index. Valid range is: 0 - 4. 632 * @retval void 633 **************************************************************************************** 634 */ 635 void (*app_gap_stop_sync_cb)(uint8_t inst_idx, uint8_t status); 636 637 /** 638 **************************************************************************************** 639 * @brief This callback function will be called once the periodic advertising synchronization has been lost. 640 * @param[in] inst_idx: The periodic syncronization index. Valid range is: 0 - 4. 641 * @retval void 642 **************************************************************************************** 643 */ 644 void (*app_gap_sync_lost_cb)(uint8_t inst_idx); 645 646 // ---------------------------------------------------------------------------------- 647 // ------------------------- Initiating Callbacks -------------------------------------- 648 // ---------------------------------------------------------------------------------- 649 650 /** 651 **************************************************************************************** 652 * @brief This callback function will be called when connection completed. 653 * @param[in] conn_idx: The connection index. 654 * @param[in] status: The status of operation. If status is not success, conn_idx and p_conn_param are invalid. 655 * @param[in] p_conn_param: Pointer to the connection param. See @ref gap_conn_cmp_t. 656 * @retval void 657 **************************************************************************************** 658 */ 659 void (*app_gap_connect_cb)(uint8_t conn_idx, uint8_t status, const gap_conn_cmp_t *p_conn_param); 660 661 /** 662 **************************************************************************************** 663 * @brief This callback function will be called when disconnection completed. 664 * @param[in] conn_idx: The connection index. 665 * @param[in] status: The status of operation. If status is not success, disconnection reason is invalid. 666 * @param[in] reason: The reason of disconnection. See @ref BLE_STACK_ERROR_CODES. 667 * @retval void 668 **************************************************************************************** 669 */ 670 void (*app_gap_disconnect_cb)(uint8_t conn_idx, uint8_t status, uint8_t reason); 671 672 /** 673 **************************************************************************************** 674 * @brief This callback function will be called when connection canceled. 675 * @param[in] status: The status of cancel operation. 676 * @retval void 677 **************************************************************************************** 678 */ 679 void (*app_gap_connect_cancel_cb)(uint8_t status); 680 681 /** 682 **************************************************************************************** 683 * @brief This callback function will be called when an automatic connection timeout occurs. 684 * @retval void 685 **************************************************************************************** 686 */ 687 void (*app_gap_auto_connection_timeout_cb)(void); 688 689 /** 690 **************************************************************************************** 691 * @brief This callback function will be called when the peer name info has been available. 692 * @param[in] conn_idx: The connection index. 693 * @param[in] p_peer_name: Pointer to the peer device name indication info. See @ref gap_peer_name_ind_t. 694 * @retval void 695 **************************************************************************************** 696 */ 697 void (*app_gap_peer_name_ind_cb)(uint8_t conn_idx, const gap_peer_name_ind_t *p_peer_name); 698 699 // ---------------------------------------------------------------------------------- 700 // ------------------------- Connection Control Callbacks ------------------------------ 701 // ---------------------------------------------------------------------------------- 702 703 /** 704 **************************************************************************************** 705 * @brief This callback function will be called when connection update completed. 706 * @param[in] conn_idx: The connection index. 707 * @param[in] status: The status of GAP operation. 708 * @param[in] p_conn_param_update_info: Pointer to the connection update complete param. 709 See @ref gap_conn_update_cmp_t. 710 * @retval void 711 **************************************************************************************** 712 */ 713 void (*app_gap_connection_update_cb)(uint8_t conn_idx, uint8_t status, 714 const gap_conn_update_cmp_t *p_conn_param_update_info); 715 716 /** 717 **************************************************************************************** 718 * @brief This callback function will be called when the peer device requests updating connection. 719 * @param[in] conn_idx: The connection index. 720 * @param[in] p_conn_param_update_req: Pointer to the connection update request param. See @ref gap_conn_param_t. 721 * @retval void 722 **************************************************************************************** 723 */ 724 void (*app_gap_connection_update_req_cb)(uint8_t conn_idx, const gap_conn_param_t *p_conn_param_update_req); 725 726 /** 727 **************************************************************************************** 728 * @brief This callback function will be called when app has got the connection info. 729 * @param[in] conn_idx: The connection index. 730 * @param[in] status: The status of GAP operation. 731 * @param[in] p_conn_info: Pointer to the connection info. See @ref gap_conn_info_param_t. 732 * @retval void 733 **************************************************************************************** 734 */ 735 void (*app_gap_connection_info_get_cb)(uint8_t conn_idx, uint8_t status, const gap_conn_info_param_t *p_conn_info); 736 737 /** 738 **************************************************************************************** 739 * @brief This callback function will be called when app has got the peer info. 740 * @param[in] conn_idx: The connection index. 741 * @param[in] status: The status of GAP operation. 742 * @param[in] p_peer_dev_info: Pointer to the peer device info. See @ref gap_peer_info_param_t. 743 * @retval void 744 **************************************************************************************** 745 */ 746 void (*app_gap_peer_info_get_cb)(uint8_t conn_idx, uint8_t status, const gap_peer_info_param_t *p_peer_dev_info); 747 748 /** 749 **************************************************************************************** 750 * @brief This callback function will be called when an app sets the length size of the supported data. 751 * @param[in] conn_idx: The connection index. 752 * @param[in] status: The status of GAP operation. 753 * @param[in] p_supported_data_length_size: Supported data length size. See @ref gap_le_pkt_size_ind_t. 754 * @retval void 755 **************************************************************************************** 756 */ 757 void (*app_gap_le_pkt_size_info_cb)(uint8_t conn_idx, uint8_t status, 758 const gap_le_pkt_size_ind_t *p_supported_data_length_size); 759 760 /** 761 **************************************************************************************** 762 * @brief This callback function will be called when an app reads the local or peer reslovable address. 763 * @param[in] status: The status of GAP operation. 764 * @param[in] p_read_rslv_addr: Read resolvable address info. See @ref gap_rslv_addr_read_t. 765 * @retval void 766 **************************************************************************************** 767 */ 768 void (*app_gap_rslv_addr_read_cb)(uint8_t status, const gap_rslv_addr_read_t *p_read_rslv_addr); 769 } gap_cb_fun_t; 770 771 /** @} */ 772 773 /** 774 * @defgroup BLE_GAPC_FUNCTION Functions 775 * @{ 776 */ 777 /** 778 **************************************************************************************** 779 * @brief Terminate an existing connection. 780 * @note When APP wants to disconnect a connection, it should call this function, 781 * and when the disconnection is finished, 782 * the callback function @ref gap_cb_fun_t::app_gap_disconnect_cb will be called. 783 * 784 * @param[in] conn_idx: The index of connection. 785 * 786 * @retval ::SDK_SUCCESS: Operation is Success. 787 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied. 788 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 789 **************************************************************************************** 790 */ 791 uint16_t ble_gap_disconnect(uint8_t conn_idx); 792 793 /** 794 **************************************************************************************** 795 * @brief Terminate an existing connection with a specified reason. 796 * @note When APP wants to disconnect a connection, it should call this function, 797 * and when the disconnection is finished, 798 * the callback function @ref gap_cb_fun_t::app_gap_disconnect_cb will be called. 799 * 800 * @param[in] conn_idx: The index of connection. 801 * @param[in] reason: The specified reason. 802 * 803 * @retval ::SDK_SUCCESS: Operation is Success. 804 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied. 805 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 806 **************************************************************************************** 807 */ 808 uint16_t ble_gap_disconnect_with_reason(uint8_t conn_idx, gap_disconn_reason_t reason); 809 810 /** 811 **************************************************************************************** 812 * @brief Change the Link Layer connection parameters of a connection. 813 * @note When APP wants to update connection param, it should call this function, 814 * and if the update connection param is finished, 815 * the callback function @ref gap_cb_fun_t::app_gap_connection_update_cb will be called. 816 * 817 * @param[in] conn_idx: The index of connection. 818 * @param[in] p_conn_param: Pointer to the new connection param. 819 * 820 * @retval ::SDK_SUCCESS: Operation is Success. 821 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied. 822 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 823 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 824 **************************************************************************************** 825 */ 826 uint16_t ble_gap_conn_param_update (uint8_t conn_idx, const gap_conn_update_param_t *p_conn_param); 827 828 /** 829 ***************************************************************************************** 830 * @brief Set connection's Latency. 831 * @note The latency shall be set to X value by LLCP firstly, then uses this API to change the latency in [0, X]. 832 * 833 * @param[in] conn_idx: The index of connection. 834 * @param[in] latency: The latency of connection. 835 * 836 * @retval ::SDK_SUCCESS: Operation is Success. 837 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied. 838 ***************************************************************************************** 839 */ 840 uint16_t ble_gap_latency_set(uint8_t conn_idx, uint16_t latency); 841 842 /** 843 ***************************************************************************************** 844 * @brief Consult BLE connection activity - plan situation function. 845 * @note This function should be called when connection established and no periodic advertising exists. 846 * 847 * @param[out] p_act_num: Pointer to the number of existing connection activities. 848 * @param[out] p_conn_plan_arr: Pointer to the global array that stores planned connection activities. 849 * 850 * @retval ::SDK_SUCCESS: Operation is Success. 851 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 852 ***************************************************************************************** 853 */ 854 uint16_t ble_gap_con_plan_consult(uint8_t *p_act_num, gap_con_plan_tag_t **p_conn_plan_arr); 855 856 /** 857 **************************************************************************************** 858 * @brief Connection param update reply to peer device. 859 * 860 * @note If the Host receives the param update request from the peer device, it will call the callback function. 861 * @ref gap_cb_fun_t::app_gap_connection_update_req_cb, and then the APP should call this function to confirm. 862 * 863 * @param[in] conn_idx: The index of connection. 864 * @param[in] accept: True to accept connection parameters, false to reject. 865 * 866 * @retval ::SDK_SUCCESS: Operation is success. 867 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied. 868 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 869 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 870 **************************************************************************************** 871 */ 872 uint16_t ble_gap_conn_param_update_reply(uint8_t conn_idx, bool accept); 873 874 /** 875 **************************************************************************************** 876 * @brief The suggested maximum transmission packet size and maximum packet transmission time 877 * to be used for a given connection. 878 * @note Once this operation has been completed, the callback function @ref gap_cb_fun_t: 879 * app_gap_le_pkt_size_info_cb will be called. 880 * 881 * @param[in] conn_idx: The index of connection. 882 * @param[in] tx_octects: Preferred maximum number of payload octets that the local Controller 883 * should include in a single Link Layer packet on this connection. 884 * Range 0x001B-0x00FB (all other values reserved for future use). 885 * @param[in] tx_time: Preferred maximum number of microseconds that the local Controller 886 * should use to transmit a single Link Layer packet on this connection. 887 * Range 0x0148-0x4290 (all other values reserved for future use). 888 * 889 * @retval ::SDK_SUCCESS: Operation is Success. 890 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied. 891 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 892 **************************************************************************************** 893 */ 894 uint16_t ble_gap_data_length_update(uint8_t conn_idx, uint16_t tx_octects, uint16_t tx_time); 895 896 /** 897 **************************************************************************************** 898 * @brief Set the PHY preferences for the connection identified by the connection index. 899 * @note Once this operation has been completed, the callback function @ref gap_cb_fun_t: 900 * app_gap_phy_update_cb will be called. 901 * 902 * @param[in] conn_idx: The index of connection. 903 * @param[in] tx_phys: The transmitter PHYs that the Host prefers the Controller to use (see @ref BLE_GAP_PHYS). 904 * @param[in] rx_phys: A bit field that indicates the receiver PHYs that the Host prefers the Controller to use 905 * (see @ref BLE_GAP_PHYS). 906 * @param[in] phy_opt: A bit field that allows the Host to specify options for PHYs (see @ref BLE_GAP_PHY_OPTIONS). 907 * 908 * @retval ::SDK_SUCCESS: Operation is Success. 909 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied. 910 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 911 **************************************************************************************** 912 */ 913 uint16_t ble_gap_phy_update(uint8_t conn_idx, uint8_t tx_phys, uint8_t rx_phys, uint8_t phy_opt); 914 915 /** 916 **************************************************************************************** 917 * @brief Get the information of the connection. 918 * @note Once the connection information has been available, the callback function @ref gap_cb_fun_t: 919 * app_gap_connection_info_get_cb will be called. 920 * 921 * @param[in] conn_idx: The index of connection. 922 * @param[in] opcode: The operation code. See @ref gap_get_conn_info_op_t. 923 * 924 * @retval ::SDK_SUCCESS: Operation is Success. 925 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied. 926 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied. 927 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 928 **************************************************************************************** 929 */ 930 uint16_t ble_gap_conn_info_get(uint8_t conn_idx, gap_get_conn_info_op_t opcode); 931 932 /** 933 **************************************************************************************** 934 * @brief Get the information of the peer device. 935 * @note Once the peer information has been available, the callback function @ref gap_cb_fun_t: 936 * app_gap_peer_info_get_cb will be called. 937 * 938 * @param[in] conn_idx: The index of connection. 939 * @param[in] opcode: The operation code. See @ref gap_get_peer_info_op_t. 940 * 941 * @retval ::SDK_SUCCESS: Operation is Success. 942 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied. 943 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied. 944 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 945 **************************************************************************************** 946 */ 947 uint16_t ble_gap_peer_info_get(uint8_t conn_idx, gap_get_peer_info_op_t opcode); 948 949 /** @} */ 950 951 #endif 952 /** @} */ 953 /** @} */ 954 /** @} */ 955