1 /*
2 * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 #ifndef __ESP_GAP_BT_API_H__
8 #define __ESP_GAP_BT_API_H__
9
10 #include <stdint.h>
11 #include "esp_err.h"
12 #include "esp_bt_defs.h"
13
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17
18 /// RSSI threshold
19 #define ESP_BT_GAP_RSSI_HIGH_THRLD -20 /*!< High RSSI threshold */
20 #define ESP_BT_GAP_RSSI_LOW_THRLD -45 /*!< Low RSSI threshold */
21
22 /// Class of device
23 typedef struct {
24 uint32_t reserved_2: 2; /*!< undefined */
25 uint32_t minor: 6; /*!< minor class */
26 uint32_t major: 5; /*!< major class */
27 uint32_t service: 11; /*!< service class */
28 uint32_t reserved_8: 8; /*!< undefined */
29 } esp_bt_cod_t;
30
31 /// class of device settings
32 typedef enum {
33 ESP_BT_SET_COD_MAJOR_MINOR = 0x01, /*!< overwrite major, minor class */
34 ESP_BT_SET_COD_SERVICE_CLASS = 0x02, /*!< set the bits in the input, the current bit will remain */
35 ESP_BT_CLR_COD_SERVICE_CLASS = 0x04, /*!< clear the bits in the input, others will remain */
36 ESP_BT_SET_COD_ALL = 0x08, /*!< overwrite major, minor, set the bits in service class, reserved_2 remain unchanged */
37 ESP_BT_INIT_COD = 0x0a, /*!< overwrite major, minor, and service class, reserved_2 remain unchanged */
38 ESP_BT_SET_COD_RESERVED_2 = 0x10, /*!< overwrite the two least significant bits reserved_2 whose default value is 0b00; other values of reserved_2 are invalid according to Bluetooth Core Specification 5.4 */
39 } esp_bt_cod_mode_t;
40
41 #define ESP_BT_GAP_AFH_CHANNELS_LEN 10
42 typedef uint8_t esp_bt_gap_afh_channels[ESP_BT_GAP_AFH_CHANNELS_LEN];
43
44
45 /// Discoverability and Connectability mode
46 typedef enum {
47 ESP_BT_NON_CONNECTABLE, /*!< Non-connectable */
48 ESP_BT_CONNECTABLE, /*!< Connectable */
49 } esp_bt_connection_mode_t;
50
51 typedef enum {
52 ESP_BT_NON_DISCOVERABLE, /*!< Non-discoverable */
53 ESP_BT_LIMITED_DISCOVERABLE, /*!< Limited Discoverable */
54 ESP_BT_GENERAL_DISCOVERABLE, /*!< General Discoverable */
55 } esp_bt_discovery_mode_t;
56
57 /// Bluetooth Device Property type
58 typedef enum {
59 ESP_BT_GAP_DEV_PROP_BDNAME = 1, /*!< Bluetooth device name, value type is int8_t [] */
60 ESP_BT_GAP_DEV_PROP_COD, /*!< Class of Device, value type is uint32_t */
61 ESP_BT_GAP_DEV_PROP_RSSI, /*!< Received Signal strength Indication, value type is int8_t, ranging from -128 to 127 */
62 ESP_BT_GAP_DEV_PROP_EIR, /*!< Extended Inquiry Response, value type is uint8_t [] */
63 } esp_bt_gap_dev_prop_type_t;
64
65 /// Maximum bytes of Bluetooth device name
66 #define ESP_BT_GAP_MAX_BDNAME_LEN (248)
67
68 /// Maximum size of EIR Significant part
69 #define ESP_BT_GAP_EIR_DATA_LEN (240)
70
71 /// Bluetooth Device Property Descriptor
72 typedef struct {
73 esp_bt_gap_dev_prop_type_t type; /*!< Device property type */
74 int len; /*!< Device property value length */
75 void *val; /*!< Device property value */
76 } esp_bt_gap_dev_prop_t;
77
78 /// Extended Inquiry Response data type
79 #define ESP_BT_EIR_TYPE_FLAGS 0x01 /*!< Flag with information such as BR/EDR and LE support */
80 #define ESP_BT_EIR_TYPE_INCMPL_16BITS_UUID 0x02 /*!< Incomplete list of 16-bit service UUIDs */
81 #define ESP_BT_EIR_TYPE_CMPL_16BITS_UUID 0x03 /*!< Complete list of 16-bit service UUIDs */
82 #define ESP_BT_EIR_TYPE_INCMPL_32BITS_UUID 0x04 /*!< Incomplete list of 32-bit service UUIDs */
83 #define ESP_BT_EIR_TYPE_CMPL_32BITS_UUID 0x05 /*!< Complete list of 32-bit service UUIDs */
84 #define ESP_BT_EIR_TYPE_INCMPL_128BITS_UUID 0x06 /*!< Incomplete list of 128-bit service UUIDs */
85 #define ESP_BT_EIR_TYPE_CMPL_128BITS_UUID 0x07 /*!< Complete list of 128-bit service UUIDs */
86 #define ESP_BT_EIR_TYPE_SHORT_LOCAL_NAME 0x08 /*!< Shortened Local Name */
87 #define ESP_BT_EIR_TYPE_CMPL_LOCAL_NAME 0x09 /*!< Complete Local Name */
88 #define ESP_BT_EIR_TYPE_TX_POWER_LEVEL 0x0a /*!< Tx power level, value is 1 octet ranging from -127 to 127, unit is dBm*/
89 #define ESP_BT_EIR_TYPE_URL 0x24 /*!< Uniform resource identifier */
90 #define ESP_BT_EIR_TYPE_MANU_SPECIFIC 0xff /*!< Manufacturer specific data */
91 #define ESP_BT_EIR_TYPE_MAX_NUM 12 /*!< MAX number of EIR type */
92
93 typedef uint8_t esp_bt_eir_type_t;
94
95 /* ACL Packet Types */
96 #define ESP_BT_ACL_PKT_TYPES_MASK_DM1 0x0008
97 #define ESP_BT_ACL_PKT_TYPES_MASK_DH1 0x0010
98 #define ESP_BT_ACL_PKT_TYPES_MASK_DM3 0x0400
99 #define ESP_BT_ACL_PKT_TYPES_MASK_DH3 0x0800
100 #define ESP_BT_ACL_PKT_TYPES_MASK_DM5 0x4000
101 #define ESP_BT_ACL_PKT_TYPES_MASK_DH5 0x8000
102 #define ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH1 0x0002
103 #define ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH1 0x0004
104 #define ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH3 0x0100
105 #define ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH3 0x0200
106 #define ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH5 0x1000
107 #define ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH5 0x2000
108
109 // DM1 cann not be disabled. All options are mandatory to include DM1.
110 #define ESP_BT_ACL_DM1_ONLY (ESP_BT_ACL_PKT_TYPES_MASK_DM1 | 0x330e) /* 0x330e */
111 #define ESP_BT_ACL_DH1_ONLY (ESP_BT_ACL_PKT_TYPES_MASK_DH1 | 0x330e) /* 0x331e */
112 #define ESP_BT_ACL_DM3_ONLY (ESP_BT_ACL_PKT_TYPES_MASK_DM3 | 0x330e) /* 0x370e */
113 #define ESP_BT_ACL_DH3_ONLY (ESP_BT_ACL_PKT_TYPES_MASK_DH3 | 0x330e) /* 0x3b0e */
114 #define ESP_BT_ACL_DM5_ONLY (ESP_BT_ACL_PKT_TYPES_MASK_DM5 | 0x330e) /* 0x730e */
115 #define ESP_BT_ACL_DH5_ONLY (ESP_BT_ACL_PKT_TYPES_MASK_DH5 | 0x330e) /* 0xb30e */
116 #define ESP_BT_ACL_2_DH1_ONLY (~ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH1 & 0x330e) /* 0x330c */
117 #define ESP_BT_ACL_3_DH1_ONLY (~ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH1 & 0x330e) /* 0x330a */
118 #define ESP_BT_ACL_2_DH3_ONLY (~ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH3 & 0x330e) /* 0x320e */
119 #define ESP_BT_ACL_3_DH3_ONLY (~ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH3 & 0x330e) /* 0x310e */
120 #define ESP_BT_ACL_2_DH5_ONLY (~ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH5 & 0x330e) /* 0x230e */
121 #define ESP_BT_ACL_3_DH5_ONLY (~ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH5 & 0x330e) /* 0x130e */
122
123 typedef uint16_t esp_bt_acl_pkt_type_t;
124
125 /* ESP_BT_EIR_FLAG bit definition */
126 #define ESP_BT_EIR_FLAG_LIMIT_DISC (0x01 << 0)
127 #define ESP_BT_EIR_FLAG_GEN_DISC (0x01 << 1)
128 #define ESP_BT_EIR_FLAG_BREDR_NOT_SPT (0x01 << 2)
129 #define ESP_BT_EIR_FLAG_DMT_CONTROLLER_SPT (0x01 << 3)
130 #define ESP_BT_EIR_FLAG_DMT_HOST_SPT (0x01 << 4)
131
132 #define ESP_BT_EIR_MAX_LEN 240
133 /// EIR data content, according to "Supplement to the Bluetooth Core Specification"
134 typedef struct {
135 bool fec_required; /*!< FEC is required or not, true by default */
136 bool include_txpower; /*!< EIR data include TX power, false by default */
137 bool include_uuid; /*!< EIR data include UUID, false by default */
138 bool include_name; /*!< EIR data include device name, true by default */
139 uint8_t flag; /*!< EIR flags, see ESP_BT_EIR_FLAG for details, EIR will not include flag if it is 0, 0 by default */
140 uint16_t manufacturer_len; /*!< Manufacturer data length, 0 by default */
141 uint8_t *p_manufacturer_data; /*!< Manufacturer data point */
142 uint16_t url_len; /*!< URL length, 0 by default */
143 uint8_t *p_url; /*!< URL point */
144 } esp_bt_eir_data_t;
145
146 /// Major service class field of Class of Device, mutiple bits can be set
147 typedef enum {
148 ESP_BT_COD_SRVC_NONE = 0, /*!< None indicates an invalid value */
149 ESP_BT_COD_SRVC_LMTD_DISCOVER = 0x1, /*!< Limited Discoverable Mode */
150 ESP_BT_COD_SRVC_POSITIONING = 0x8, /*!< Positioning (Location identification) */
151 ESP_BT_COD_SRVC_NETWORKING = 0x10, /*!< Networking, e.g. LAN, Ad hoc */
152 ESP_BT_COD_SRVC_RENDERING = 0x20, /*!< Rendering, e.g. Printing, Speakers */
153 ESP_BT_COD_SRVC_CAPTURING = 0x40, /*!< Capturing, e.g. Scanner, Microphone */
154 ESP_BT_COD_SRVC_OBJ_TRANSFER = 0x80, /*!< Object Transfer, e.g. v-Inbox, v-Folder */
155 ESP_BT_COD_SRVC_AUDIO = 0x100, /*!< Audio, e.g. Speaker, Microphone, Headset service */
156 ESP_BT_COD_SRVC_TELEPHONY = 0x200, /*!< Telephony, e.g. Cordless telephony, Modem, Headset service */
157 ESP_BT_COD_SRVC_INFORMATION = 0x400, /*!< Information, e.g., WEB-server, WAP-server */
158 } esp_bt_cod_srvc_t;
159
160 typedef enum{
161 ESP_BT_PIN_TYPE_VARIABLE = 0, /*!< Refer to BTM_PIN_TYPE_VARIABLE */
162 ESP_BT_PIN_TYPE_FIXED = 1, /*!< Refer to BTM_PIN_TYPE_FIXED */
163 } esp_bt_pin_type_t;
164
165 #define ESP_BT_PIN_CODE_LEN 16 /*!< Max pin code length */
166 typedef uint8_t esp_bt_pin_code_t[ESP_BT_PIN_CODE_LEN]; /*!< Pin Code (upto 128 bits) MSB is 0 */
167
168 typedef enum {
169 ESP_BT_SP_IOCAP_MODE = 0, /*!< Set IO mode */
170 //ESP_BT_SP_OOB_DATA, //TODO /*!< Set OOB data */
171 } esp_bt_sp_param_t;
172
173 /* relate to BTM_IO_CAP_xxx in stack/btm_api.h */
174 #define ESP_BT_IO_CAP_OUT 0 /*!< DisplayOnly */ /* relate to BTM_IO_CAP_OUT in stack/btm_api.h */
175 #define ESP_BT_IO_CAP_IO 1 /*!< DisplayYesNo */ /* relate to BTM_IO_CAP_IO in stack/btm_api.h */
176 #define ESP_BT_IO_CAP_IN 2 /*!< KeyboardOnly */ /* relate to BTM_IO_CAP_IN in stack/btm_api.h */
177 #define ESP_BT_IO_CAP_NONE 3 /*!< NoInputNoOutput */ /* relate to BTM_IO_CAP_NONE in stack/btm_api.h */
178 typedef uint8_t esp_bt_io_cap_t; /*!< Combination of the IO Capability */
179
180
181 /* BTM Power manager modes */
182 #define ESP_BT_PM_MD_ACTIVE 0x00 /*!< Active mode */
183 #define ESP_BT_PM_MD_HOLD 0x01 /*!< Hold mode */
184 #define ESP_BT_PM_MD_SNIFF 0x02 /*!< Sniff mode */
185 #define ESP_BT_PM_MD_PARK 0x03 /*!< Park state */
186 typedef uint8_t esp_bt_pm_mode_t;
187
188
189
190 /// Bits of major service class field
191 #define ESP_BT_COD_SRVC_BIT_MASK (0xffe000) /*!< Major service bit mask */
192 #define ESP_BT_COD_SRVC_BIT_OFFSET (13) /*!< Major service bit offset */
193
194 /// Major device class field of Class of Device
195 typedef enum {
196 ESP_BT_COD_MAJOR_DEV_MISC = 0, /*!< Miscellaneous */
197 ESP_BT_COD_MAJOR_DEV_COMPUTER = 1, /*!< Computer */
198 ESP_BT_COD_MAJOR_DEV_PHONE = 2, /*!< Phone(cellular, cordless, pay phone, modem */
199 ESP_BT_COD_MAJOR_DEV_LAN_NAP = 3, /*!< LAN, Network Access Point */
200 ESP_BT_COD_MAJOR_DEV_AV = 4, /*!< Audio/Video(headset, speaker, stereo, video display, VCR */
201 ESP_BT_COD_MAJOR_DEV_PERIPHERAL = 5, /*!< Peripheral(mouse, joystick, keyboard) */
202 ESP_BT_COD_MAJOR_DEV_IMAGING = 6, /*!< Imaging(printer, scanner, camera, display */
203 ESP_BT_COD_MAJOR_DEV_WEARABLE = 7, /*!< Wearable */
204 ESP_BT_COD_MAJOR_DEV_TOY = 8, /*!< Toy */
205 ESP_BT_COD_MAJOR_DEV_HEALTH = 9, /*!< Health */
206 ESP_BT_COD_MAJOR_DEV_UNCATEGORIZED = 31, /*!< Uncategorized: device not specified */
207 } esp_bt_cod_major_dev_t;
208
209 /// Minor device class field of Class of Device for Peripheral Major Class
210 typedef enum {
211 ESP_BT_COD_MINOR_PERIPHERAL_KEYBOARD = 0x10, /*!< Keyboard */
212 ESP_BT_COD_MINOR_PERIPHERAL_POINTING = 0x20, /*!< Pointing */
213 ESP_BT_COD_MINOR_PERIPHERAL_COMBO = 0x30, /*!< Combo
214 ESP_BT_COD_MINOR_PERIPHERAL_KEYBOARD, ESP_BT_COD_MINOR_PERIPHERAL_POINTING
215 and ESP_BT_COD_MINOR_PERIPHERAL_COMBO can be OR'd with one of the
216 following values to identify a multifunctional device. e.g.
217 ESP_BT_COD_MINOR_PERIPHERAL_KEYBOARD | ESP_BT_COD_MINOR_PERIPHERAL_GAMEPAD
218 ESP_BT_COD_MINOR_PERIPHERAL_POINTING | ESP_BT_COD_MINOR_PERIPHERAL_SENSING_DEVICE
219 */
220 ESP_BT_COD_MINOR_PERIPHERAL_JOYSTICK = 0x01, /*!< Joystick */
221 ESP_BT_COD_MINOR_PERIPHERAL_GAMEPAD = 0x02, /*!< Gamepad */
222 ESP_BT_COD_MINOR_PERIPHERAL_REMOTE_CONTROL = 0x03, /*!< Remote Control */
223 ESP_BT_COD_MINOR_PERIPHERAL_SENSING_DEVICE = 0x04, /*!< Sensing Device */
224 ESP_BT_COD_MINOR_PERIPHERAL_DIGITIZING_TABLET = 0x05, /*!< Digitizing Tablet */
225 ESP_BT_COD_MINOR_PERIPHERAL_CARD_READER = 0x06, /*!< Card Reader */
226 ESP_BT_COD_MINOR_PERIPHERAL_DIGITAL_PAN = 0x07, /*!< Digital Pan */
227 ESP_BT_COD_MINOR_PERIPHERAL_HAND_SCANNER = 0x08, /*!< Hand Scanner */
228 ESP_BT_COD_MINOR_PERIPHERAL_HAND_GESTURAL_INPUT = 0x09, /*!< Hand Gestural Input */
229 } esp_bt_cod_minor_peripheral_t;
230
231 /// Bits of major device class field
232 #define ESP_BT_COD_MAJOR_DEV_BIT_MASK (0x1f00) /*!< Major device bit mask */
233 #define ESP_BT_COD_MAJOR_DEV_BIT_OFFSET (8) /*!< Major device bit offset */
234
235 /// Bits of minor device class field
236 #define ESP_BT_COD_MINOR_DEV_BIT_MASK (0xfc) /*!< Minor device bit mask */
237 #define ESP_BT_COD_MINOR_DEV_BIT_OFFSET (2) /*!< Minor device bit offset */
238
239 /// Bits of format type
240 #define ESP_BT_COD_FORMAT_TYPE_BIT_MASK (0x03) /*!< Format type bit mask */
241 #define ESP_BT_COD_FORMAT_TYPE_BIT_OFFSET (0) /*!< Format type bit offset */
242
243 /// Class of device format type 1
244 #define ESP_BT_COD_FORMAT_TYPE_1 (0x00)
245
246 /** Bluetooth Device Discovery state */
247 typedef enum {
248 ESP_BT_GAP_DISCOVERY_STOPPED, /*!< Device discovery stopped */
249 ESP_BT_GAP_DISCOVERY_STARTED, /*!< Device discovery started */
250 } esp_bt_gap_discovery_state_t;
251
252 /// BT GAP callback events
253 typedef enum {
254 ESP_BT_GAP_DISC_RES_EVT = 0, /*!< Device discovery result event */
255 ESP_BT_GAP_DISC_STATE_CHANGED_EVT, /*!< Discovery state changed event */
256 ESP_BT_GAP_RMT_SRVCS_EVT, /*!< Get remote services event */
257 ESP_BT_GAP_RMT_SRVC_REC_EVT, /*!< Get remote service record event */
258 ESP_BT_GAP_AUTH_CMPL_EVT, /*!< Authentication complete event */
259 ESP_BT_GAP_PIN_REQ_EVT, /*!< Legacy Pairing Pin code request */
260 ESP_BT_GAP_CFM_REQ_EVT, /*!< Security Simple Pairing User Confirmation request. */
261 ESP_BT_GAP_KEY_NOTIF_EVT, /*!< Security Simple Pairing Passkey Notification */
262 ESP_BT_GAP_KEY_REQ_EVT, /*!< Security Simple Pairing Passkey request */
263 ESP_BT_GAP_READ_RSSI_DELTA_EVT, /*!< Read rssi event */
264 ESP_BT_GAP_CONFIG_EIR_DATA_EVT, /*!< Config EIR data event */
265 ESP_BT_GAP_SET_AFH_CHANNELS_EVT, /*!< Set AFH channels event */
266 ESP_BT_GAP_READ_REMOTE_NAME_EVT, /*!< Read Remote Name event */
267 ESP_BT_GAP_MODE_CHG_EVT,
268 ESP_BT_GAP_REMOVE_BOND_DEV_COMPLETE_EVT, /*!< remove bond device complete event */
269 ESP_BT_GAP_QOS_CMPL_EVT, /*!< QOS complete event */
270 ESP_BT_GAP_ACL_CONN_CMPL_STAT_EVT, /*!< ACL connection complete status event */
271 ESP_BT_GAP_ACL_DISCONN_CMPL_STAT_EVT, /*!< ACL disconnection complete status event */
272 ESP_BT_GAP_ACL_PKT_TYPE_CHANGED_EVT, /*!< Set ACL packet types event */
273 ESP_BT_GAP_EVT_MAX,
274 } esp_bt_gap_cb_event_t;
275
276 /** Inquiry Mode */
277 typedef enum {
278 ESP_BT_INQ_MODE_GENERAL_INQUIRY, /*!< General inquiry mode */
279 ESP_BT_INQ_MODE_LIMITED_INQUIRY, /*!< Limited inquiry mode */
280 } esp_bt_inq_mode_t;
281
282 /** Minimum and Maximum inquiry length*/
283 #define ESP_BT_GAP_MIN_INQ_LEN (0x01) /*!< Minimum inquiry duration, unit is 1.28s */
284 #define ESP_BT_GAP_MAX_INQ_LEN (0x30) /*!< Maximum inquiry duration, unit is 1.28s */
285
286 /** Minimum, Default and Maximum poll interval **/
287 #define ESP_BT_GAP_TPOLL_MIN (0x0006) /*!< Minimum poll interval, unit is 625 microseconds */
288 #define ESP_BT_GAP_TPOLL_DFT (0x0028) /*!< Default poll interval, unit is 625 microseconds */
289 #define ESP_BT_GAP_TPOLL_MAX (0x1000) /*!< Maximum poll interval, unit is 625 microseconds */
290
291 /// GAP state callback parameters
292 typedef union {
293 /**
294 * @brief ESP_BT_GAP_DISC_RES_EVT
295 */
296 struct disc_res_param {
297 esp_bd_addr_t bda; /*!< remote bluetooth device address*/
298 int num_prop; /*!< number of properties got */
299 esp_bt_gap_dev_prop_t *prop; /*!< properties discovered from the new device */
300 } disc_res; /*!< discovery result parameter struct */
301
302 /**
303 * @brief ESP_BT_GAP_DISC_STATE_CHANGED_EVT
304 */
305 struct disc_state_changed_param {
306 esp_bt_gap_discovery_state_t state; /*!< discovery state */
307 } disc_st_chg; /*!< discovery state changed parameter struct */
308
309 /**
310 * @brief ESP_BT_GAP_RMT_SRVCS_EVT
311 */
312 struct rmt_srvcs_param {
313 esp_bd_addr_t bda; /*!< remote bluetooth device address*/
314 esp_bt_status_t stat; /*!< service search status */
315 int num_uuids; /*!< number of UUID in uuid_list */
316 esp_bt_uuid_t *uuid_list; /*!< list of service UUIDs of remote device */
317 } rmt_srvcs; /*!< services of remote device parameter struct */
318
319 /**
320 * @brief ESP_BT_GAP_RMT_SRVC_REC_EVT
321 */
322 struct rmt_srvc_rec_param {
323 esp_bd_addr_t bda; /*!< remote bluetooth device address*/
324 esp_bt_status_t stat; /*!< service search status */
325 } rmt_srvc_rec; /*!< specific service record from remote device parameter struct */
326
327 /**
328 * @brief ESP_BT_GAP_READ_RSSI_DELTA_EVT *
329 */
330 struct read_rssi_delta_param {
331 esp_bd_addr_t bda; /*!< remote bluetooth device address*/
332 esp_bt_status_t stat; /*!< read rssi status */
333 int8_t rssi_delta; /*!< rssi delta value range -128 ~127, The value zero indicates that the RSSI is inside the Golden Receive Power Range, the Golden Receive Power Range is from ESP_BT_GAP_RSSI_LOW_THRLD to ESP_BT_GAP_RSSI_HIGH_THRLD */
334 } read_rssi_delta; /*!< read rssi parameter struct */
335
336 /**
337 * @brief ESP_BT_GAP_CONFIG_EIR_DATA_EVT *
338 */
339 struct config_eir_data_param {
340 esp_bt_status_t stat; /*!< config EIR status:
341 ESP_BT_STATUS_SUCCESS: config success
342 ESP_BT_STATUS_EIR_TOO_LARGE: the EIR data is more than 240B. The EIR may not contain the whole data.
343 others: failed
344 */
345 uint8_t eir_type_num; /*!< the number of EIR types in EIR type */
346 esp_bt_eir_type_t eir_type[ESP_BT_EIR_TYPE_MAX_NUM]; /*!< EIR types in EIR type */
347 } config_eir_data; /*!< config EIR data */
348
349 /**
350 * @brief ESP_BT_GAP_AUTH_CMPL_EVT
351 */
352 struct auth_cmpl_param {
353 esp_bd_addr_t bda; /*!< remote bluetooth device address*/
354 esp_bt_status_t stat; /*!< authentication complete status */
355 uint8_t device_name[ESP_BT_GAP_MAX_BDNAME_LEN + 1]; /*!< device name */
356 } auth_cmpl; /*!< authentication complete parameter struct */
357
358 /**
359 * @brief ESP_BT_GAP_PIN_REQ_EVT
360 */
361 struct pin_req_param {
362 esp_bd_addr_t bda; /*!< remote bluetooth device address*/
363 bool min_16_digit; /*!< TRUE if the pin returned must be at least 16 digits */
364 } pin_req; /*!< pin request parameter struct */
365
366 /**
367 * @brief ESP_BT_GAP_CFM_REQ_EVT
368 */
369 struct cfm_req_param {
370 esp_bd_addr_t bda; /*!< remote bluetooth device address*/
371 uint32_t num_val; /*!< the numeric value for comparison. */
372 } cfm_req; /*!< confirm request parameter struct */
373
374 /**
375 * @brief ESP_BT_GAP_KEY_NOTIF_EVT
376 */
377 struct key_notif_param {
378 esp_bd_addr_t bda; /*!< remote bluetooth device address*/
379 uint32_t passkey; /*!< the numeric value for passkey entry. */
380 } key_notif; /*!< passkey notif parameter struct */
381
382 /**
383 * @brief ESP_BT_GAP_KEY_REQ_EVT
384 */
385 struct key_req_param {
386 esp_bd_addr_t bda; /*!< remote bluetooth device address*/
387 } key_req; /*!< passkey request parameter struct */
388
389 /**
390 * @brief ESP_BT_GAP_SET_AFH_CHANNELS_EVT
391 */
392 struct set_afh_channels_param {
393 esp_bt_status_t stat; /*!< set AFH channel status */
394 } set_afh_channels; /*!< set AFH channel parameter struct */
395
396 /**
397 * @brief ESP_BT_GAP_READ_REMOTE_NAME_EVT
398 */
399 struct read_rmt_name_param {
400 esp_bd_addr_t bda; /*!< remote bluetooth device address*/
401 esp_bt_status_t stat; /*!< read Remote Name status */
402 uint8_t rmt_name[ESP_BT_GAP_MAX_BDNAME_LEN + 1]; /*!< Remote device name */
403 } read_rmt_name; /*!< read Remote Name parameter struct */
404
405 /**
406 * @brief ESP_BT_GAP_MODE_CHG_EVT
407 */
408 struct mode_chg_param {
409 esp_bd_addr_t bda; /*!< remote bluetooth device address */
410 esp_bt_pm_mode_t mode; /*!< PM mode */
411 uint16_t interval; /*!< Number of baseband slots. unit is 0.625ms */
412 } mode_chg; /*!< mode change event parameter struct */
413
414 /**
415 * @brief ESP_BT_GAP_REMOVE_BOND_DEV_COMPLETE_EVT
416 */
417 struct bt_remove_bond_dev_cmpl_evt_param {
418 esp_bd_addr_t bda; /*!< remote bluetooth device address*/
419 esp_bt_status_t status; /*!< Indicate the remove bond device operation success status */
420 }remove_bond_dev_cmpl; /*!< Event parameter of ESP_BT_GAP_REMOVE_BOND_DEV_COMPLETE_EVT */
421
422 /**
423 * @brief ESP_BT_GAP_QOS_CMPL_EVT
424 */
425 struct qos_cmpl_param {
426 esp_bt_status_t stat; /*!< QoS status */
427 esp_bd_addr_t bda; /*!< remote bluetooth device address*/
428 uint32_t t_poll; /*!< poll interval, the maximum time between transmissions
429 which from the master to a particular slave on the ACL
430 logical transport. unit is 0.625ms. */
431 } qos_cmpl; /*!< QoS complete parameter struct */
432
433 /**
434 * @brief ESP_BT_GAP_ACL_PKT_TYPE_CHANGED_EVT
435 */
436 struct set_acl_pkt_types_param {
437 esp_bt_status_t status; /*!< set ACL packet types status */
438 esp_bd_addr_t bda; /*!< remote bluetooth device address */
439 uint16_t pkt_types; /*!< packet types successfully set */
440 } set_acl_pkt_types; /*!< set ACL packet types parameter struct */
441
442 /**
443 * @brief ESP_BT_GAP_ACL_CONN_CMPL_STAT_EVT
444 */
445 struct acl_conn_cmpl_stat_param {
446 esp_bt_status_t stat; /*!< ACL connection status */
447 uint16_t handle; /*!< ACL connection handle */
448 esp_bd_addr_t bda; /*!< remote bluetooth device address */
449 } acl_conn_cmpl_stat; /*!< ACL connection complete status parameter struct */
450
451 /**
452 * @brief ESP_BT_GAP_ACL_DISCONN_CMPL_STAT_EVT
453 */
454 struct acl_disconn_cmpl_stat_param {
455 esp_bt_status_t reason; /*!< ACL disconnection reason */
456 uint16_t handle; /*!< ACL connection handle */
457 esp_bd_addr_t bda; /*!< remote bluetooth device address */
458 } acl_disconn_cmpl_stat; /*!< ACL disconnection complete status parameter struct */
459 } esp_bt_gap_cb_param_t;
460
461 /**
462 * @brief bluetooth GAP callback function type
463 *
464 * @param event : Event type
465 *
466 * @param param : Pointer to callback parameter
467 */
468 typedef void (* esp_bt_gap_cb_t)(esp_bt_gap_cb_event_t event, esp_bt_gap_cb_param_t *param);
469
470 /**
471 * @brief get major service field of COD
472 *
473 * @param[in] cod: Class of Device
474 *
475 * @return major service bits
476 */
esp_bt_gap_get_cod_srvc(uint32_t cod)477 static inline uint32_t esp_bt_gap_get_cod_srvc(uint32_t cod)
478 {
479 return (cod & ESP_BT_COD_SRVC_BIT_MASK) >> ESP_BT_COD_SRVC_BIT_OFFSET;
480 }
481
482 /**
483 * @brief get major device field of COD
484 *
485 * @param[in] cod: Class of Device
486 *
487 * @return major device bits
488 */
esp_bt_gap_get_cod_major_dev(uint32_t cod)489 static inline uint32_t esp_bt_gap_get_cod_major_dev(uint32_t cod)
490 {
491 return (cod & ESP_BT_COD_MAJOR_DEV_BIT_MASK) >> ESP_BT_COD_MAJOR_DEV_BIT_OFFSET;
492 }
493
494 /**
495 * @brief get minor service field of COD
496 *
497 * @param[in] cod: Class of Device
498 *
499 * @return minor service bits
500 */
esp_bt_gap_get_cod_minor_dev(uint32_t cod)501 static inline uint32_t esp_bt_gap_get_cod_minor_dev(uint32_t cod)
502 {
503 return (cod & ESP_BT_COD_MINOR_DEV_BIT_MASK) >> ESP_BT_COD_MINOR_DEV_BIT_OFFSET;
504 }
505
506 /**
507 * @brief get format type of COD
508 *
509 * @param[in] cod: Class of Device
510 *
511 * @return format type
512 */
esp_bt_gap_get_cod_format_type(uint32_t cod)513 static inline uint32_t esp_bt_gap_get_cod_format_type(uint32_t cod)
514 {
515 return (cod & ESP_BT_COD_FORMAT_TYPE_BIT_MASK);
516 }
517
518 /**
519 * @brief decide the integrity of COD
520 *
521 * @param[in] cod: Class of Device
522 *
523 * @return
524 * - true if cod is valid
525 * - false otherise
526 */
esp_bt_gap_is_valid_cod(uint32_t cod)527 static inline bool esp_bt_gap_is_valid_cod(uint32_t cod)
528 {
529 if (esp_bt_gap_get_cod_format_type(cod) == ESP_BT_COD_FORMAT_TYPE_1 &&
530 esp_bt_gap_get_cod_srvc(cod) != ESP_BT_COD_SRVC_NONE) {
531 return true;
532 }
533
534 return false;
535 }
536
537 /**
538 * @brief register callback function. This function should be called after esp_bluedroid_enable() completes successfully
539 *
540 * @return
541 * - ESP_OK : Succeed
542 * - ESP_FAIL: others
543 */
544 esp_err_t esp_bt_gap_register_callback(esp_bt_gap_cb_t callback);
545
546 /**
547 * @brief Set discoverability and connectability mode for legacy bluetooth. This function should
548 * be called after esp_bluedroid_enable() completes successfully
549 *
550 * @param[in] c_mode : one of the enums of esp_bt_connection_mode_t
551 *
552 * @param[in] d_mode : one of the enums of esp_bt_discovery_mode_t
553 *
554 * @return
555 * - ESP_OK : Succeed
556 * - ESP_ERR_INVALID_ARG: if argument invalid
557 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
558 * - ESP_FAIL: others
559 */
560 esp_err_t esp_bt_gap_set_scan_mode(esp_bt_connection_mode_t c_mode, esp_bt_discovery_mode_t d_mode);
561
562 /**
563 * @brief This function starts Inquiry and Name Discovery. This function should be called after esp_bluedroid_enable() completes successfully.
564 * When Inquiry is halted and cached results do not contain device name, then Name Discovery will connect to the peer target to get the device name.
565 * esp_bt_gap_cb_t will be called with ESP_BT_GAP_DISC_STATE_CHANGED_EVT when Inquiry is started or Name Discovery is completed.
566 * esp_bt_gap_cb_t will be called with ESP_BT_GAP_DISC_RES_EVT each time the two types of discovery results are got.
567 *
568 * @param[in] mode - Inquiry mode
569 *
570 * @param[in] inq_len - Inquiry duration in 1.28 sec units, ranging from 0x01 to 0x30. This parameter only specifies the total duration of the Inquiry process,
571 * - when this time expires, Inquiry will be halted.
572 *
573 * @param[in] num_rsps - Number of responses that can be received before the Inquiry is halted, value 0 indicates an unlimited number of responses.
574 *
575 * @return
576 * - ESP_OK : Succeed
577 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
578 * - ESP_ERR_INVALID_ARG: if invalid parameters are provided
579 * - ESP_FAIL: others
580 */
581 esp_err_t esp_bt_gap_start_discovery(esp_bt_inq_mode_t mode, uint8_t inq_len, uint8_t num_rsps);
582
583 /**
584 * @brief Cancel Inquiry and Name Discovery. This function should be called after esp_bluedroid_enable() completes successfully.
585 * esp_bt_gap_cb_t will be called with ESP_BT_GAP_DISC_STATE_CHANGED_EVT if Inquiry or Name Discovery is cancelled by
586 * calling this function.
587 *
588 * @return
589 * - ESP_OK : Succeed
590 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
591 * - ESP_FAIL: others
592 */
593 esp_err_t esp_bt_gap_cancel_discovery(void);
594
595 /**
596 * @brief Start SDP to get remote services. This function should be called after esp_bluedroid_enable() completes successfully.
597 * esp_bt_gap_cb_t will be called with ESP_BT_GAP_RMT_SRVCS_EVT after service discovery ends.
598 *
599 * @return
600 * - ESP_OK : Succeed
601 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
602 * - ESP_FAIL: others
603 */
604 esp_err_t esp_bt_gap_get_remote_services(esp_bd_addr_t remote_bda);
605
606 /**
607 * @brief Start SDP to look up the service matching uuid on the remote device. This function should be called after
608 * esp_bluedroid_enable() completes successfully.
609 *
610 * esp_bt_gap_cb_t will be called with ESP_BT_GAP_RMT_SRVC_REC_EVT after service discovery ends
611 * @return
612 * - ESP_OK : Succeed
613 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
614 * - ESP_FAIL: others
615 */
616 esp_err_t esp_bt_gap_get_remote_service_record(esp_bd_addr_t remote_bda, esp_bt_uuid_t *uuid);
617
618 /**
619 * @brief This function is called to get EIR data for a specific type.
620 *
621 * @param[in] eir - pointer of raw eir data to be resolved
622 * @param[in] type - specific EIR data type
623 * @param[out] length - return the length of EIR data excluding fields of length and data type
624 *
625 * @return pointer of starting position of eir data excluding eir data type, NULL if not found
626 *
627 */
628 uint8_t *esp_bt_gap_resolve_eir_data(uint8_t *eir, esp_bt_eir_type_t type, uint8_t *length);
629
630 /**
631 * @brief This function is called to config EIR data.
632 *
633 * esp_bt_gap_cb_t will be called with ESP_BT_GAP_CONFIG_EIR_DATA_EVT after config EIR ends.
634 *
635 * @param[in] eir_data - pointer of EIR data content
636 * @return
637 * - ESP_OK : Succeed
638 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
639 * - ESP_ERR_INVALID_ARG: if param is invalid
640 * - ESP_FAIL: others
641 */
642 esp_err_t esp_bt_gap_config_eir_data(esp_bt_eir_data_t *eir_data);
643
644 /**
645 * @brief This function is called to set class of device.
646 * The structure esp_bt_gap_cb_t will be called with ESP_BT_GAP_SET_COD_EVT after set COD ends.
647 * This function should be called after Bluetooth profiles are initialized, otherwise the user configured
648 * class of device can be overwritten.
649 * Some profiles have special restrictions on class of device, and changes may make these profiles unable to work.
650 *
651 * @param[in] cod - class of device
652 * @param[in] mode - setting mode
653 *
654 * @return
655 * - ESP_OK : Succeed
656 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
657 * - ESP_ERR_INVALID_ARG: if param is invalid
658 * - ESP_FAIL: others
659 */
660 esp_err_t esp_bt_gap_set_cod(esp_bt_cod_t cod, esp_bt_cod_mode_t mode);
661
662 /**
663 * @brief This function is called to get class of device.
664 *
665 * @param[out] cod - class of device
666 *
667 * @return
668 * - ESP_OK : Succeed
669 * - ESP_FAIL: others
670 */
671 esp_err_t esp_bt_gap_get_cod(esp_bt_cod_t *cod);
672
673 /**
674 * @brief This function is called to read RSSI delta by address after connected. The RSSI value returned by ESP_BT_GAP_READ_RSSI_DELTA_EVT.
675 *
676 *
677 * @param[in] remote_addr - remote device address, corresponding to a certain connection handle
678 * @return
679 * - ESP_OK : Succeed
680 * - ESP_FAIL: others
681 *
682 */
683 esp_err_t esp_bt_gap_read_rssi_delta(esp_bd_addr_t remote_addr);
684
685 /**
686 * @brief Removes a device from the security database list of
687 * peer device.
688 *
689 * @param[in] bd_addr : BD address of the peer device
690 *
691 * @return - ESP_OK : success
692 * - ESP_FAIL : failed
693 *
694 */
695 esp_err_t esp_bt_gap_remove_bond_device(esp_bd_addr_t bd_addr);
696
697 /**
698 * @brief Get the device number from the security database list of peer device.
699 * It will return the device bonded number immediately.
700 *
701 * @return - >= 0 : bonded devices number
702 * - ESP_FAIL : failed
703 *
704 */
705 int esp_bt_gap_get_bond_device_num(void);
706
707 /**
708 * @brief Get the device from the security database list of peer device.
709 * It will return the device bonded information immediately.
710 *
711 * @param[inout] dev_num: Indicate the dev_list array(buffer) size as input.
712 * If dev_num is large enough, it means the actual number as output.
713 * Suggest that dev_num value equal to esp_ble_get_bond_device_num().
714 *
715 * @param[out] dev_list: an array(buffer) of `esp_bd_addr_t` type. Use for storing the bonded devices address.
716 * The dev_list should be allocated by who call this API.
717 *
718 * @return
719 * - ESP_OK : Succeed
720 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
721 * - ESP_FAIL: others
722 */
723 esp_err_t esp_bt_gap_get_bond_device_list(int *dev_num, esp_bd_addr_t *dev_list);
724
725 /**
726 * @brief Set pin type and default pin code for legacy pairing.
727 *
728 * @param[in] pin_type: Use variable or fixed pin.
729 * If pin_type is ESP_BT_PIN_TYPE_VARIABLE, pin_code and pin_code_len
730 * will be ignored, and ESP_BT_GAP_PIN_REQ_EVT will come when control
731 * requests for pin code.
732 * Else, will use fixed pin code and not callback to users.
733 *
734 * @param[in] pin_code_len: Length of pin_code
735 *
736 * @param[in] pin_code: Pin_code
737 *
738 * @return - ESP_OK : success
739 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
740 * - other : failed
741 */
742 esp_err_t esp_bt_gap_set_pin(esp_bt_pin_type_t pin_type, uint8_t pin_code_len, esp_bt_pin_code_t pin_code);
743
744 /**
745 * @brief Reply the pin_code to the peer device for legacy pairing
746 * when ESP_BT_GAP_PIN_REQ_EVT is coming.
747 *
748 * @param[in] bd_addr: BD address of the peer
749 *
750 * @param[in] accept: Pin_code reply successful or declined.
751 *
752 * @param[in] pin_code_len: Length of pin_code
753 *
754 * @param[in] pin_code: Pin_code
755 *
756 * @return - ESP_OK : success
757 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
758 * - other : failed
759 */
760 esp_err_t esp_bt_gap_pin_reply(esp_bd_addr_t bd_addr, bool accept, uint8_t pin_code_len, esp_bt_pin_code_t pin_code);
761
762 #if (BT_SSP_INCLUDED == TRUE)
763 /**
764 * @brief Set a GAP security parameter value. Overrides the default value.
765 *
766 * @param[in] param_type : the type of the param which is to be set
767 *
768 * @param[in] value : the param value
769 *
770 * @param[in] len : the length of the param value
771 *
772 * @return - ESP_OK : success
773 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
774 * - other : failed
775 *
776 */
777 esp_err_t esp_bt_gap_set_security_param(esp_bt_sp_param_t param_type,
778 void *value, uint8_t len);
779
780 /**
781 * @brief Reply the key value to the peer device in the legacy connection stage.
782 *
783 * @param[in] bd_addr : BD address of the peer
784 *
785 * @param[in] accept : passkey entry successful or declined.
786 *
787 * @param[in] passkey : passkey value, must be a 6 digit number, can be lead by 0.
788 *
789 * @return - ESP_OK : success
790 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
791 * - other : failed
792 *
793 */
794 esp_err_t esp_bt_gap_ssp_passkey_reply(esp_bd_addr_t bd_addr, bool accept, uint32_t passkey);
795
796
797 /**
798 * @brief Reply the confirm value to the peer device in the legacy connection stage.
799 *
800 * @param[in] bd_addr : BD address of the peer device
801 *
802 * @param[in] accept : numbers to compare are the same or different
803 *
804 * @return - ESP_OK : success
805 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
806 * - other : failed
807 *
808 */
809 esp_err_t esp_bt_gap_ssp_confirm_reply(esp_bd_addr_t bd_addr, bool accept);
810
811 #endif /*(BT_SSP_INCLUDED == TRUE)*/
812
813 /**
814 * @brief Set the AFH channels
815 *
816 * @param[in] channels : The n th such field (in the range 0 to 78) contains the value for channel n :
817 * 0 means channel n is bad.
818 * 1 means channel n is unknown.
819 * The most significant bit is reserved and shall be set to 0.
820 * At least 20 channels shall be marked as unknown.
821 *
822 * @return - ESP_OK : success
823 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
824 * - other : failed
825 *
826 */
827 esp_err_t esp_bt_gap_set_afh_channels(esp_bt_gap_afh_channels channels);
828
829 /**
830 * @brief Read the remote device name
831 *
832 * @param[in] remote_bda: The remote device's address
833 *
834 * @return - ESP_OK : success
835 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
836 * - other : failed
837 *
838 */
839 esp_err_t esp_bt_gap_read_remote_name(esp_bd_addr_t remote_bda);
840
841 /**
842 * @brief Config Quality of service
843 *
844 * @param[in] remote_bda: The remote device's address
845 * @param[in] t_poll: Poll interval, the maximum time between transmissions
846 which from the master to a particular slave on the ACL
847 logical transport. unit is 0.625ms
848 *
849 * @return - ESP_OK : success
850 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
851 * - other : failed
852 *
853 */
854 esp_err_t esp_bt_gap_set_qos(esp_bd_addr_t remote_bda, uint32_t t_poll);
855
856 /**
857 * @brief Set ACL packet types. FOR INTERNAL TESTING ONLY.
858 * An ESP_BT_GAP_SET_ACL_PPKT_TYPES_EVT event will reported to
859 * the APP layer.
860 *
861 * @return - ESP_OK: success
862 * - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
863 * - other: failed
864 */
865 esp_err_t esp_bt_gap_set_acl_pkt_types(esp_bd_addr_t remote_bda, esp_bt_acl_pkt_type_t pkt_types);
866
867 #ifdef __cplusplus
868 }
869 #endif
870
871 #endif /* __ESP_GAP_BT_API_H__ */
872
