1 /** 2 **************************************************************************************** 3 * 4 * @file ble_gapm.h 5 * 6 * @brief BLE GAPM 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 #ifndef __BLE_GAPM_H__ 51 #define __BLE_GAPM_H__ 52 53 /* 54 * INCLUDE FILES 55 **************************************************************************************** 56 */ 57 #include <stdint.h> // standard definitions 58 #include "ble_gapc.h" 59 60 /** 61 @addtogroup BLE_GAPM Generic Access Profile (GAP) Management 62 @{ 63 @brief Definitions and prototypes for the GAP Management interface. 64 */ 65 66 #define CO_BIT(pos) (1UL << (pos)) /**< Bit operation helper. */ 67 #define MAX_ADV_NUM 5 /**< Maximal advertising instance number. */ 68 #define MAX_PER_SYNC_NUM 5 /**< Maximal periodic syncronization instance number. */ 69 #define MAX_BOND_NUM 10 /**< Maximal bonding number. */ 70 #define MAX_WL_NUM 10 /**< Maximal white list number. */ 71 72 #define MAX_PRD_ADV_NUM 4 /**< Maximal periodic advertising list number. */ 73 #define MAX_KEY_LEN 16 /**< The key length. */ 74 #define INVALID_ADV_IDX 0xFF /**< Invalid adv index. */ 75 #define BLE_GAP_DEVNAME_DEFAULT "GOODIX_BLE" /**< Default device name value. */ 76 #define BLE_GAP_DEVNAME_MAX_LEN 248 /**< Maximal length of device name. */ 77 78 #define BLE_APPEARANCE_UNKNOWN 0 /**< Unknown. */ 79 #define BLE_APPEARANCE_GENERIC_PHONE 64 /**< Generic Phone. */ 80 #define BLE_APPEARANCE_GENERIC_COMPUTER 128 /**< Generic Computer. */ 81 #define BLE_APPEARANCE_GENERIC_WATCH 192 /**< Generic Watch. */ 82 #define BLE_APPEARANCE_WATCH_SPORTS_WATCH 193 /**< Watch: Sports Watch. */ 83 #define BLE_APPEARANCE_GENERIC_CLOCK 256 /**< Generic Clock. */ 84 #define BLE_APPEARANCE_GENERIC_DISPLAY 320 /**< Generic Display. */ 85 #define BLE_APPEARANCE_GENERIC_REMOTE_CONTROL 384 /**< Generic Remote Control. */ 86 #define BLE_APPEARANCE_GENERIC_EYE_GLASSES 448 /**< Generic Eye-glasses. */ 87 #define BLE_APPEARANCE_GENERIC_TAG 512 /**< Generic Tag. */ 88 #define BLE_APPEARANCE_GENERIC_KEYRING 576 /**< Generic Keyring. */ 89 #define BLE_APPEARANCE_GENERIC_MEDIA_PLAYER 640 /**< Generic Media Player. */ 90 #define BLE_APPEARANCE_GENERIC_BARCODE_SCANNER 704 /**< Generic Barcode Scanner. */ 91 #define BLE_APPEARANCE_GENERIC_THERMOMETER 768 /**< Generic Thermometer. */ 92 #define BLE_APPEARANCE_THERMOMETER_EAR 769 /**< Thermometer: Ear. */ 93 #define BLE_APPEARANCE_GENERIC_HEART_RATE_SENSOR 832 /**< Generic Heart Rate Sensor. */ 94 #define BLE_APPEARANCE_HEART_RATE_SENSOR_HEART_RATE_BELT 833 /**< Heart Rate Sensor: Heart Rate Belt. */ 95 #define BLE_APPEARANCE_GENERIC_BLOOD_PRESSURE 896 /**< Generic Blood Pressure. */ 96 #define BLE_APPEARANCE_BLOOD_PRESSURE_ARM 897 /**< Blood Pressure: Arm. */ 97 #define BLE_APPEARANCE_BLOOD_PRESSURE_WRIST 898 /**< Blood Pressure: Wrist. */ 98 #define BLE_APPEARANCE_GENERIC_HID 960 /**< Human Interface Device (HID). */ 99 #define BLE_APPEARANCE_HID_KEYBOARD 961 /**< Keyboard (HID Subtype). */ 100 #define BLE_APPEARANCE_HID_MOUSE 962 /**< Mouse (HID Subtype). */ 101 #define BLE_APPEARANCE_HID_JOYSTICK 963 /**< Joystick (HID Subtype). */ 102 #define BLE_APPEARANCE_HID_GAMEPAD 964 /**< Gamepad (HID Subtype). */ 103 #define BLE_APPEARANCE_HID_DIGITIZERSUBTYPE 965 /**< Digitizer Tablet (HID Subtype). */ 104 #define BLE_APPEARANCE_HID_CARD_READER 966 /**< Card Reader (HID Subtype). */ 105 #define BLE_APPEARANCE_HID_DIGITAL_PEN 967 /**< Digital Pen (HID Subtype). */ 106 #define BLE_APPEARANCE_HID_BARCODE 968 /**< Barcode Scanner (HID Subtype). */ 107 #define BLE_APPEARANCE_GENERIC_GLUCOSE_METER 1024 /**< Generic Glucose Meter. */ 108 #define BLE_APPEARANCE_GENERIC_RUNNING_WALKING_SENSOR 1088 /**< Generic Running Walking Sensor. */ 109 #define BLE_APPEARANCE_RUNNING_WALKING_SENSOR_IN_SHOE 1089 /**< Running Walking Sensor: In-Shoe. */ 110 #define BLE_APPEARANCE_RUNNING_WALKING_SENSOR_ON_SHOE 1090 /**< Running Walking Sensor: On-Shoe. */ 111 #define BLE_APPEARANCE_RUNNING_WALKING_SENSOR_ON_HIP 1091 /**< Running Walking Sensor: On-Hip. */ 112 #define BLE_APPEARANCE_GENERIC_CYCLING 1152 /**< Generic Cycling. */ 113 #define BLE_APPEARANCE_CYCLING_CYCLING_COMPUTER 1153 /**< Cycling: Cycling Computer. */ 114 #define BLE_APPEARANCE_CYCLING_SPEED_SENSOR 1154 /**< Cycling: Speed Sensor. */ 115 #define BLE_APPEARANCE_CYCLING_CADENCE_SENSOR 1155 /**< Cycling: Cadence Sensor. */ 116 #define BLE_APPEARANCE_CYCLING_POWER_SENSOR 1156 /**< Cycling: Power Sensor. */ 117 #define BLE_APPEARANCE_CYCLING_SPEED_CADENCE_SENSOR 1157 /**< Cycling: Speed and Cadence Sensor. */ 118 #define BLE_APPEARANCE_GENERIC_PULSE_OXIMETER 3136 /**< Generic Pulse Oximeter. */ 119 #define BLE_APPEARANCE_PULSE_OXIMETER_FINGERTIP 3137 /**< Fingertip (Pulse Oximeter subtype). */ 120 #define BLE_APPEARANCE_PULSE_OXIMETER_WRIST_WORN 3138 /**< Wrist Worn(Pulse Oximeter subtype). */ 121 #define BLE_APPEARANCE_GENERIC_WEIGHT_SCALE 3200 /**< Generic Weight Scale. */ 122 #define BLE_APPEARANCE_GENERIC_OUTDOOR_SPORTS_ACT 5184 /**< Generic Outdoor Sports Event. */ 123 #define BLE_APPEARANCE_OUTDOOR_SPORTS_ACT_LOC_DISP 5185 /**< Location Display Device 124 (Outdoor Sports Event subtype). */ 125 #define BLE_APPEARANCE_OUTDOOR_SPORTS_ACT_LOC_AND_NAV_DISP 5186 /**< Location and Navigation Display Device 126 (Outdoor Sports Event subtype). */ 127 #define BLE_APPEARANCE_OUTDOOR_SPORTS_ACT_LOC_POD 5187 /**< Location Pod (Outdoor Sports 128 Event subtype). */ 129 #define BLE_APPEARANCE_OUTDOOR_SPORTS_ACT_LOC_AND_NAV_POD 5188 /**< Location and Navigation Pod (Outdoor Sports 130 Event subtype). */ 131 132 /** @defgroup BLE_GAP_PHYS GAP PHYs (bitmask) 133 * @{ */ 134 #define BLE_GAP_PHY_ANY 0x00 /**< No preferred PHY. */ 135 #define BLE_GAP_PHY_LE_1MBPS (1 << 0) /**< LE 1M PHY preferred for an active link. */ 136 #define BLE_GAP_PHY_LE_2MBPS (1 << 1) /**< LE 2M PHY preferred for an active link. */ 137 #define BLE_GAP_PHY_LE_CODED (1 << 2) /**< LE Coded PHY preferred for an active link. */ 138 /** @} */ 139 140 141 /** @defgroup BLE_GAP_ADV_CHANNEL GAP ADV CHANNEL (bitmask) 142 * @{ */ 143 #define GAP_ADV_CHANNEL_37 0x01 /**< Advertising Channel 37 (2402MHz). */ 144 #define GAP_ADV_CHANNEL_38 0x02 /**< Advertising Channel 38 (2426MHz). */ 145 #define GAP_ADV_CHANNEL_39 0x04 /**< Advertising Channel 39 (2480MHz). */ 146 #define GAP_ADV_CHANNEL_37_38_39 0x07 /**< Advertising Channel 37, 38, 39. */ 147 /** @} */ 148 /** @} */ 149 150 /** @addtogroup BLE_GAPM_ENUMERATIONS Enumerations 151 * @{ */ 152 /** 153 * @brief GAP role options 154 */ 155 typedef enum { 156 BLE_GAP_ROLE_NONE = 0x00, /**< No role set yet. */ 157 BLE_GAP_ROLE_OBSERVER = 0x01, /**< Observer role. */ 158 BLE_GAP_ROLE_BROADCASTER = 0x02, /**< Broadcaster role. */ 159 BLE_GAP_ROLE_CENTRAL = (0x04 | BLE_GAP_ROLE_OBSERVER), /**< Master/Central role. */ 160 BLE_GAP_ROLE_PERIPHERAL = (0x08 | BLE_GAP_ROLE_BROADCASTER), /**< Peripheral/Slave role. */ 161 BLE_GAP_ROLE_ALL = (BLE_GAP_ROLE_CENTRAL | BLE_GAP_ROLE_PERIPHERAL), /**< Device has all roles, 162 both peripheral and central. */ 163 } gap_role_t; 164 165 /** 166 * @brief Own BD address source of the device 167 */ 168 typedef enum { 169 BLE_GAP_OWN_ADDR_STATIC = 0, /**< Public or Private Static Address according to device address configuration. */ 170 BLE_GAP_OWN_ADDR_GEN_RSLV, /**< Generated resolvable private random address. */ 171 BLE_GAP_OWN_ADDR_GEN_NON_RSLV, /**< Generated non-resolvable private random address. */ 172 } gap_own_addr_t; 173 174 /** 175 * @brief Write permissions of the device name characteristic 176 */ 177 typedef enum { 178 BLE_GAP_WRITE_PERM_DISABLE = 0, /**< Disable write access. */ 179 BLE_GAP_WRITE_PERM_NOAUTH, /**< LE Security Mode 1, Level 1. 180 Link does not need to be encrypted or authenticated. */ 181 BLE_GAP_WRITE_PERM_UNAUTH, /**< LE Security Mode 1, Level 2. 182 Link needs to be encrypted, but not to be authenticated. */ 183 BLE_GAP_WRITE_PERM_AUTH, /**< LE Security Mode 1, Level 3. 184 Link needs to be encrypted and authenticated (MITM). */ 185 BLE_GAP_WRITE_PERM_SEC_CON, /**< LE Security Mode 1, Level 4. 186 Link needs to be encrypted and authenticated (secure connections). */ 187 } gap_dev_name_write_perm_t; 188 189 /** 190 * @brief Advertising data type 191 */ 192 typedef enum { 193 BLE_GAP_ADV_DATA_TYPE_DATA = 0, /**< Advertising data. */ 194 BLE_GAP_ADV_DATA_TYPE_SCAN_RSP, /**< Scan response data. */ 195 BLE_GAP_ADV_DATA_TYPE_PER_DATA, /**< Periodic advertising data. */ 196 } gap_adv_data_type_t; 197 198 199 /** @brief Get device parameters operation code. */ 200 typedef enum { 201 BLE_GAP_GET_DEV_VERSION = 0, /**< Get version information for the local Controller. */ 202 BLE_GAP_GET_DEV_BDADDR, /**< Get local device BD Address. */ 203 // BLE_GAP_GET_DEV_ADV_TX_POWER, /**< Get the transmit power level used for LE advertising channel packets. */ 204 BLE_GAP_GET_SUGGESTED_DFLT_LE_DATA_LEN, /**< Get suggested values (SuggestedMaxTxOctets and SuggestedMaxTxTime) 205 for the Controller's maximum transmitted number of payload octets 206 and maximum packet transmission time to be used for new connections. */ 207 BLE_GAP_GET_MAX_LE_DATA_LEN, /**< Get the Controller' maximum supported payload octets and packet 208 duration times for transmission and reception (supportedMaxTxOctets 209 and supportedMaxTxTime, supportedMaxRxOctets, 210 and supportedMaxRxTime). */ 211 BLE_GAP_GET_NB_ADV_SETS, /**< Read the maximum number of advertising sets currently supported 212 by the controller. */ 213 BLE_GAP_GET_MAX_LE_ADV_DATA_LEN, /**< Get maximum data length for advertising data. */ 214 BLE_GAP_GET_DEV_TX_POWER, /**< Read the minimum and maximum transmit powers supported by the 215 Controller. */ 216 BLE_GAP_GET_DEV_RF_RF_PATH_COMP, /**< Get RF path compensation values. */ 217 } gap_dev_info_get_type_t; 218 219 /** @brief GAP advertising modes. */ 220 typedef enum { 221 GAP_ADV_TYPE_ADV_IND = 0, /**< Undirected connectable and scannable mode. */ 222 GAP_ADV_TYPE_ADV_NONCONN_IND, /**< Non-connectable and non-scanable mode. */ 223 GAP_ADV_TYPE_ADV_SCAN_IND, /**< Undirected scannable mode. */ 224 GAP_ADV_TYPE_ADV_HIGH_DIRECT_IND, /**< Directed high duty cycle mode. */ 225 GAP_ADV_TYPE_ADV_LOW_DIRECT_IND, /**< Directed low duty cycle mode. */ 226 } gap_adv_mode_t; 227 228 /** @brief GAP discoverability modes. */ 229 typedef enum { 230 GAP_DISC_MODE_NON_DISCOVERABLE = 0, /**< Non-discoverable mode. */ 231 GAP_DISC_MODE_GEN_DISCOVERABLE, /**< General-discoverable mode. */ 232 GAP_DISC_MODE_LIM_DISCOVERABLE, /**< Limited-discoverable mode. */ 233 GAP_DISC_MODE_BROADCASTER, /**< Broadcaster mode. */ 234 } gap_disc_mode_t; 235 236 /** 237 * @brief Advertising filter policy 238 */ 239 typedef enum { 240 GAP_ADV_ALLOW_SCAN_ANY_CON_ANY = 0, /**< Allow both scan and connection requests from anyone. */ 241 GAP_ADV_ALLOW_SCAN_WLST_CON_ANY, /**< Allow scan req from white-list devices only 242 and connection req from anyone. */ 243 GAP_ADV_ALLOW_SCAN_ANY_CON_WLST, /**< Allow scan req from anyone and connection req 244 from white-list devices only. */ 245 GAP_ADV_ALLOW_SCAN_WLST_CON_WLST, /**< Allow scan and connection requests from white-list devices only. */ 246 } gap_adv_filter_policy_t; 247 248 /** 249 * @brief Specify what PHY the Controller has changed for TX/RX. HCI:7.7.65.12 250 */ 251 typedef enum { 252 GAP_PHY_UNDEF_VALUE = 0, /**< Undefined LE PHY. */ 253 GAP_PHY_1MBPS_VALUE = 1, /**< LE 1M PHY. */ 254 GAP_PHY_2MBPS_VALUE = 2, /**< LE 2M PHY. */ 255 GAP_PHY_CODED_VALUE = 3, /**< LE Coded PHY. */ 256 } gap_le_phy_value_t; 257 258 /** 259 * @brief Advertising type 260 */ 261 typedef enum { 262 GAP_ADV_TYPE_LEGACY = 0, /**< Legacy advertising. */ 263 GAP_ADV_TYPE_EXTENDED, /**< Extended advertising. */ 264 GAP_ADV_TYPE_PERIODIC, /**< Periodic advertising. */ 265 } gap_adv_type_t; 266 267 /** 268 * @brief Advertising properties bit field and bit positions 269 */ 270 typedef enum { 271 GAP_ADV_PROP_CONNECTABLE_POS = 0, /**< Indicate that advertising is connectable, reception of CONNECT_REQ or 272 UX_CONNECT_REQ PDUs is accepted. Not applicable for periodic advertising. */ 273 GAP_ADV_PROP_SCANNABLE_POS, /**< Indicate that advertising is scannable, reception of SCAN_REQ or 274 AUX_SCAN_REQ PDUs is accepted. */ 275 GAP_ADV_PROP_DIRECTED_POS, /**< Indicate that advertising targets at a specific device. 276 Only applicable in following cases: 277 - Legacy advertising: if connectable 278 - Extended advertising: connectable or 279 (non-connectable and non-discoverable). */ 280 GAP_ADV_PROP_HDC_POS, /**< Indicate that High Duty Cycle has to be used for advertising on primary channel, 281 applicable only if created advertising is not an extended advertising. */ 282 GAP_ADV_PROP_USE_LEGACY_PDUS_POS, /**< Use legacy advertising PDUs. */ 283 GAP_ADV_PROP_ANONYMOUS_POS, /**< Enable anonymous mode. Device address will not appear in sending PDUs. 284 Valid only if the created advertising is an extended advertising. */ 285 GAP_ADV_PROP_TX_PWR_POS, /**< Include TX power in the extended header of the advertising PDU. 286 Valid only if the created advertising is not a legacy advertising. */ 287 GAP_ADV_PROP_PER_TX_PWR_POS, /**< Include TX power in the periodic advertising PDU. 288 Valid only if the created advertising is a periodic advertising. */ 289 GAP_ADV_PROP_SCAN_REQ_NTF_EN_POS, /**< Indicate if application must be informed 290 about receiving scan request PDUs. */ 291 } gap_adv_prop_pos_t; 292 293 /** 294 * @brief Advertising properties bit field bit value 295 */ 296 typedef enum { 297 GAP_ADV_PROP_CONNECTABLE_BIT = CO_BIT(GAP_ADV_PROP_CONNECTABLE_POS), 298 GAP_ADV_PROP_SCANNABLE_BIT = CO_BIT(GAP_ADV_PROP_SCANNABLE_POS), 299 GAP_ADV_PROP_DIRECTED_BIT = CO_BIT(GAP_ADV_PROP_DIRECTED_POS), 300 GAP_ADV_PROP_HDC_BIT = CO_BIT(GAP_ADV_PROP_HDC_POS), 301 GAP_ADV_PROP_USE_LEGACY_PDUS_BIT = CO_BIT(GAP_ADV_PROP_USE_LEGACY_PDUS_POS), 302 GAP_ADV_PROP_ANONYMOUS_BIT = CO_BIT(GAP_ADV_PROP_ANONYMOUS_POS), 303 GAP_ADV_PROP_TX_PWR_BIT = CO_BIT(GAP_ADV_PROP_TX_PWR_POS), 304 GAP_ADV_PROP_PER_TX_PWR_BIT = CO_BIT(GAP_ADV_PROP_PER_TX_PWR_POS), 305 GAP_ADV_PROP_SCAN_REQ_NTF_EN_BIT = CO_BIT(GAP_ADV_PROP_SCAN_REQ_NTF_EN_POS), 306 } gap_adv_prop_t; 307 308 /** 309 * @brief Scanning types 310 */ 311 typedef enum { 312 GAP_SCAN_ACTIVE = 0, /**< Active scan type. */ 313 GAP_SCAN_PASSIVE, /**< Passive scan type. */ 314 } gap_scan_type_t; 315 316 /** 317 * @brief Scanning modes 318 */ 319 typedef enum { 320 GAP_SCAN_GEN_DISC_MODE = 0, /**< General discoverable mode. */ 321 GAP_SCAN_LIM_DISC_MODE, /**< Limited discoverable mode. */ 322 GAP_SCAN_OBSERVER_MODE, /**< Observer mode. */ 323 } gap_scan_mode_t; 324 325 /** 326 * @brief Duplicate filter policy 327 */ 328 typedef enum { 329 GAP_SCAN_FILT_DUPLIC_DIS = 0, /**< Disable filtering of duplicate packets. */ 330 GAP_SCAN_FILT_DUPLIC_EN, /**< Enable filtering of duplicate packets. */ 331 } gap_scan_dup_filt_policy_t; 332 333 /** 334 * @brief Extended scanning types 335 */ 336 typedef enum { 337 GAP_EXT_SCAN_TYPE_GEN_DISC = 0, /**< General discovery. */ 338 GAP_EXT_SCAN_TYPE_LIM_DISC, /**< Limited discovery. */ 339 GAP_EXT_SCAN_TYPE_OBSERVER, /**< Observer. */ 340 GAP_EXT_SCAN_TYPE_SEL_OBSERVER, /**< Selective observer. */ 341 GAP_EXT_SCAN_TYPE_CONN_DISC, /**< Connectable discovery. */ 342 GAP_EXT_SCAN_TYPE_SEL_CONN_DISC, /**< Selective connectable discovery. */ 343 } gap_ext_scan_type_t; 344 345 /** 346 * @brief Scanning properties bit field bit value 347 */ 348 typedef enum { 349 GAP_EXT_SCAN_PROP_PHY_1M_BIT = (1 << 0), /**< Scan advertisement on the LE 1M PHY. */ 350 GAP_EXT_SCAN_PROP_PHY_CODED_BIT = (1 << 1), /**< Scan advertisement on the LE Coded PHY. */ 351 GAP_EXT_SCAN_PROP_ACTIVE_1M_BIT = (1 << 2), /**< Active scan on LE 1M PHY (scan request PDUs may be sent). */ 352 GAP_EXT_SCAN_PROP_ACTIVE_CODED_BIT = (1 << 3), /**< Active scan on LE Coded PHY (scan request PDUs may be sent). */ 353 GAP_EXT_SCAN_PROP_ACCEPT_RPA_BIT = (1 << 4), /**< Accept directed advertising packets if the uesd RPA and 354 target address cannot be solved by the controller. */ 355 GAP_EXT_SCAN_PROP_FILT_TRUNC_BIT = (1 << 5), /**< Filter truncated advertising or scan response reports. */ 356 } gap_scan_prop_t; 357 358 /** 359 * @brief Filtering policy for duplicated packets 360 */ 361 typedef enum { 362 GAP_EXT_DUP_FILT_DIS = 0, /**< Disable filtering of duplicated packets. */ 363 GAP_EXT_DUP_FILT_EN, /**< Enable filtering of duplicated packets. */ 364 GAP_EXT_DUP_FILT_EN_PERIOD, /**< Enable filtering of duplicated packets, reset for each scan period. */ 365 } gap_ext_scan_dup_filt_policy_t; 366 367 /** 368 * @brief Initiating types 369 */ 370 typedef enum { 371 GAP_INIT_TYPE_DIRECT_CONN_EST = 0, /**< Direct connection establishment: establish a connection with 372 an indicated device. */ 373 GAP_INIT_TYPE_AUTO_CONN_EST, /**< Automatic connection establishment: establish a connection with 374 all devices whose address is present in the white list. */ 375 GAP_INIT_TYPE_NAME_DISC, /**< Name discovery: establish a connection with an indicated device 376 in order to read content of its device name characteristic. 377 Connection is closed once this operation is stopped. */ 378 } gap_init_type_t; 379 380 /** 381 * @brief Initiating properties 382 */ 383 typedef enum { 384 GAP_INIT_PROP_1M_BIT = (1 << 0), /**< Scan connectable advertisements on the LE 1M PHY. 385 Connection parameters for the LE 1M PHY are provided. */ 386 GAP_INIT_PROP_2M_BIT = (1 << 1), /**< Connection parameters for the LE 2M PHY are provided. */ 387 GAP_INIT_PROP_CODED_BIT = (1 << 2), /**< Scan connectable advertisements on the LE Coded PHY. 388 Connection parameters for the LE Coded PHY are provided. */ 389 } gap_init_prop_t; 390 391 /** 392 * @brief Scanning properties bit field bit value 393 */ 394 enum gap_scan_prop { 395 GAP_SCAN_PROP_PHY_1M_BIT = (1 << 0), /**< Scan advertisement on the LE 1M PHY. */ 396 GAP_SCAN_PROP_PHY_CODED_BIT = (1 << 1), /**< Scan advertisement on the LE Coded PHY. */ 397 GAP_SCAN_PROP_ACTIVE_1M_BIT = (1 << 2), /**< Active scan on LE 1M PHY (scan request PDUs may be sent). */ 398 GAP_SCAN_PROP_ACTIVE_CODED_BIT = (1 << 3), /**< Active scan on LE Coded PHY (scan request PDUs may be sent). */ 399 GAP_SCAN_PROP_ACCEPT_RPA_BIT = (1 << 4), /**< Accept directed advertising packets if the used RPA and 400 target address cannot be solved by the controller. */ 401 GAP_SCAN_PROP_FILT_TRUNC_BIT = (1 << 5), /**< Filter truncated advertising or scan response reports. */ 402 }; 403 404 /** 405 * @brief Periodic synchronization types 406 */ 407 enum gap_per_sync_type { 408 GAP_PER_SYNC_TYPE_GENERAL = 0, /**< Do not use periodic advertiser list for synchronization. */ 409 GAP_PER_SYNC_TYPE_SELECTIVE, /**< Use periodic advertiser list for synchronization. */ 410 }; 411 412 /** 413 * @brief Security level types 414 */ 415 enum gap_sec_lvl_type { 416 GAP_SEC_LVL_NO_SECURITY = 0, /**< No encryption or auth. */ 417 GAP_SEC_LVL_ENC_NO_AUTH, /**< Encryption with no auth. */ 418 GAP_SEC_LVL_LE_ENC_AUTH, /**< Legacy encryption with auth. */ 419 GAP_SEC_LVL_SC_ENC_AUTH, /**< Security connection encryption with auth. */ 420 }; 421 422 /** 423 * @brief GAP advertising types 424 */ 425 typedef enum { 426 BLE_GAP_AD_TYPE_FLAGS = 0x01, /**< Flag. */ 427 BLE_GAP_AD_TYPE_MORE_16_BIT_UUID = 0x02, /**< Use of more than 16-bit UUID. */ 428 BLE_GAP_AD_TYPE_COMPLETE_LIST_16_BIT_UUID = 0x03, /**< Complete List of 16-bit UUID. */ 429 BLE_GAP_AD_TYPE_MORE_32_BIT_UUID = 0x04, /**< Use of more than 32-bit UUD. */ 430 BLE_GAP_AD_TYPE_COMPLETE_LIST_32_BIT_UUID = 0x05, /**< Complete List of 32-bit UUID. */ 431 BLE_GAP_AD_TYPE_MORE_128_BIT_UUID = 0x06, /**< Use of more than 128-bit UUID. */ 432 BLE_GAP_AD_TYPE_COMPLETE_LIST_128_BIT_UUID = 0x07, /**< Complete List of 128-bit UUID. */ 433 BLE_GAP_AD_TYPE_SHORTENED_NAME = 0x08, /**< Shortened Device name. */ 434 BLE_GAP_AD_TYPE_COMPLETE_NAME = 0x09, /**< Complete Device name. */ 435 BLE_GAP_AD_TYPE_TRANSMIT_POWER = 0x0A, /**< Transmit power. */ 436 BLE_GAP_AD_TYPE_CLASS_OF_DEVICE = 0x0D, /**< Class of device. */ 437 BLE_GAP_AD_TYPE_SP_HASH_C = 0x0E, /**< Simple Pairing Hash C. */ 438 BLE_GAP_AD_TYPE_SP_RANDOMIZER_R = 0x0F, /**< Simple Pairing Randomizer. */ 439 BLE_GAP_AD_TYPE_TK_VALUE = 0x10, /**< Temporary key value. */ 440 BLE_GAP_AD_TYPE_OOB_FLAGS = 0x11, /**< Out of Band Flag. */ 441 BLE_GAP_AD_TYPE_SLAVE_CONN_INT_RANGE = 0x12, /**< Slave connection interval range. */ 442 BLE_GAP_AD_TYPE_RQRD_16_BIT_SVC_UUID = 0x14, /**< Require 16-bit service UUID. */ 443 BLE_GAP_AD_TYPE_RQRD_32_BIT_SVC_UUID = 0x1F, /**< Require 32-bit service UUID. */ 444 BLE_GAP_AD_TYPE_RQRD_128_BIT_SVC_UUID = 0x15, /**< Require 128-bit service UUID. */ 445 BLE_GAP_AD_TYPE_SERVICE_16_BIT_DATA = 0x16, /**< Service data 16-bit UUID. */ 446 BLE_GAP_AD_TYPE_SERVICE_32_BIT_DATA = 0x20, /**< Service data 32-bit UUID. */ 447 BLE_GAP_AD_TYPE_SERVICE_128_BIT_DATA = 0x21, /**< Service data 128-bit UUID. */ 448 BLE_GAP_AD_TYPE_PUB_TGT_ADDR = 0x17, /**< Public Target Address. */ 449 BLE_GAP_AD_TYPE_RAND_TGT_ADDR = 0x18, /**< Random Target Address. */ 450 BLE_GAP_AD_TYPE_APPEARANCE = 0x19, /**< Appearance. */ 451 BLE_GAP_AD_TYPE_ADV_INTV = 0x1A, /**< Advertising Interval. */ 452 BLE_GAP_AD_TYPE_LE_BT_ADDR = 0x1B, /**< LE Bluetooth Device Address. */ 453 BLE_GAP_AD_TYPE_LE_ROLE = 0x1C, /**< LE Role. */ 454 BLE_GAP_AD_TYPE_SPAIR_HASH = 0x1D, /**< Simple Pairing Hash C-256. */ 455 BLE_GAP_AD_TYPE_SPAIR_RAND = 0x1E, /**< Simple Pairing Randomizer R-256. */ 456 BLE_GAP_AD_TYPE_3D_INFO = 0x3D, /**< 3D Information Data. */ 457 458 BLE_GAP_AD_TYPE_MANU_SPECIFIC_DATA = 0xFF, /**< Manufacturer specific data. */ 459 } gap_ad_type_t; 460 461 /** 462 * @brief AD Type Flag - Bit mask. 463 */ 464 typedef enum { 465 GAP_ADV_FLAG_LE_LIMITED_DISC_MODE = 0x01, /**< Limited discovery flag: AD Flag. */ 466 GAP_ADV_FLAG_LE_GENERAL_DISC_MODE = 0x02, /**< General discovery flag: AD Flag. */ 467 GAP_ADV_FLAG_BR_EDR_NOT_SUPPORTED = 0x04, /**< Legacy BT not supported: AD Flag. */ 468 GAP_ADV_FLAG_SIMUL_BR_EDR_LE_CONTROLLER = 0x08, /**< Dual mode for controller supported (BR/EDR/LE): AD Flag. */ 469 GAP_ADV_FLAG_SIMUL_BR_EDR_LE_HOST = 0x10, /**< Dual mode for host supported (BR/EDR/LE): AD Flag. */ 470 } gap_adv_flags_t; 471 472 /** 473 * @brief Privacy mode. 474 */ 475 476 typedef enum { 477 PRIVACY_MODE_NETWORK = 0x00, /**< Set to the network privacy mode for the peer device. */ 478 PRIVACY_MODE_DEVICE = 0x01, /**< Set to the device privacy mode for the peer device. */ 479 } privacy_mode_t; 480 481 /** 482 * @brief Possible roles for the event. 483 */ 484 typedef enum { 485 GAP_EVENT_ROLE_ADV = 0, /**< Adertise role. */ 486 GAP_EVENT_ROLE_CON = 1, /**< Connect role. */ 487 GAP_EVENT_ROLE_SCAN_INIT = 2, /**< Scann role. */ 488 GAP_EVENT_ROLE_UNKNOWN = 0xf, /**< Unknown role. */ 489 } gap_event_role_t; 490 491 /** 492 * @brief Event type. 493 */ 494 typedef enum { 495 TYPE_ADV = 0, 496 TYPE_SCAN, 497 TYPE_INIT, 498 TYPE_PER_SYNC, 499 } ble_actv_type_t; 500 501 /** @} */ 502 503 /** @addtogroup BLE_GAPM_STRUCTURES Structures 504 * @{ */ 505 506 /** 507 * @brief Advertising parameters for legacy advertising 508 */ 509 typedef struct { 510 uint8_t adv_mode; /**< Advertising mode (see enum @ref gap_adv_mode_t). */ 511 uint8_t disc_mode; /**< Discovery mode (see enum @ref gap_disc_mode_t). */ 512 uint8_t filter_pol; /**< Advertising filtering policy (see enum @ref gap_adv_filter_policy_t). */ 513 gap_bdaddr_t 514 peer_addr; /**< Peer address configuration (only used in case of directed advertising, 515 or used to locate the IRK list). */ 516 uint16_t adv_intv_min; /**< Minimum advertising interval (in unit of 625 us). Must be greater than 20 ms. */ 517 uint16_t 518 adv_intv_max; /**< Maximum advertising interval (in unit of 625 us). Must be greater than 20 ms. */ 519 uint8_t chnl_map; /**< Advertising channel map. See @ref BLE_GAP_ADV_CHANNEL. */ 520 bool 521 scan_req_ind_en; /**< Indicate if the application should be informed when receiving 522 a scan request from the scanner. */ 523 int8_t 524 max_tx_pwr; /**< Maximum power level at which the advertising packets 525 have to be transmitted (between -20dbm and 7dbm). 526 For the real value, please refer to GR551x Datasheet. */ 527 } gap_adv_param_t; 528 529 /** 530 * @brief Configuration for advertising on primary channel 531 */ 532 typedef struct { 533 uint32_t adv_intv_min; /**< Minimum advertising interval (in unit of 625 us). Must be greater than 20 ms. */ 534 uint32_t adv_intv_max; /**< Maximum advertising interval (in unit of 625 us). Must be greater than 20 ms. */ 535 uint8_t chnl_map; /**< Bit field indicating the channel map. See @ref BLE_GAP_ADV_CHANNEL. */ 536 gap_le_phy_value_t phy; /**< Indicate on which PHY primary advertising has to be performed. 537 See enum @ref gap_le_phy_value_t. Note that LE 2M PHY is not allowed and that 538 legacy advertising only supports LE 1M PHY. */ 539 } gap_adv_prim_cfg_t; 540 541 /** 542 * @brief Configuration for advertising on secondary channel 543 */ 544 typedef struct { 545 uint8_t max_skip; /**< Maximum number of advertising events the controller can skip 546 before sending the AUX_ADV_IND packets. 547 The range is 0x00 to 0xFF. 548 0x00 means that AUX_ADV_IND PDUs shall be sent prior to each advertising events. */ 549 gap_le_phy_value_t phy; /**< Indicate on which PHY secondary advertising has to be performed. 550 See enum @ref gap_le_phy_value_t. */ 551 uint8_t adv_sid; /**< Advertising SID. Allowed range is 0x00 to 0x0F. */ 552 } gap_adv_second_cfg_t; 553 554 /** 555 * @brief Configuration for periodic advertising 556 */ 557 typedef struct { 558 uint16_t adv_intv_min; /**< Minimum advertising interval (in unit of 1.25 ms). Must be greater than 20 ms. */ 559 uint16_t 560 adv_intv_max; /**< Maximum advertising interval (in unit of 1.25 ms). Must be greater than 20 ms. */ 561 } gap_adv_period_cfg_t; 562 563 /** 564 * @brief Advertising parameters for extended advertising and periodic advertising 565 */ 566 typedef struct { 567 uint8_t type; /**< Advertising type (see enum @ref gap_adv_type_t). */ 568 uint8_t disc_mode; /**< Discovery mode (see enum @ref gap_disc_mode_t). */ 569 uint16_t prop; /**< Bit field value provided by advertising properties. 570 See enum @ref gap_adv_prop_t for bit signification. */ 571 int8_t max_tx_pwr; /**< Maximum power level at which the advertising packets have to be transmitted 572 (between -20 and 7 dBm). */ 573 uint8_t filter_pol; /**< Advertising filtering policy (see enum @ref gap_adv_filter_policy_t). */ 574 gap_bdaddr_t peer_addr; /**< Peer address configuration (only used in case of directed advertising or 575 used to locate the IRK list). */ 576 gap_adv_prim_cfg_t prim_cfg; /**< Configuration for primary advertising. */ 577 gap_adv_second_cfg_t second_cfg; /**< Configuration for secondary advertising (valid only if advertising type is 578 GAP_ADV_TYPE_EXTENDED or GAP_ADV_TYPE_PERIODIC). */ 579 gap_adv_period_cfg_t period_cfg; /**< Configuration for periodic advertising 580 (valid only if advertising type is GAP_ADV_TYPE_PERIODIC). */ 581 } gap_ext_adv_param_t; 582 583 /** 584 * @brief Advertising timing parameter 585 */ 586 typedef struct { 587 uint16_t duration; /**< Advertising duration (in unit of 10ms). 588 0 means that advertising continues until the host disables it. 589 If Advertising discovery mode is GAP_DISC_MODE_LIM_DISCOVERABLE 590 (see enum @ref gap_disc_mode_t), the setting duration range is [1, 18000]. 591 If adv mode is high duty, duration time range is [1, 128]. */ 592 uint8_t max_adv_evt; /**< Maximum number of extended advertising events. 593 The controller shall attempt to send prior to terminating the extending advertising. 594 The range is [0, 255]. 0 means no maximum number of advertising events. 595 Valid only if the created advertising is an extended advertising. */ 596 } gap_adv_time_param_t; 597 598 /** 599 * @brief Security key 600 */ 601 typedef struct { 602 uint8_t key[MAX_KEY_LEN]; /**< Key value MSB -> LSB (MSB followed by LSB). */ 603 } gap_sec_key_t; 604 605 /** 606 * @brief Parameters for legacy scanning 607 */ 608 typedef struct { 609 gap_scan_type_t scan_type; /**< Active scanning or passive scanning. */ 610 gap_scan_mode_t scan_mode; /**< Scan mode. */ 611 gap_scan_dup_filt_policy_t scan_dup_filt; /**< Duplicate filter policy. */ 612 bool use_whitelist; /**< Filter policy. */ 613 uint16_t interval; /**< Scan interval between 0x0004 and 0x4000 in 0.625 ms (range: 2.5 ms to 10.24s). */ 614 uint16_t window; /**< Scan window between 0x0004 and 0x4000 in 0.625 ms (range: 2.5 ms to 10.24s). */ 615 uint16_t timeout; /**< Scan timeout should be a value between 0x0001 and 0xFFFF(unit: 10 ms). 616 0x0000 indicates that the timeout has no effect. */ 617 } gap_scan_param_t; 618 619 /** 620 * @brief Scan Window operation parameters 621 */ 622 typedef struct { 623 uint16_t scan_intv; /**< Scan interval between 0x0004 and 0xFFFF in 0.625 ms (range: 2.5 ms to 40.959375s). */ 624 uint16_t scan_wd; /**< Scan window between 0x0004 and 0xFFFF in 0.625 ms (range: 2.5 ms to 40.959375s). */ 625 } gap_scan_wd_op_param_t; 626 627 /** 628 * @brief Parameters for extended scanning 629 */ 630 typedef struct { 631 uint8_t type; /**< Type of scanning to be started (see enum @ref gap_ext_scan_type_t). */ 632 uint8_t prop; /**< Properties for the scan procedure (see enum @ref gap_scan_prop for bit signification). */ 633 uint8_t dup_filt_pol; /**< Duplicate packet filtering policy (see enum @ref gap_ext_scan_dup_filt_policy_t). */ 634 uint8_t rsvd; /**< Reserved for future use. */ 635 gap_scan_wd_op_param_t scan_param_1m; /**< Scan window opening parameters for LE 1M PHY. */ 636 gap_scan_wd_op_param_t scan_param_coded; /**< Scan window opening parameters for LE Coded PHY. */ 637 uint16_t duration; /**< Scan duration (in unit of 10ms). 0 means that the controller will scan continuously 638 until receiving a stop command from the application (10 ms to 655.35s). */ 639 uint16_t period; /**< Scan period, which is the time interval between two consequent starts of a scan duration 640 by the controller. 641 0 means that the scan procedure is not periodic, in unit of 1.28s (1.28s to 83,884.8s). */ 642 } gap_ext_scan_param_t; 643 644 /** 645 * @brief Periodic advertising information 646 */ 647 typedef struct { 648 gap_bdaddr_t bd_addr; /**< Advertiser address information. */ 649 uint8_t adv_sid; /**< Advertising SID. */ 650 } gap_period_adv_addr_cfg_t; 651 652 /** 653 * @brief Periodic advertising synchronization parameters 654 */ 655 typedef struct { 656 uint16_t skip; /**< Number of periodic advertising that can be skipped after a successful reception. 657 Maximum authorized value is 499. */ 658 uint16_t sync_to; /**< Synchronization timeout for the periodic advertising 659 (in unit of 10ms between 100ms and 163.84s). */ 660 uint8_t type; /**< Periodic synchronization type (see enum @ref gap_per_sync_type). */ 661 uint8_t rsvd; /**< Reserved for future use.*/ 662 gap_period_adv_addr_cfg_t adv_addr; /**< Address of advertiser with which synchronization has to be established 663 (used only if use_pal is false). */ 664 } gap_per_sync_param_t; 665 666 /** 667 * @brief Legacy initiating parameters 668 */ 669 typedef struct { 670 uint8_t type; /**< Initiating type (see enum @ref gap_init_type_t). */ 671 gap_bdaddr_t peer_addr; /**< Peer device address. */ 672 uint16_t interval_min; /**< Minimum value for the connection interval (in unit of 1.25ms). 673 Shall be less than or equal to interval_max value. 674 Allowed range is 7.5 ms to 4s. */ 675 uint16_t interval_max; /**< Maximum value for the connection interval (in unit of 1.25ms). 676 Shall be greater than or equal to interval_min value. 677 Allowed range is 7.5 ms to 4s. */ 678 uint16_t slave_latency; /**< Slave latency. Number of events that can be missed by a connected slave device. */ 679 uint16_t sup_timeout; /**< Link supervision timeout (in unit of 10ms). Allowed range is 100 ms to 32s. */ 680 uint16_t conn_timeout; /**< Timeout for connection establishment (in unit of 10ms). 681 Cancel the procedure if connection has not been connected when the timeout occurs. 682 0 means there is no timeout. */ 683 } gap_init_param_t; 684 685 686 /** 687 * @brief Connection parameters 688 */ 689 typedef struct { 690 uint16_t conn_intv_min; /**< Minimum value for the connection interval (in unit of 1.25ms). 691 Shall be less than or equal to conn_intv_max value. 692 Allowed range is 7.5 ms to 4s. */ 693 uint16_t conn_intv_max; /**< Maximum value for the connection interval (in unit of 1.25ms). 694 Shall be greater than or equal to conn_intv_min value. 695 Allowed range is 7.5 ms to 4s. */ 696 uint16_t conn_latency; /**< Slave latency. Number of events that can be missed by a connected slave device. */ 697 uint16_t supervision_to; /**< Link supervision timeout (in unit of 10ms). Allowed range is 100 ms to 32s. */ 698 uint16_t ce_len; /**< The length of connection event needed for this LE connection. 699 Range: 0x0002 to 0xFFFF, Unit:0.625 ms, Time Range: 1.25 ms to 40.9s. */ 700 } gap_ext_conn_param_t; 701 702 /** 703 * @brief Extended initiating parameters 704 */ 705 typedef struct { 706 uint8_t type; /**< Initiating type (see enum @ref gap_init_type_t). */ 707 uint8_t prop; /**< Properties for the initiating procedure 708 (see enum @ref gap_init_prop_t for bit signification). */ 709 uint16_t conn_to; /**< Timeout for automatic connection establishment (in unit of 10ms). 710 Cancel the procedure if connection has not been connected when the timeout occurs. 711 0 means there is no timeout. */ 712 gap_scan_wd_op_param_t scan_param_1m; /**< Scan window opening parameters for LE 1M PHY. */ 713 gap_scan_wd_op_param_t scan_param_coded; /**< Scan window opening parameters for LE Coded PHY. */ 714 gap_ext_conn_param_t conn_param_1m; /**< Connection parameters for LE 1M PHY. */ 715 gap_ext_conn_param_t conn_param_2m; /**< Connection parameters for LE 2M PHY. */ 716 gap_ext_conn_param_t conn_param_coded; /**< Connection parameters for LE Coded PHY. */ 717 gap_bdaddr_t peer_addr; /**< Address of peer device in case white list is not used for connection. */ 718 } gap_ext_init_param_t; 719 720 /** 721 * @brief LE Protocol/Service Multiplexer information 722 */ 723 typedef struct { 724 uint16_t le_psm; /**< LE Protocol/Service Multiplexer (range: 1 to 255), PSMs should be odd. */ 725 uint8_t sec_lvl; /**< Security level requirement, see @ref gap_sec_lvl_type. */ 726 bool mks_flag; /**< Whether to use maximum-size key (16 bytes) or not. */ 727 } gap_lepsm_register_t; 728 729 /** 730 * @brief Bonded device list 731 */ 732 typedef struct { 733 uint8_t num; /**< Number of bonded device. */ 734 gap_bdaddr_t items[MAX_BOND_NUM]; /**< Bonded device addr info. */ 735 } bond_dev_list_t; 736 737 /** 738 * @brief White list 739 */ 740 typedef struct { 741 uint8_t num; /**< Number of available items. */ 742 gap_bdaddr_t items[MAX_WL_NUM]; /**< Content of each item. */ 743 } white_list_t; 744 745 /** 746 * @brief Periodic advertising list 747 */ 748 typedef struct { 749 uint8_t num; /**< Number of available items. */ 750 gap_period_adv_addr_cfg_t items[MAX_PRD_ADV_NUM]; /**< Content of each item. */ 751 } period_adv_list_t; 752 753 /** 754 * @brief RPA list item info 755 */ 756 typedef struct { 757 gap_bdaddr_t bd_addr; /**< Peer device identity. */ 758 uint8_t priv_mode; /**< Privacy mode, see enum @ref privacy_mode_t. */ 759 uint8_t peer_irk[MAX_KEY_LEN]; /**< Peer IRK. */ 760 uint8_t local_irk[MAX_KEY_LEN]; /**< Local IRK. */ 761 } gap_ral_dev_info_t; 762 763 /** 764 * @brief RPA list info 765 */ 766 typedef struct { 767 uint8_t num; /**< Number of RPA list. */ 768 gap_ral_dev_info_t items[MAX_BOND_NUM]; /**< RPA list item info. */ 769 } ral_dev_list_t; 770 771 /** 772 * @brief The BLE reslove rpa address callback. 773 */ 774 typedef void (*reslv_rpa_addr_callback_t) (uint8_t status, gap_bdaddr_t *iden_addr, 775 uint8_t src_info); 776 777 /** 778 * @brief The BLE rpa address report callback. 779 */ 780 typedef void (*rpa_addr_report_callback_t) (ble_actv_type_t type, uint8_t index, 781 const uint8_t *rpa_addr); 782 783 /** @} */ 784 785 786 /** @addtogroup BLE_GAPM_FUNCTION Functions 787 * @{ */ 788 789 /** 790 **************************************************************************************** 791 * @brief Decide whether to support the pair feature. 792 * 793 * @param[in] enable: Support flag. 794 **************************************************************************************** 795 */ 796 void ble_gap_pair_enable(bool enable); 797 798 /** 799 **************************************************************************************** 800 * @brief Set the device identity address (public or random static). 801 * 802 * @param[in] p_addr: Provided public or static random address. If addr_type = 0, it means public address, 803 * If addr_type = 1, it means static random address. 804 * 805 * @retval ::SDK_SUCCESS: Operation is successful. 806 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 807 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 808 **************************************************************************************** 809 */ 810 uint16_t ble_gap_addr_set(gap_bdaddr_t const *p_addr); 811 812 /** 813 **************************************************************************************** 814 * @brief Get the device identity address (public or random static). 815 * 816 * @param[in] p_addr: The pointer for the returned identity address. 817 * 818 * @retval ::SDK_SUCCESS: Operation is successful. 819 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 820 **************************************************************************************** 821 */ 822 uint16_t ble_gap_addr_get(gap_bdaddr_t *p_addr); 823 824 /** 825 **************************************************************************************** 826 * @brief Set the tx power 827 * 828 * @param[in] role: Select the role to set tx power. @ref gap_event_role_t for possible roles. 829 * @param[in] index: The idx parameter is interpreted on role. 830 * -If the role is @ref GAP_EVENT_ROLE_ADV, it's the index of Advertising. 831 * -If the role is @ref GAP_EVENT_ROLE_CON, it's the index of connection. 832 * -For all other roles, it should be ignored. 833 * @param[in] txpwr_dbm: The value of the tx power, Range: -20dbm to 7dbm. 834 * 835 * @retval ::SDK_SUCCESS: Operation is Success. 836 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied. 837 * @retval ::SDK_ERR_INVALID_ADV_IDX: Invalid advertising index supplied. 838 * @retval ::SDK_ERR_INVALID_HANDLE: Invalid handle supplied. 839 **************************************************************************************** 840 */ 841 uint16_t ble_gap_tx_power_set(gap_event_role_t role, uint8_t index, int8_t txpwr_dbm); 842 843 /** 844 **************************************************************************************** 845 * @brief Get the tx power 846 * 847 * @param[in] role: Select the role to Get tx power. @ref gap_event_role_t for possible roles. 848 * @param[in] index: The idx parameter is interpreted on role. 849 * -If the role is @ref GAP_EVENT_ROLE_ADV, it's the index of Advertising. 850 * -If the role is @ref GAP_EVENT_ROLE_CON, it's the index of connection. 851 * -For all other roles, it should be ignored. 852 * @param[in] txpwr_dbm: The value of the tx power, Range: -20dbm to 7dbm. 853 * 854 * @retval ::SDK_SUCCESS: Operation is Success. 855 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied. 856 * @retval ::SDK_ERR_INVALID_ADV_IDX: Invalid advertising index supplied. 857 * @retval ::SDK_ERR_INVALID_HANDLE: Invalid handle supplied. 858 **************************************************************************************** 859 */ 860 uint16_t ble_gap_tx_power_get(gap_event_role_t role, uint8_t index, int8_t *txpwr_dbm); 861 862 /** 863 **************************************************************************************** 864 * @brief Set the default tx power for all roles. 865 * 866 * @note This function should be called before BLE stack init. 867 * 868 * @param[in] txpwr_dbm: The value of the tx power, Range: -20dbm to 7dbm. 869 * 870 * @retval ::SDK_SUCCESS: Operation is Success. 871 **************************************************************************************** 872 */ 873 uint16_t ble_gap_default_tx_power_set(int8_t txpwr_dbm); 874 875 /** 876 **************************************************************************************** 877 * @brief Get the default tx power for all roles. 878 * 879 * @param[in] txpwr_dbm: The value of the tx power, Range: -20dbm to 7dbm. 880 * 881 * @retval ::SDK_SUCCESS: Operation is Success. 882 **************************************************************************************** 883 */ 884 uint16_t ble_gap_default_tx_power_get(int8_t *txpwr_dbm); 885 886 887 /** 888 **************************************************************************************** 889 * @brief Set IRK used for resolvable random BD address generation (LSB first). 890 * 891 * @param[in] p_irk: Device IRK (Identity Resolving Key). 892 * 893 * @retval ::SDK_SUCCESS: Operation is successful. 894 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 895 **************************************************************************************** 896 */ 897 uint16_t ble_gap_irk_set(gap_sec_key_t* p_irk); 898 899 /** 900 **************************************************************************************** 901 * @brief Set privacy related parameters. 902 * @param[in] renew_dur: Duration before regenerating a device address when privacy is enabled in seconds. 903 * Range: 0x0001 (1s) ~ 0xA1B8 (11.5 hr). The suggested time is 900s(15 minutes). 904 * @param[in] enable_flag: Indicate the controller privacy is enabled or disabled. 905 * 906 * @retval ::SDK_SUCCESS: Operation is successful. 907 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied. 908 **************************************************************************************** 909 */ 910 uint16_t ble_gap_privacy_params_set(uint16_t renew_dur, bool enable_flag); 911 912 /** 913 **************************************************************************************** 914 * @brief Set suggested default LE data length. 915 * 916 * @param[in] sugg_max_tx_octet: Suggested value for the Controller's maximum transmitted number of 917 * payload octets to be used, the range is 27~251. 918 * @param[in] sugg_max_tx_time: Suggested value for the Controller's maximum packet transmission time to be used, 919 * the range is 328~2120. 920 * 921 * @retval ::SDK_SUCCESS: Operation is successful. 922 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied. 923 **************************************************************************************** 924 */ 925 uint16_t ble_gap_data_length_set(uint16_t sugg_max_tx_octet, uint16_t sugg_max_tx_time); 926 927 /** 928 **************************************************************************************** 929 * @brief Set L2CAP related parameters. 930 * 931 * @param[in] max_mtu: Maximal MTU acceptable for device, the range is 65~512. 932 * @param[in] max_mps: Maximal MPS Packet size acceptable for device (for COC SDU), the range is 65~max_mtu. 933 * @param[in] max_nb_lecb: Maximum number of LE Credit based connection that can be established, 934 * this range is 0x00~0x20. The actual number is decided by resource available. 935 * 936 * @retval ::SDK_SUCCESS: Operation is successful. 937 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied. 938 * 939 * @note If these parameters are not set, the stack will config the default value as 940 * (max_mtu = 512, max_mps = 512 and max_nb_lecb = 10). 941 **************************************************************************************** 942 */ 943 uint16_t ble_gap_l2cap_params_set(uint16_t max_mtu, uint16_t max_mps, uint8_t max_nb_lecb); 944 945 /** 946 **************************************************************************************** 947 * @brief Set the preferred values for the transmitter PHY and receiver PHY. 948 * 949 * @param[in] tx_pref_phy: A bit field that indicates the transmitter PHYs 950 * that the Host prefers the Controller to use(see @ref BLE_GAP_PHYS). 951 * @param[in] rx_pref_phy: A bit field that indicates the receiver PHYs that the Host prefers the 952 * Controller to use(see @ref BLE_GAP_PHYS). 953 **************************************************************************************** 954 */ 955 void ble_gap_pref_phy_set(uint8_t tx_pref_phy, uint8_t rx_pref_phy); 956 957 /** 958 **************************************************************************************** 959 * @brief Set the RF path gain or loss between the RF transceiver and the antenna 960 * contributed by intermediate components. 961 * 962 * @param[in] tx_path_comp: RF TX Path Compensation value (from -128dB to 128dB, unit is 0.1dB). 963 * @param[in] rx_path_comp: RF RX Path Compensation value (from -128dB to 128dB, unit is 0.1dB). 964 * 965 * @retval ::SDK_SUCCESS: Operation is successful. 966 * @retval ::SDK_ERR_INVALID_PARAM: The parameter is invalid. 967 **************************************************************************************** 968 */ 969 uint16_t ble_gap_path_compensation_set(int16_t tx_path_comp, int16_t rx_path_comp); 970 971 /** 972 **************************************************************************************** 973 * @brief Set advertising channel map before advertising starts. 974 * 975 * @param[in] p_chnl_map: Bitmask of LE channel map. See enum @ref gap_chnl_map_t for BT Core Spec version <= 4.2. 976 * 977 * @retval ::SDK_SUCCESS: Operation is successful. 978 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 979 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 980 * 981 * @note This API is asynchronous. 982 * @note @ref gap_cb_fun_t::app_gap_param_set_cb with op_id: @ref GAP_OPCODE_CHNL_MAP_SET 983 will be called once the operation has completed. 984 **************************************************************************************** 985 */ 986 uint16_t ble_gap_chnl_map_set(gap_chnl_map_t* p_chnl_map); 987 988 /** 989 **************************************************************************************** 990 * @brief Get all bonded devices. 991 * 992 * @retval ::SDK_SUCCESS: Operation is successful. 993 * @retval ::SDK_ERR_SDK_INTERNAL: SDK internal error. 994 * @retval ::SDK_ERR_NVDS_NOT_INIT: NVDS is not initiated. 995 * @retval ::SDK_ERR_LIST_ITEM_NOT_FOUND: Item not found in list. 996 * @retval ::SDK_ERR_LIST_FULL: List is full. 997 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 998 **************************************************************************************** 999 */ 1000 uint16_t ble_gap_bond_devs_get(bond_dev_list_t *p_bond_list); 1001 1002 /** 1003 **************************************************************************************** 1004 * @brief Get BD address of the bonded device. 1005 * 1006 * @param[in] conn_idx: The index of connection. 1007 * @param[in] p_peer_addr: Pointer to the peer BD addrss 1008 * 1009 * @retval ::SDK_SUCCESS: Operation is successful. 1010 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1011 * @retval ::SDK_ERR_INVALID_PARAM: The parameter is invalid. 1012 **************************************************************************************** 1013 */ 1014 uint16_t ble_gap_bond_dev_addr_get(uint8_t conn_idx, gap_bdaddr_t *p_peer_addr); 1015 1016 /** 1017 **************************************************************************************** 1018 * @brief Clear all bonded devices. 1019 * 1020 * @retval ::SDK_SUCCESS: Operation is successful. 1021 * @retval ::SDK_ERR_SDK_INTERNAL: SDK internal error. 1022 * @retval ::SDK_ERR_NVDS_NOT_INIT: NVDS is not initiated. 1023 * @retval ::SDK_ERR_LIST_ITEM_NOT_FOUND: Item not found in list. 1024 * @retval ::SDK_ERR_LIST_FULL: List is full. 1025 **************************************************************************************** 1026 */ 1027 uint16_t ble_gap_bond_devs_clear(void); 1028 1029 /** 1030 **************************************************************************************** 1031 * @brief Delete a bond device with the specified BD address. 1032 * 1033 * @param[in] p_peer_addr: Pointer to the BD addrss. 1034 * 1035 * @retval ::SDK_SUCCESS: Operation is successful. 1036 * @retval ::SDK_ERR_SDK_INTERNAL: SDK internal error. 1037 * @retval ::SDK_ERR_NVDS_NOT_INIT: NVDS is not initiated. 1038 * @retval ::SDK_ERR_LIST_ITEM_NOT_FOUND: Item not found in list. 1039 * @retval ::SDK_ERR_LIST_FULL: List is full. 1040 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1041 **************************************************************************************** 1042 */ 1043 uint16_t ble_gap_bond_dev_del(const gap_bdaddr_t *p_peer_addr); 1044 1045 /** 1046 **************************************************************************************** 1047 * @brief Get the content of the whole white list. 1048 * 1049 * @param[in] p_whitelist: Pointer to the output white list. 1050 * 1051 * @retval ::SDK_SUCCESS: Operation is successful. 1052 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1053 **************************************************************************************** 1054 */ 1055 uint16_t ble_gap_whitelist_get(white_list_t *p_whitelist); 1056 1057 /** 1058 **************************************************************************************** 1059 * @brief Add the devices into current white list. If white list is full or there are duplicated entries, 1060 * it will return error. 1061 * 1062 * @param[in] p_whitelist: Pointer to input white list. 1063 * 1064 * @retval ::SDK_SUCCESS: Operation is successful. 1065 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1066 * @retval ::SDK_ERR_LIST_ITEM_ALREADY_EXISTED: Item already existed in list. 1067 * @retval ::SDK_ERR_LIST_FULL: List is full. 1068 * @retval ::SDK_ERR_DISALLOWED: Operation is disallowed. 1069 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 1070 * 1071 * @note This API is asynchronous. 1072 * @note @ref gap_cb_fun_t::app_gap_param_set_cb with op_id: @ref GAP_OPCODE_WHITELIST_SET 1073 * will be called once the operation has completed. 1074 **************************************************************************************** 1075 */ 1076 uint16_t ble_gap_whitelist_add(const white_list_t *p_whitelist); 1077 1078 /** 1079 **************************************************************************************** 1080 * @brief Delete the devices out of current white list. If the entries do not exist in the current white list, 1081 * it will return error. 1082 * 1083 * @param[in] p_whitelist: Pointer to input white list. 1084 * 1085 * @retval ::SDK_SUCCESS: Operation is successful. 1086 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1087 * @retval ::SDK_ERR_LIST_ITEM_NOT_FOUND: Item not found in list. 1088 * @retval ::SDK_ERR_DISALLOWED: Operation is disallowed. 1089 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied. 1090 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 1091 * 1092 * @note This API is asynchronous. 1093 * @note @ref gap_cb_fun_t::app_gap_param_set_cb with op_id: @ref GAP_OPCODE_WHITELIST_SET 1094 * will be called once the operation has completed. 1095 **************************************************************************************** 1096 */ 1097 uint16_t ble_gap_whitelist_del(const white_list_t *p_whitelist); 1098 1099 /** 1100 **************************************************************************************** 1101 * @brief Clear all the entries in the current white list. 1102 * 1103 * @retval ::SDK_SUCCESS: Operation is successful. 1104 * @retval ::SDK_ERR_DISALLOWED: Operation is disallowed. 1105 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 1106 * 1107 * @note This API is asynchronous. 1108 * @note @ref gap_cb_fun_t::app_gap_param_set_cb with op_id: @ref GAP_OPCODE_WHITELIST_SET 1109 * will be called once the operation has completed. 1110 **************************************************************************************** 1111 */ 1112 uint16_t ble_gap_whitelist_clear(void); 1113 1114 /** 1115 **************************************************************************************** 1116 * @brief Get the content of the whole periodic advertising list. 1117 * 1118 * @param[in] p_pal_list: Pointer to the output periodic advertising list. 1119 * 1120 * @retval ::SDK_SUCCESS: Operation is successful. 1121 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1122 **************************************************************************************** 1123 */ 1124 uint16_t ble_gap_per_adv_list_get(period_adv_list_t *p_pal_list); 1125 1126 /** 1127 **************************************************************************************** 1128 * @brief Add the devices into current periodic advertising list. If periodic advertising list is full or there are 1129 * duplicated entries, it will return error. 1130 * 1131 * @param[in] p_pal_list: Pointer to input periodic advertising list. 1132 * 1133 * @retval ::SDK_SUCCESS: Operation is successful. 1134 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1135 * @retval ::SDK_ERR_LIST_ITEM_ALREADY_EXISTED: Item already existed in list. 1136 * @retval ::SDK_ERR_LIST_FULL: List is full. 1137 * @retval ::SDK_ERR_DISALLOWED: Operation is disallowed. 1138 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 1139 * 1140 * @note This API is asynchronous. 1141 * @note @ref gap_cb_fun_t::app_gap_param_set_cb with op_id: @ref GAP_OPCODE_PER_ADV_LIST_SET 1142 * will be called once the operation has completed. 1143 **************************************************************************************** 1144 */ 1145 uint16_t ble_gap_per_adv_list_add(const period_adv_list_t *p_pal_list); 1146 1147 /** 1148 **************************************************************************************** 1149 * @brief Delete the devices out of periodic advertising list. If the entries do not exist in the current list, 1150 * an error will be returned. 1151 * 1152 * @param[in] p_pal_list: Pointer to input periodic advertising list. 1153 * 1154 * @retval ::SDK_SUCCESS: Operation is successful. 1155 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1156 * @retval ::SDK_ERR_LIST_ITEM_NOT_FOUND: Item not found in list. 1157 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied. 1158 * @retval ::SDK_ERR_DISALLOWED: Operation is disallowed. 1159 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 1160 * 1161 * @note This API is asynchronous. 1162 * @note @ref gap_cb_fun_t::app_gap_param_set_cb with op_id: @ref GAP_OPCODE_PER_ADV_LIST_SET 1163 * will be called once the operation has completed. 1164 **************************************************************************************** 1165 */ 1166 uint16_t ble_gap_per_adv_list_del(const period_adv_list_t *p_pal_list); 1167 1168 /** 1169 **************************************************************************************** 1170 * @brief Clear all the entries in the current periodic advertising list. 1171 * 1172 * @note This API is asynchronous. 1173 * @note @ref gap_cb_fun_t::app_gap_param_set_cb with op_id: @ref GAP_OPCODE_PER_ADV_LIST_SET 1174 * will be called once the operation has completed. 1175 * 1176 * @retval ::SDK_SUCCESS: Operation is successful. 1177 * @retval ::SDK_ERR_DISALLOWED: Operation is disallowed. 1178 **************************************************************************************** 1179 */ 1180 uint16_t ble_gap_per_adv_list_clear(void); 1181 1182 /** 1183 **************************************************************************************** 1184 * @brief Get the RPA list info. 1185 * @param[in] p_rpa_list: Pointer to the output RPA list. 1186 * 1187 * @retval ::SDK_SUCCESS: Operation is successful. 1188 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1189 **************************************************************************************** 1190 */ 1191 uint16_t ble_gap_rpa_list_get(ral_dev_list_t *p_rpa_list); 1192 1193 /** 1194 **************************************************************************************** 1195 * @brief Get the device information according to param type. 1196 * 1197 * @param[in] type: Param type. 1198 * 1199 * @retval ::SDK_SUCCESS: Operation is successful. 1200 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied. 1201 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 1202 * 1203 * @note This API is asynchronous. 1204 * @note @ref gap_cb_fun_t::app_gap_dev_info_get_cb with the specified op_id (see @ref gap_dev_info_get_type_t) 1205 * will be called once the requested parameters has been got. 1206 **************************************************************************************** 1207 */ 1208 uint16_t ble_gap_dev_info_get(gap_dev_info_get_type_t type); 1209 1210 /** 1211 **************************************************************************************** 1212 * @brief Set parameters for advertising. Note that this function must be called prior to advertising started. 1213 * @param[in] adv_idx: Advertising index, range is 0 to 4. 1214 * @param[in] own_addr_type: Own BD address source of the local device. 1215 * @param[in] p_adv_param: The advertising parameters. 1216 * 1217 * @retval ::SDK_SUCCESS: Operation is successful. 1218 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1219 * @retval ::SDK_ERR_INVALID_ADV_IDX: Invalid advertising index supplied. 1220 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied. 1221 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 1222 * 1223 1224 * @note Discovery mode param contains Flags AD type, setting adv data should not set the Flags AD type. 1225 * @note This API is for legacy advertsing (BT Core Spec version <= 4.2). 1226 **************************************************************************************** 1227 */ 1228 uint16_t ble_gap_adv_param_set(uint8_t adv_idx, gap_own_addr_t own_addr_type, 1229 gap_adv_param_t* p_adv_param); 1230 1231 /** 1232 **************************************************************************************** 1233 * @brief Set extended parameters for advertising. Note that this function must be called prior to advertising. 1234 * @param[in] adv_idx: Advertising index, range is 0 to 4. 1235 * @param[in] own_addr_type: Own BD address source of the local device. 1236 * @param[in] p_adv_param: The advertising parameters. 1237 * 1238 * @retval ::SDK_SUCCESS: Operation is successful. 1239 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1240 * @retval ::SDK_ERR_INVALID_ADV_IDX: Invalid advertising index supplied. 1241 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied. 1242 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 1243 * 1244 * @note This API is for extended and periodic advertising (BT Core Spec version >= 5.0). 1245 **************************************************************************************** 1246 */ 1247 uint16_t ble_gap_ext_adv_param_set(uint8_t adv_idx, gap_own_addr_t own_addr_type, 1248 gap_ext_adv_param_t* p_adv_param); 1249 1250 /** 1251 **************************************************************************************** 1252 * @brief Set Advertising Data, Scan Response Data and Periodic Advertising Data. See ENUM @ref gap_ad_type_t 1253 for ADV Type definitions. See ENUM @ref gap_adv_flags_t for ADV flag definitions. 1254 * 1255 * @param[in] adv_idx: Advertising index, range is 0 to 4. 1256 * @param[in] type: Data type. 1257 * @param[in] p_data: The data pointer. 1258 * @param[in] length: Data length. 1259 * 1260 * @retval ::SDK_SUCCESS: Operation is successful. 1261 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1262 * @retval ::SDK_ERR_INVALID_ADV_IDX: Invalid advertising index supplied. 1263 * @retval ::SDK_ERR_INVALID_ADV_DATA_TYPE: Invalid advertising data type supplied. 1264 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 1265 * 1266 * @note User should not add extra Flags AD type as the BLE Stack has added the Flags AD type already. 1267 **************************************************************************************** 1268 */ 1269 uint16_t ble_gap_adv_data_set(uint8_t adv_idx, gap_adv_data_type_t type, const uint8_t* p_data, 1270 uint16_t length); 1271 1272 /** 1273 **************************************************************************************** 1274 * @brief Update Advertising Data, Scan Response Data and Periodic Advertising Data. See ENUM @ref gap_ad_type_t 1275 * for ADV Type definitions. See ENUM @ref gap_adv_flags_t for ADV flag definitions. 1276 * 1277 * @param[in] adv_idx: Advertising index, range is 0 to 4. 1278 * @param[in] type: Data type. 1279 * @param[in] p_data: The data pointer. 1280 * @param[in] length: Data length. 1281 * 1282 * @retval ::SDK_SUCCESS: Operation is successful. 1283 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1284 * @retval ::SDK_ERR_INVALID_ADV_IDX: Invalid advertising index supplied. 1285 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied. 1286 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 1287 * 1288 * @note User should not add extra Flags AD type as the BLE Stack has added the Flags AD type already. 1289 **************************************************************************************** 1290 */ 1291 uint16_t ble_gap_update_adv_data(uint8_t adv_idx, gap_adv_data_type_t type, const uint8_t* p_data, 1292 uint16_t length); 1293 1294 /** 1295 **************************************************************************************** 1296 * @brief Start advertising. 1297 * @param[in] adv_idx: Advertising index, range is 0 to 4. 1298 * @param[in] p_timeout: Advertising timing parameter. 1299 * 1300 * @retval ::SDK_SUCCESS: Operation is successful. 1301 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1302 * @retval ::SDK_ERR_INVALID_ADV_IDX: Invalid advertising index supplied. 1303 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied. 1304 * @retval ::SDK_ERR_DISALLOWED: Operation is disallowed. 1305 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 1306 * 1307 * @note If advertising mode is directed high duty cycle mode, 1308 * duration should be set nonzero and not be greater than 1.28s. 1309 * @note This API is asynchronous. 1310 * @note If the field scan_req_ind_en in @ref gap_adv_param_t is TRUE passed in @ref ble_gap_adv_param_set function, 1311 or if the GAP_ADV_PROP_SCAN_REQ_NTF_EN_BIT is set in @ref gap_adv_prop_t and 1312 passed in @ref ble_gap_ext_adv_param_set function, 1313 @ref gap_cb_fun_t::app_gap_scan_req_ind_cb will be called once a scan request has been received. 1314 * @note @ref gap_cb_fun_t::app_gap_adv_start_cb will be called once the operation has completed. 1315 **************************************************************************************** 1316 */ 1317 uint16_t ble_gap_adv_start(uint8_t adv_idx, gap_adv_time_param_t* p_timeout); 1318 1319 /** 1320 **************************************************************************************** 1321 * @brief Stop advertising. 1322 * @param[in] adv_idx: Advertising index, range is 0 to 4. 1323 * 1324 * @retval ::SDK_SUCCESS: Operation is successful. 1325 * @retval ::SDK_ERR_INVALID_ADV_IDX: Invalid advertising index supplied. 1326 * @retval ::SDK_ERR_DISALLOWED: Operation is disallowed. 1327 * 1328 * @note This API is asynchronous. 1329 * @note @ref gap_cb_fun_t::app_gap_adv_stop_cb will be called once the operation has completed 1330 * or advertising has been stopped. 1331 **************************************************************************************** 1332 */ 1333 uint16_t ble_gap_adv_stop(uint8_t adv_idx); 1334 1335 /** 1336 **************************************************************************************** 1337 * @brief Set parameters for scanning. Note that this function must be called prior to scanning started. 1338 * @param[in] own_addr_type: Own BD address source of the local device. 1339 * @param[in] p_scan_param: The scanning parameters. 1340 * 1341 * @retval ::SDK_SUCCESS: Operation is successful. 1342 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1343 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied. 1344 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 1345 * 1346 * @note This API is for legacy scanning (BT Core Spec version <= 4.2). 1347 **************************************************************************************** 1348 */ 1349 uint16_t ble_gap_scan_param_set(gap_own_addr_t own_addr_type, gap_scan_param_t* p_scan_param); 1350 1351 /** 1352 **************************************************************************************** 1353 * @brief Set extended parameters for scanning. Note that this function must be called prior to scanning started. 1354 * @param[in] own_addr_type: Own BD address source of the local device. 1355 * @param[in] p_scan_param: The scanning parameters. 1356 * 1357 * @retval ::SDK_SUCCESS: Operation is successful. 1358 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1359 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 1360 * 1361 * @note This API is for extended scanning (BT Core Spec version >= 5.0). 1362 * The Scan window in p_scan_param should be enough to recieve one packet. For example. 1363 * If you want to recieve packects with 1270 bytes on coded phy(S8), the scan_wd should be greater than 82ms. 1364 * If you want to recieve packects with 1270 bytes on coded phy(S2), the scan_wd should be greater than 21ms. 1365 **************************************************************************************** 1366 */ 1367 uint16_t ble_gap_ext_scan_param_set(gap_own_addr_t own_addr_type, 1368 gap_ext_scan_param_t* p_scan_param); 1369 1370 /** 1371 **************************************************************************************** 1372 * @brief Start scanning 1373 * 1374 * @retval ::SDK_SUCCESS: Operation is successful. 1375 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1376 * @retval ::SDK_ERR_DISALLOWED: Operation is disallowed. 1377 * 1378 * @note This API is asynchronous. 1379 * @note @ref gap_cb_fun_t::app_gap_adv_report_ind_cb will be called once the advertising report has been received. 1380 * @note @ref gap_cb_fun_t::app_gap_scan_stop_cb will be called once the scanning has been stopped. 1381 * @note @ref gap_cb_fun_t::app_gap_scan_start_cb will be called once the operation has completed. 1382 **************************************************************************************** 1383 */ 1384 uint16_t ble_gap_scan_start(void); 1385 1386 /** 1387 **************************************************************************************** 1388 * @brief Stop scanning 1389 * 1390 * @retval ::SDK_SUCCESS: Operation is successful. 1391 * @retval ::SDK_ERR_DISALLOWED: Operation is disallowed. 1392 * 1393 * @note This API is asynchronous. 1394 * @note @ref gap_cb_fun_t::app_gap_scan_stop_cb will be called once the operation has completed 1395 * or the scanning has been stopped. 1396 **************************************************************************************** 1397 */ 1398 uint16_t ble_gap_scan_stop(void); 1399 1400 /** 1401 **************************************************************************************** 1402 * @brief Set the parameters used for periodic sync. 1403 * @param[in] per_sync_idx: Periodic synchronization index (range is 0 to 4). 1404 * @param[in] p_per_sync_param: Periodic synchronization parameters. 1405 * 1406 * @retval ::SDK_SUCCESS: Operation is successful. 1407 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1408 * @retval ::SDK_ERR_INVALID_PER_SYNC_IDX: Invalid periodic syncronization index supplied. 1409 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 1410 **************************************************************************************** 1411 */ 1412 uint16_t ble_gap_per_sync_param_set(uint8_t per_sync_idx, gap_per_sync_param_t* p_per_sync_param); 1413 1414 /** 1415 **************************************************************************************** 1416 * @brief Start to synchronize with periodic advertising from an advertiser 1417 * and begin receiving periodic advertising packets. 1418 * @param[in] per_sync_idx: Periodic synchronization index (range is 0 to 4). 1419 * 1420 * @retval ::SDK_SUCCESS: Operation is successful. 1421 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1422 * @retval ::SDK_ERR_INVALID_PER_SYNC_IDX: Invalid periodic syncronization index supplied. 1423 * @retval ::SDK_ERR_DISALLOWED: Operation is disallowed. 1424 * 1425 * @note This API is asynchronous. 1426 * @note @ref gap_cb_fun_t::app_gap_sync_establish_cb will be called 1427 * once the periodic advertising synchronization has been established. 1428 **************************************************************************************** 1429 */ 1430 uint16_t ble_gap_per_sync_start(uint8_t per_sync_idx); 1431 1432 /** 1433 **************************************************************************************** 1434 * @brief Stop periodic synchronization. 1435 * @param[in] per_sync_idx: Periodic synchronization index (range is 0 to 4). 1436 * 1437 * @retval ::SDK_SUCCESS: Operation is successful. 1438 * @retval ::SDK_ERR_INVALID_PER_SYNC_IDX: Invalid periodic syncronization index supplied. 1439 * @retval ::SDK_ERR_DISALLOWED: Operation is disallowed. 1440 * 1441 * @note This API is asynchronous. 1442 * @note @ref gap_cb_fun_t::app_gap_stop_sync_cb will be called once the operation has completed. 1443 **************************************************************************************** 1444 */ 1445 uint16_t ble_gap_per_sync_stop(uint8_t per_sync_idx); 1446 1447 /** 1448 **************************************************************************************** 1449 * @brief Start a legacy connection to a device. 1450 * @param[in] own_addr_type: Own BD address source of the local device. 1451 * @param[in] p_init_param: Initiate parameters. 1452 * 1453 * @retval ::SDK_SUCCESS: Operation is successful. 1454 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1455 * @retval ::SDK_ERR_DISALLOWED: Operation is disallowed. 1456 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 1457 * 1458 * @note This API is for legacy connection (BT Core Spec version <= 4.2). 1459 * 1460 * @note This API is asynchronous. 1461 * @note @ref gap_cb_fun_t::app_gap_connect_cb will be called once the operation has completed 1462 * or the connection has been completed. 1463 * @note @ref gap_cb_fun_t::app_gap_peer_name_ind_cb will be called once the peer name has been got for the 1464 Name Discovery Procedure. See enum @ref GAP_INIT_TYPE_NAME_DISC of type @ref gap_init_type_t. 1465 **************************************************************************************** 1466 */ 1467 uint16_t ble_gap_connect(gap_own_addr_t own_addr_type, gap_init_param_t* p_init_param); 1468 1469 /** 1470 **************************************************************************************** 1471 * @brief Start an extended connection to a device. 1472 * @param[in] own_addr_type: Own BD address source of the local device. 1473 * @param[in] p_init_param: Initiate parameters. 1474 * 1475 * @retval ::SDK_SUCCESS: Operation is successful. 1476 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1477 * @retval ::SDK_ERR_DISALLOWED: Operation is disallowed. 1478 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 1479 * 1480 * @note This API is for extended connection (BT Core Spec version >= 5.0). 1481 * 1482 * @note This API is asynchronous. 1483 * @note @ref gap_cb_fun_t::app_gap_connect_cb will be called once\ 1484 * the operation has completed or the connection has been completed. 1485 **************************************************************************************** 1486 */ 1487 uint16_t ble_gap_ext_connect(gap_own_addr_t own_addr_type, gap_ext_init_param_t* p_init_param); 1488 1489 /** 1490 **************************************************************************************** 1491 * @brief Cancel an initiated connection. 1492 * 1493 * @retval ::SDK_SUCCESS: Operation is successful. 1494 * @retval ::SDK_ERR_DISALLOWED: Operation is disallowed. 1495 * 1496 * @note This API is asynchronous. 1497 * @note @ref gap_cb_fun_t::app_gap_connect_cancel_cb will be called once the operation has completed. 1498 **************************************************************************************** 1499 */ 1500 uint16_t ble_gap_connect_cancel(void); 1501 1502 /** 1503 **************************************************************************************** 1504 * @brief Set GAP appearance value. 1505 * @param[in] appearance: Appearance value. 1506 **************************************************************************************** 1507 */ 1508 void ble_gap_appearance_set(uint16_t appearance); 1509 1510 /** 1511 **************************************************************************************** 1512 * @brief Get GAP appearance value. 1513 * @param[out] p_appearance: The pointer to appearance value. 1514 * 1515 * @retval ::SDK_SUCCESS: Operation is successful. 1516 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1517 **************************************************************************************** 1518 */ 1519 uint16_t ble_gap_appearance_get(uint16_t *p_appearance); 1520 1521 /** 1522 **************************************************************************************** 1523 * @brief Set GAP Peripheral Preferred Connection Parameters present flag. 1524 * 1525 * @param[in] present_flag: Present or not. 1526 **************************************************************************************** 1527 */ 1528 void ble_gap_ppcp_present_set(bool present_flag); 1529 1530 /** 1531 **************************************************************************************** 1532 * @brief Set GAP Peripheral Preferred Connection Parameters. 1533 * @param[in] p_conn_params: The pointer to PPCP values. 1534 * 1535 * @retval ::SDK_SUCCESS: Operation is successful. 1536 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1537 **************************************************************************************** 1538 */ 1539 uint16_t ble_gap_ppcp_set(gap_conn_param_t const *p_conn_params); 1540 1541 /** 1542 **************************************************************************************** 1543 * @brief Get GAP Peripheral Preferred Connection Parameters. 1544 * @param[out] p_conn_params: The pointer to PPCP values. 1545 * 1546 * @retval ::SDK_SUCCESS: Operation is successful. 1547 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1548 **************************************************************************************** 1549 */ 1550 uint16_t ble_gap_ppcp_get(gap_conn_param_t *p_conn_params); 1551 1552 /** 1553 **************************************************************************************** 1554 * @brief Set GAP device name. 1555 * @param[in] write_perm: Write permissions of the device name characteristic. 1556 * @param[in] p_dev_name: The pointer to device name value. If p_dev_name is NULL, 1557 this function will only set write permissions of the device name. 1558 * @param[in] length: Device name length. 1559 * 1560 * @retval ::SDK_SUCCESS: Operation is successful. 1561 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied. 1562 **************************************************************************************** 1563 */ 1564 uint16_t ble_gap_device_name_set(gap_dev_name_write_perm_t write_perm, uint8_t const *p_dev_name, 1565 uint16_t length); 1566 1567 /** 1568 **************************************************************************************** 1569 * @brief Get GAP device name. 1570 * @param[out] p_dev_name: The pointer to device name value, set to NULL to obtain the complete device name length. 1571 * @param[in, out] p_length: Length of the buffer pointed by p_dev_name, complete device name length on output. 1572 * 1573 * @retval ::SDK_SUCCESS: Operation is successful. 1574 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1575 * @retval ::SDK_ERR_INVALID_DATA_LENGTH: Invalid data size(s) supplied. 1576 * 1577 * @note If device name was not set, the default device name "GOODIX_BLE" will be available. 1578 * @note If the device name is longer than the size of the supplied buffer,p_len will return 1579 * the complete device name length, and not the number of bytes actually returned in p_dev_name. 1580 * The application may use this information to allocate a suitable buffer size. 1581 **************************************************************************************** 1582 */ 1583 uint16_t ble_gap_device_name_get(uint8_t *p_dev_name, uint16_t *p_length); 1584 1585 /** 1586 **************************************************************************************** 1587 * @brief Register a LE Protocol/Service Multiplexer. 1588 * @param[in] p_lepsm: The lepsm information to be registerred. 1589 * 1590 * @retval ::SDK_SUCCESS: Operation is successful. 1591 * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied. 1592 * @retval ::SDK_ERR_INVALID_PSM_NUM: Invalid psm number. 1593 * @retval ::SDK_ERR_INVALID_PSM_EXCEEDED_MAX_PSM_NUM: The maximum psm number limit is exceeded. 1594 * @retval ::SDK_ERR_INVALID_PSM_ALREADY_REGISTERED: The psm number has been registered. 1595 * 1596 * @note This API is asynchronous. 1597 * @ref gap_cb_fun_t::app_gap_psm_manager_cb callback with op_id: @ref GAP_OPCODE_LEPSM_REGISTER will be called. 1598 **************************************************************************************** 1599 */ 1600 uint16_t ble_gap_lepsm_register(gap_lepsm_register_t* p_lepsm); 1601 1602 /** 1603 **************************************************************************************** 1604 * @brief Unregister a LE Protocol/Service Multiplexer. 1605 * @param[in] le_psm: LE Protocol/Service Multiplexer (1 to 255). 1606 * 1607 * @retval ::SDK_SUCCESS: Operation is successful. 1608 * @retval ::SDK_ERR_INVALID_PSM_NUM: Invalid psm number. 1609 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 1610 * 1611 * @note This API is asynchronous. 1612 * @note app_gap_psm_manager_cb will be called once the operation has completed, 1613 * @ref gap_cb_fun_t::app_gap_psm_manager_cb callback with op_id: @ref GAP_OPCODE_LEPSM_UNREGISTER will be called. 1614 **************************************************************************************** 1615 */ 1616 uint16_t ble_gap_lepsm_unregister(uint16_t le_psm); 1617 1618 /** 1619 **************************************************************************************** 1620 * @brief Set privacy mode for peer device. 1621 * @param[in] peer_addr: The peer address. 1622 * @param[in] mode: Privacy mode (see @ref privacy_mode_t). 1623 * 1624 * @retval ::SDK_SUCCESS: Operation is successful. 1625 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied. 1626 * @retval ::SDK_ERR_DISALLOWED: Operation is disallowed. 1627 * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources. 1628 * 1629 **************************************************************************************** 1630 */ 1631 uint16_t ble_gap_privacy_mode_set(gap_bdaddr_t peer_addr, privacy_mode_t mode); 1632 1633 /** 1634 **************************************************************************************** 1635 * @brief Read peer or local resolvable address. 1636 * @param[in] op_code: The operation code (see @ref gap_rslv_addr_read_op_id_t). 1637 * @param[in] peer_iden_addr: The peer identity address. 1638 * 1639 * @retval ::SDK_SUCCESS: Operation is successful. 1640 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied. 1641 * 1642 **************************************************************************************** 1643 */ 1644 uint16_t ble_gap_rslv_addr_read(gap_rslv_addr_read_op_id_t op_code, gap_bdaddr_t peer_iden_addr); 1645 1646 /** 1647 ***************************************************************************************** 1648 * @brief Resolve the rpa address. 1649 * 1650 * @param[in] reslv_addr: rpa address. 1651 * @param[in] src_info: Information used retrieve requester (src_info >= 10). 1652 * @param[in] cb: Function that will handle the resolved result. 1653 * 1654 * @retval ::SDK_SUCCESS: Operation is Success. 1655 * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied. 1656 ***************************************************************************************** 1657 */ 1658 uint16_t ble_gap_reslv_rpa_addr(uint8_t *reslv_addr, uint8_t src_info, 1659 reslv_rpa_addr_callback_t cb); 1660 1661 /** 1662 ***************************************************************************************** 1663 * @brief Set the method for updating connection parameter. 1664 * 1665 * @param[in] conn_idx: Connection index. 1666 * @param[in] use_l2cap_flag: Preferred to use l2cap to update connection parameter. 1667 * 1668 * @retval ::SDK_SUCCESS: Operation is Success. 1669 * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied. 1670 ***************************************************************************************** 1671 */ 1672 uint16_t ble_gap_update_conn_param_method_set(uint8_t conn_idx, bool use_l2cap_flag); 1673 1674 /** 1675 ***************************************************************************************** 1676 * @brief Set the cb for rpa address report. 1677 * 1678 * @param[in] cb: the cb for rpa address report. 1679 * 1680 ***************************************************************************************** 1681 */ 1682 void ble_gap_rpa_addr_report_cb_register(rpa_addr_report_callback_t cb); 1683 1684 /** @} */ 1685 1686 #endif 1687 /** @} */ 1688 1689 /** @} */ 1690 /** @} */ 1691