GAP API

Overview

Instructions

Application Example

Check bluetooth/bluedroid/ble 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
  • [in] 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
  • [in] 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
  • [in] 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
  • [in] 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
  • [in] 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
  • [in] 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 sets the static Random Address and Non-Resolvable Private Address for the application.

Return

  • ESP_OK : success

  • other : failed

Parameters
  • [in] rand_addr: the random address which should be setting

esp_err_t esp_ble_gap_clear_rand_addr(void)

This function clears the random address for the application.

Return

  • ESP_OK : success

  • other : failed

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
  • [in] 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, esp_ble_wl_addr_type_t wl_addr_type)

Add or remove device from white list.

Return

  • ESP_OK : success

  • other : failed

Parameters
  • [in] add_remove: the value is true if added the ble device to the white list, and false remove to the white list.

  • [in] remote_bda: the remote device address add/remove from the white list.

  • [in] wl_addr_type: whitelist address type

esp_err_t esp_ble_gap_clear_whitelist(void)

Clear all white list.

Return

  • ESP_OK : success

  • other : failed

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
  • [out] 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
  • [in] bd_addr: BD address of the peripheral

  • [in] min_conn_int: minimum preferred connection interval

  • [in] max_conn_int: maximum preferred connection interval

  • [in] slave_latency: preferred slave latency

  • [in] 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
  • [in] name: - device name.

esp_err_t esp_ble_gap_get_device_name(void)

Get device name of the local device.

Return

  • ESP_OK : success

  • other : failed

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 address type. uint8_t *esp_bt_dev_get_address(void) get the public address.

Return

- ESP_OK : success

  • other : failed

Parameters
  • [in] local_used_addr: - current local used ble address (six bytes)

  • [in] 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
  • [in] adv_data: - pointer of ADV data which to be resolved

  • [in] type: - finding ADV data type

  • [out] 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
  • [in] raw_data: : raw advertising data

  • [in] 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
  • [in] raw_data: : raw scan response data

  • [in] 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
  • [in] remote_addr: : The remote connection device address.

esp_err_t esp_ble_gap_add_duplicate_scan_exceptional_device(esp_ble_duplicate_exceptional_info_type_t type, esp_duplicate_info_t device_info)

This function is called to add a device info into the duplicate scan exceptional list.

Return

  • ESP_OK : success

  • other : failed

Parameters
  • [in] type: device info type, it is defined in esp_ble_duplicate_exceptional_info_type_t when type is MESH_BEACON_TYPE, MESH_PROV_SRV_ADV or MESH_PROXY_SRV_ADV , device_info is invalid.

  • [in] device_info: the device information.

esp_err_t esp_ble_gap_remove_duplicate_scan_exceptional_device(esp_ble_duplicate_exceptional_info_type_t type, esp_duplicate_info_t device_info)

This function is called to remove a device info from the duplicate scan exceptional list.

Return

  • ESP_OK : success

  • other : failed

Parameters
  • [in] type: device info type, it is defined in esp_ble_duplicate_exceptional_info_type_t when type is MESH_BEACON_TYPE, MESH_PROV_SRV_ADV or MESH_PROXY_SRV_ADV , device_info is invalid.

  • [in] device_info: the device information.

esp_err_t esp_ble_gap_clean_duplicate_scan_exceptional_list(esp_duplicate_scan_exceptional_list_type_t list_type)

This function is called to clean the duplicate scan exceptional list. This API will delete all device information in the duplicate scan exceptional list.

Return

  • ESP_OK : success

  • other : failed

Parameters
  • [in] list_type: duplicate scan exceptional list type, the value can be one or more of esp_duplicate_scan_exceptional_list_type_t.

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.

Secure connection is highly recommended to avoid some major vulnerabilities like ‘Impersonation in the Pin Pairing Protocol’ (CVE-2020-26555) and ‘Authentication of the LE Legacy Pairing Protocol’.

To accept only secure connection mode, it is necessary do as following:

  1. Set bit ESP_LE_AUTH_REQ_SC_ONLY (param_type is ESP_BLE_SM_AUTHEN_REQ_MODE), bit ESP_LE_AUTH_BOND and bit ESP_LE_AUTH_REQ_MITM is optional as required.

  2. Set to ESP_BLE_ONLY_ACCEPT_SPECIFIED_AUTH_ENABLE (param_type is ESP_BLE_SM_ONLY_ACCEPT_SPECIFIED_SEC_AUTH).

Return

- ESP_OK : success

  • other : failed

Parameters
  • [in] param_type: : the type of the param which to be set

  • [in] value: : the param value

  • [in] 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
  • [in] bd_addr: : BD address of the peer

  • [in] 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
  • [in] bd_addr: : the address of the peer device need to encryption

  • [in] 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 legacy connection stage.

Return

- ESP_OK : success

  • other : failed

Parameters
  • [in] bd_addr: : BD address of the peer

  • [in] accept: : passkey entry successful or declined.

  • [in] 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 confirm value to the peer device in the secure connection stage.

Return

- ESP_OK : success

  • other : failed

Parameters
  • [in] bd_addr: : BD address of the peer device

  • [in] 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
  • [in] 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
  • [inout] 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().

  • [out] 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_oob_req_reply(esp_bd_addr_t bd_addr, uint8_t *TK, uint8_t len)

This function is called to provide the OOB data for SMP in response to ESP_GAP_BLE_OOB_REQ_EVT.

Return

- ESP_OK : success

  • other : failed

Parameters
  • [in] bd_addr: BD address of the peer device.

  • [in] TK: TK value, the TK value shall be a 128-bit random number

  • [in] len: length of tk, should always be 128-bit

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 may have multiple virtual GATT server connections when multiple app_id registered. 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
  • [in] remote_device: : BD address of the peer device

esp_err_t esp_ble_get_current_conn_params(esp_bd_addr_t bd_addr, esp_gap_conn_params_t *conn_params)

This function is called to read the connection parameters information of the device.

Return

- ESP_OK : success

  • other : failed

Parameters
  • [in] bd_addr: BD address of the peer device.

  • [out] conn_params: the connection parameters information

esp_err_t esp_gap_ble_set_channels(esp_gap_ble_channels channels)

BLE set channels.

Return

- ESP_OK : success

  • ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

  • other : failed

Parameters
  • [in] channels: : The n th such field (in the range 0 to 36) contains the value for the link layer channel index n. 0 means channel n is bad. 1 means channel n is unknown. The most significant bits are reserved and shall be set to 0. At least one channel shall be marked as unknown.

esp_err_t esp_gap_ble_set_authorization(esp_bd_addr_t bd_addr, bool authorize)

This function is called to authorized a link after Authentication(MITM protection)

Return

- ESP_OK : success

  • other : failed

Parameters
  • [in] bd_addr: BD address of the peer device.

  • [out] authorize: Authorized the link or not.

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_get_dev_name_cmpl_evt_param get_dev_name_cmpl

Event parameter of ESP_GAP_BLE_GET_DEV_NAME_COMPLETE_EVT

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 esp_ble_gap_cb_param_t::ble_update_duplicate_exceptional_list_cmpl_evt_param update_duplicate_exceptional_list_cmpl

Event parameter of ESP_GAP_BLE_UPDATE_DUPLICATE_EXCEPTIONAL_LIST_COMPLETE_EVT

struct esp_ble_gap_cb_param_t::ble_set_channels_evt_param