GAP API

Overview

Instructions

Application Example

Check bluetooth folder in ESP-IDF examples, which contains the following demos and their tutorials:

API Reference

Functions

esp_err_t esp_ble_gap_register_callback(esp_gap_ble_cb_t callback)

This function is called to occur gap event, such as scan result.

Return
  • ESP_OK : success
  • other : failed
Parameters
  • callback: callback function

esp_err_t esp_ble_gap_config_adv_data(esp_ble_adv_data_t *adv_data)

This function is called to override the BTA default ADV parameters.

Return
  • ESP_OK : success
  • other : failed
Parameters
  • adv_data: Pointer to User defined ADV data structure. This memory space can not be freed until callback of config_adv_data is received.

esp_err_t esp_ble_gap_set_scan_params(esp_ble_scan_params_t *scan_params)

This function is called to set scan parameters.

Return
  • ESP_OK : success
  • other : failed
Parameters
  • scan_params: Pointer to User defined scan_params data structure. This memory space can not be freed until callback of set_scan_params

esp_err_t esp_ble_gap_start_scanning(uint32_t duration)

This procedure keep the device scanning the peer device which advertising on the air.

Return
  • ESP_OK : success
  • other : failed
Parameters
  • duration: Keeping the scanning time, the unit is second.

esp_err_t esp_ble_gap_stop_scanning(void)

This function call to stop the device scanning the peer device which advertising on the air.

Return
  • ESP_OK : success
    • other : failed

esp_err_t esp_ble_gap_start_advertising(esp_ble_adv_params_t *adv_params)

This function is called to start advertising.

Return
  • ESP_OK : success
  • other : failed
Parameters
  • adv_params: pointer to User defined adv_params data structure.

esp_err_t esp_ble_gap_stop_advertising(void)

This function is called to stop advertising.

Return
  • ESP_OK : success
  • other : failed

esp_err_t esp_ble_gap_update_conn_params(esp_ble_conn_update_params_t *params)

Update connection parameters, can only be used when connection is up.

Return
  • ESP_OK : success
  • other : failed
Parameters
  • params: - connection update parameters

esp_err_t esp_ble_gap_set_pkt_data_len(esp_bd_addr_t remote_device, uint16_t tx_data_length)

This function is to set maximum LE data packet size.

Return
  • ESP_OK : success
  • other : failed

esp_err_t esp_ble_gap_set_rand_addr(esp_bd_addr_t rand_addr)

This function set the random address for the application.

Return
  • ESP_OK : success
  • other : failed
Parameters
  • rand_addr: the random address which should be setting

esp_err_t esp_ble_gap_config_local_privacy(bool privacy_enable)

Enable/disable privacy on the local device.

Return
  • ESP_OK : success
  • other : failed
Parameters
  • privacy_enable: - enable/disable privacy on remote device.

esp_err_t esp_ble_gap_config_local_icon(uint16_t icon)

set local gap appearance icon

Return
  • ESP_OK : success
  • other : failed
Parameters

esp_err_t esp_ble_gap_update_whitelist(bool add_remove, esp_bd_addr_t remote_bda)

Add or remove device from white list.

Return
  • ESP_OK : success
  • other : failed
Parameters
  • add_remove: the value is true if added the ble device to the white list, and false remove to the white list.
  • remote_bda: the remote device address add/remove from the white list.

esp_err_t esp_ble_gap_get_whitelist_size(uint16_t *length)

Get the whitelist size in the controller.

Return
  • ESP_OK : success
  • other : failed
Parameters
  • length: the white list length.

esp_err_t esp_ble_gap_set_prefer_conn_params(esp_bd_addr_t bd_addr, uint16_t min_conn_int, uint16_t max_conn_int, uint16_t slave_latency, uint16_t supervision_tout)

This function is called to set the preferred connection parameters when default connection parameter is not desired before connecting. This API can only be used in the master role.

Return
  • ESP_OK : success
  • other : failed
Parameters
  • bd_addr: BD address of the peripheral
  • min_conn_int: minimum preferred connection interval
  • max_conn_int: maximum preferred connection interval
  • slave_latency: preferred slave latency
  • supervision_tout: preferred supervision timeout

esp_err_t esp_ble_gap_set_device_name(const char *name)

Set device name to the local device.

Return
  • ESP_OK : success
  • other : failed
Parameters
  • name: - device name.

esp_err_t esp_ble_gap_get_local_used_addr(esp_bd_addr_t local_used_addr, uint8_t *addr_type)

This function is called to get local used address and adress type. uint8_t *esp_bt_dev_get_address(void) get the public address.

Return
- ESP_OK : success
  • other : failed
Parameters
  • local_used_addr: - current local used ble address (six bytes)
  • addr_type: - ble address type

uint8_t *esp_ble_resolve_adv_data(uint8_t *adv_data, uint8_t type, uint8_t *length)

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

Return
pointer of ADV data
Parameters
  • adv_data: - pointer of ADV data which to be resolved
  • type: - finding ADV data type
  • length: - return the length of ADV data not including type

esp_err_t esp_ble_gap_config_adv_data_raw(uint8_t *raw_data, uint32_t raw_data_len)

This function is called to set raw advertising data. User need to fill ADV data by self.

Return
  • ESP_OK : success
  • other : failed
Parameters
  • raw_data: : raw advertising data
  • raw_data_len: : raw advertising data length , less than 31 bytes

esp_err_t esp_ble_gap_config_scan_rsp_data_raw(uint8_t *raw_data, uint32_t raw_data_len)

This function is called to set raw scan response data. User need to fill scan response data by self.

Return
  • ESP_OK : success
  • other : failed
Parameters
  • raw_data: : raw scan response data
  • raw_data_len: : raw scan response data length , less than 31 bytes

esp_err_t esp_ble_gap_read_rssi(esp_bd_addr_t remote_addr)

This function is called to read the RSSI of remote device. The address of link policy results are returned in the gap callback function with ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT event.

Return
  • ESP_OK : success
  • other : failed
Parameters
  • remote_addr: : The remote connection device address.

esp_err_t esp_ble_gap_set_security_param(esp_ble_sm_param_t param_type, void *value, uint8_t len)

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

Return
- ESP_OK : success
  • other : failed
Parameters
  • param_type: : the type of the param which to be set
  • value: : the param value
  • len: : the length of the param value

esp_err_t esp_ble_gap_security_rsp(esp_bd_addr_t bd_addr, bool accept)

Grant security request access.

Return
- ESP_OK : success
  • other : failed
Parameters
  • bd_addr: : BD address of the peer
  • accept: : accept the security request or not

esp_err_t esp_ble_set_encryption(esp_bd_addr_t bd_addr, esp_ble_sec_act_t sec_act)

Set a gap parameter value. Use this function to change the default GAP parameter values.

Return
- ESP_OK : success
  • other : failed
Parameters
  • bd_addr: : the address of the peer device need to encryption
  • sec_act: : This is the security action to indicate what kind of BLE security level is required for the BLE link if the BLE is supported

esp_err_t esp_ble_passkey_reply(esp_bd_addr_t bd_addr, bool accept, uint32_t passkey)

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

Return
- ESP_OK : success
  • other : failed
Parameters
  • bd_addr: : BD address of the peer
  • accept: : passkey entry sucessful or declined.
  • passkey: : passkey value, must be a 6 digit number, can be lead by 0.

esp_err_t esp_ble_confirm_reply(esp_bd_addr_t bd_addr, bool accept)

Reply the comfirm value to the peer device in the lagecy connection stage.

Return
- ESP_OK : success
  • other : failed
Parameters
  • bd_addr: : BD address of the peer device
  • accept: : numbers to compare are the same or different.

esp_err_t esp_ble_remove_bond_device(esp_bd_addr_t bd_addr)

Removes a device from the security database list of peer device. It manages unpairing event while connected.

Return
- ESP_OK : success
  • other : failed
Parameters
  • bd_addr: : BD address of the peer device

int esp_ble_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.

Return
- >= 0 : bonded devices number.
  • ESP_FAIL : failed

esp_err_t esp_ble_get_bond_device_list(int *dev_num, esp_ble_bond_dev_t *dev_list)

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

Return
- ESP_OK : success
  • other : failed
Parameters
  • dev_num: 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: an array(buffer) of esp_ble_bond_dev_t type. Use for storing the bonded devices address. The dev_list should be allocated by who call this API.

esp_err_t esp_ble_gap_disconnect(esp_bd_addr_t remote_device)

This function is to disconnect the physical connection of the peer device gattc maybe have multiple virtual GATT server connections when multiple app_id registed. esp_ble_gattc_close (esp_gatt_if_t gattc_if, uint16_t conn_id) only close one virtual GATT server connection. if there exist other virtual GATT server connections, it does not disconnect the physical connection. esp_ble_gap_disconnect(esp_bd_addr_t remote_device) disconnect the physical connection directly.

Return
- ESP_OK : success
  • other : failed
Parameters
  • remote_device: : BD address of the peer device

Unions

union esp_ble_key_value_t
#include <esp_gap_ble_api.h>

union type of the security key value

Public Members

esp_ble_penc_keys_t penc_key

received peer encryption key

esp_ble_pcsrk_keys_t pcsrk_key

received peer device SRK

esp_ble_pid_keys_t pid_key

peer device ID key

esp_ble_lenc_keys_t lenc_key

local encryption reproduction keys LTK = = d1(ER,DIV,0)

esp_ble_lcsrk_keys lcsrk_key

local device CSRK = d1(ER,DIV,1)

union esp_ble_sec_t
#include <esp_gap_ble_api.h>

union associated with ble security

Public Members

esp_ble_sec_key_notif_t key_notif

passkey notification

esp_ble_sec_req_t ble_req

BLE SMP related request

esp_ble_key_t ble_key

BLE SMP keys used when pairing

esp_ble_local_id_keys_t ble_id_keys

BLE IR event

esp_ble_auth_cmpl_t auth_cmpl

Authentication complete indication.

union esp_ble_gap_cb_param_t
#include <esp_gap_ble_api.h>

Gap callback parameters union.

Public Members

struct esp_ble_gap_cb_param_t::ble_adv_data_cmpl_evt_param adv_data_cmpl

Event parameter of ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT

struct esp_ble_gap_cb_param_t::ble_scan_rsp_data_cmpl_evt_param scan_rsp_data_cmpl

Event parameter of ESP_GAP_BLE_SCAN_RSP_DATA_SET_COMPLETE_EVT

struct esp_ble_gap_cb_param_t::ble_scan_param_cmpl_evt_param scan_param_cmpl

Event parameter of ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT

struct esp_ble_gap_cb_param_t::ble_scan_result_evt_param scan_rst

Event parameter of ESP_GAP_BLE_SCAN_RESULT_EVT

struct esp_ble_gap_cb_param_t::ble_adv_data_raw_cmpl_evt_param adv_data_raw_cmpl

Event parameter of ESP_GAP_BLE_ADV_DATA_RAW_SET_COMPLETE_EVT

struct esp_ble_gap_cb_param_t::ble_scan_rsp_data_raw_cmpl_evt_param scan_rsp_data_raw_cmpl

Event parameter of ESP_GAP_BLE_SCAN_RSP_DATA_RAW_SET_COMPLETE_EVT

struct esp_ble_gap_cb_param_t::ble_adv_start_cmpl_evt_param adv_start_cmpl

Event parameter of ESP_GAP_BLE_ADV_START_COMPLETE_EVT

struct esp_ble_gap_cb_param_t::ble_scan_start_cmpl_evt_param scan_start_cmpl

Event parameter of ESP_GAP_BLE_SCAN_START_COMPLETE_EVT

esp_ble_sec_t ble_security

ble gap security union type

struct esp_ble_gap_cb_param_t::ble_scan_stop_cmpl_evt_param scan_stop_cmpl

Event parameter of ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT

struct esp_ble_gap_cb_param_t::ble_adv_stop_cmpl_evt_param adv_stop_cmpl

Event parameter of ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT

struct esp_ble_gap_cb_param_t::ble_set_rand_cmpl_evt_param set_rand_addr_cmpl

Event parameter of ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT

struct esp_ble_gap_cb_param_t::ble_update_conn_params_evt_param update_conn_params

Event parameter of ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT

struct esp_ble_gap_cb_param_t::ble_pkt_data_length_cmpl_evt_param pkt_data_lenth_cmpl

Event parameter of ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVT

struct esp_ble_gap_cb_param_t::ble_local_privacy_cmpl_evt_param local_privacy_cmpl

Event parameter of ESP_GAP_BLE_SET_LOCAL_PRIVACY_COMPLETE_EVT

struct esp_ble_gap_cb_param_t::ble_remove_bond_dev_cmpl_evt_param remove_bond_dev_cmpl

Event parameter of ESP_GAP_BLE_REMOVE_BOND_DEV_COMPLETE_EVT

struct esp_ble_gap_cb_param_t::ble_clear_bond_dev_cmpl_evt_param clear_bond_dev_cmpl

Event parameter of ESP_GAP_BLE_CLEAR_BOND_DEV_COMPLETE_EVT

struct esp_ble_gap_cb_param_t::ble_get_bond_dev_cmpl_evt_param get_bond_dev_cmpl

Event parameter of ESP_GAP_BLE_GET_BOND_DEV_COMPLETE_EVT

struct esp_ble_gap_cb_param_t::ble_read_rssi_cmpl_evt_param read_rssi_cmpl

Event parameter of ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT

struct esp_ble_gap_cb_param_t::ble_update_whitelist_cmpl_evt_param update_whitelist_cmpl

Event parameter of ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT

struct ble_adv_data_cmpl_evt_param
#include <esp_gap_ble_api.h>

ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT.

Public Members

esp_bt_status_t status

Indicate the set advertising data operation success status

struct ble_adv_data_raw_cmpl_evt_param
#include <esp_gap_ble_api.h>

ESP_GAP_BLE_ADV_DATA_RAW_SET_COMPLETE_EVT.

Public Members

esp_bt_status_t status

Indicate the set raw advertising data operation success status

struct ble_adv_start_cmpl_evt_param
#include <esp_gap_ble_api.h>

ESP_GAP_BLE_ADV_START_COMPLETE_EVT.

Public Members

esp_bt_status_t status

Indicate advertising start operation success status

struct ble_adv_stop_cmpl_evt_param
#include <esp_gap_ble_api.h>

ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT.

Public Members

esp_bt_status_t status

Indicate adv stop operation success status

struct ble_clear_bond_dev_cmpl_evt_param
#include <esp_gap_ble_api.h>

ESP_GAP_BLE_CLEAR_BOND_DEV_COMPLETE_EVT.

Public Members

esp_bt_status_t status

Indicate the clear bond device operation success status

struct ble_get_bond_dev_cmpl_evt_param
#include <esp_gap_ble_api.h>

ESP_GAP_BLE_GET_BOND_DEV_COMPLETE_EVT.

Public Members

esp_bt_status_t status

Indicate the get bond device operation success status

uint8_t dev_num

Indicate the get number device in the bond list

esp_ble_bond_dev_t *bond_dev

the pointer to the bond device Structure

struct ble_local_privacy_cmpl_evt_param
#include <esp_gap_ble_api.h>

ESP_GAP_BLE_SET_LOCAL_PRIVACY_COMPLETE_EVT.

Public Members

esp_bt_status_t status

Indicate the set local privacy operation success status

struct ble_pkt_data_length_cmpl_evt_param
#include <esp_gap_ble_api.h>

ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVT.

Public Members

esp_bt_status_t status

Indicate the set pkt data length operation success status

esp_ble_pkt_data_length_params_t params

pkt data length value

struct ble_read_rssi_cmpl_evt_param
#include <esp_gap_ble_api.h>

ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT.

Public Members

esp_bt_status_t status

Indicate the read adv tx power operation success status

int8_t rssi

The ble remote device rssi value, the range is from -127 to 20, the unit is dbm, if the RSSI cannot be read, the RSSI metric shall be set to 127.

esp_bd_addr_t remote_addr

The remote device address

struct ble_remove_bond_dev_cmpl_evt_param
#include <esp_gap_ble_api.h>

ESP_GAP_BLE_REMOVE_BOND_DEV_COMPLETE_EVT.

Public Members

esp_bt_status_t status

Indicate the remove bond device operation success status

esp_bd_addr_t bd_addr

The device address which has been remove from the bond list

struct ble_scan_param_cmpl_evt_param
#include <esp_gap_ble_api.h>

ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT.

Public Members

esp_bt_status_t status

Indicate the set scan param operation success status

struct ble_scan_result_evt_param
#include <esp_gap_ble_api.h>

ESP_GAP_BLE_SCAN_RESULT_EVT.

Public Members

esp_gap_search_evt_t search_evt

Search event type

esp_bd_addr_t bda

Bluetooth device address which has been searched

esp_bt_dev_type_t dev_type

Device type

esp_ble_addr_type_t ble_addr_type

Ble device address type

esp_ble_evt_type_t ble_evt_type

Ble scan result event type

int rssi

Searched device’s RSSI

uint8_t ble_adv[ESP_BLE_ADV_DATA_LEN_MAX + ESP_BLE_SCAN_RSP_DATA_LEN_MAX]

Received EIR

int flag

Advertising data flag bit

int num_resps

Scan result number

uint8_t adv_data_len

Adv data length

uint8_t scan_rsp_len

Scan response length

uint32_t num_dis

The number of discard packets

struct ble_scan_rsp_data_cmpl_evt_param
#include <esp_gap_ble_api.h>

ESP_GAP_BLE_SCAN_RSP_DATA_SET_COMPLETE_EVT.

Public Members

esp_bt_status_t status

Indicate the set scan response data operation success status

struct ble_scan_rsp_data_raw_cmpl_evt_param
#include <esp_gap_ble_api.h>

ESP_GAP_BLE_SCAN_RSP_DATA_RAW_SET_COMPLETE_EVT.

Public Members

esp_bt_status_t status

Indicate the set raw advertising data operation success status

struct ble_scan_start_cmpl_evt_param
#include <esp_gap_ble_api.h>

ESP_GAP_BLE_SCAN_START_COMPLETE_EVT.

Public Members

esp_bt_status_t status

Indicate scan start operation success status

struct ble_scan_stop_cmpl_evt_param
#include <esp_gap_ble_api.h>

ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT.

Public Members

esp_bt_status_t status

Indicate scan stop operation success status

struct ble_set_rand_cmpl_evt_param
#include <esp_gap_ble_api.h>

ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT.

Public Members

esp_bt_status_t status

Indicate set static rand address operation success status

struct ble_update_conn_params_evt_param
#include <esp_gap_ble_api.h>

ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT.

Public Members

esp_bt_status_t status

Indicate update connection parameters success status

esp_bd_addr_t bda

Bluetooth device address

uint16_t min_int

Min connection interval

uint16_t max_int

Max connection interval

uint16_t latency

Slave latency for the connection in number of connection events. Range: 0x0000 to 0x01F3

uint16_t conn_int

Current connection interval

uint16_t timeout

Supervision timeout for the LE Link. Range: 0x000A to 0x0C80. Mandatory Range: 0x000A to 0x0C80 Time = N * 10 msec

struct ble_update_whitelist_cmpl_evt_param
#include <esp_gap_ble_api.h>

ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT.

Public Members

esp_bt_status_t status

Indicate the add or remove whitelist operation success status

esp_ble_wl_opration_t wl_opration

The value is ESP_BLE_WHITELIST_ADD if add address to whitelist operation success, ESP_BLE_WHITELIST_REMOVE if remove address from the whitelist operation success

Structures

struct esp_ble_adv_params_t

Advertising parameters.

Public Members

uint16_t adv_int_min

Minimum advertising interval for undirected and low duty cycle directed advertising. Range: 0x0020 to 0x4000 Default: N = 0x0800 (1.28 second) Time = N * 0.625 msec Time Range: 20 ms to 10.24 sec

uint16_t adv_int_max

Maximum advertising interval for undirected and low duty cycle directed advertising. Range: 0x0020 to 0x4000 Default: N = 0x0800 (1.28 second) Time = N * 0.625 msec Time Range: 20 ms to 10.24 sec Advertising max interval

esp_ble_adv_type_t adv_type

Advertising type

esp_ble_addr_type_t own_addr_type

Owner bluetooth device address type

esp_bd_addr_t peer_addr

Peer device bluetooth device address

esp_ble_addr_type_t peer_addr_type

Peer device bluetooth device address type, only support public address type and random address type

esp_ble_adv_channel_t channel_map

Advertising channel map

esp_ble_adv_filter_t adv_filter_policy

Advertising filter policy

struct esp_ble_adv_data_t

Advertising data content, according to “Supplement to the Bluetooth Core Specification”.

Public Members

bool set_scan_rsp

Set this advertising data as scan response or not

bool include_name

Advertising data include device name or not

bool include_txpower

Advertising data include TX power

int min_interval

Advertising data show advertising min interval

int max_interval

Advertising data show advertising max interval

int appearance

External appearance of device

uint16_t manufacturer_len

Manufacturer data length

uint8_t *p_manufacturer_data

Manufacturer data point

uint16_t service_data_len

Service data length

uint8_t *p_service_data

Service data point

uint16_t service_uuid_len

Service uuid length

uint8_t *p_service_uuid

Service uuid array point

uint8_t flag

Advertising flag of discovery mode, see BLE_ADV_DATA_FLAG detail

struct esp_ble_scan_params_t

Ble scan parameters.

Public Members

esp_ble_scan_type_t scan_type

Scan type

esp_ble_addr_type_t own_addr_type

Owner address type

esp_ble_scan_filter_t scan_filter_policy

Scan filter policy

uint16_t scan_interval

Scan interval. This is defined as the time interval from when the Controller started its last LE scan until it begins the subsequent LE scan. Range: 0x0004 to 0x4000 Default: 0x0010 (10 ms) Time = N * 0.625 msec Time Range: 2.5 msec to 10.24 seconds

uint16_t scan_window

Scan window. The duration of the LE scan. LE_Scan_Window shall be less than or equal to LE_Scan_Interval Range: 0x0004 to 0x4000 Default: 0x0010 (10 ms) Time = N * 0.625 msec Time Range: 2.5 msec to 10240 msec

esp_ble_scan_duplicate_t scan_duplicate

The Scan_Duplicates parameter controls whether the Link Layer should filter out duplicate advertising reports (BLE_SCAN_DUPLICATE_ENABLE) to the Host, or if the Link Layer should generate advertising reports for each packet received

struct esp_ble_conn_update_params_t

Connection update parameters.

Public Members

esp_bd_addr_t bda

Bluetooth device address

uint16_t min_int

Min connection interval

uint16_t max_int

Max connection interval

uint16_t latency

Slave latency for the connection in number of connection events. Range: 0x0000 to 0x01F3

uint16_t timeout

Supervision timeout for the LE Link. Range: 0x000A to 0x0C80. Mandatory Range: 0x000A to 0x0C80 Time = N * 10 msec Time Range: 100 msec to 32 seconds

struct esp_ble_pkt_data_length_params_t

BLE pkt date length keys.

Public Members

uint16_t rx_len

pkt rx data length value

uint16_t tx_len

pkt tx data length value

struct esp_ble_penc_keys_t

BLE encryption keys.

Public Members

esp_bt_octet16_t ltk

The long term key

esp_bt_octet8_t rand

The random number

uint16_t ediv

The ediv value

uint8_t sec_level

The security level of the security link

uint8_t key_size

The key size(7~16) of the security link

struct esp_ble_pcsrk_keys_t

BLE CSRK keys.

Public Members

uint32_t counter

The counter

esp_bt_octet16_t csrk

The csrk key

uint8_t sec_level

The security level

struct esp_ble_pid_keys_t

BLE pid keys.

Public Members

esp_bt_octet16_t irk

The irk value

esp_ble_addr_type_t addr_type

The address type

esp_bd_addr_t static_addr

The static address

struct esp_ble_lenc_keys_t

BLE Encryption reproduction keys.

Public Members

esp_bt_octet16_t ltk

The long term key

uint16_t div

The div value

uint8_t key_size

The key size of the security link

uint8_t sec_level

The security level of the security link

struct esp_ble_lcsrk_keys

BLE SRK keys.

Public Members

uint32_t counter

The counter value

uint16_t div

The div value

uint8_t sec_level

The security level of the security link

esp_bt_octet16_t csrk

The csrk key value

struct esp_ble_sec_key_notif_t

Structure associated with ESP_KEY_NOTIF_EVT.

Public Members

esp_bd_addr_t bd_addr

peer address

uint32_t passkey

the numeric value for comparison. If just_works, do not show this number to UI

struct esp_ble_sec_req_t

Structure of the security request.

Public Members

esp_bd_addr_t bd_addr

peer address

struct esp_ble_bond_key_info_t

struct type of the bond key informatuon value

Public Members

esp_ble_key_mask_t key_mask

the key mask to indicate witch key is present

esp_ble_penc_keys_t penc_key

received peer encryption key

esp_ble_pcsrk_keys_t pcsrk_key

received peer device SRK

esp_ble_pid_keys_t pid_key

peer device ID key

struct esp_ble_bond_dev_t

struct type of the bond device value

Public Members

esp_bd_addr_t bd_addr

peer address

esp_ble_bond_key_info_t bond_key

the bond key information

struct esp_ble_key_t

union type of the security key value

Public Members

esp_bd_addr_t bd_addr

peer address

esp_ble_key_type_t key_type

key type of the security link

esp_ble_key_value_t p_key_value

the pointer to the key value

struct esp_ble_local_id_keys_t

structure type of the ble local id keys value

Public Members

esp_bt_octet16_t ir

the 16 bits of the ir value

esp_bt_octet16_t irk

the 16 bits of the ir key value

esp_bt_octet16_t dhk

the 16 bits of the dh key value

struct esp_ble_auth_cmpl_t

Structure associated with ESP_AUTH_CMPL_EVT.

Public Members

esp_bd_addr_t bd_addr

BD address peer device.

bool key_present

Valid link key value in key element

esp_link_key key

Link key associated with peer device.

uint8_t key_type

The type of Link Key

bool success

TRUE of authentication succeeded, FALSE if failed.

uint8_t fail_reason

The HCI reason/error code for when success=FALSE

esp_ble_addr_type_t addr_type

Peer device address type

esp_bt_dev_type_t dev_type

Device type

esp_ble_auth_req_t auth_mode

authentication mode

Macros

ESP_BLE_ADV_FLAG_LIMIT_DISC

BLE_ADV_DATA_FLAG data flag bit definition used for advertising data flag

ESP_BLE_ADV_FLAG_GEN_DISC
ESP_BLE_ADV_FLAG_BREDR_NOT_SPT
ESP_BLE_ADV_FLAG_DMT_CONTROLLER_SPT
ESP_BLE_ADV_FLAG_DMT_HOST_SPT
ESP_BLE_ADV_FLAG_NON_LIMIT_DISC
ESP_LE_KEY_NONE
ESP_LE_KEY_PENC
ESP_LE_KEY_PID
ESP_LE_KEY_PCSRK
ESP_LE_KEY_PLK
ESP_LE_KEY_LLK
ESP_LE_KEY_LENC
ESP_LE_KEY_LID
ESP_LE_KEY_LCSRK
ESP_LE_AUTH_NO_BOND
ESP_LE_AUTH_BOND
ESP_LE_AUTH_REQ_MITM
ESP_LE_AUTH_REQ_BOND_MITM

0101

ESP_LE_AUTH_REQ_SC_ONLY
ESP_LE_AUTH_REQ_SC_BOND
ESP_LE_AUTH_REQ_SC_MITM
ESP_LE_AUTH_REQ_SC_MITM_BOND
ESP_BLE_ONLY_ACCEPT_SPECIFIED_AUTH_DISABLE
ESP_BLE_ONLY_ACCEPT_SPECIFIED_AUTH_ENABLE
ESP_IO_CAP_OUT
ESP_IO_CAP_IO
ESP_IO_CAP_IN
ESP_IO_CAP_NONE
ESP_IO_CAP_KBDISP
ESP_BLE_APPEARANCE_UNKNOWN
ESP_BLE_APPEARANCE_GENERIC_PHONE
ESP_BLE_APPEARANCE_GENERIC_COMPUTER
ESP_BLE_APPEARANCE_GENERIC_WATCH
ESP_BLE_APPEARANCE_SPORTS_WATCH
ESP_BLE_APPEARANCE_GENERIC_CLOCK
ESP_BLE_APPEARANCE_GENERIC_DISPLAY
ESP_BLE_APPEARANCE_GENERIC_REMOTE
ESP_BLE_APPEARANCE_GENERIC_EYEGLASSES
ESP_BLE_APPEARANCE_GENERIC_TAG
ESP_BLE_APPEARANCE_GENERIC_KEYRING
ESP_BLE_APPEARANCE_GENERIC_MEDIA_PLAYER
ESP_BLE_APPEARANCE_GENERIC_BARCODE_SCANNER
ESP_BLE_APPEARANCE_GENERIC_THERMOMETER
ESP_BLE_APPEARANCE_THERMOMETER_EAR
ESP_BLE_APPEARANCE_GENERIC_HEART_RATE
ESP_BLE_APPEARANCE_HEART_RATE_BELT
ESP_BLE_APPEARANCE_GENERIC_BLOOD_PRESSURE
ESP_BLE_APPEARANCE_BLOOD_PRESSURE_ARM
ESP_BLE_APPEARANCE_BLOOD_PRESSURE_WRIST
ESP_BLE_APPEARANCE_GENERIC_HID
ESP_BLE_APPEARANCE_HID_KEYBOARD
ESP_BLE_APPEARANCE_HID_MOUSE
ESP_BLE_APPEARANCE_HID_JOYSTICK
ESP_BLE_APPEARANCE_HID_GAMEPAD
ESP_BLE_APPEARANCE_HID_DIGITIZER_TABLET
ESP_BLE_APPEARANCE_HID_CARD_READER
ESP_BLE_APPEARANCE_HID_DIGITAL_PEN
ESP_BLE_APPEARANCE_HID_BARCODE_SCANNER
ESP_BLE_APPEARANCE_GENERIC_GLUCOSE
ESP_BLE_APPEARANCE_GENERIC_WALKING
ESP_BLE_APPEARANCE_WALKING_IN_SHOE
ESP_BLE_APPEARANCE_WALKING_ON_SHOE
ESP_BLE_APPEARANCE_WALKING_ON_HIP
ESP_BLE_APPEARANCE_GENERIC_CYCLING
ESP_BLE_APPEARANCE_CYCLING_COMPUTER
ESP_BLE_APPEARANCE_CYCLING_SPEED
ESP_BLE_APPEARANCE_CYCLING_CADENCE
ESP_BLE_APPEARANCE_CYCLING_POWER
ESP_BLE_APPEARANCE_CYCLING_SPEED_CADENCE
ESP_BLE_APPEARANCE_GENERIC_PULSE_OXIMETER
ESP_BLE_APPEARANCE_PULSE_OXIMETER_FINGERTIP
ESP_BLE_APPEARANCE_PULSE_OXIMETER_WRIST
ESP_BLE_APPEARANCE_GENERIC_WEIGHT
ESP_BLE_APPEARANCE_GENERIC_PERSONAL_MOBILITY_DEVICE
ESP_BLE_APPEARANCE_POWERED_WHEELCHAIR
ESP_BLE_APPEARANCE_MOBILITY_SCOOTER
ESP_BLE_APPEARANCE_GENERIC_CONTINUOUS_GLUCOSE_MONITOR
ESP_BLE_APPEARANCE_GENERIC_INSULIN_PUMP
ESP_BLE_APPEARANCE_INSULIN_PUMP_DURABLE_PUMP
ESP_BLE_APPEARANCE_INSULIN_PUMP_PATCH_PUMP
ESP_BLE_APPEARANCE_INSULIN_PEN
ESP_BLE_APPEARANCE_GENERIC_MEDICATION_DELIVERY
ESP_BLE_APPEARANCE_GENERIC_OUTDOOR_SPORTS
ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION
ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_AND_NAV
ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_POD
ESP_BLE_APPEARANCE_OUTDOOR_SPORTS_LOCATION_POD_AND_NAV
ESP_GAP_BLE_ADD_WHITELIST_COMPLETE_EVT

This is the old name, just for backwards compatibility.

ESP_BLE_ADV_DATA_LEN_MAX

Advertising data maximum length.

ESP_BLE_SCAN_RSP_DATA_LEN_MAX

Scan response data maximum length.

Type Definitions

typedef uint8_t esp_ble_key_type_t
typedef uint8_t esp_ble_auth_req_t

combination of the above bit pattern

typedef uint8_t esp_ble_io_cap_t

combination of the io capability

typedef void (*esp_gap_ble_cb_t)(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_param_t *param)

GAP callback function type.

Parameters
  • event: : Event type
  • param: : Point to callback parameter, currently is union type

Enumerations

enum esp_gap_ble_cb_event_t

GAP BLE callback event type.

Values:

ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT = 0

When advertising data set complete, the event comes

ESP_GAP_BLE_SCAN_RSP_DATA_SET_COMPLETE_EVT

When scan response data set complete, the event comes

ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT

When scan parameters set complete, the event comes

ESP_GAP_BLE_SCAN_RESULT_EVT

When one scan result ready, the event comes each time

ESP_GAP_BLE_ADV_DATA_RAW_SET_COMPLETE_EVT

When raw advertising data set complete, the event comes

ESP_GAP_BLE_SCAN_RSP_DATA_RAW_SET_COMPLETE_EVT

When raw advertising data set complete, the event comes

ESP_GAP_BLE_ADV_START_COMPLETE_EVT

When start advertising complete, the event comes

ESP_GAP_BLE_SCAN_START_COMPLETE_EVT

When start scan complete, the event comes

ESP_GAP_BLE_AUTH_CMPL_EVT
ESP_GAP_BLE_KEY_EVT
ESP_GAP_BLE_SEC_REQ_EVT
ESP_GAP_BLE_PASSKEY_NOTIF_EVT
ESP_GAP_BLE_PASSKEY_REQ_EVT
ESP_GAP_BLE_OOB_REQ_EVT
ESP_GAP_BLE_LOCAL_IR_EVT
ESP_GAP_BLE_LOCAL_ER_EVT
ESP_GAP_BLE_NC_REQ_EVT
ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT

When stop adv complete, the event comes

ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT

When stop scan complete, the event comes

ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT

When set the static rand address complete, the event comes

ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT

When update connection parameters complete, the event comes

ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVT

When set pkt lenght complete, the event comes

ESP_GAP_BLE_SET_LOCAL_PRIVACY_COMPLETE_EVT

When Enable/disable privacy on the local device complete, the event comes

ESP_GAP_BLE_REMOVE_BOND_DEV_COMPLETE_EVT

When remove the bond device complete, the event comes

ESP_GAP_BLE_CLEAR_BOND_DEV_COMPLETE_EVT

When clear the bond device clear complete, the event comes

ESP_GAP_BLE_GET_BOND_DEV_COMPLETE_EVT

When get the bond device list complete, the event comes

ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT

When read the rssi complete, the event comes

ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT

When add or remove whitelist complete, the event comes

ESP_GAP_BLE_EVT_MAX
enum esp_ble_adv_data_type

The type of advertising data(not adv_type)

Values:

ESP_BLE_AD_TYPE_FLAG = 0x01
ESP_BLE_AD_TYPE_16SRV_PART = 0x02
ESP_BLE_AD_TYPE_16SRV_CMPL = 0x03
ESP_BLE_AD_TYPE_32SRV_PART = 0x04
ESP_BLE_AD_TYPE_32SRV_CMPL = 0x05
ESP_BLE_AD_TYPE_128SRV_PART = 0x06
ESP_BLE_AD_TYPE_128SRV_CMPL = 0x07
ESP_BLE_AD_TYPE_NAME_SHORT = 0x08
ESP_BLE_AD_TYPE_NAME_CMPL = 0x09
ESP_BLE_AD_TYPE_TX_PWR = 0x0A
ESP_BLE_AD_TYPE_DEV_CLASS = 0x0D
ESP_BLE_AD_TYPE_SM_TK = 0x10
ESP_BLE_AD_TYPE_SM_OOB_FLAG = 0x11
ESP_BLE_AD_TYPE_INT_RANGE = 0x12
ESP_BLE_AD_TYPE_SOL_SRV_UUID = 0x14
ESP_BLE_AD_TYPE_128SOL_SRV_UUID = 0x15
ESP_BLE_AD_TYPE_SERVICE_DATA = 0x16
ESP_BLE_AD_TYPE_PUBLIC_TARGET = 0x17
ESP_BLE_AD_TYPE_RANDOM_TARGET = 0x18
ESP_BLE_AD_TYPE_APPEARANCE = 0x19
ESP_BLE_AD_TYPE_ADV_INT = 0x1A
ESP_BLE_AD_TYPE_LE_DEV_ADDR = 0x1b
ESP_BLE_AD_TYPE_LE_ROLE = 0x1c
ESP_BLE_AD_TYPE_SPAIR_C256 = 0x1d
ESP_BLE_AD_TYPE_SPAIR_R256 = 0x1e
ESP_BLE_AD_TYPE_32SOL_SRV_UUID = 0x1f
ESP_BLE_AD_TYPE_32SERVICE_DATA = 0x20
ESP_BLE_AD_TYPE_128SERVICE_DATA = 0x21
ESP_BLE_AD_TYPE_LE_SECURE_CONFIRM = 0x22
ESP_BLE_AD_TYPE_LE_SECURE_RANDOM = 0x23
ESP_BLE_AD_TYPE_URI = 0x24
ESP_BLE_AD_TYPE_INDOOR_POSITION = 0x25
ESP_BLE_AD_TYPE_TRANS_DISC_DATA = 0x26
ESP_BLE_AD_TYPE_LE_SUPPORT_FEATURE = 0x27
ESP_BLE_AD_TYPE_CHAN_MAP_UPDATE = 0x28
ESP_BLE_AD_MANUFACTURER_SPECIFIC_TYPE = 0xFF
enum esp_ble_adv_type_t

Advertising mode.

Values:

ADV_TYPE_IND = 0x00
ADV_TYPE_DIRECT_IND_HIGH = 0x01
ADV_TYPE_SCAN_IND = 0x02
ADV_TYPE_NONCONN_IND = 0x03
ADV_TYPE_DIRECT_IND_LOW = 0x04
enum esp_ble_adv_channel_t

Advertising channel mask.

Values:

ADV_CHNL_37 = 0x01
ADV_CHNL_38 = 0x02
ADV_CHNL_39 = 0x04
ADV_CHNL_ALL = 0x07
enum esp_ble_adv_filter_t

Values:

ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY = 0x00

Allow both scan and connection requests from anyone.

ADV_FILTER_ALLOW_SCAN_WLST_CON_ANY

Allow both scan req from White List devices only and connection req from anyone.

ADV_FILTER_ALLOW_SCAN_ANY_CON_WLST

Allow both scan req from anyone and connection req from White List devices only.

ADV_FILTER_ALLOW_SCAN_WLST_CON_WLST

Allow scan and connection requests from White List devices only.

enum esp_ble_sec_act_t

Values:

ESP_BLE_SEC_ENCRYPT = 1
ESP_BLE_SEC_ENCRYPT_NO_MITM
ESP_BLE_SEC_ENCRYPT_MITM
enum esp_ble_sm_param_t

Values:

ESP_BLE_SM_PASSKEY = 0
ESP_BLE_SM_AUTHEN_REQ_MODE
ESP_BLE_SM_IOCAP_MODE
ESP_BLE_SM_SET_INIT_KEY
ESP_BLE_SM_SET_RSP_KEY
ESP_BLE_SM_MAX_KEY_SIZE
ESP_BLE_SM_SET_STATIC_PASSKEY
ESP_BLE_SM_CLEAR_STATIC_PASSKEY
ESP_BLE_SM_ONLY_ACCEPT_SPECIFIED_SEC_AUTH
ESP_BLE_SM_MAX_PARAM
enum esp_ble_scan_type_t

Ble scan type.

Values:

BLE_SCAN_TYPE_PASSIVE = 0x0

Passive scan

BLE_SCAN_TYPE_ACTIVE = 0x1

Active scan

enum esp_ble_scan_filter_t

Ble scan filter type.

Values:

BLE_SCAN_FILTER_ALLOW_ALL = 0x0

Accept all :

  1. advertisement packets except directed advertising packets not addressed to this device (default).

BLE_SCAN_FILTER_ALLOW_ONLY_WLST = 0x1

Accept only :

  1. advertisement packets from devices where the advertiser’s address is in the White list.
  2. Directed advertising packets which are not addressed for this device shall be ignored.

BLE_SCAN_FILTER_ALLOW_UND_RPA_DIR = 0x2

Accept all :

  1. undirected advertisement packets, and
  2. directed advertising packets where the initiator address is a resolvable private address, and
  3. directed advertising packets addressed to this device.

BLE_SCAN_FILTER_ALLOW_WLIST_PRA_DIR = 0x3

Accept all :

  1. advertisement packets from devices where the advertiser’s address is in the White list, and
  2. directed advertising packets where the initiator address is a resolvable private address, and
  3. directed advertising packets addressed to this device.

enum esp_ble_scan_duplicate_t

Ble scan duplicate type.

Values:

BLE_SCAN_DUPLICATE_DISABLE = 0x0

the Link Layer should generate advertising reports to the host for each packet received

BLE_SCAN_DUPLICATE_ENABLE = 0x1

the Link Layer should filter out duplicate advertising reports to the Host

BLE_SCAN_DUPLICATE_MAX = 0x2

0x02 – 0xFF, Reserved for future use

enum esp_gap_search_evt_t

Sub Event of ESP_GAP_BLE_SCAN_RESULT_EVT.

Values:

ESP_GAP_SEARCH_INQ_RES_EVT = 0

Inquiry result for a peer device.

ESP_GAP_SEARCH_INQ_CMPL_EVT = 1

Inquiry complete.

ESP_GAP_SEARCH_DISC_RES_EVT = 2

Discovery result for a peer device.

ESP_GAP_SEARCH_DISC_BLE_RES_EVT = 3

Discovery result for BLE GATT based service on a peer device.

ESP_GAP_SEARCH_DISC_CMPL_EVT = 4

Discovery complete.

ESP_GAP_SEARCH_DI_DISC_CMPL_EVT = 5

Discovery complete.

ESP_GAP_SEARCH_SEARCH_CANCEL_CMPL_EVT = 6

Search cancelled

ESP_GAP_SEARCH_INQ_DISCARD_NUM_EVT = 7

The number of pkt discarded by flow control

enum esp_ble_evt_type_t

Ble scan result event type, to indicate the result is scan response or advertising data or other.

Values:

ESP_BLE_EVT_CONN_ADV = 0x00

Connectable undirected advertising (ADV_IND)

ESP_BLE_EVT_CONN_DIR_ADV = 0x01

Connectable directed advertising (ADV_DIRECT_IND)

ESP_BLE_EVT_DISC_ADV = 0x02

Scannable undirected advertising (ADV_SCAN_IND)

ESP_BLE_EVT_NON_CONN_ADV = 0x03

Non connectable undirected advertising (ADV_NONCONN_IND)

ESP_BLE_EVT_SCAN_RSP = 0x04

Scan Response (SCAN_RSP)

enum esp_ble_wl_opration_t

Values:

ESP_BLE_WHITELIST_REMOVE = 0X00

remove mac from whitelist

ESP_BLE_WHITELIST_ADD = 0X01

add address to whitelist