# Bluetooth® Classic GAP API

## Overview

The Bluetooth Classic GAP (Generic Access Profile) API provides interfaces for device discovery, pairing, and security management, allowing applications to control visibility, initiate connections, and configure authentication and encryption for Bluetooth Classic links.

## Application Examples

- bluetooth/bluedroid/classic_bt/bt_discovery demonstrates how to use APIs to search for a target device with a Major device type of "Phone" or "Audio/Video" in the Class of Device field, and then perform a service discovery via the Service Discovery Protocol.

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

  Parameters:

    callback -- [in] : callback function

  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.

  Parameters:

    remote_bda -- [in] : remote bluetooth device address

  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

  Parameters:

    - remote_bda -- [in] : remote bluetooth device address

    - uuid -- [in] : uuid

  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_ACL_PKT_TYPE_CHANGED_EVT event will be reported to the APP layer.

  Parameters:

    - remote_bda -- [in] : remote bluetooth device address

    - pkt_types -- [in] : packet type

  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.

  Parameters:

    key_size -- [in] : the 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

esp_err_t esp_bt_gap_get_profile_status(esp_bt_gap_profile_status_t *profile_status)

  Get the status of GAP.

  Parameters:

    profile_status -- [out] - GAP status

  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

  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

struct esp_bt_gap_profile_status_t

  GAP status

  Public Members

  esp_bt_gap_discovery_state_t disc_stat

    Device Discovery state

  esp_bt_connection_mode_t conn_mode

    Connection mode

  esp_bt_discovery_mode_t disc_mode

    Discovery mode

  uint8_t bredr_acl_link_num

    Number of bredr link connections

### Macros

ESP_BT_GAP_AFH_CHANNELS_LEN

  length of AFH channel map in bytes

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

  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

  DM1 packet type mask

ESP_BT_ACL_PKT_TYPES_MASK_DH1

  DH1 packet type mask

ESP_BT_ACL_PKT_TYPES_MASK_DM3

  DM3 packet type mask

ESP_BT_ACL_PKT_TYPES_MASK_DH3

  DH3 packet type mask

ESP_BT_ACL_PKT_TYPES_MASK_DM5

  DM5 packet type mask

ESP_BT_ACL_PKT_TYPES_MASK_DH5

  DH5 packet type mask

ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH1

  No 2-DH1 packet type mask

ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH1

  No 3-DH1 packet type mask

ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH3

  No 2-DH3 packet type mask

ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH3

  No 3-DH3 packet type mask

ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH5

  No 2-DH5 packet type mask

ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH5

  No 3-DH5 packet type mask

ESP_BT_ACL_DM1_ONLY

  0x330e

ESP_BT_ACL_DH1_ONLY

  0x331e

ESP_BT_ACL_DM3_ONLY

  0x370e

ESP_BT_ACL_DH3_ONLY

  0x3b0e

ESP_BT_ACL_DM5_ONLY

  0x730e

ESP_BT_ACL_DH5_ONLY

  0xb30e

ESP_BT_ACL_2_DH1_ONLY

  0x330c

ESP_BT_ACL_3_DH1_ONLY

  0x330a

ESP_BT_ACL_2_DH3_ONLY

  0x320e

ESP_BT_ACL_3_DH3_ONLY

  0x310e

ESP_BT_ACL_2_DH5_ONLY

  0x230e

ESP_BT_ACL_3_DH5_ONLY

  0x130e

ESP_BT_ENC_KEY_SIZE_CTRL_MAX

  Maximum of encryption key size

ESP_BT_ENC_KEY_SIZE_CTRL_MIN

  Minimum of encryption key size

ESP_BT_EIR_FLAG_LIMIT_DISC

  Limited discoverable flag

ESP_BT_EIR_FLAG_GEN_DISC

  General discoverable flag

ESP_BT_EIR_FLAG_BREDR_NOT_SPT

  BR/EDR not supported flag

ESP_BT_EIR_FLAG_DMT_CONTROLLER_SPT

  DMT controller supported flag

ESP_BT_EIR_FLAG_DMT_HOST_SPT

  DMT host supported flag

ESP_BT_EIR_MAX_LEN

  Maximum of EIR length

ESP_BT_PIN_CODE_LEN

  Max pin code length

ESP_BT_IO_CAP_OUT

  DisplayOnly

ESP_BT_IO_CAP_IO

  DisplayYesNo

ESP_BT_IO_CAP_IN

  KeyboardOnly

ESP_BT_IO_CAP_NONE

  NoInputNoOutput

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

  Major service bit mask

ESP_BT_COD_SRVC_BIT_OFFSET

  Major service bit offset

ESP_BT_COD_MAJOR_DEV_BIT_MASK

  Major device bit mask

ESP_BT_COD_MAJOR_DEV_BIT_OFFSET

  Major device bit offset

ESP_BT_COD_MINOR_DEV_BIT_MASK

  Minor device bit mask

ESP_BT_COD_MINOR_DEV_BIT_OFFSET

  Minor device bit offset

ESP_BT_COD_FORMAT_TYPE_BIT_MASK

  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

  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

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

  AFH channels

typedef uint8_t esp_bt_eir_type_t

  EIR type

typedef uint16_t esp_bt_acl_pkt_type_t

  ACL packet type

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

  BT Power manager mode type

typedef uint8_t esp_bt_link_key_type_t

  Link key type

typedef uint8_t esp_bt_enc_mode_t

  encryption mode type

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

  Connectability mode.

  Values:

  enumerator ESP_BT_NON_CONNECTABLE

    Non-connectable

  enumerator ESP_BT_CONNECTABLE

    Connectable

enum esp_bt_discovery_mode_t

  Discoverability mode.

  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

  Pin type.

  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

  SP parameter type.

  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

    Mode change event

  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

Was this page helpful?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.