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