Classic Bluetooth® GAP API

API Reference

Header File

components/bt/host/bluedroid/api/include/api/esp_gap_bt_api.h
This header file can be included with:
#include "esp_gap_bt_api.h"
This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:
REQUIRES bt
or
PRIV_REQUIRES bt

Functions

static inline uint32_t esp_bt_gap_get_cod_srvc(uint32_t cod)

get major service field of COD

Parameters: cod -- [in] Class of Device
Returns: major service bits

static inline uint32_t esp_bt_gap_get_cod_major_dev(uint32_t cod)

get major device field of COD

Parameters: cod -- [in] Class of Device
Returns: major device bits

static inline uint32_t esp_bt_gap_get_cod_minor_dev(uint32_t cod)

get minor service field of COD

Parameters: cod -- [in] Class of Device
Returns: minor service bits

static inline uint32_t esp_bt_gap_get_cod_format_type(uint32_t cod)

get format type of COD

Parameters: cod -- [in] Class of Device
Returns: format type

static inline bool esp_bt_gap_is_valid_cod(uint32_t cod)

decide the integrity of COD

Parameters

cod -- [in] Class of Device

Returns

true if cod is valid
false otherwise

esp_err_t esp_bt_gap_register_callback(esp_bt_gap_cb_t callback)

register callback function. This function should be called after esp_bluedroid_enable() completes successfully

Returns

ESP_OK : Succeed
ESP_FAIL: others

esp_err_t esp_bt_gap_set_scan_mode(esp_bt_connection_mode_t c_mode, esp_bt_discovery_mode_t d_mode)

Set discoverability and connectability mode for legacy bluetooth. This function should be called after esp_bluedroid_enable() completes successfully.

Parameters

c_mode -- [in] : one of the enums of esp_bt_connection_mode_t
d_mode -- [in] : one of the enums of esp_bt_discovery_mode_t

Returns

ESP_OK : Succeed
ESP_ERR_INVALID_ARG: if argument invalid
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: others

esp_err_t esp_bt_gap_start_discovery(esp_bt_inq_mode_t mode, uint8_t inq_len, uint8_t num_rsps)

This function starts Inquiry and Name Discovery. This function should be called after esp_bluedroid_enable() completes successfully. 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. 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. 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.

Parameters

mode -- [in] - Inquiry mode
inq_len -- [in] - Inquiry duration in 1.28 sec units, ranging from 0x01 to 0x30. This parameter only specifies the total duration of the Inquiry process,
- when this time expires, Inquiry will be halted.
num_rsps -- [in] - Number of responses that can be received before the Inquiry is halted, value 0 indicates an unlimited number of responses.

Returns

ESP_OK : Succeed
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_ERR_INVALID_ARG: if invalid parameters are provided
ESP_FAIL: others

esp_err_t esp_bt_gap_cancel_discovery(void)

Cancel Inquiry and Name Discovery. This function should be called after esp_bluedroid_enable() completes successfully. esp_bt_gap_cb_t will be called with ESP_BT_GAP_DISC_STATE_CHANGED_EVT if Inquiry or Name Discovery is cancelled by calling this function.

Returns

ESP_OK : Succeed
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: others

esp_err_t esp_bt_gap_get_remote_services(esp_bd_addr_t remote_bda)

Start SDP to get remote services. This function should be called after esp_bluedroid_enable() completes successfully. esp_bt_gap_cb_t will be called with ESP_BT_GAP_RMT_SRVCS_EVT after service discovery ends.

Returns

ESP_OK : Succeed
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: others

esp_err_t esp_bt_gap_get_remote_service_record(esp_bd_addr_t remote_bda, esp_bt_uuid_t *uuid)

Start SDP to look up the service matching uuid on the remote device. This function should be called after esp_bluedroid_enable() completes successfully.

esp_bt_gap_cb_t will be called with ESP_BT_GAP_RMT_SRVC_REC_EVT after service discovery ends

Returns

ESP_OK : Succeed
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: others

uint8_t *esp_bt_gap_resolve_eir_data(uint8_t *eir, esp_bt_eir_type_t type, uint8_t *length)

This function is called to get EIR data for a specific type.

Parameters

eir -- [in] - pointer of raw eir data to be resolved
type -- [in] - specific EIR data type
length -- [out] - return the length of EIR data excluding fields of length and data type

Returns

pointer of starting position of eir data excluding eir data type, NULL if not found

esp_err_t esp_bt_gap_config_eir_data(esp_bt_eir_data_t *eir_data)

This function is called to config EIR data.

             esp_bt_gap_cb_t will be called with ESP_BT_GAP_CONFIG_EIR_DATA_EVT after config EIR ends.

Parameters

eir_data -- [in] - pointer of EIR data content

Returns

ESP_OK : Succeed
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_ERR_INVALID_ARG: if param is invalid
ESP_FAIL: others

esp_err_t esp_bt_gap_set_cod(esp_bt_cod_t cod, esp_bt_cod_mode_t mode)

This function is called to set class of device. The structure esp_bt_gap_cb_t will be called with ESP_BT_GAP_SET_COD_EVT after set COD ends. This function should be called after Bluetooth profiles are initialized, otherwise the user configured class of device can be overwritten. Some profiles have special restrictions on class of device, and changes may make these profiles unable to work.

Parameters

cod -- [in] - class of device
mode -- [in] - setting mode

Returns

ESP_OK : Succeed
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_ERR_INVALID_ARG: if param is invalid
ESP_FAIL: others

esp_err_t esp_bt_gap_get_cod(esp_bt_cod_t *cod)

This function is called to get class of device.

Parameters

cod -- [out] - class of device

Returns

ESP_OK : Succeed
ESP_FAIL: others

esp_err_t esp_bt_gap_read_rssi_delta(esp_bd_addr_t remote_addr)

This function is called to read RSSI delta by address after connected. The RSSI value returned by ESP_BT_GAP_READ_RSSI_DELTA_EVT.

Parameters

remote_addr -- [in] - remote device address, corresponding to a certain connection handle

Returns

ESP_OK : Succeed
ESP_FAIL: others

esp_err_t esp_bt_gap_remove_bond_device(esp_bd_addr_t bd_addr)

Removes a device from the security database list of peer device.

Parameters

bd_addr -- [in] : BD address of the peer device

Returns

- ESP_OK : success

ESP_FAIL : failed

int esp_bt_gap_get_bond_device_num(void)

Get the device number from the security database list of peer device. It will return the device bonded number immediately.

Returns

- >= 0 : bonded devices number

ESP_FAIL : failed

esp_err_t esp_bt_gap_get_bond_device_list(int *dev_num, esp_bd_addr_t *dev_list)

Get the device from the security database list of peer device. It will return the device bonded information immediately.

Parameters

dev_num -- [inout] Indicate the dev_list array(buffer) size as input. If dev_num is large enough, it means the actual number as output. Suggest that dev_num value equal to esp_ble_get_bond_device_num().
dev_list -- [out] an array(buffer) of esp_bd_addr_t type. Use for storing the bonded devices address. The dev_list should be allocated by who call this API.

Returns

ESP_OK : Succeed
ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
ESP_FAIL: others

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)

Set pin type and default pin code for legacy pairing.

Parameters

pin_type -- [in] Use variable or fixed pin. If pin_type is ESP_BT_PIN_TYPE_VARIABLE, pin_code and pin_code_len will be ignored, and ESP_BT_GAP_PIN_REQ_EVT will come when control requests for pin code. Else, will use fixed pin code and not callback to users.
pin_code_len -- [in] Length of pin_code
pin_code -- [in] Pin_code

Returns

- ESP_OK : success

ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
other : failed

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)

Reply the pin_code to the peer device for legacy pairing when ESP_BT_GAP_PIN_REQ_EVT is coming.

Parameters

bd_addr -- [in] BD address of the peer
accept -- [in] Pin_code reply successful or declined.
pin_code_len -- [in] Length of pin_code
pin_code -- [in] Pin_code

Returns

- ESP_OK : success

ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
other : failed

esp_err_t esp_bt_gap_set_security_param(esp_bt_sp_param_t param_type, void *value, uint8_t len)

Set a GAP security parameter value. Overrides the default value.

Parameters

param_type -- [in] : the type of the param which is to be set
value -- [in] : the param value
len -- [in] : the length of the param value

Returns

- ESP_OK : success

ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
other : failed

esp_err_t esp_bt_gap_ssp_passkey_reply(esp_bd_addr_t bd_addr, bool accept, uint32_t passkey)

Reply the key value to the peer device in the legacy connection stage.

Parameters

bd_addr -- [in] : BD address of the peer
accept -- [in] : passkey entry successful or declined.
passkey -- [in] : passkey value, must be a 6 digit number, can be lead by 0.

Returns

- ESP_OK : success

ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
other : failed

esp_err_t esp_bt_gap_ssp_confirm_reply(esp_bd_addr_t bd_addr, bool accept)

Reply the confirm value to the peer device in the legacy connection stage.

Parameters

bd_addr -- [in] : BD address of the peer device
accept -- [in] : numbers to compare are the same or different

Returns

- ESP_OK : success

ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
other : failed

esp_err_t esp_bt_gap_set_afh_channels(esp_bt_gap_afh_channels channels)

Set the AFH channels.

Parameters

channels -- [in] : The n th such field (in the range 0 to 78) contains the value for channel n : 0 means channel n is bad. 1 means channel n is unknown. The most significant bit is reserved and shall be set to 0. At least 20 channels shall be marked as unknown.

Returns

- ESP_OK : success

ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
other : failed

esp_err_t esp_bt_gap_read_remote_name(esp_bd_addr_t remote_bda)

Read the remote device name.

Parameters

remote_bda -- [in] The remote device's address

Returns

- ESP_OK : success

ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
other : failed

esp_err_t esp_bt_gap_set_qos(esp_bd_addr_t remote_bda, uint32_t t_poll)

Config Quality of service.

Parameters

remote_bda -- [in] The remote device's address
t_poll -- [in] Poll interval, the maximum time between transmissions which from the master to a particular slave on the ACL logical transport. unit is 0.625ms

Returns

- ESP_OK : success

ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
other : failed

esp_err_t esp_bt_gap_set_page_timeout(uint16_t page_to)

Set the page timeout esp_bt_gap_cb_t will be called with ESP_BT_GAP_SET_PAGE_TO_EVT after set page timeout ends. The value to be set will not be effective util the next page procedure, it's suggested to set the page timeout before initiating a connection.

Parameters

page_to -- [in] Page timeout, the maximum time the master will wait for a Base-band page response from the remote device at a locally initiated connection attempt. The valid range is 0x0016 ~ 0xffff, the default value is 0x2000, unit is 0.625ms.

Returns

- ESP_OK: success

ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
other: failed

esp_err_t esp_bt_gap_get_page_timeout(void)

Get the page timeout esp_bt_gap_cb_t will be called with ESP_BT_GAP_GET_PAGE_TO_EVT after get page timeout ends.

Returns

- ESP_OK: success

ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
other: failed

esp_err_t esp_bt_gap_set_acl_pkt_types(esp_bd_addr_t remote_bda, esp_bt_acl_pkt_type_t pkt_types)

Set ACL packet types An ESP_BT_GAP_SET_ACL_PPKT_TYPES_EVT event will reported to the APP layer.

Returns

- ESP_OK: success

ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
other: failed

esp_err_t esp_bt_gap_set_min_enc_key_size(uint8_t key_size)

Set the minimal size of encryption key.

Returns

- ESP_OK: success

ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
other: failed

esp_err_t esp_bt_gap_set_device_name(const char *name)

Set device name to the local device.

Parameters

name -- [in] - device name.

Returns

ESP_OK : success
other : failed

esp_err_t esp_bt_gap_get_device_name(void)

Get device name of the local device.

Returns

ESP_OK : success
other : failed

Unions

union esp_bt_gap_cb_param_t

#include <esp_gap_bt_api.h>

GAP state callback parameters.

Public Members

struct esp_bt_gap_cb_param_t::disc_res_param disc_res: discovery result parameter struct

struct esp_bt_gap_cb_param_t::disc_state_changed_param disc_st_chg: discovery state changed parameter struct

struct esp_bt_gap_cb_param_t::rmt_srvcs_param rmt_srvcs: services of remote device parameter struct

struct esp_bt_gap_cb_param_t::rmt_srvc_rec_param rmt_srvc_rec: specific service record from remote device parameter struct

struct esp_bt_gap_cb_param_t::read_rssi_delta_param read_rssi_delta: read rssi parameter struct

struct esp_bt_gap_cb_param_t::config_eir_data_param config_eir_data: config EIR data

struct esp_bt_gap_cb_param_t::auth_cmpl_param auth_cmpl: authentication complete parameter struct

struct esp_bt_gap_cb_param_t::enc_chg_param enc_chg: encryption change parameter struct

struct esp_bt_gap_cb_param_t::pin_req_param pin_req: pin request parameter struct

struct esp_bt_gap_cb_param_t::cfm_req_param cfm_req: confirm request parameter struct

struct esp_bt_gap_cb_param_t::key_notif_param key_notif: passkey notif parameter struct

struct esp_bt_gap_cb_param_t::key_req_param key_req: passkey request parameter struct

struct esp_bt_gap_cb_param_t::set_afh_channels_param set_afh_channels: set AFH channel parameter struct

struct esp_bt_gap_cb_param_t::read_rmt_name_param read_rmt_name: read Remote Name parameter struct

struct esp_bt_gap_cb_param_t::mode_chg_param mode_chg: mode change event parameter struct

struct esp_bt_gap_cb_param_t::bt_remove_bond_dev_cmpl_evt_param remove_bond_dev_cmpl: Event parameter of ESP_BT_GAP_REMOVE_BOND_DEV_COMPLETE_EVT

struct esp_bt_gap_cb_param_t::qos_cmpl_param qos_cmpl: QoS complete parameter struct

struct esp_bt_gap_cb_param_t::page_to_set_param set_page_timeout: set page timeout parameter struct

struct esp_bt_gap_cb_param_t::page_to_get_param get_page_timeout: get page timeout parameter struct

struct esp_bt_gap_cb_param_t::set_acl_pkt_types_param set_acl_pkt_types: set ACL packet types parameter struct

struct esp_bt_gap_cb_param_t::set_min_enc_key_size_param set_min_enc_key_size: set minimum encryption key size parameter struct

struct esp_bt_gap_cb_param_t::acl_conn_cmpl_stat_param acl_conn_cmpl_stat: ACL connection complete status parameter struct

struct esp_bt_gap_cb_param_t::acl_disconn_cmpl_stat_param acl_disconn_cmpl_stat: ACL disconnection complete status parameter struct

struct esp_bt_gap_cb_param_t::get_dev_name_cmpl_evt_param get_dev_name_cmpl: Get device name complete status parameter struct

struct acl_conn_cmpl_stat_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_ACL_CONN_CMPL_STAT_EVT.

Public Members

esp_bt_status_t stat: ACL connection status

uint16_t handle: ACL connection handle

esp_bd_addr_t bda: remote bluetooth device address

struct acl_disconn_cmpl_stat_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_ACL_DISCONN_CMPL_STAT_EVT.

Public Members

esp_bt_status_t reason: ACL disconnection reason

uint16_t handle: ACL connection handle

esp_bd_addr_t bda: remote bluetooth device address

struct auth_cmpl_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_AUTH_CMPL_EVT.

Public Members

esp_bd_addr_t bda: remote bluetooth device address

esp_bt_status_t stat: authentication complete status

esp_bt_link_key_type_t lk_type: type of link key generated

uint8_t device_name[ESP_BT_GAP_MAX_BDNAME_LEN + 1]: device name

struct bt_remove_bond_dev_cmpl_evt_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_REMOVE_BOND_DEV_COMPLETE_EVT.

Public Members

esp_bd_addr_t bda: remote bluetooth device address

esp_bt_status_t status: Indicate the remove bond device operation success status

struct cfm_req_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_CFM_REQ_EVT.

Public Members

esp_bd_addr_t bda: remote bluetooth device address

uint32_t num_val: the numeric value for comparison.

struct config_eir_data_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_CONFIG_EIR_DATA_EVT *.

Public Members

esp_bt_status_t stat: config EIR status: ESP_BT_STATUS_SUCCESS: config success ESP_BT_STATUS_EIR_TOO_LARGE: the EIR data is more than 240B. The EIR may not contain the whole data. others: failed

uint8_t eir_type_num: the number of EIR types in EIR type

esp_bt_eir_type_t eir_type[ESP_BT_EIR_TYPE_MAX_NUM]: EIR types in EIR type

struct disc_res_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_DISC_RES_EVT.

Public Members

esp_bd_addr_t bda: remote bluetooth device address

int num_prop: number of properties got

esp_bt_gap_dev_prop_t *prop: properties discovered from the new device

struct disc_state_changed_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_DISC_STATE_CHANGED_EVT.

Public Members

esp_bt_gap_discovery_state_t state: discovery state

struct enc_chg_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_ENC_CHG_EVT.

Public Members

esp_bd_addr_t bda: remote bluetooth device address

esp_bt_enc_mode_t enc_mode: encryption mode

struct get_dev_name_cmpl_evt_param

#include <esp_gap_bt_api.h>

ESP_GAP_BT_GET_DEV_NAME_CMPL_EVT.

Public Members

esp_bt_status_t status: Indicate the get device name success status

char *name: Name of bluetooth device

struct key_notif_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_KEY_NOTIF_EVT.

Public Members

esp_bd_addr_t bda: remote bluetooth device address

uint32_t passkey: the numeric value for passkey entry.

struct key_req_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_KEY_REQ_EVT.

Public Members

esp_bd_addr_t bda: remote bluetooth device address

struct mode_chg_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_MODE_CHG_EVT.

Public Members

esp_bd_addr_t bda: remote bluetooth device address

esp_bt_pm_mode_t mode: PM mode

uint16_t interval: Number of baseband slots. unit is 0.625ms

struct page_to_get_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_GET_PAGE_TO_EVT.

Public Members

esp_bt_status_t stat: get page timeout status

uint16_t page_to: page_timeout value to be set, unit is 0.625ms.

struct page_to_set_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_SET_PAGE_TO_EVT.

Public Members

esp_bt_status_t stat: set page timeout status

struct pin_req_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_PIN_REQ_EVT.

Public Members

esp_bd_addr_t bda: remote bluetooth device address

bool min_16_digit: TRUE if the pin returned must be at least 16 digits

struct qos_cmpl_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_QOS_CMPL_EVT.

Public Members

esp_bt_status_t stat: QoS status

esp_bd_addr_t bda: remote bluetooth device address

uint32_t t_poll: poll interval, the maximum time between transmissions which from the master to a particular slave on the ACL logical transport. unit is 0.625ms.

struct read_rmt_name_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_READ_REMOTE_NAME_EVT.

Public Members

esp_bd_addr_t bda: remote bluetooth device address

esp_bt_status_t stat: read Remote Name status

uint8_t rmt_name[ESP_BT_GAP_MAX_BDNAME_LEN + 1]: Remote device name

struct read_rssi_delta_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_READ_RSSI_DELTA_EVT *.

Public Members

esp_bd_addr_t bda: remote bluetooth device address

esp_bt_status_t stat: read rssi status

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

struct rmt_srvc_rec_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_RMT_SRVC_REC_EVT.

Public Members

esp_bd_addr_t bda: remote bluetooth device address

esp_bt_status_t stat: service search status

struct rmt_srvcs_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_RMT_SRVCS_EVT.

Public Members

esp_bd_addr_t bda: remote bluetooth device address

esp_bt_status_t stat: service search status

int num_uuids: number of UUID in uuid_list

esp_bt_uuid_t *uuid_list: list of service UUIDs of remote device

struct set_acl_pkt_types_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_ACL_PKT_TYPE_CHANGED_EVT.

Public Members

esp_bt_status_t status: set ACL packet types status

esp_bd_addr_t bda: remote bluetooth device address

uint16_t pkt_types: packet types successfully set

struct set_afh_channels_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_SET_AFH_CHANNELS_EVT.

Public Members

esp_bt_status_t stat: set AFH channel status

struct set_min_enc_key_size_param

#include <esp_gap_bt_api.h>

ESP_BT_GAP_SET_MIN_ENC_KEY_SIZE_EVT.

Public Members

esp_bt_status_t status: set minimum encryption key size status

Structures

struct esp_bt_cod_t

Class of device.

Public Members

uint32_t reserved_2: undefined

uint32_t minor: minor class

uint32_t major: major class

uint32_t service: service class

uint32_t reserved_8: undefined

struct esp_bt_gap_dev_prop_t

Bluetooth Device Property Descriptor.

Public Members

esp_bt_gap_dev_prop_type_t type: Device property type

int len: Device property value length

void *val: Device property value

struct esp_bt_eir_data_t

EIR data content, according to "Supplement to the Bluetooth Core Specification".

Public Members

bool fec_required: FEC is required or not, true by default

bool include_txpower: EIR data include TX power, false by default

bool include_uuid: EIR data include UUID, false by default

bool include_name: EIR data include device name, true by default

uint8_t flag: EIR flags, see ESP_BT_EIR_FLAG for details, EIR will not include flag if it is 0, 0 by default

uint16_t manufacturer_len: Manufacturer data length, 0 by default

uint8_t *p_manufacturer_data: Manufacturer data point

uint16_t url_len: URL length, 0 by default

uint8_t *p_url: URL point

Macros

ESP_BT_GAP_RSSI_HIGH_THRLD

RSSI threshold.

High RSSI threshold

ESP_BT_GAP_RSSI_LOW_THRLD: Low RSSI threshold

ESP_BT_GAP_AFH_CHANNELS_LEN

ESP_BT_GAP_MAX_BDNAME_LEN: Maximum bytes of Bluetooth device name.

ESP_BT_GAP_EIR_DATA_LEN: Maximum size of EIR Significant part.

ESP_BT_EIR_TYPE_FLAGS

Extended Inquiry Response data type.

Flag with information such as BR/EDR and LE support

ESP_BT_EIR_TYPE_INCMPL_16BITS_UUID: Incomplete list of 16-bit service UUIDs

ESP_BT_EIR_TYPE_CMPL_16BITS_UUID: Complete list of 16-bit service UUIDs

ESP_BT_EIR_TYPE_INCMPL_32BITS_UUID: Incomplete list of 32-bit service UUIDs

ESP_BT_EIR_TYPE_CMPL_32BITS_UUID: Complete list of 32-bit service UUIDs

ESP_BT_EIR_TYPE_INCMPL_128BITS_UUID: Incomplete list of 128-bit service UUIDs

ESP_BT_EIR_TYPE_CMPL_128BITS_UUID: Complete list of 128-bit service UUIDs

ESP_BT_EIR_TYPE_SHORT_LOCAL_NAME: Shortened Local Name

ESP_BT_EIR_TYPE_CMPL_LOCAL_NAME: Complete Local Name

ESP_BT_EIR_TYPE_TX_POWER_LEVEL: Tx power level, value is 1 octet ranging from -127 to 127, unit is dBm

ESP_BT_EIR_TYPE_URL: Uniform resource identifier

ESP_BT_EIR_TYPE_MANU_SPECIFIC: Manufacturer specific data

ESP_BT_EIR_TYPE_MAX_NUM: MAX number of EIR type

ESP_BT_ACL_PKT_TYPES_MASK_DM1

ESP_BT_ACL_PKT_TYPES_MASK_DH1

ESP_BT_ACL_PKT_TYPES_MASK_DM3

ESP_BT_ACL_PKT_TYPES_MASK_DH3

ESP_BT_ACL_PKT_TYPES_MASK_DM5

ESP_BT_ACL_PKT_TYPES_MASK_DH5

ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH1

ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH1

ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH3

ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH3

ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH5

ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH5

ESP_BT_ACL_DM1_ONLY

ESP_BT_ACL_DH1_ONLY

ESP_BT_ACL_DM3_ONLY

ESP_BT_ACL_DH3_ONLY

ESP_BT_ACL_DM5_ONLY

ESP_BT_ACL_DH5_ONLY

ESP_BT_ACL_2_DH1_ONLY

ESP_BT_ACL_3_DH1_ONLY

ESP_BT_ACL_2_DH3_ONLY

ESP_BT_ACL_3_DH3_ONLY

ESP_BT_ACL_2_DH5_ONLY

ESP_BT_ACL_3_DH5_ONLY

ESP_BT_ENC_KEY_SIZE_CTRL_MAX

ESP_BT_ENC_KEY_SIZE_CTRL_MIN

ESP_BT_EIR_FLAG_LIMIT_DISC

ESP_BT_EIR_FLAG_GEN_DISC

ESP_BT_EIR_FLAG_BREDR_NOT_SPT

ESP_BT_EIR_FLAG_DMT_CONTROLLER_SPT

ESP_BT_EIR_FLAG_DMT_HOST_SPT

ESP_BT_EIR_MAX_LEN

ESP_BT_PIN_CODE_LEN: Max pin code length

ESP_BT_IO_CAP_OUT

ESP_BT_IO_CAP_IO

ESP_BT_IO_CAP_IN

ESP_BT_IO_CAP_NONE

ESP_BT_PM_MD_ACTIVE: Active mode

ESP_BT_PM_MD_HOLD: Hold mode

ESP_BT_PM_MD_SNIFF: Sniff mode

ESP_BT_PM_MD_PARK: Park state

ESP_BT_COD_SRVC_BIT_MASK

Bits of major service class field.

Major service bit mask

ESP_BT_COD_SRVC_BIT_OFFSET: Major service bit offset

ESP_BT_COD_MAJOR_DEV_BIT_MASK

Bits of major device class field.

Major device bit mask

ESP_BT_COD_MAJOR_DEV_BIT_OFFSET: Major device bit offset

ESP_BT_COD_MINOR_DEV_BIT_MASK

Bits of minor device class field.

Minor device bit mask

ESP_BT_COD_MINOR_DEV_BIT_OFFSET: Minor device bit offset

ESP_BT_COD_FORMAT_TYPE_BIT_MASK

Bits of format type.

Format type bit mask

ESP_BT_COD_FORMAT_TYPE_BIT_OFFSET: Format type bit offset

ESP_BT_COD_FORMAT_TYPE_1: Class of device format type 1.

ESP_BT_LINK_KEY_COMB

Type of link key.

Combination Key

ESP_BT_LINK_KEY_DBG_COMB: Debug Combination Key

ESP_BT_LINK_KEY_UNAUTHED_COMB_P192: Unauthenticated Combination Key generated from P-192

ESP_BT_LINK_KEY_AUTHED_COMB_P192: Authenticated Combination Key generated from P-192

ESP_BT_LINK_KEY_CHG_COMB: Changed Combination Key

ESP_BT_LINK_KEY_UNAUTHED_COMB_P256: Unauthenticated Combination Key generated from P-256

ESP_BT_LINK_KEY_AUTHED_COMB_P256: Authenticated Combination Key generated from P-256

ESP_BT_ENC_MODE_OFF

Type of encryption.

Link Level Encryption is OFF

ESP_BT_ENC_MODE_E0: Link Level Encryption is ON with E0

ESP_BT_ENC_MODE_AES: Link Level Encryption is ON with AES-CCM

ESP_BT_GAP_MIN_INQ_LEN: Minimum and Maximum inquiry length Minimum inquiry duration, unit is 1.28s

ESP_BT_GAP_MAX_INQ_LEN: Maximum inquiry duration, unit is 1.28s

ESP_BT_GAP_TPOLL_MIN: Minimum, Default and Maximum poll interval Minimum poll interval, unit is 625 microseconds

ESP_BT_GAP_TPOLL_DFT: Default poll interval, unit is 625 microseconds

ESP_BT_GAP_TPOLL_MAX: Maximum poll interval, unit is 625 microseconds

Type Definitions

typedef uint8_t esp_bt_gap_afh_channels[ESP_BT_GAP_AFH_CHANNELS_LEN]

typedef uint8_t esp_bt_eir_type_t

typedef uint16_t esp_bt_acl_pkt_type_t

typedef uint8_t esp_bt_pin_code_t[ESP_BT_PIN_CODE_LEN]: Pin Code (upto 128 bits) MSB is 0

typedef uint8_t esp_bt_io_cap_t: Combination of the IO Capability

typedef uint8_t esp_bt_pm_mode_t

typedef uint8_t esp_bt_link_key_type_t

typedef uint8_t esp_bt_enc_mode_t

typedef void (*esp_bt_gap_cb_t)(esp_bt_gap_cb_event_t event, esp_bt_gap_cb_param_t *param)

bluetooth GAP callback function type

Param event: : Event type
Param param: : Pointer to callback parameter

Enumerations

enum esp_bt_cod_mode_t

class of device settings

Values:

enumerator ESP_BT_SET_COD_MAJOR_MINOR: overwrite major, minor class

enumerator ESP_BT_SET_COD_SERVICE_CLASS: set the bits in the input, the current bit will remain

enumerator ESP_BT_CLR_COD_SERVICE_CLASS: clear the bits in the input, others will remain

enumerator ESP_BT_SET_COD_ALL: overwrite major, minor, set the bits in service class, reserved_2 remain unchanged

enumerator ESP_BT_INIT_COD: overwrite major, minor, and service class, reserved_2 remain unchanged

enumerator ESP_BT_SET_COD_RESERVED_2: 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

enum esp_bt_connection_mode_t

Discoverability and Connectability mode.

Values:

enumerator ESP_BT_NON_CONNECTABLE: Non-connectable

enumerator ESP_BT_CONNECTABLE: Connectable

enum esp_bt_discovery_mode_t

Values:

enumerator ESP_BT_NON_DISCOVERABLE: Non-discoverable

enumerator ESP_BT_LIMITED_DISCOVERABLE: Limited Discoverable

enumerator ESP_BT_GENERAL_DISCOVERABLE: General Discoverable

enum esp_bt_gap_dev_prop_type_t

Bluetooth Device Property type.

Values:

enumerator ESP_BT_GAP_DEV_PROP_BDNAME: Bluetooth device name, value type is int8_t []

enumerator ESP_BT_GAP_DEV_PROP_COD: Class of Device, value type is uint32_t

enumerator ESP_BT_GAP_DEV_PROP_RSSI: Received Signal strength Indication, value type is int8_t, ranging from -128 to 127

enumerator ESP_BT_GAP_DEV_PROP_EIR: Extended Inquiry Response, value type is uint8_t []

enum esp_bt_cod_srvc_t

Major service class field of Class of Device, multiple bits can be set.

Values:

enumerator ESP_BT_COD_SRVC_NONE: None indicates an invalid value

enumerator ESP_BT_COD_SRVC_LMTD_DISCOVER: Limited Discoverable Mode

enumerator ESP_BT_COD_SRVC_POSITIONING: Positioning (Location identification)

enumerator ESP_BT_COD_SRVC_NETWORKING: Networking, e.g. LAN, Ad hoc

enumerator ESP_BT_COD_SRVC_RENDERING: Rendering, e.g. Printing, Speakers

enumerator ESP_BT_COD_SRVC_CAPTURING: Capturing, e.g. Scanner, Microphone

enumerator ESP_BT_COD_SRVC_OBJ_TRANSFER: Object Transfer, e.g. v-Inbox, v-Folder

enumerator ESP_BT_COD_SRVC_AUDIO: Audio, e.g. Speaker, Microphone, Headset service

enumerator ESP_BT_COD_SRVC_TELEPHONY: Telephony, e.g. Cordless telephony, Modem, Headset service

enumerator ESP_BT_COD_SRVC_INFORMATION: Information, e.g., WEB-server, WAP-server

enum esp_bt_pin_type_t

Values:

enumerator ESP_BT_PIN_TYPE_VARIABLE: Refer to BTM_PIN_TYPE_VARIABLE

enumerator ESP_BT_PIN_TYPE_FIXED: Refer to BTM_PIN_TYPE_FIXED

enum esp_bt_sp_param_t

Values:

enumerator ESP_BT_SP_IOCAP_MODE: Set IO mode

enum esp_bt_cod_major_dev_t

Major device class field of Class of Device.

Values:

enumerator ESP_BT_COD_MAJOR_DEV_MISC: Miscellaneous

enumerator ESP_BT_COD_MAJOR_DEV_COMPUTER: Computer

enumerator ESP_BT_COD_MAJOR_DEV_PHONE: Phone(cellular, cordless, pay phone, modem

enumerator ESP_BT_COD_MAJOR_DEV_LAN_NAP: LAN, Network Access Point

enumerator ESP_BT_COD_MAJOR_DEV_AV: Audio/Video(headset, speaker, stereo, video display, VCR

enumerator ESP_BT_COD_MAJOR_DEV_PERIPHERAL: Peripheral(mouse, joystick, keyboard)

enumerator ESP_BT_COD_MAJOR_DEV_IMAGING: Imaging(printer, scanner, camera, display

enumerator ESP_BT_COD_MAJOR_DEV_WEARABLE: Wearable

enumerator ESP_BT_COD_MAJOR_DEV_TOY: Toy

enumerator ESP_BT_COD_MAJOR_DEV_HEALTH: Health

enumerator ESP_BT_COD_MAJOR_DEV_UNCATEGORIZED: Uncategorized: device not specified

enum esp_bt_cod_minor_peripheral_t

Minor device class field of Class of Device for Peripheral Major Class.

Values:

enumerator ESP_BT_COD_MINOR_PERIPHERAL_KEYBOARD: Keyboard

enumerator ESP_BT_COD_MINOR_PERIPHERAL_POINTING: Pointing

enumerator ESP_BT_COD_MINOR_PERIPHERAL_COMBO: Combo ESP_BT_COD_MINOR_PERIPHERAL_KEYBOARD, ESP_BT_COD_MINOR_PERIPHERAL_POINTING and ESP_BT_COD_MINOR_PERIPHERAL_COMBO can be OR'd with one of the following values to identify a multifunctional device. e.g. ESP_BT_COD_MINOR_PERIPHERAL_KEYBOARD | ESP_BT_COD_MINOR_PERIPHERAL_GAMEPAD ESP_BT_COD_MINOR_PERIPHERAL_POINTING | ESP_BT_COD_MINOR_PERIPHERAL_SENSING_DEVICE

enumerator ESP_BT_COD_MINOR_PERIPHERAL_JOYSTICK: Joystick

enumerator ESP_BT_COD_MINOR_PERIPHERAL_GAMEPAD: Gamepad

enumerator ESP_BT_COD_MINOR_PERIPHERAL_REMOTE_CONTROL: Remote Control

enumerator ESP_BT_COD_MINOR_PERIPHERAL_SENSING_DEVICE: Sensing Device

enumerator ESP_BT_COD_MINOR_PERIPHERAL_DIGITIZING_TABLET: Digitizing Tablet

enumerator ESP_BT_COD_MINOR_PERIPHERAL_CARD_READER: Card Reader

enumerator ESP_BT_COD_MINOR_PERIPHERAL_DIGITAL_PAN: Digital Pan

enumerator ESP_BT_COD_MINOR_PERIPHERAL_HAND_SCANNER: Hand Scanner

enumerator ESP_BT_COD_MINOR_PERIPHERAL_HAND_GESTURAL_INPUT: Hand Gestural Input

enum esp_bt_gap_discovery_state_t

Bluetooth Device Discovery state

Values:

enumerator ESP_BT_GAP_DISCOVERY_STOPPED: Device discovery stopped

enumerator ESP_BT_GAP_DISCOVERY_STARTED: Device discovery started

enum esp_bt_gap_cb_event_t

BT GAP callback events.

Values:

enumerator ESP_BT_GAP_DISC_RES_EVT: Device discovery result event

enumerator ESP_BT_GAP_DISC_STATE_CHANGED_EVT: Discovery state changed event

enumerator ESP_BT_GAP_RMT_SRVCS_EVT: Get remote services event

enumerator ESP_BT_GAP_RMT_SRVC_REC_EVT: Get remote service record event

enumerator ESP_BT_GAP_AUTH_CMPL_EVT: Authentication complete event

enumerator ESP_BT_GAP_PIN_REQ_EVT: Legacy Pairing Pin code request

enumerator ESP_BT_GAP_CFM_REQ_EVT: Security Simple Pairing User Confirmation request.

enumerator ESP_BT_GAP_KEY_NOTIF_EVT: Security Simple Pairing Passkey Notification

enumerator ESP_BT_GAP_KEY_REQ_EVT: Security Simple Pairing Passkey request

enumerator ESP_BT_GAP_READ_RSSI_DELTA_EVT: Read rssi event

enumerator ESP_BT_GAP_CONFIG_EIR_DATA_EVT: Config EIR data event

enumerator ESP_BT_GAP_SET_AFH_CHANNELS_EVT: Set AFH channels event

enumerator ESP_BT_GAP_READ_REMOTE_NAME_EVT: Read Remote Name event

enumerator ESP_BT_GAP_MODE_CHG_EVT

enumerator ESP_BT_GAP_REMOVE_BOND_DEV_COMPLETE_EVT: remove bond device complete event

enumerator ESP_BT_GAP_QOS_CMPL_EVT: QOS complete event

enumerator ESP_BT_GAP_ACL_CONN_CMPL_STAT_EVT: ACL connection complete status event

enumerator ESP_BT_GAP_ACL_DISCONN_CMPL_STAT_EVT: ACL disconnection complete status event

enumerator ESP_BT_GAP_SET_PAGE_TO_EVT: Set page timeout event

enumerator ESP_BT_GAP_GET_PAGE_TO_EVT: Get page timeout event

enumerator ESP_BT_GAP_ACL_PKT_TYPE_CHANGED_EVT: Set ACL packet types event

enumerator ESP_BT_GAP_ENC_CHG_EVT: Encryption change event

enumerator ESP_BT_GAP_SET_MIN_ENC_KEY_SIZE_EVT: Set minimum encryption key size

enumerator ESP_BT_GAP_GET_DEV_NAME_CMPL_EVT: Get device name complete event

enumerator ESP_BT_GAP_EVT_MAX

enum esp_bt_inq_mode_t

Inquiry Mode

Values:

enumerator ESP_BT_INQ_MODE_GENERAL_INQUIRY: General inquiry mode

enumerator ESP_BT_INQ_MODE_LIMITED_INQUIRY: Limited inquiry mode

Provide feedback about this document