CLASSIC BLUETOOTH GAP API¶

Overview¶

Instructions

Application Example¶

Instructions

API Reference¶

Header File¶

bt/bluedroid/api/include/api/esp_gap_bt_api.h

Functions¶

uint32_t esp_bt_gap_get_cod_srvc(uint32_t cod)¶

get major service field of COD

Return

major service bits

Parameters

cod: Class of Device

uint32_t esp_bt_gap_get_cod_major_dev(uint32_t cod)¶

get major device field of COD

Return

major device bits

Parameters

cod: Class of Device

uint32_t esp_bt_gap_get_cod_minor_dev(uint32_t cod)¶

get minor service field of COD

Return

minor service bits

Parameters

cod: Class of Device

uint32_t esp_bt_gap_get_cod_format_type(uint32_t cod)¶

get format type of COD

Return

format type

Parameters

cod: Class of Device

bool esp_bt_gap_is_valid_cod(uint32_t cod)¶

decide the integrity of COD

Return

true if cod is valid
false otherise

Parameters

cod: Class of Device

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

Return

ESP_OK : Succeed
ESP_FAIL: others

esp_err_t esp_bt_gap_set_scan_mode(esp_bt_scan_mode_t mode)¶

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

Return

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

Parameters

mode: : one of the enums of bt_scan_mode_t

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. It 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 Inquriry 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.

Return

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

Parameters

mode: - Inquiry mode
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,
- when this time expires, Inquiry will be halted.
num_rsps: - Number of responses that can be received before the Inquiry is halted, value 0 indicates an unlimited number of responses.

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.

Return

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 is called with ESP_BT_GAP_RMT_SRVCS_EVT after service discovery ends.

Return

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 is called with ESP_BT_GAP_RMT_SRVC_REC_EVT after service discovery ends

Return

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.

Return

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

Parameters

eir: - pointer of raw eir data to be resolved
type: - specific EIR data type
length: - return the length of EIR data excluding fields of length and data type

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. esp_bt_gap_cb_t will is called with ESP_BT_GAP_SET_COD_EVT after set COD ends Some profile have special restrictions on class of device, changes may cause these profile do not work.

Return

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

Parameters

cod: - class of device
mode: - setting mode

esp_err_t esp_bt_gap_get_cod(esp_bt_cod_t *cod)¶

This function is called to get class of device.

Return

ESP_OK : Succeed
ESP_FAIL: others

Parameters

cod: - class of device

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.

Return

ESP_OK : Succeed
ESP_FAIL: others

Parameters

remote_addr: - remote device address, corresponding to a certain connection handle.

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.

Return

- ESP_OK : success

ESP_FAIL : failed

Parameters

bd_addr: : BD address of the peer device

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.

Return

- >= 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.

Return

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

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_bd_addr_t type. Use for storing the bonded devices address. The dev_list should be allocated by who call this API.

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.

Return

- ESP_OK : success

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

Parameters

pin_type: 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: Length of pin_code
pin_code: Pin_code

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.

Return

- ESP_OK : success

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

Parameters

bd_addr: BD address of the peer
accept: Pin_code reply successful or declined.
pin_code_len: Length of pin_code
pin_code: Pin_code

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.

Return

- ESP_OK : success

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

Parameters

param_type: : the type of the param which is to be set
value: : the param value
len: : the length of the param value

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.

Return

- ESP_OK : success

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

Parameters

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

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.

Return

- ESP_OK : success

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

Parameters

bd_addr: : BD address of the peer device
accept: : numbers to compare are the same or different.

Unions¶

union esp_bt_gap_cb_param_t¶

#include <esp_gap_bt_api.h>

A2DP 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::auth_cmpl_param auth_cmpl¶: authentication complete 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 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

uint8_t device_name[ESP_BT_GAP_MAX_BDNAME_LEN + 1]¶: device name

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

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

Macros¶

ESP_BT_GAP_RSSI_HIGH_THRLD¶

RSSI threshold.

High RSSI threshold

ESP_BT_GAP_RSSI_LOW_THRLD¶: Low RSSI threshold

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_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_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_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

Type Definitions¶

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

Parameters

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

Enumerations¶

enum esp_bt_cod_mode_t¶

class of device settings

Values:

ESP_BT_SET_COD_MAJOR_MINOR = 0x01¶: overwrite major, minor class

ESP_BT_SET_COD_SERVICE_CLASS = 0x02¶: set the bits in the input, the current bit will remain

ESP_BT_CLR_COD_SERVICE_CLASS = 0x04¶: clear the bits in the input, others will remain

ESP_BT_SET_COD_ALL = 0x08¶: overwrite major, minor, set the bits in service class

ESP_BT_INIT_COD = 0x0a¶: overwrite major, minor, and service class

enum esp_bt_scan_mode_t¶

Discoverability and Connectability mode.

Values:

ESP_BT_SCAN_MODE_NONE = 0¶: Neither discoverable nor connectable

ESP_BT_SCAN_MODE_CONNECTABLE¶: Connectable but not discoverable

ESP_BT_SCAN_MODE_CONNECTABLE_DISCOVERABLE¶: both discoverable and connectable

enum esp_bt_gap_dev_prop_type_t¶

Bluetooth Device Property type.

Values:

ESP_BT_GAP_DEV_PROP_BDNAME = 1¶: Bluetooth device name, value type is int8_t []

ESP_BT_GAP_DEV_PROP_COD¶: Class of Device, value type is uint32_t

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

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

enum esp_bt_eir_type_t¶

Extended Inquiry Response data type.

Values:

ESP_BT_EIR_TYPE_FLAGS = 0x01¶: Flag with information such as BR/EDR and LE support

ESP_BT_EIR_TYPE_INCMPL_16BITS_UUID = 0x02¶: Incomplete list of 16-bit service UUIDs

ESP_BT_EIR_TYPE_CMPL_16BITS_UUID = 0x03¶: Complete list of 16-bit service UUIDs

ESP_BT_EIR_TYPE_INCMPL_32BITS_UUID = 0x04¶: Incomplete list of 32-bit service UUIDs

ESP_BT_EIR_TYPE_CMPL_32BITS_UUID = 0x05¶: Complete list of 32-bit service UUIDs

ESP_BT_EIR_TYPE_INCMPL_128BITS_UUID = 0x06¶: Incomplete list of 128-bit service UUIDs

ESP_BT_EIR_TYPE_CMPL_128BITS_UUID = 0x07¶: Complete list of 128-bit service UUIDs

ESP_BT_EIR_TYPE_SHORT_LOCAL_NAME = 0x08¶: Shortened Local Name

ESP_BT_EIR_TYPE_CMPL_LOCAL_NAME = 0x09¶: Complete Local Name

ESP_BT_EIR_TYPE_TX_POWER_LEVEL = 0x0a¶: Tx power level, value is 1 octet ranging from -127 to 127, unit is dBm

ESP_BT_EIR_TYPE_MANU_SPECIFIC = 0xff¶: Manufacturer specific data

enum esp_bt_cod_srvc_t¶

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

Values:

ESP_BT_COD_SRVC_NONE = 0¶: None indicates an invalid value

ESP_BT_COD_SRVC_LMTD_DISCOVER = 0x1¶: Limited Discoverable Mode

ESP_BT_COD_SRVC_POSITIONING = 0x8¶: Positioning (Location identification)

ESP_BT_COD_SRVC_NETWORKING = 0x10¶: Networking, e.g. LAN, Ad hoc

ESP_BT_COD_SRVC_RENDERING = 0x20¶: Rendering, e.g. Printing, Speakers

ESP_BT_COD_SRVC_CAPTURING = 0x40¶: Capturing, e.g. Scanner, Microphone

ESP_BT_COD_SRVC_OBJ_TRANSFER = 0x80¶: Object Transfer, e.g. v-Inbox, v-Folder

ESP_BT_COD_SRVC_AUDIO = 0x100¶: Audio, e.g. Speaker, Microphone, Headset service

ESP_BT_COD_SRVC_TELEPHONY = 0x200¶: Telephony, e.g. Cordless telephony, Modem, Headset service

ESP_BT_COD_SRVC_INFORMATION = 0x400¶: Information, e.g., WEB-server, WAP-server

enum esp_bt_pin_type_t¶

Values:

ESP_BT_PIN_TYPE_VARIABLE = 0¶: Refer to BTM_PIN_TYPE_VARIABLE

ESP_BT_PIN_TYPE_FIXED = 1¶: Refer to BTM_PIN_TYPE_FIXED

enum esp_bt_sp_param_t¶

Values:

ESP_BT_SP_IOCAP_MODE = 0¶: Set IO mode

enum esp_bt_cod_major_dev_t¶

Major device class field of Class of Device.

Values:

ESP_BT_COD_MAJOR_DEV_MISC = 0¶: Miscellaneous

ESP_BT_COD_MAJOR_DEV_COMPUTER = 1¶: Computer

ESP_BT_COD_MAJOR_DEV_PHONE = 2¶: Phone(cellular, cordless, pay phone, modem

ESP_BT_COD_MAJOR_DEV_LAN_NAP = 3¶: LAN, Network Access Point

ESP_BT_COD_MAJOR_DEV_AV = 4¶: Audio/Video(headset, speaker, stereo, video display, VCR

ESP_BT_COD_MAJOR_DEV_PERIPHERAL = 5¶: Peripheral(mouse, joystick, keyboard)

ESP_BT_COD_MAJOR_DEV_IMAGING = 6¶: Imaging(printer, scanner, camera, display

ESP_BT_COD_MAJOR_DEV_WEARABLE = 7¶: Wearable

ESP_BT_COD_MAJOR_DEV_TOY = 8¶: Toy

ESP_BT_COD_MAJOR_DEV_HEALTH = 9¶: Health

ESP_BT_COD_MAJOR_DEV_UNCATEGORIZED = 31¶: Uncategorized: device not specified

enum esp_bt_gap_discovery_state_t¶

Bluetooth Device Discovery state

Values:

ESP_BT_GAP_DISCOVERY_STOPPED¶: device discovery stopped

ESP_BT_GAP_DISCOVERY_STARTED¶: device discovery started

enum esp_bt_gap_cb_event_t¶

BT GAP callback events.

Values:

ESP_BT_GAP_DISC_RES_EVT = 0¶: device discovery result event

ESP_BT_GAP_DISC_STATE_CHANGED_EVT¶: discovery state changed event

ESP_BT_GAP_RMT_SRVCS_EVT¶: get remote services event

ESP_BT_GAP_RMT_SRVC_REC_EVT¶: get remote service record event

ESP_BT_GAP_AUTH_CMPL_EVT¶: AUTH complete event

ESP_BT_GAP_PIN_REQ_EVT¶: Legacy Pairing Pin code request

ESP_BT_GAP_CFM_REQ_EVT¶: Simple Pairing User Confirmation request.

ESP_BT_GAP_KEY_NOTIF_EVT¶: Simple Pairing Passkey Notification

ESP_BT_GAP_KEY_REQ_EVT¶: Simple Pairing Passkey request

ESP_BT_GAP_READ_RSSI_DELTA_EVT¶: read rssi event

ESP_BT_GAP_EVT_MAX¶

enum esp_bt_inq_mode_t¶

Inquiry Mode

Values:

ESP_BT_INQ_MODE_GENERAL_INQUIRY¶: General inquiry mode

ESP_BT_INQ_MODE_LIMITED_INQUIRY¶: Limited inquiry mode