1 /** 2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. * 14 * Description: BTS GAP module. 15 */ 16 17 /** 18 * @defgroup bluetooth_bts_gap BTS LE GAP API 19 * @ingroup bluetooth 20 * @{ 21 */ 22 #ifndef BTS_LE_GAP_H 23 #define BTS_LE_GAP_H 24 25 #include <stdint.h> 26 #include "errcode.h" 27 #include "bts_def.h" 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 /** 34 * @if Eng 35 * @brief Enum of BLE appearance type samples, see the Appearance Values file for details. 36 * @else 37 * @brief BLE显示类型部分举例,具体参考Appearance Values文件 38 * @endif 39 */ 40 typedef enum { 41 GAP_BLE_APPEARANCE_TYPE_UNKNOWN = 00, /*!< @if Eng Unknown 42 @else 未知类型 @endif */ 43 GAP_BLE_APPEARANCE_TYPE_GENERIC_PHONE = 64, /*!< @if Eng Generic Phone 44 @else 通用手机 @endif */ 45 GAP_BLE_APPEARANCE_TYPE_GENERIC_COMPUTER = 128, /*!< @if Eng Generic Computer 46 @else 通用电脑 @endif */ 47 GAP_BLE_APPEARANCE_TYPE_GENERIC_WATCH = 192, /*!< @if Eng Generic Watch 48 @else 通用手表 @endif */ 49 GAP_BLE_APPEARANCE_TYPE_GENERIC_DISPLAY = 320, /*!< @if Eng Generic Display 50 @else 通用显示器 @endif */ 51 GAP_BLE_APPEARANCE_TYPE_GENERIC_HID = 960, /*!< @if Eng Generic Human Interface Device 52 @else 通用人机界面设备 @endif */ 53 GAP_BLE_APPEARANCE_TYPE_KEYBOARD = 961, /*!< @if Eng Keyboard 54 @else 键盘 @endif */ 55 GAP_BLE_APPEARANCE_TYPE_MOUSE = 962, /*!< @if Eng Mouse 56 @else 鼠标 @endif */ 57 GAP_BLE_APPEARANCE_TYPE_DIGITAL_PEN = 967, /*!< @if Eng Digital Pen 58 @else 电子笔 @endif */ 59 } gap_ble_appearance_type_t; 60 61 /** 62 * @if Eng 63 * @brief Enum of advertising filter parameters. 64 * @else 65 * @brief 广播过滤参数。 66 * @endif 67 */ 68 typedef enum { 69 GAP_BLE_ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY = 0x00, /*!< @if Eng Accepts all scan and connect requests 70 @else 处理所有设备的扫描和连接请求 @endif */ 71 GAP_BLE_ADV_FILTER_ALLOW_SCAN_WLST_CON_ANY = 0x01, /*!< @if Eng Accepts all connect but white list scan requests 72 @else 处理所有连接请求，仅处理白名单的扫描请求 @endif */ 73 GAP_BLE_ADV_FILTER_ALLOW_SCAN_ANY_CON_WLST = 0x02, /*!< @if Eng Accepts all scan but white list connect requests 74 @else 处理所有扫描请求，仅处理白名单的连接请求 @endif */ 75 GAP_BLE_ADV_FILTER_ALLOW_SCAN_WLST_CON_WLST = 0x03, /*!< @if Eng Accepts only white list connect and scan requests 76 @else 仅处理白名单中扫描请求和连接请求 @endif */ 77 } gap_ble_adv_filter_allow_scan_t; 78 79 /** 80 * @if Eng 81 * @brief Enum of advertising type. 82 * @else 83 * @brief 广播类型。 84 * @endif 85 */ 86 typedef enum { 87 GAP_BLE_ADV_CONN_SCAN_UNDIR = 0, /*!< @if Eng Connectable, scanable, undirected advertising(default). 88 @else 可连接可扫描非定向广播(默认)。 @endif */ 89 GAP_BLE_ADV_CONN_NONSCAN_DIR, /*!< @if Eng Connectable, nonscanble, high duty directed advertising. 90 @else 可连接不可扫描高频定向广播。 @endif */ 91 GAP_BLE_ADV_NONCONN_SCAN_UNDIR, /*!< @if Eng Nonconnectable, scanable, undirected advertising. 92 @else 不可连接可扫描非定向广播。 @endif */ 93 GAP_BLE_ADV_NONCONN_NONSCAN_UNDIR, /*!< @if Eng Nonconnectable, nonscanable, undirected advertising. 94 @else 不可连接不可扫描非定向广播。 @endif */ 95 GAP_BLE_ADV_CONN_NONSCAN_DIR_LOW_DUTY, /*!< @if Eng Connectable, nonscanble, low duty directed advertising. 96 @else 可连接不可扫描低频定向广播。 @endif */ 97 } gap_ble_adv_type_t; 98 99 /** 100 * @if Eng 101 * @brief Enum of BLE scan type. 102 * @else 103 * @brief BLE扫描类型。 104 * @endif 105 */ 106 typedef enum { 107 GAP_BLE_SCAN_TYPE_PASSIVE = 0x00, /*!< @if Eng Passive scan 108 @else 被动扫描 @endif */ 109 GAP_BLE_SCAN_TYPE_ACTIVE, /*!< @if Eng Active scan 110 @else 主动扫描 @endif */ 111 } gap_ble_scan_type_t; 112 113 /** 114 * @if Eng 115 * @brief Enum of BLE scan filter policy. 116 * @else 117 * @brief BLE扫描过滤策略。 118 * @endif 119 */ 120 typedef enum { 121 GAP_BLE_SCAN_FILTER_POLICY_ACCEPT_ALL = 0x00, /*!< @if Eng Accept all advertising packets except directed 122 advertising packets not addressed to this device 123 (default) 124 @else 接收所有广播不接收目标地址不是本设备地址的定向广播 125 （默认） 126 @endif */ 127 GAP_BLE_SCAN_FILTER_POLICY_ONLY_WHITE_LIST, /*!< @if Eng Accept only advertisement packets from white list 128 devices. Directed advertising packets which are 129 not addressed for this device shall be ignored 130 @else 只接收白名单里设备的广播， 131 不接收目标地址不是本设备地址的定向广播 @endif */ 132 GAP_BLE_SCAN_FILTER_POLICY_ACCEPT_ALL_AND_RPA, /*!< @if Eng Accept all undirected advertisement packets, and 133 all directed advertising packets where the 134 initiator address is a resolvable private address, 135 and all directed advertising packets addressed to 136 this device 137 @else 接收所有的非定向广播、 138 地址是可解析私有地址的广播方发送的定向广播、 139 发给该设备的定向广播 @endif */ 140 GAP_BLE_SCAN_FILTER_POLICY_ONLY_WHITE_LIST_AND_RPA, /*!< @if Eng Accept all undirected advertisement packets from 141 devices where the advertiser's address is in the 142 White list, and all directed advertising packets 143 where the initiator address is a resolvable 144 private address, and all directed advertising 145 packets addressed to this device 146 @else 接收白名单中的所有非定向广播、 147 地址是可解析私有地址的广播方发送的定向广播、 148 发给该设备的定向广播 @endif */ 149 } gap_ble_scan_filter_policy_t; 150 151 /** 152 * @if Eng 153 * @brief Enum of BLE scan event type. 154 * @else 155 * @brief BLE扫描结果广播类型。 156 * @endif 157 */ 158 typedef enum { 159 GAP_BLE_EVT_NON_CONNECTABLE_NON_SCANNABLE = 0x00, /*!< @if Eng Non-connectable, non-scannable, undirected 160 @else 扩展的不可连接不可扫描非定向 @endif */ 161 GAP_BLE_EVT_NON_CONNECTABLE_NON_SCANNABLE_DIRECTED = 0x04, /*!< @if Eng Non-connectable, non-scannable, directed 162 @else 扩展的不可连接不可扫描定向 @endif */ 163 GAP_BLE_EVT_CONNECTABLE = 0x01, /*!< @if Eng Connectable and undirected 164 @else 扩展的可连接非定向 @endif */ 165 GAP_BLE_EVT_CONNECTABLE_DIRECTED = 0x05, /*!< @if Eng Connectable and directed 166 @else 扩展的可连接定向 @endif */ 167 GAP_BLE_EVT_SCANNABLE = 0x02, /*!< @if Eng Scannable and undirected 168 @else 扩展的可扫描非定向 @endif */ 169 GAP_BLE_EVT_SCANNABLE_DIRECTED = 0x06, /*!< @if Eng Scannable and directed 170 @else 扩展的可扫描定向 @endif */ 171 GAP_BLE_EVT_LEGACY_NON_CONNECTABLE = 0x10, /*!< @if Eng Legacy, non-connectable and undirected 172 @else 传统的不可连接非定向 @endif */ 173 GAP_BLE_EVT_LEGACY_SCANNABLE = 0x12, /*!< @if Eng Legacy, scannable and undirected 174 @else 传统的可扫描非定向 @endif */ 175 GAP_BLE_EVT_LEGACY_CONNECTABLE = 0x13, /*!< @if Eng Legacy, connectable, scannable and 176 undirected 177 @else 传统的可连接可扫描非定向 @endif */ 178 GAP_BLE_EVT_LEGACY_CONNECTABLE_DIRECTED = 0x15, /*!< @if Eng Legacy, connectable, and directed 179 @else 传统的可连接定向 @endif */ 180 GAP_BLE_EVT_LEGACY_SCAN_RSP_TO_ADV_SCAN = 0x1A, /*!< @if Eng Legacy scan response corresponding to 181 ADV_SCAN_IND 182 @else 传统的与ADV_SCAN_IND对应的扫描响应 @endif */ 183 GAP_BLE_EVT_LEGACY_SCAN_RSP_TO_ADV = 0x1B /*!< @if Eng Legacy scan response corresponding to 184 ADV_IND 185 @else 传统的与ADV_IND对应的扫描响应 @endif */ 186 } gap_ble_scan_result_evt_type_t; 187 188 /** 189 * @if Eng 190 * @brief Struct of ble connect parameter update struct. 191 * @else 192 * @brief ble连接参数更新数据结构。 193 * @endif 194 */ 195 typedef struct { 196 uint16_t conn_handle; /*!< @if Eng connection id 197 @else 连接 ID @endif */ 198 uint16_t interval_min; /*!< @if Eng min interval 199 @else 最小间隔 @endif */ 200 uint16_t interval_max; /*!< @if Eng max interval 201 @else 最大间隔 @endif */ 202 uint16_t slave_latency; /*!< @if Eng slave reply min latency 203 @else 从设备回复最小间隔 @endif */ 204 uint16_t timeout_multiplier; /*!< @if Eng interval for disconnection due to timeout 205 @else 超时断连间隔 @endif */ 206 } gap_conn_param_update_t; 207 208 /** 209 * @if Eng 210 * @brief Struct of BLE PHY parameters. 211 * @else 212 * @brief BLE PHY参数数据结构。 213 * @endif 214 */ 215 typedef struct { 216 uint16_t conn_handle; /*!< @if Eng interval 217 @else 连接句柄 @endif */ 218 uint8_t all_phys; /*!< @if Eng interval 219 @else 所有PHY @endif */ 220 uint8_t tx_phys; /*!< @if Eng interval 221 @else 发送PHY @endif */ 222 uint8_t rx_phys; /*!< @if Eng interval 223 @else 接收PHY @endif */ 224 uint16_t phy_options; /*!< @if Eng interval 225 @else PHY选项 @endif */ 226 } gap_le_set_phy_t; 227 228 /** 229 * @if Eng 230 * @brief Struct of BLE packet transmission parameters. 231 * @else 232 * @brief BLE发包参数数据结构。 233 * @endif 234 */ 235 typedef struct { 236 uint16_t conn_handle; /*!< @if Eng interval 237 @else 连接句柄 @endif */ 238 uint16_t maxtxoctets; /*!< @if Eng interval 239 @else 最大字节数 @endif */ 240 uint16_t maxtxtime; /*!< @if Eng interval 241 @else 最大发送时间 @endif */ 242 } gap_le_set_data_length_t; 243 244 /** 245 * @if Eng 246 * @brief Enum of BLE scan result data status. 247 * @else 248 * @brief BLE扫描结果数据完整性。 249 * @endif 250 */ 251 typedef enum { 252 GAP_BLE_DATA_COMPLETE = 0x00, /*!< @if Eng Complete, or last segment 253 @else 完整数据或最后一个片段 @endif */ 254 GAP_BLE_DATA_INCOMPLETE_MORE_TO_COME = 0x01, /*!< @if Eng Incomplete 255 @else 不完整的数据 @endif */ 256 GAP_BLE_DATA_INCOMPLETE_TRUNCATED = 0x02, /*!< @if Eng Truncated 257 @else 被截断不完整的数据 @endif */ 258 } gap_ble_scan_result_data_status_t; 259 260 /** 261 * @if Eng 262 * @brief Enum of BLE PHY type. 263 * @else 264 * @brief BLE PHY类型。 265 * @endif 266 */ 267 typedef enum { 268 GAP_BLE_PHY_NO_PACKET = 0x00, /*!< @if Eng No packet 269 @else 无广播包 @endif */ 270 GAP_BLE_PHY_1M = 0x01, /*!< @if Eng 1M PHY 271 @else 1M PHY @endif */ 272 GAP_BLE_PHY_2M = 0x02, /*!< @if Eng 2M PHY 273 @else 2M PHY @endif */ 274 GAP_BLE_PHY_CODED = 0x03 /*!< @if Eng Coded PHY 275 @else Coded PHY @endif */ 276 } gap_ble_phy_type_t; 277 278 /** 279 * @if Eng 280 * @brief Advtertising status 281 * @else 282 * @brief 广播状态 283 * @endif 284 */ 285 typedef enum { 286 ADV_STATUS_STOPPED = 0x00, /*!< @if Eng advertising stoped 287 @else 广播停止 @endif */ 288 ADV_STATUS_ADVERTISING, /*!< @if Eng advertising 289 @else 正在广播 @endif */ 290 } adv_status_t; 291 292 /** 293 * @if Eng 294 * @brief Struct of BLE advertising data. 295 * @else 296 * @brief BLE广播数据。 297 * @endif 298 */ 299 typedef struct { 300 uint16_t adv_length; /*!< @if Eng Length of advertising data 301 @else 广播数据长度 @endif */ 302 uint8_t *adv_data; /*!< @if Eng Advertising data 303 @else 广播数据 @endif */ 304 uint16_t scan_rsp_length; /*!< @if Eng Length of scan response data 305 @else 扫描响应数据长度 @endif */ 306 uint8_t *scan_rsp_data; /*!< @if Eng Scan response data 307 @else 扫描响应数据 @endif */ 308 } gap_ble_config_adv_data_t; 309 310 /** 311 * @if Eng 312 * @brief Struct of BLE advertising parameters. 313 * @else 314 * @brief BLE广播参数。 315 * @endif 316 */ 317 typedef struct { 318 uint32_t min_interval; /*!< @if Eng Min interval[N * 0.625ms] 319 @else 最小的广播间隔[N * 0.625ms] @endif */ 320 uint32_t max_interval; /*!< @if Eng Max interval[N * 0.625ms] 321 @else 最大的广播间隔[N * 0.625ms] @endif */ 322 uint8_t adv_type; /*!< @if Eng Advertising type { @ref gap_ble_adv_type_t } 323 @else 广播类型 { @ref gap_ble_adv_type_t } @endif */ 324 bd_addr_t own_addr; /*!< @if Eng own address 325 @else 本端地址 @endif */ 326 bd_addr_t peer_addr; /*!< @if Eng Peer address 327 @else 对端地址 @endif */ 328 uint8_t channel_map; /*!< @if Eng channel bitmap 329 @else 广播通道选择: 330 0x01----使用37通道 331 0x07----使用37/38/39三个通道 @endif */ 332 uint8_t adv_filter_policy; /*!< @if Eng Advertising filter policy 333 { @ref gap_ble_adv_filter_allow_scan_t } 334 @else 白名单过滤策略 335 { @ref gap_ble_adv_filter_allow_scan_t } @endif */ 336 int8_t tx_power; /*!< @if Eng Transmissive power 337 @else 发送功率,单位dbm,范围-127~20 @endif */ 338 uint32_t duration; /*!< @if Eng Duration 339 @else 广播持续发送时长,单位dbm @endif */ 340 } gap_ble_adv_params_t; 341 342 /** 343 * @if Eng 344 * @brief Enum of advertising type. 345 * @else 346 * @brief 设备输入输出能力 347 * @endif 348 */ 349 typedef enum { 350 GAP_BLE_GAP_SECURITY_MODE1_LEVEL1 = 0, /*!< @if Eng No security 351 @else 没有安全能力 @endif */ 352 GAP_BLE_GAP_SECURITY_MODE1_LEVEL2, /*!< @if Eng Unauthenticated pairing and encryption 353 @else 不需要认证基于链路进行配对和加密 @endif */ 354 GAP_BLE_GAP_SECURITY_MODE1_LEVEL3, /*!< @if Eng Authenticated Pairing and encryption 355 @else 需要认证基于链路进行配对和加密 @endif */ 356 GAP_BLE_GAP_SECURITY_MODE1_LEVEL4, /*!< @if Eng Authenticated ECDH Pairing and encryption 357 @else 需要认证基于链路采用ECDH算法进行加密和配对 @endif */ 358 GAP_BLE_GAP_SECURITY_MODE2_LEVEL1, /*!< @if Eng Unauthenticated pairing and data signing 359 @else 不需要认证基于数据进行配对和加密 @endif */ 360 GAP_BLE_GAP_SECURITY_MODE2_LEVEL2, /*!< @if Eng Authenticated pairing and data signing 361 @else 需要认证基于数据进行配对和加密 @endif */ 362 } gap_ble_sec_mode_t; 363 364 /** 365 * @if Eng 366 * @brief Enum of advertising type. 367 * @else 368 * @brief 设备输入输出能力 369 * @endif 370 */ 371 typedef enum { 372 GAP_BLE_IO_CAPABILITY_DISPLAYONLY = 0, /*!< @if Eng only display 373 @else 只展示 @endif */ 374 GAP_BLE_IO_CAPABILITY_DISPLAYYESNO, /*!< @if Eng display and select yes or no 375 @else 展示，并且可以选择Yes或者No @endif */ 376 GAP_BLE_IO_CAPABILITY_KEYBOARDONLY, /*!< @if Eng only keyboard 377 @else 只支持键盘 @endif */ 378 GAP_BLE_IO_CAPABILITY_NOINPUTNOOUTPUT, /*!< @if Eng no input and no output 379 @else 没有输入输出 @endif */ 380 GAP_BLE_IO_CAPABILITY_KEYBOARDDISPLAY, /*!< @if Eng display and keyboard 381 @else 支持键盘和展示 @endif */ 382 } gap_ble_io_ability_t; 383 384 /** 385 * @if Eng 386 * @brief Struct of BLE scan parameters. 387 * @else 388 * @brief BLE扫描参数。 389 * @endif 390 */ 391 typedef struct { 392 uint16_t scan_interval; /*!< @if Eng Scan interval[N * 0.625ms] 393 @else 扫描间隔，[N * 0.625 ms] @endif */ 394 uint16_t scan_window; /*!< @if Eng Scan window[N * 0.625ms] 395 @else 扫描窗长，[N * 0.625 ms] @endif */ 396 uint8_t scan_type; /*!< @if Eng Scan type { @ref gap_ble_scan_type_t } 397 @else 扫描类型 { @ref gap_ble_scan_type_t } @endif */ 398 uint8_t scan_phy; /*!< @if Eng PHY type { @ref gap_ble_phy_type_t } 399 @else PHY类型 { @ref gap_ble_phy_type_t } @endif */ 400 uint8_t scan_filter_policy; /*!< @if Eng Scan fileter policy { @ref gap_ble_scan_filter_policy_t } 401 @else 扫描过滤策略 { @ref gap_ble_scan_filter_policy_t } @endif */ 402 } gap_ble_scan_params_t; 403 404 /** 405 * @if Eng 406 * @brief Struct of scan result data. 407 * @else 408 * @brief 扫描结果数据。 409 * @endif 410 */ 411 typedef struct { 412 uint8_t event_type; /*!< @if Eng Event type { @ref gap_ble_scan_result_evt_type_t } 413 @else 广播类型 { @ref gap_ble_scan_result_evt_type_t } @endif */ 414 uint8_t data_status; /*!< @if Eng Data status { @ref gap_ble_scan_result_data_status_t } 415 @else 扫描结果数据状态 { @ref gap_ble_scan_result_data_status_t } @endif */ 416 bd_addr_t addr; /*!< @if Eng Address 417 @else 地址 @endif */ 418 uint8_t primary_phy; /*!< @if Eng primary PHY { @ref gap_ble_phy_type_t } 419 @else 主广播PHY类型 { @ref gap_ble_phy_type_t } @endif */ 420 uint8_t secondary_phy; /*!< @if Eng secondary PHY { @ref gap_ble_phy_type_t } 421 @else 辅广播PHY类型 { @ref gap_ble_phy_type_t } @endif */ 422 uint8_t adv_sid; /*!< @if Eng Value of the Advertising SID subfield in the ADI field of the PDU 423 @else 广播SID @endif */ 424 int8_t tx_power; /*!< @if Eng Transmissive power 425 @else 发送功率，范围: -127 ~ +20dBm @endif */ 426 int8_t rssi; /*!< @if Eng RSSI 427 @else 信号强度，范围: -127 ~ +20dBm @endif */ 428 uint16_t periodic_adv_interval; /*!< @if Eng Periodic advertising interval 429 @else 周期广播间隔，[N * 1.25 ms] @endif */ 430 bd_addr_t direct_addr; /*!< @if Eng Directed address 431 @else 定向广播地址 @endif */ 432 uint8_t adv_len; /*!< @if Eng Advertising data length 433 @else 广播数据长度 @endif */ 434 uint8_t *adv_data; /*!< @if Eng Advertising data 435 @else 广播数据 @endif */ 436 } gap_scan_result_data_t; 437 438 /** 439 * @if Eng 440 * @brief Enum of scan filter duplicates. 441 * @else 442 * @brief 扫描过滤配置 443 * @endif 444 */ 445 typedef enum { 446 GAP_BLE_FILTER_DUPLICATES_DISABLE = 0, /*!< @if Eng reports each received broadcast packet 447 @else 上报每个收到的广播包 @endif */ 448 GAP_BLE_FILTER_DUPLICATES_ENABLE, /*!< @if Eng do not report duplicate broadcast packets 449 @else 不上报重复的广播包 @endif */ 450 GAP_BLE_FILTER_DUPLICATES_ENABLE_FOR_PERIOD, /*!< @if Eng do not report duplicate broadcast packets 451 in a period. 452 @else 周期内不上报重复的广播包 @endif */ 453 } gap_ble_filter_duplicates_t; 454 455 /** 456 * @if Eng 457 * @brief Struct of BLE scan extended parameters. 458 * @else 459 * @brief BLE扫描扩展参数。 460 * @endif 461 */ 462 typedef struct { 463 uint8_t filter_duplicate; /*!< @if Eng Scan filter duplicates { @ref gap_ble_filter_duplicates_t } 464 @else 扫描的过滤配置 { @ref gap_ble_filter_duplicates_t } @endif */ 465 uint8_t limited; /*!< @if Eng Reserved field 466 @else 保留字段 @endif */ 467 uint16_t duration; /*!< @if Eng Indicates the scanning duration. The value 0 indicates 468 continuous scanning. The default value is 0. Unit: 10 ms. 469 @else 扫描的持续时间，0表示持续扫描，默认值为0，单位: 10ms @endif */ 470 uint16_t period; /*!< @if Eng Indicates the scanning period. When the value is 0, 471 the scanning ends after the specified duration. 472 The default value is 0. Unit: 1.28s. 473 @else 扫描周期, 取0时扫描执行duration时间后会超时结束 474 默认值为0, 单位: 1.28s @endif */ 475 } gap_ble_extern_scan_params_t; 476 477 /** 478 * @if Eng 479 * @brief Enum of Bluetooth pairing state. 480 * @else 481 * @brief 蓝牙配对状态。 482 * @endif 483 */ 484 typedef enum { 485 GAP_BLE_PAIR_NONE = 0x01, /*!< @if Eng Pair state of none 486 @else 未配对状态 @endif */ 487 GAP_BLE_PAIR_PAIRING = 0x02, /*!< @if Eng Pair state of pairing 488 @else 正在配对 @endif */ 489 GAP_BLE_PAIR_PAIRED = 0x03 /*!< @if Eng Pair state of paired 490 @else 已完成配对 @endif */ 491 } gap_ble_pair_state_t; 492 493 /** 494 * @if Eng 495 * @brief Enum of disconnect reason. 496 * @else 497 * @brief 蓝牙断链原因。 498 * @endif 499 */ 500 typedef enum { 501 GAP_BLE_DISCONN_UNKNOWN = 0x00, /*!< @if Eng disconnect by local 502 @else 未知原因断链 @endif */ 503 GAP_BLE_ERR_CONN_TIMEOUT = 0x8, /*!< @if Eng disconnect by local 504 @else 连接超时断链 @endif */ 505 GAP_BLE_DICSCONNECT_BY_REMOTE_USER = 0x13, /*!< @if Eng disconnect by remote 506 @else 远端用户断链 @endif */ 507 GAP_BLE_CONN_TERMINATE_BY_LOCAL_HOST = 0x16, /*!< @if Eng disconnect by remote 508 @else 本端HOST断链 @endif */ 509 } gap_ble_disc_reason_t; 510 511 /** 512 * @if Eng 513 * @brief Enum of acl state. 514 * @else 515 * @brief 定义acl链路状态。 516 * @endif 517 */ 518 typedef enum { 519 GAP_BLE_STATE_DISCONNECTED,/*!< @if Eng BLE GAP ACL state of disconnected 520 @else BLE GAP ACL 已断连 @endif */ 521 GAP_BLE_STATE_CONNECTED /*!< @if Eng BLE GAP ACL state of connected 522 @else BLE GAP ACL 已连接 @endif */ 523 } gap_ble_conn_state_t; 524 525 526 /** 527 * @if Eng 528 * @brief Enum of ble link update event parameters. 529 * @else 530 * @brief ACL链路更新事件参数 531 * @endif 532 */ 533 typedef struct { 534 uint16_t interval; /*!< @if Eng interval 535 @else 链路调度间隔，单位slot @endif */ 536 uint16_t latency; /*!< @if Eng latency 537 @else 延迟周期，单位slot @endif */ 538 uint16_t timeout; /*!< @if Eng timeout 539 @else 超时时间，单位10ms @endif */ 540 } gap_ble_conn_param_update_t; 541 542 /** 543 * @if Eng 544 * @brief Struct of BLE advertising parameters. 545 * @else 546 * @brief BLE广播参数。 547 * @endif 548 */ 549 typedef struct { 550 uint8_t bondable; /*!< @if Eng bondable 551 @else 绑定能力选择： 552 0x01----支持绑定 553 0x00----不支持绑定 @endif */ 554 uint8_t io_capability; /*!< @if Eng input and output type { @ref gap_ble_io_ability_t } 555 @else 输入输出能力 { @ref gap_ble_io_ability_t } @endif */ 556 uint8_t sc_enable; /*!< @if Eng security enable 557 @else 安全配对能力选择： 558 0x01----支持安全配对 559 0x00----不支持安全配对 @endif */ 560 uint8_t sc_mode; /*!< @if Eng security mode type { @ref gap_ble_sec_mode_t } 561 @else 安全模式 { @ref gap_ble_sec_mode_t } @endif */ 562 } gap_ble_sec_params_t; 563 564 /** 565 * @if Eng 566 * @brief Length of device smp ltk. 567 * @else 568 * @brief 蓝牙设备配对的LTK长度。 569 * @endif 570 */ 571 #define BLE_PAIRED_LTK_LEN 16 572 573 /** 574 * @if Eng 575 * @brief Enum of sle authentication result. 576 * @else 577 * @brief BLE认证结果。 578 * @endif 579 */ 580 typedef struct { 581 uint8_t ltk_len; /*!< @if Eng link key len. 582 @else 链路密钥长度。 @endif */ 583 uint8_t ltk[BLE_PAIRED_LTK_LEN]; /*!< @if Eng link key. 584 @else 链路密钥。 @endif */ 585 } ble_auth_info_evt_t; 586 587 /** 588 * @if Eng 589 * @brief Callback invoked when ble enabled. 590 * @par When registered, this callback notifies the upper layer when ble enabled. 591 * @attention 1. This function is called in bts context,should not be blocked or do long time waiting. 592 * @attention 2. The memories of devices are requested and freed by the bts automatically. 593 * @param [in] status enable ble status. 594 * @par Dependency: 595 * @li bts_def.h 596 * @see gap_ble_callbacks_t 597 * @else 598 * @brief ble协议栈启动回调函数。 599 * @par 注册该回调函数之后，BTS在ble协议栈启动后上报启动结果给上层。 600 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 601 * @attention 2. devices由bts申请内存，也由bts释放，回调中不应释放。 602 * @param [in] status enable协议栈状态 603 * @par 依赖: 604 * @li bts_def.h 605 * @see gap_ble_callbacks_t 606 * @endif 607 */ 608 typedef void (*gap_ble_enable_callback)(errcode_t status); 609 610 /** 611 * @if Eng 612 * @brief Callback invoked when ble disabled. 613 * @par When registered, this callback notifies the upper layer when ble disabled. 614 * @attention 1. This function is called in bts context,should not be blocked or do long time waiting. 615 * @attention 2. The memories of devices are requested and freed by the bts automatically. 616 * @param [in] status disable ble status. 617 * @par Dependency: 618 * @li bts_def.h 619 * @see gap_ble_callbacks_t 620 * @else 621 * @brief ble协议栈关闭回调函数。 622 * @par 注册该回调函数之后，BTS在ble协议栈关闭后上报关闭结果给上层。 623 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 624 * @attention 2. devices由bts申请内存，也由bts释放，回调中不应释放。 625 * @param [in] status 关闭ble协议栈状态。 626 * @par 依赖: 627 * @li bts_def.h 628 * @see gap_ble_callbacks_t 629 * @endif 630 */ 631 typedef void (*gap_ble_disable_callback)(errcode_t status); 632 633 /** 634 * @if Eng 635 * @brief Callback invoked in response to advertising being enabled. 636 * @par When registered, this callback notifies the upper layer whether advertising is enabled successfully. 637 * @attention 1. This function is called in bts context,should not be blocked or do long time waiting. 638 * @attention 2. The memories of devices are requested and freed by the bts automatically. 639 * @param [in] adv_id advertising ID. 640 * @param [in] status advertising status. 641 * @par Dependency: 642 * @li bts_def.h 643 * @see gap_ble_callbacks_t 644 * @else 645 * @brief 启动广播回调函数。 646 * @par 注册该回调函数之后，BTS在每次启动广播后调用该接口上报启动结果给上层。 647 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 648 * @attention 2. devices由bts申请内存，也由bts释放，回调中不应释放。 649 * @param [in] adv_id 广播ID。 650 * @param [in] status 当前广播状态。 651 * @par 依赖: 652 * @li bts_def.h 653 * @see gap_ble_callbacks_t 654 * @endif 655 */ 656 typedef void (*gap_ble_start_adv_callback)(uint8_t adv_id, adv_status_t status); 657 658 /** 659 * @if Eng 660 * @brief Callback invoked in response to advertising being disabled. 661 * @par When registered, this callback notifies the upper layer whether advertising is disabled successfully. 662 * @attention 1. This function is called in bts context,should not be blocked or do long time waiting. 663 * @attention 2. The memories of devices are requested and freed by the bts automatically. 664 * @param [in] adv_id advertising ID. 665 * @param [in] status advertising status. 666 * @par Dependency: 667 * @li bts_def.h 668 * @see gap_ble_callbacks_t 669 * @else 670 * @brief 停止广播回调函数。 671 * @par 注册该回调函数之后，BTS在每次停止广播后调用该接口上报停止结果给上层。 672 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 673 * @attention 2. devices由bts申请内存，也由bts释放，回调中不应释放。 674 * @param [in] adv_id 广播ID。 675 * @param [in] status 当前广播状态。 676 * @par 依赖: 677 * @li bts_def.h 678 * @see gap_ble_callbacks_t 679 * @endif 680 */ 681 typedef void (*gap_ble_stop_adv_callback)(uint8_t adv_id, adv_status_t status); 682 683 /** 684 * @if Eng 685 * @brief Callback invoked in response to advertising data being configured. 686 * @par When registered, this callback notifies the upper layer if advertising data is configured as expected. 687 * @attention 1.This function is called in bts context,should not be blocked or do long time waiting. 688 * @attention 2. The memories of devices are requested and freed by the bts automatically. 689 * @param [in] adv_id advertising ID. 690 * @param [in] status error code. 691 * @par Dependency: 692 * @li bts_def.h 693 * @see gap_ble_callbacks_t 694 * @else 695 * @brief 设置广播数据后的回调函数。 696 * @par 注册该回调函数之后，BTS在每次设置广播数据后调用该接口上报设置结果给上层。 697 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 698 * @attention 2. devices由bts申请内存，也由bts释放，回调中不应释放。 699 * @param [in] adv_id 广播ID。 700 * @param [in] status 执行结果错误码。 701 * @par 依赖: 702 * @li bts_def.h 703 * @see gap_ble_callbacks_t 704 * @endif 705 */ 706 typedef void (*gap_ble_set_adv_data_callback)(uint8_t adv_id, errcode_t status); 707 708 /** 709 * @if Eng 710 * @brief Callback invoked in response to advertising being set. 711 * @par When registered, this callback notifies the upper layer if advertising data is set successfully. 712 * @attention 1.This function is called in bts context,should not be blocked or do long time waiting. 713 * @attention 2. The memories of devices are requested and freed by the bts automatically. 714 * @param [in] adv_id advertising ID. 715 * @param [in] status error code. 716 * @par Dependency: 717 * @li bts_def.h 718 * @see gap_ble_callbacks_t 719 * @else 720 * @brief 设置广播参数后的回调函数。 721 * @par 注册该回调函数之后，BTS在每次设置广播参数后调用该接口上报更新结果给上层。 722 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 723 * @attention 2. devices由bts申请内存，也由bts释放，回调中不应释放。 724 * @param [in] adv_id 广播ID。 725 * @param [in] status 执行结果错误码. 726 * @par 依赖: 727 * @li bts_def.h 728 * @see gap_ble_callbacks_t 729 * @endif 730 */ 731 typedef void (*gap_ble_set_adv_param_callback)(uint8_t adv_id, errcode_t status); 732 733 /** 734 * @if Eng 735 * @brief Callback invoked in response to scan being enabled. 736 * @par When registered, this callback notifies the upper layer about the scan result data. 737 * @attention 1.This function is called in bts context,should not be blocked or do long time waiting. 738 * @attention 2. The memories of devices are requested and freed by the bts automatically. 739 * @param [in] gap_scan_result_data_t scan result data. 740 * @par Dependency: 741 * @li bts_def.h 742 * @see gap_ble_callbacks_t 743 * @else 744 * @brief 启动扫描后的回调函数。 745 * @par 注册该回调函数之后，BTS在每次收到扫描结果后调用该接口上报结果数据给上层。 746 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 747 * @attention 2. devices由bts申请内存，也由bts释放，回调中不应释放。 748 * @attention 3. 暂不支持 749 * @param [in] gap_scan_result_data_t 扫描结果数据。 750 * @par 依赖: 751 * @li bts_def.h 752 * @see gap_ble_callbacks_t 753 * @endif 754 */ 755 typedef void (*gap_ble_scan_result_callback)(gap_scan_result_data_t *scan_result_data); 756 757 /** 758 * @if Eng 759 * @brief Callback invoked in response to scan parameter being set. 760 * @par When registered, this callback notifies the upper layer if the scan parameter is set as expected. 761 * @attention 1.This function is called in bts context,should not be blocked or do long time waiting. 762 * @attention 2. The memories of devices are requested and freed by the bts automatically. 763 * @param [in] status errcode_t 764 * @par Dependency: 765 * @li bts_def.h 766 * @see gap_ble_callbacks_t 767 * @else 768 * @brief 扫描参数设置完成后的回调函数。 769 * @par 注册该回调函数之后，BTS在扫描参数设置完成后调用该接口上报设置状态给上层。 770 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 771 * @attention 2. devices由bts申请内存，也由bts释放，回调中不应释放。 772 * @param [in] status 执行结果错误码。 773 * @par 依赖: 774 * @li bts_def.h 775 * @see gap_ble_callbacks_t 776 * @endif 777 */ 778 typedef void (*gap_ble_set_scan_param_callback)(errcode_t status); 779 780 /** 781 * @if Eng 782 * @brief Callback invoked when connection completed. 783 * @par When registered, this callback notifies the upper layer if a connnection is established. 784 * @attention 1.This function is called in bts context,should not be blocked or do long time waiting. 785 * @attention 2. The memories of devices are requested and freed by the bts automatically. 786 * @param [in] conn_id connection ID. 787 * @param [in] conn_state the connection state. 788 * @param [in] pair_status the pair state. 789 * @param [in] disc_reason the reason of disconnect. 790 * @par Dependency: 791 * @li bts_def.h 792 * @see gap_ble_callbacks_t 793 * @else 794 * @brief 连接事件完成的回调函数。 795 * @par 注册该回调函数之后，BTS在连接成后调用该接口上报连接状态信息给上层。 796 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 797 * @attention 2. devices由bts申请内存，也由bts释放，回调中不应释放。 798 * @param [in] conn_id 连接ID。 799 * @param [in] conn_state 连接状态。 800 * @param [in] pair_status 配对状态。 801 * @param [in] disc_reason 断链原因。 802 * @par 依赖: 803 * @li bts_def.h 804 * @see gap_ble_callbacks_t 805 * @endif 806 */ 807 typedef void (*gap_ble_connect_state_changed_callback)(uint16_t conn_id, bd_addr_t *addr, 808 gap_ble_conn_state_t conn_state, gap_ble_pair_state_t pair_state, gap_ble_disc_reason_t disc_reason); 809 810 /** 811 * @if Eng 812 * @brief Callback invoked when pair completed. 813 * @par When registered, this callback notifies the upper layer if a connnection is established. 814 * @attention 1.This function is called in bts context,should not be blocked or do long time waiting. 815 * @attention 2. The memories of devices are requested and freed by the bts automatically. 816 * @param [in] conn_id connection ID. 817 * @param [in] conn_state the connection state. 818 * @param [in] status the pair state. 819 * @par Dependency: 820 * @li bts_def.h 821 * @see gap_ble_callbacks_t 822 * @else 823 * @brief 配对事件完成的回调函数。 824 * @par 注册该回调函数之后，BTS在配对后调用该接口上报配对状态信息给上层。 825 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 826 * @attention 2. devices由bts申请内存，也由bts释放，回调中不应释放。 827 * @param [in] conn_id 连接ID。 828 * @param [in] status 配对状态。 829 * @par 依赖: 830 * @li bts_def.h 831 * @see gap_ble_callbacks_t 832 * @endif 833 */ 834 typedef void (*gap_ble_paired_complete_callback)(uint16_t conn_id, const bd_addr_t *addr, errcode_t status); 835 836 /** 837 * @if Eng 838 * @brief Callback invoked when advertising stoped. 839 * @par When registered, this callback notifies the upper layer if an advertising is stoped. 840 * @attention 1.This function is called in bts context,should not be blocked or do long time waiting. 841 * @attention 2. The memories of devices are requested and freed by the bts automatically. 842 * @param [in] adv_id advertising ID. 843 * @param [in] adv_status_t the advertising state. 844 * @par Dependency: 845 * @li bts_def.h 846 * @see gap_ble_callbacks_t 847 * @else 848 * @brief 配对事件完成的回调函数。 849 * @par 注册该回调函数之后，BTS在配对后调用该接口上报配对状态信息给上层。 850 * @attention 1. 该回调函数运行于bts线程，不能阻塞或长时间等待。 851 * @attention 2. devices由bts申请内存，也由bts释放，回调中不应释放。 852 * @param [in] adv_id 连接ID。 853 * @param [in] status 配对状态。 854 * @par 依赖: 855 * @li bts_def.h 856 * @see gap_ble_callbacks_t 857 * @endif 858 */ 859 typedef void (*gap_ble_terminate_adv_callback)(uint8_t adv_id, adv_status_t status); 860 861 /** 862 * @if Eng 863 * @brief Callback invoked when rssi read complete. 864 * @par Callback invoked when rssi read complete. 865 * @attention 1.This function is called in service context,should not be blocked or do long time waiting. 866 * @attention 2.The memories of pointer are requested and freed by the BLE service automatically. 867 * @param [in] conn_id connection ID. 868 * @param [in] rssi rssi. 869 * @param [in] status error code. 870 * @par Dependency: 871 * @li bts_def.h 872 * @see gap_ble_callbacks_t 873 * @else 874 * @brief 读取rssi的回调函数。 875 * @par 读取rssi的回调函数。 876 * @attention 1. 该回调函数运行于 service线程，不能阻塞或长时间等待。 877 * @attention 2. 指针由 service申请内存，也由 service释放，回调中不应释放。 878 * @param [in] conn_id 连接 ID。 879 * @param [in] rssi rssi。 880 * @param [in] status 执行结果错误码。 881 * @par 依赖: 882 * @li bts_def.h 883 * @see gap_ble_callbacks_t 884 * @endif 885 */ 886 typedef void (*gap_ble_read_rssi_callback)(uint16_t conn_id, int8_t rssi, errcode_t status); 887 888 /** 889 * @if Eng 890 * @brief Callback invoked when authentication complete. 891 * @par Callback invoked when authentication complete. 892 * @attention 1.This function is called in SLE service context,should not be blocked or do long time waiting. 893 * @attention 2.The memories of pointer are requested and freed by the SLE service automatically. 894 * @param [in] conn_id connection ID. 895 * @param [in] addr address. 896 * @param [in] status error code. 897 * @param [in] evt authentication event. 898 * @par Dependency: 899 * @li sle_common.h 900 * @see sle_connection_callbacks_t 901 * @else 902 * @brief 认证完成的回调函数。 903 * @par 认证完成的回调函数。 904 * @attention 1. 该回调函数运行于SLE service线程，不能阻塞或长时间等待。 905 * @attention 2. 指针由SLE service申请内存，也由SLE service释放，回调中不应释放。 906 * @param [in] conn_id 连接 ID。 907 * @param [in] addr 地址。 908 * @param [in] status 执行结果错误码。 909 * @param [in] evt 认证事件。 910 * @par 依赖: 911 * @li sle_common.h 912 * @see sle_connection_callbacks_t 913 * @endif 914 */ 915 typedef void (*gap_ble_auth_complete_callback)(uint16_t conn_id, const bd_addr_t *addr, errcode_t status, 916 const ble_auth_info_evt_t* evt); 917 918 /** 919 * @if Eng 920 * @brief Callback invoked when connect parameter updated. 921 * @par Callback invoked when connect parameter updated. 922 * @attention 1.This function is called in SLE service context, should not be blocked or do long time waiting. 923 * @attention 2.The memories of pointer are requested and freed by the SLE service automatically. 924 * @param [in] conn_id connection ID. 925 * @param [in] status error code. 926 * @param [in] param connection param. 927 * @par Dependency: 928 * @li ble_common.h 929 * @see ble_connection_callbacks_t 930 * @else 931 * @brief 连接参数更新的回调函数。 932 * @par 连接参数更新的回调函数。 933 * @attention 1. 该回调函数运行于BLE service线程，不能阻塞或长时间等待。 934 * @attention 2. 指针由BLE service申请内存，也由BLE service释放，回调中不应释放。 935 * @param [in] conn_id 连接 ID。 936 * @param [in] status 执行结果错误码。 937 * @param [in] param 连接参数。 938 * @par 依赖: 939 * @li sle_common.h 940 * @see sle_connection_callbacks_t 941 * @endif 942 */ 943 typedef void (*gap_ble_connect_param_update_callback)(uint16_t conn_id, errcode_t status, 944 const gap_ble_conn_param_update_t *param); 945 946 /** 947 * @if Eng 948 * @brief Struct of GAP BLE callback function. 949 * @else 950 * @brief GAP BLE回调函数接口定义。 951 * @endif 952 */ 953 typedef struct { 954 gap_ble_enable_callback ble_enable_cb; /*!< @if Eng Ble enable callback 955 @else BLE启动回调函数 @endif */ 956 gap_ble_disable_callback ble_disable_cb; /*!< @if Eng Ble disable callback 957 @else BLE关闭回调函数 @endif */ 958 gap_ble_set_adv_data_callback set_adv_data_cb; /*!< @if Eng Set advertising data callback 959 @else 设置广播数据回调函数 @endif */ 960 gap_ble_set_adv_param_callback set_adv_param_cb; /*!< @if Eng Set advertising parameter callback 961 @else 设置广播参数回调函数 @endif */ 962 gap_ble_set_scan_param_callback set_scan_param_cb; /*!< @if Eng Set scan parameter callback 963 @else 设置扫描参数回调函数 @endif */ 964 gap_ble_start_adv_callback start_adv_cb; /*!< @if Eng Start advertising callback 965 @else 开启广播回调函数 @endif */ 966 gap_ble_stop_adv_callback stop_adv_cb; /*!< @if Eng Stop advertising callback 967 @else 关闭广播回调函数 @endif */ 968 gap_ble_scan_result_callback scan_result_cb; /*!< @if Eng Scan result callback 969 @else 扫描结果回调函数 @endif */ 970 gap_ble_connect_state_changed_callback conn_state_change_cb; /*!< @if Eng Connect state changed callback 971 @else 连接状态改变回调函数 @endif */ 972 gap_ble_paired_complete_callback pair_result_cb; /*!< @if Eng pair complete callback 973 @else 连接状态改变回调函数 @endif */ 974 gap_ble_read_rssi_callback read_rssi_cb; /*!< @if Eng Read rssi callback. 975 @else 读取rssi回调函数。 @endif */ 976 gap_ble_terminate_adv_callback terminate_adv_cb; /*!< @if Eng terminate adv callback 977 @else 被动中止广播回调函数 @endif */ 978 gap_ble_auth_complete_callback auth_complete_cb; /*!< @if Eng authentication complete callback 979 @else 认证完成回调函数 @endif */ 980 gap_ble_connect_param_update_callback conn_param_update_cb; /*!< @if Eng connect param update callback 981 @else 连接参数更新回调函数 @endif */ 982 } gap_ble_callbacks_t; 983 984 /** 985 * @if Eng 986 * @brief Use this funtion to enable BLE. 987 * @par Use this funtion to enable BLE. 988 * @retval error code, ble enable result will be returned at { @ref gap_ble_enable_callback }. 989 * @par Dependency: 990 * @li bts_def.h 991 * @else 992 * @brief 使能BLE协议栈。 993 * @par 使能BLE协议栈。 994 * @retval 执行结果错误码，执行结果将在 { @ref gap_ble_enable_callback }中返回。 995 * @par 依赖: 996 * @li bts_def.h 997 * @endif 998 */ 999 errcode_t enable_ble(void); 1000 1001 /** 1002 * @if Eng 1003 * @brief Use this funtion to disable BLE stack. 1004 * @par Use this funtion to disable BLE stack. 1005 * @retval ERRCODE_SUCC Success. 1006 * @retval Other Failure. For details, see @ref errcode_t 1007 * @par Dependency: 1008 * @li bts_def.h 1009 * @else 1010 * @brief 去使能BLE协议栈。 1011 * @par 去使能BLE协议栈。 1012 * @retval ERRCODE_SUCC 成功。 1013 * @retval Other 失败。参考 @ref errcode_t 1014 * @par 依赖: 1015 * @li bts_def.h 1016 * @endif 1017 */ 1018 errcode_t disable_ble(void); 1019 1020 /** 1021 * @if Eng 1022 * @brief Use this funtion to set local device address. 1023 * @par Use this funtion to set local device address. 1024 * @param [in] addr local device address. 1025 * @retval ERRCODE_SUCC Success. 1026 * @retval Other Failure. For details, see @ref errcode_t 1027 * @par Dependency: 1028 * @li bts_def.h 1029 * @else 1030 * @brief 设置本地设备地址。 1031 * @par 设置本地设备地址。 1032 * @param [in] addr 本地设备地址。 1033 * @retval ERRCODE_SUCC 成功。 1034 * @retval Other 失败。参考 @ref errcode_t 1035 * @par 依赖: 1036 * @li bts_def.h 1037 * @endif 1038 */ 1039 errcode_t gap_ble_set_local_addr(const bd_addr_t *addr); 1040 1041 /** 1042 * @if Eng 1043 * @brief Use this funtion to get local device address. 1044 * @par Use this funtion to get local device address. 1045 * @param [out] addr local device address 1046 * @retval ERRCODE_SUCC Success. 1047 * @retval Other Failure. For details, see @ref errcode_t 1048 * @par Dependency: 1049 * @li bts_def.h 1050 * @else 1051 * @brief 获取本地设备地址。 1052 * @par 获取本地设备地址。 1053 * @param [out] addr 本地设备地址 1054 * @retval ERRCODE_SUCC 成功。 1055 * @retval Other 失败。参考 @ref errcode_t 1056 * @par 依赖: 1057 * @li bts_def.h 1058 * @endif 1059 */ 1060 errcode_t gap_ble_get_local_addr(bd_addr_t *addr); 1061 1062 /** 1063 * @if Eng 1064 * @brief Use this funtion to set local device appearance. 1065 * @par Use this funtion to set local device appearance. 1066 * @param [in] appearance local device appearance { @ref gap_ble_appearance_type_t }. 1067 * @retval ERRCODE_SUCC Success. 1068 * @retval Other Failure. For details, see @ref errcode_t 1069 * @par Dependency: 1070 * @li bts_def.h 1071 * @else 1072 * @brief 设置本地设备地址。 1073 * @par 设置本地设备地址。 1074 * @retval ERRCODE_SUCC 成功。 1075 * @retval Other 失败。参考 @ref errcode_t 1076 * @par 依赖: 1077 * @li bts_def.h 1078 * @endif 1079 */ 1080 errcode_t gap_ble_set_local_appearance(uint16_t appearance); 1081 1082 /** 1083 * @if Eng 1084 * @brief Use this funtion to set local device name. 1085 * @par Use this funtion to set local device name. 1086 * @param [out] name the name of local host bluetooth device. 1087 * @param [in] len the length of device name, including the endding 0. 1088 * @retval ERRCODE_SUCC Success. 1089 * @retval Other Failure. For details, see @ref errcode_t 1090 * @par Dependency: 1091 * @li bts_def.h 1092 * @else 1093 * @brief 设置本地设备名称。 1094 * @par 设置本地设备名称。 1095 * @param [out] name 设备名称。 1096 * @param [in] len 名称长度，包括结束符\0。 1097 * @retval ERRCODE_SUCC 成功。 1098 * @retval Other 失败。参考 @ref errcode_t 1099 * @par 依赖: 1100 * @li bts_def.h 1101 * @endif 1102 */ 1103 errcode_t gap_ble_set_local_name(const uint8_t *name, const uint8_t len); 1104 1105 /** 1106 * @if Eng 1107 * @brief Use this funtion to get local device name. 1108 * @par Use this funtion to get local device name. 1109 * @param [out] name local device name. 1110 * @param [inout] len as input parameter, the buffer size of user, 1111 as output parameter, the length of local device name. 1112 * @retval error code 1113 * @par Dependency: 1114 * @li bts_def.h 1115 * @else 1116 * @brief 获取本地设备名称。 1117 * @par 获取本地设备名称。 1118 * @param [out] name 本地设备名称。 1119 * @param [inout] len 作为入参时为用户分配的内存大小，作为出参时为本地设备名称长度。 1120 * @retval 执行结果错误码 1121 * @par 依赖: 1122 * @li bts_def.h 1123 * @endif 1124 */ 1125 errcode_t gap_ble_get_local_name(uint8_t *name, uint8_t *len); 1126 1127 /** 1128 * @if Eng 1129 * @brief Use this funtion to set advertising data. 1130 * @par Use this funtion to set advertising data 1131 * @param [in] adv_id advertising ID 1132 * @param [in] data a pointer to the advertising data 1133 * @retval error code, the data set result will be returned at { @ref gap_ble_set_adv_data_callback }. 1134 * @par Dependency: 1135 * @li bts_def.h 1136 * @else 1137 * @brief 设置广播数据。 1138 * @par 设置广播数据。 1139 * @param [in] adv_id 广播ID 1140 * @param [in] data 广播数据 1141 * @retval 执行结果错误码，数据设置状态将在 { @ref gap_ble_set_adv_data_callback }中返回。 1142 * @par 依赖: 1143 * @li bts_def.h 1144 * @endif 1145 */ 1146 errcode_t gap_ble_set_adv_data(uint8_t adv_id, const gap_ble_config_adv_data_t *data); 1147 1148 /** 1149 * @if Eng 1150 * @brief Use this funtion to set advertising parameter. 1151 * @par Use this funtion to set advertising parameter. 1152 * @param [in] adv_id advertising ID. 1153 * @param [in] param a pointer to the advertising parameter. 1154 * @retval error code, the parameter set result will be returned at { @ref gap_ble_set_adv_param_callback }. 1155 * @par Dependency: 1156 * @li bts_def.h 1157 * @else 1158 * @brief 设置广播参数。 1159 * @par 设置广播参数。 1160 * @param [in] adv_id 广播ID 1161 * @param [in] param 广播参数 1162 * @retval 执行结果错误码，参数设置状态将在 { @ref gap_ble_set_adv_param_callback }中返回。 1163 * @par 依赖: 1164 * @li bts_def.h 1165 * @endif 1166 */ 1167 errcode_t gap_ble_set_adv_param(uint8_t adv_id, const gap_ble_adv_params_t *param); 1168 1169 /** 1170 * @if Eng 1171 * @brief Use this funtion to start advertising. 1172 * @par Use this funtion to start advertising 1173 * @param [in] adv_id advertising ID 1174 * @retval error code, the advertising status will be returned in { @ref gap_ble_start_adv_callback }. 1175 * @par Dependency: 1176 * @li bts_def.h 1177 * @else 1178 * @brief 开始发送广播。 1179 * @par 开始发送广播。 1180 * @param [in] adv_id 广播ID 1181 * @retval 执行结果错误码，广播状态将在 { @ref gap_ble_start_adv_callback } 中返回。 1182 * @par 依赖: 1183 * @li bts_def.h 1184 * @endif 1185 */ 1186 errcode_t gap_ble_start_adv(uint8_t adv_id); 1187 1188 /** 1189 * @if Eng 1190 * @brief Use this funtion to stop advertising. 1191 * @par Use this funtion to stop advertising 1192 * @param [in] adv_id advertising ID 1193 * @retval error code, the advertising status will be returned in { @ref gap_ble_stop_adv_callback }. 1194 * @par Dependency: 1195 * @li bts_def.h 1196 * @else 1197 * @brief 停止发送广播。 1198 * @par 停止发送广播。 1199 * @param [in] adv_id 广播ID 1200 * @retval 执行结果错误码，广播状态将在 { @ref gap_ble_stop_adv_callback } 中返回。 1201 * @par 依赖: 1202 * @li bts_def.h 1203 * @endif 1204 */ 1205 errcode_t gap_ble_stop_adv(uint8_t adv_id); 1206 1207 /** 1208 * @if Eng 1209 * @brief Use this funtion to set scan parameter. 1210 * @par Use this funtion to set scan parameter. 1211 * @param [in] param scan parameter. 1212 * @retval error code, the parameter set status will be returned in { @ref gap_ble_set_scan_param_callback }. 1213 * @par Dependency: 1214 * @li bts_def.h 1215 * @else 1216 * @brief 设置扫描参数。 1217 * @par 设置扫描参数。 1218 * @param [in] param 扫描参数。 1219 * @retval 执行结果错误码，参数设置状态将在 { @ref gap_ble_set_scan_param_callback }中返回。 1220 * @par 依赖: 1221 * @li bts_def.h 1222 * @endif 1223 */ 1224 errcode_t gap_ble_set_scan_parameters(const gap_ble_scan_params_t *param); 1225 1226 /** 1227 * @if Eng 1228 * @brief Use this funtion to set scan extended parameters. 1229 * @par Use this funtion to set scan extended parameters. 1230 * @param [in] param scan extended parameters. 1231 * @retval error code. 1232 * @par Dependency: 1233 * @li bts_def.h 1234 * @else 1235 * @brief 设置扫描扩展参数。 1236 * @par 设置扫描扩展参数。 1237 * @param [in] param 扫描扩展参数。 1238 * @retval 执行结果错误码。 1239 * @par 依赖: 1240 * @li bts_def.h 1241 * @endif 1242 */ 1243 errcode_t gap_ble_set_scan_extern_parameters(const gap_ble_extern_scan_params_t *param); 1244 1245 /** 1246 * @if Eng 1247 * @brief Use this funtion to start scan. 1248 * @par Use this funtion to start scan. 1249 * @retval error code, the scan result will be returned at { @ref gap_ble_scan_result_callback }. 1250 * @par Dependency: 1251 * @li bts_def.h 1252 * @else 1253 * @brief 开始扫描。 1254 * @par 开始扫描。 1255 * @retval 执行结果错误码，扫描结果将在 { @ref gap_ble_scan_result_callback }。 1256 * @par 依赖: 1257 * @li bts_def.h 1258 * @endif 1259 */ 1260 errcode_t gap_ble_start_scan(void); 1261 1262 /** 1263 * @if Eng 1264 * @brief Use this funtion to stop scan. 1265 * @par Use this funtion to stop scan. 1266 * @retval ERRCODE_SUCC Success. 1267 * @retval Other Failure. For details, see @ref errcode_t 1268 * @par Dependency: 1269 * @li bts_def.h 1270 * @else 1271 * @brief 停止扫描。 1272 * @par 停止扫描。 1273 * @retval ERRCODE_SUCC 成功。 1274 * @retval Other 失败。参考 @ref errcode_t 1275 * @par 依赖: 1276 * @li bts_def.h 1277 * @endif 1278 */ 1279 errcode_t gap_ble_stop_scan(void); 1280 1281 /** 1282 * @if Eng 1283 * @brief Use this funtion to set the BLE PHY parameters. 1284 * @par Use this funtion to set the BLE PHY parameters. 1285 * @param [in] param BLE PHY parameters. 1286 * @retval ERRCODE_SUCC Success. 1287 * @retval Other Failure. For details, see @ref errcode_t 1288 * @par Dependency: 1289 * @li bts_def.h 1290 * @else 1291 * @brief 设置BLE PHY参数。 1292 * @par 设置BLE PHY参数。 1293 * @param [in] param BLE PHY参数。 1294 * @retval ERRCODE_SUCC 成功。 1295 * @retval Other 失败。参考 @ref errcode_t 1296 * @par 依赖: 1297 * @li bts_def.h 1298 * @endif 1299 */ 1300 errcode_t gap_ble_set_phy(gap_le_set_phy_t *param); 1301 1302 /** 1303 * @if Eng 1304 * @brief Use this funtion to set the BLE packet transmission parameters. 1305 * @par Use this funtion to set the BLE packet transmission parameters. 1306 * @param [in] param BLE packet transmission parameters. 1307 * @retval ERRCODE_SUCC Success. 1308 * @retval Other Failure. For details, see @ref errcode_t 1309 * @par Dependency: 1310 * @li bts_def.h 1311 * @else 1312 * @brief 设置BLE发包参数。 1313 * @par 设置BLE发包参数。 1314 * @param [in] param BLE发包参数。 1315 * @retval ERRCODE_SUCC 成功。 1316 * @retval Other 失败。参考 @ref errcode_t 1317 * @par 依赖: 1318 * @li bts_def.h 1319 * @endif 1320 */ 1321 errcode_t gap_ble_set_data_length(gap_le_set_data_length_t *param); 1322 1323 /** 1324 * @if Eng 1325 * @brief Use this funtion to start pairing. 1326 * @par Use this funtion to start pairing. 1327 * @param [out] addr the list of paired devices address. 1328 * @retval ERRCODE_SUCC Success. 1329 * @retval Other Failure. For details, see @ref errcode_t 1330 * @par Dependency: 1331 * @li bts_def.h 1332 * @else 1333 * @brief 启动配对。 1334 * @par 启动配对。 1335 * @param [out] addr 配对设备地址链表。 1336 * @retval ERRCODE_SUCC 成功。 1337 * @retval Other 失败。参考 @ref errcode_t 1338 * @par 依赖: 1339 * @li bts_def.h 1340 * @endif 1341 */ 1342 errcode_t gap_ble_pair_remote_device(const bd_addr_t *addr); 1343 1344 /** 1345 * @if Eng 1346 * @brief Use this funtion to get the number of paired devices. 1347 * @par Use this funtion to get the number of paired devices. 1348 * @param [out] number number of paired devices. 1349 * @retval ERRCODE_SUCC Success. 1350 * @retval Other Failure. For details, see @ref errcode_t 1351 * @par Dependency: 1352 * @li bts_def.h 1353 * @else 1354 * @brief 获取配对设备数量。 1355 * @par 获取配对设备数量。 1356 * @param [out] number 配对设备数量。 1357 * @retval ERRCODE_SUCC 成功。 1358 * @retval Other 失败。参考 @ref errcode_t 1359 * @par 依赖: 1360 * @li bts_def.h 1361 * @endif 1362 */ 1363 errcode_t gap_ble_get_paired_devices_num(uint16_t *number); 1364 1365 /** 1366 * @if Eng 1367 * @brief Use this funtion to get the number of paired devices. 1368 * @par Use this funtion to get the number of paired devices. 1369 * @param [out] addr the list of paired devices address. 1370 * @param [inout] number as input parameter, the buffer size of user, 1371 as output parameter, the number of paired devices. 1372 * @retval ERRCODE_SUCC Success. 1373 * @retval Other Failure. For details, see @ref errcode_t 1374 * @par Dependency: 1375 * @li bts_def.h 1376 * @else 1377 * @brief 获取配对设备数量。 1378 * @par 获取配对设备数量。 1379 * @param [out] addr 配对设备地址链表。 1380 * @param [inout] number 作为入参时为用户分配的内存大小，作为出参时为配对设备数量。 1381 * @retval ERRCODE_SUCC 成功。 1382 * @retval Other 失败。参考 @ref errcode_t 1383 * @par 依赖: 1384 * @li bts_def.h 1385 * @endif 1386 */ 1387 errcode_t gap_ble_get_paired_devices(bd_addr_t *addr, uint16_t *number); 1388 1389 /** 1390 * @if Eng 1391 * @brief Use this funtion to get the pairing state of a specific device. 1392 * @par Use this funtion to get the pairing state of a specific device. 1393 * @param [in] addr address of the device. 1394 * @param [out] status status of the device. 1395 * @retval pair state 1396 * @par Dependency: 1397 * @li bts_def.h 1398 * @else 1399 * @brief 获取设备的配对状态。 1400 * @par 获取设备的配对状态。 1401 * @param [in] addr 待查询的设备地址。 1402 * @param [out] status 配对设备状态. 1403 * @retval 配对状态。 1404 * @par 依赖: 1405 * @li bts_def.h 1406 * @endif 1407 */ 1408 errcode_t gap_ble_get_pair_state(const bd_addr_t *addr, gap_ble_pair_state_t *status); 1409 1410 /** 1411 * @if Eng 1412 * @brief Use this funtion to remove pair of remote device. 1413 * @par Use this funtion to remove pair of remote device. 1414 * @param [in] addr address of the remote device. 1415 * @retval error code 1416 * @par Dependency: 1417 * @li bts_def.h 1418 * @else 1419 * @brief 与指定设备取消配对。 1420 * @par 与指定设备取消配对。 1421 * @param [in] addr 对端设备地址。 1422 * @retval ERRCODE_SUCC 成功。 1423 * @retval Other 失败。参考 @ref errcode_t 1424 * @par 依赖: 1425 * @li bts_def.h 1426 * @endif 1427 */ 1428 errcode_t gap_ble_remove_pair(const bd_addr_t *addr); 1429 1430 /** 1431 * @if Eng 1432 * @brief Use this funtion to remove all paired devices from the paired list. 1433 * @par Use this funtion to remove all paired devices from the paired list. 1434 * @retval ERRCODE_SUCC Success. 1435 * @retval Other Failure. For details, see @ref errcode_t 1436 * @par Dependency: 1437 * @li bts_def.h 1438 * @else 1439 * @brief 删除所有BLE配对设备。 1440 * @par 删除所有BLE配对设备。 1441 * @retval ERRCODE_SUCC 成功。 1442 * @retval Other 失败。参考 @ref errcode_t 1443 * @par 依赖: 1444 * @li bts_def.h 1445 * @endif 1446 */ 1447 errcode_t gap_ble_remove_all_pairs(void); 1448 1449 /** 1450 * @if Eng 1451 * @brief Use this funtion to get the bonded state of a specific device. 1452 * @par Use this funtion to get the bonded state of a specific device. 1453 * @attention NULL 1454 * @param [out] addr the list of paired devices address. 1455 * @param [inout] number as input parameter, the buffer size of user, 1456 as output parameter, the number of paired devices. 1457 * @retval error code. 1458 * @par Dependency: 1459 * @li bts_def.h 1460 * @else 1461 * @brief 获取本端设备的已绑定设备。 1462 * @par 获取本端设备的已绑定设备。 1463 * @attention 无 1464 * @param [out] addr 绑定设备地址链表。 1465 * @param [inout] number 作为入参时为用户分配的内存大小，作为出参时为绑定设备数量。 1466 * @retval 执行结果错误码。 1467 * @par 依赖: 1468 * @li bts_def.h 1469 * @endif 1470 */ 1471 errcode_t gap_ble_get_bonded_devices(bd_addr_t *addr, uint16_t *number); 1472 1473 /** 1474 * @if Eng 1475 * @brief Use this funtion to update ble connect param. 1476 * @par 1477 * @param [in] params user set connect param in it. 1478 * @retval ERRCODE_SUCC Success. 1479 * @retval Other Failure. For details, see @ref errcode_t 1480 * @par Dependency: 1481 * @li bts_def.h 1482 * @else 1483 * @brief ble连接参数更新 1484 * @par 1485 * @param [in] params 待更新连接参数。 1486 * @retval ERRCODE_SUCC 成功。 1487 * @retval Other 失败。参考 @ref errcode_t 1488 * @par 依赖: 1489 * @li bts_def.h 1490 * @endif 1491 */ 1492 errcode_t gap_ble_connect_param_update(gap_conn_param_update_t *params); 1493 1494 /** 1495 * @if Eng 1496 * @brief Use this funtion to connect to a remote device. 1497 * @par Use this funtion to establish an ACL connection with a remote device. 1498 * @param [in] addr address of the remote device. 1499 * @retval error code, the connect status will be returned at { @ref gap_ble_connect_state_changed_callback }. 1500 * @par Dependency: 1501 * @li bts_def.h 1502 * @else 1503 * @brief 与设备建立连接。 1504 * @par 与设备建立ACL连接。 1505 * @param [in] addr 待连接的设备地址。 1506 * @retval 执行结果错误码，连接状态将在{ @ref gap_ble_connect_state_changed_callback }中返回。 1507 * @par 依赖: 1508 * @li bts_def.h 1509 * @endif 1510 */ 1511 errcode_t gap_ble_connect_remote_device(const bd_addr_t *addr); 1512 1513 /** 1514 * @if Eng 1515 * @brief Use this funtion to disconnect from a remote device. 1516 * @par Use this funtion to disconnect all profiles from a remote device. 1517 * @param [in] addr address of the remote device. 1518 * @retval error code, the connect status will be returned at { @ref gap_ble_connect_state_changed_callback }. 1519 * @par Dependency: 1520 * @li bts_def.h 1521 * @else 1522 * @brief 断开设备连接。 1523 * @par 断开设备连接，包括所有profile连接。 1524 * @param [in] addr 待断开的设备地址。 1525 * @retval 执行结果错误码，连接状态将在{ @ref gap_ble_connect_state_changed_callback }中返回。 1526 * @par 依赖: 1527 * @li bts_def.h 1528 * @endif 1529 */ 1530 errcode_t gap_ble_disconnect_remote_device(const bd_addr_t *addr); 1531 1532 /** 1533 * @if Eng 1534 * @brief Use this funtion to set security parameter. 1535 * @par Use this funtion to set security parameter. 1536 * @param [in] params a pointer to the security parameter. 1537 * @retval NULL。 1538 * @par Dependency: 1539 * @li bts_def.h 1540 * @else 1541 * @brief 设置安全参数。 1542 * @par 设置安全参数。 1543 * @param [in] params 安全参数 1544 * @retval 无回调函数。 1545 * @par 依赖: 1546 * @li bts_def.h 1547 * @endif 1548 */ 1549 errcode_t gap_ble_set_sec_param(gap_ble_sec_params_t *params); 1550 1551 /** 1552 * @if Eng 1553 * @brief Use this funtion to read rssi of remote device. 1554 * @par Use this funtion to read rssi of remote device by connect id. 1555 * @param [in] conn_id id. 1556 * @retval error code, the rssi result will be returned at { @ref gap_ble_read_rssi_callback }. 1557 * @par Dependency: 1558 * @li bts_def.h 1559 * @else 1560 * @brief 读对端rssi值 1561 * @par 通过连接ID读对端rssi 1562 * @param [in] conn_id 连接ID。 1563 * @retval 执行结果错误码，rssi 结果将在{ @ref gap_ble_read_rssi_callback }中返回。 1564 * @par 依赖: 1565 * @li bts_def.h 1566 * @endif 1567 */ 1568 errcode_t gap_ble_read_remote_device_rssi(uint16_t conn_id); 1569 1570 /** 1571 * @if Eng 1572 * @brief Use this funtion to register callback function of gap 1573 * @par Use this funtion to register callback function of gap 1574 * @param [in] func gap_ble_callbacks_t *, a pointer to the callback functions. 1575 * @retval ERRCODE_SUCC Success. 1576 * @retval Other Failure. For details, see @ref errcode_t 1577 * @par Dependency: 1578 * @li bts_def.h 1579 * @else 1580 * @brief 注册ble gap回调函数。 1581 * @par 注册ble gap回调函数。 1582 * @param [in] func 指向回调函数接口定义的指针 1583 * @retval ERRCODE_SUCC 成功。 1584 * @retval Other 失败。参考 @ref errcode_t 1585 * @par 依赖: 1586 * @li bts_def.h 1587 * @endif 1588 */ 1589 errcode_t gap_ble_register_callbacks(gap_ble_callbacks_t *func); 1590 1591 /** 1592 * @if Eng 1593 * @brief Use this funtion to initializes bth ota channel. 1594 * @par Use this funtion to initializes bth ota channel. 1595 * @retval ERRCODE_SUCC Success. 1596 * @retval Other Failure. For details, see @ref errcode_t 1597 * @par Dependency: 1598 * @li bts_def.h 1599 * @else 1600 * @brief 初始化bth ota通道。 1601 * @par 初始化bth ota通道。 1602 * @retval ERRCODE_SUCC 成功。 1603 * @retval Other 失败。参考 @ref errcode_t 1604 * @par 依赖: 1605 * @li bts_def.h 1606 * @endif 1607 */ 1608 errcode_t bth_ota_init(void); 1609 1610 /** 1611 * @if Eng 1612 * @brief Use this funtion to config customize information. 1613 * @par Use this funtion to config customize information. 1614 * @param [in] ble_pwr ble max power. 1615 * @param [in] sle_pwr sle max power. 1616 * @retval ERRCODE_SUCC Success. 1617 * @retval Other Failure. For details, see @ref errcode_t 1618 * @par Dependency: 1619 * @li nv_common.h 1620 * @else 1621 * @brief 配置定制化信息 1622 * @par 配置定制化信息 1623 * @param [in] ble_pwr ble 最大功率. 1624 * @param [in] sle_pwr sle 最大功率. 1625 * @retval ERRCODE_SUCC 成功。 1626 * @retval Other 失败。参考 @ref errcode_t 1627 * @par 依赖: 1628 * @li bt_data_config.h 1629 * @endif 1630 */ 1631 errcode_t ble_customize_max_pwr(int8_t ble_pwr, int8_t sle_pwr); 1632 1633 /** 1634 * @} 1635 */ 1636 1637 #ifdef __cplusplus 1638 } 1639 #endif 1640 #endif 1641 1642