Warning

This document is not updated for ESP32H4 yet, so some of the content may not be correct.

This warning was automatically inserted due to the source file being in the add_warnings_pages list.

# Bluetooth® Generic Defines

## API Reference

### Header File

- components/bt/host/bluedroid/api/include/api/esp_bt_defs.h

- This header file can be included with:

  >     #include "esp_bt_defs.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

### Structures

struct esp_ble_conn_params_t

  create connection parameters

  Public Members

  uint16_t scan_interval

    Initial scan interval, in units of 0.625ms, the range is 0x0004(2.5ms) to 0xFFFF(10.24s).

  uint16_t scan_window

    Initial scan window, in units of 0.625ms, the range is 0x0004(2.5ms) to 0xFFFF(10.24s).

  uint16_t interval_min

    Minimum connection interval, in units of 1.25 ms, the range is 0x0006(7.5ms) to 0x0C80(4s). Sub-spec values are accepted only if the controller supports them.

  uint16_t interval_max

    Maximum connection interval, in units of 1.25 ms, the range is 0x0006(7.5ms) to 0x0C80(4s). Same bounds as interval_min.

  uint16_t latency

    Connection latency, the range is 0x0000(0) to 0x01F3(499).

  uint16_t supervision_timeout

    Connection supervision timeout, in units of 10ms, the range is from 0x000A(100ms) to 0x0C80(32s).

  uint16_t min_ce_len

    Minimum connection event length, in units of 0.625ms, setting to 0 for no preferred parameters.

  uint16_t max_ce_len

    Maximum connection event length, in units of 0.625ms, setting to 0 for no preferred parameters.

struct esp_bt_uuid_t

  UUID type.

  Public Members

  uint16_t len

    UUID length, 16bit, 32bit or 128bit

  uint16_t uuid16

    16bit UUID

  uint32_t uuid32

    32bit UUID

  uint8_t uuid128[ESP_UUID_LEN_128]

    128bit UUID

  union esp_bt_uuid_t uuid

    UUID

### Macros

ESP_BLUEDROID_STATUS_CHECK(status)

ESP_BT_STATUS_BASE_FOR_HCI_ERR

ESP_HCI_ERR_SUCCESS

ESP_HCI_ERR_UNKNOWN_CMD

ESP_HCI_ERR_UNKNOWN_CONN_ID

ESP_HCI_ERR_HW_FAILURE

ESP_HCI_ERR_PAGE_TIMEOUT

ESP_HCI_ERR_AUTH_FAIL

ESP_HCI_ERR_PIN_OR_KEY_MISSING

ESP_HCI_ERR_MEM_CAPACITY_EXCEEDED

ESP_HCI_ERR_CONN_TIMEOUT

ESP_HCI_ERR_CONN_LIMIT_EXCEEDED

ESP_HCI_ERR_SYNC_CONN_LIMIT_EXCEEDED

ESP_HCI_ERR_CONN_ALREADY_EXISTS

ESP_HCI_ERR_CMD_DISALLOWED

ESP_HCI_ERR_INSUFFICIENT_RESOURCES

ESP_HCI_ERR_INSUFFICIENT_SECURITY

ESP_HCI_ERR_BD_ADDR_UNACCEPTABLE

ESP_HCI_ERR_CONN_ACCEPT_TIMEOUT

ESP_HCI_ERR_UNSUPP_FEATURE_PARAM_VAL

ESP_HCI_ERR_INVALID_PARAM

ESP_HCI_ERR_REMOTE_USER_TERM_CONN

ESP_HCI_ERR_REMOTE_LOW_RESOURCES

ESP_HCI_ERR_REMOTE_POWER_OFF

ESP_HCI_ERR_LOCALHOST_TERM_CONN

ESP_HCI_ERR_REPEATED_ATTEMPTS

ESP_HCI_ERR_PAIRING_NOT_ALLOWED

ESP_HCI_ERR_UNKNOWN_LMP_PDU

ESP_HCI_ERR_UNSUPP_REMOTE_FEATURE

ESP_HCI_ERR_SCO_OFFSET_REJECTED

ESP_HCI_ERR_SCO_INTERVAL_REJECTED

ESP_HCI_ERR_SCO_AIR_MODE_REJECTED

ESP_HCI_ERR_INVALID_LL_PARAM

ESP_HCI_ERR_UNSPECIFIED

ESP_HCI_ERR_UNSUPP_LL_PARAM_VAL

ESP_HCI_ERR_ROLE_CHANGE_NOT_ALLOWED

ESP_HCI_ERR_LL_RESP_TIMEOUT

ESP_HCI_ERR_LL_PROC_COLLISION

ESP_HCI_ERR_LMP_PDU_NOT_ALLOWED

ESP_HCI_ERR_ENC_MODE_NOT_ACCEPTABLE

ESP_HCI_ERR_LINK_KEY_CANNOT_BE_CHANGED

ESP_HCI_ERR_REQUESTED_QOS_NOT_SUPPORTED

ESP_HCI_ERR_INSTANT_PASSED

ESP_HCI_ERR_PAIRING_NOT_SUPPORTED

ESP_HCI_ERR_DIFF_TRANS_COLLISION

ESP_HCI_ERR_UNDEFINED_0x2B

ESP_HCI_ERR_QOS_UNACCEPTABLE_PARAM

ESP_HCI_ERR_QOS_REJECTED

ESP_HCI_ERR_CHAN_ASSESS_NOT_SUPPORTED

ESP_HCI_ERR_INSUFF_SECURITY

ESP_HCI_ERR_PARAM_OUT_OF_MANDATORY_RANGE

ESP_HCI_ERR_UNDEFINED_0x31

ESP_HCI_ERR_ROLE_SWITCH_PENDING

ESP_HCI_ERR_UNDEFINED_0x33

ESP_HCI_ERR_RESERVED_SLOT_VIOLATION

ESP_HCI_ERR_ROLE_SWITCH_FAILED

ESP_HCI_ERR_EXT_INQ_RESP_TOO_LARGE

ESP_HCI_ERR_SIMPLE_PAIR_NOT_SUPP_BY_HOST

ESP_HCI_ERR_HOST_BUSY_PAIRING

ESP_HCI_ERR_CONN_REJECTED_DUE_TO_NO_CHAN

ESP_HCI_ERR_CONTROLLER_BUSY

ESP_HCI_ERR_UNACCEPT_CONN_PARAM

ESP_HCI_ERR_ADV_TIMEOUT

ESP_HCI_ERR_TERM_DUE_TO_MIC_FAIL

ESP_HCI_ERR_CONN_FAIL_TO_ESTAB

ESP_HCI_ERR_MAC_CONN_FAILED

ESP_HCI_ERR_CLOCK_ADJUST_REJECTED

ESP_HCI_ERR_SUBMAP_NOT_DEFINED

ESP_HCI_ERR_UNKNOWN_ADV_IDENTIFIER

ESP_HCI_ERR_LIMIT_REACHED

ESP_HCI_ERR_OP_CANCELLED_BY_HOST

ESP_HCI_ERR_PACKET_TOO_LONG

ESP_HCI_ERR_TOO_LATE

ESP_HCI_ERR_TOO_EARLY

ESP_HCI_ERR_INSUFFICIENT_CHANNELS

ESP_BT_OCTET16_LEN

ESP_BT_OCTET8_LEN

ESP_DEFAULT_GATT_IF

  Default GATT interface id.

ESP_BLE_PRIM_ADV_INT_MIN

  Minimum advertising interval for undirected and low duty cycle directed advertising

ESP_BLE_PRIM_ADV_INT_MAX

  Maximum advertising interval for undirected and low duty cycle directed advertising

ESP_BLE_CONN_INT_MIN

  Minimum connection interval, 7.5 ms (BLE Core Spec minimum)

ESP_BLE_CONN_INT_MAX

  relate to BTM_BLE_CONN_INT_MAX in stack/btm_ble_api.h

ESP_BLE_CONN_LATENCY_MAX

  relate to ESP_BLE_CONN_LATENCY_MAX in stack/btm_ble_api.h

ESP_BLE_CONN_SUP_TOUT_MIN

  relate to BTM_BLE_CONN_SUP_TOUT_MIN in stack/btm_ble_api.h

ESP_BLE_CONN_SUP_TOUT_MAX

  relate to ESP_BLE_CONN_SUP_TOUT_MAX in stack/btm_ble_api.h

ESP_BLE_PHY_1M_PREF_MASK

  The Host prefers use the LE1M transmitter or receiver PHY

ESP_BLE_PHY_2M_PREF_MASK

  The Host prefers use the LE2M transmitter or receiver PHY

ESP_BLE_PHY_CODED_PREF_MASK

  The Host prefers use the LE CODED transmitter or receiver PHY

ESP_BLE_IS_VALID_PARAM(x, min, max)

  Check the param is valid or not.

ESP_UUID_LEN_16

ESP_UUID_LEN_32

ESP_UUID_LEN_128

ESP_BD_ADDR_LEN

  Bluetooth address length.

ESP_PEER_IRK_LEN

  Bluetooth peer irk.

ESP_BLE_ENC_KEY_MASK

  Used to exchange the encryption key in the init key & response key.

ESP_BLE_ID_KEY_MASK

  Used to exchange the IRK key in the init key & response key.

ESP_BLE_CSR_KEY_MASK

  Used to exchange the CSRK key in the init key & response key.

ESP_BLE_LINK_KEY_MASK

  Used to exchange the link key(this key just used in the BLE & BR/EDR coexist mode) in the init key & response key.

ESP_APP_ID_MIN

  Minimum of the application id.

ESP_APP_ID_MAX

  Maximum of the application id.

ESP_BD_ADDR_STR

ESP_BD_ADDR_HEX(addr)

ESP_BLE_ADV_NAME_LEN_MAX

ESP_INVALID_CONN_HANDLE

### Type Definitions

typedef uint8_t esp_bt_octet16_t[ESP_BT_OCTET16_LEN]

typedef uint8_t esp_bt_octet8_t[ESP_BT_OCTET8_LEN]

typedef uint8_t esp_link_key[ESP_BT_OCTET16_LEN]

typedef uint8_t esp_ble_phy_mask_t

typedef uint8_t esp_bd_addr_t[ESP_BD_ADDR_LEN]

  Bluetooth device address.

typedef uint8_t esp_ble_key_mask_t

### Enumerations

enum esp_bt_status_t

  Status Return Value.

  Values:

  enumerator ESP_BT_STATUS_SUCCESS
  enumerator ESP_BT_STATUS_FAIL
  enumerator ESP_BT_STATUS_NOT_READY
  enumerator ESP_BT_STATUS_NOMEM
  enumerator ESP_BT_STATUS_BUSY
  enumerator ESP_BT_STATUS_DONE
  enumerator ESP_BT_STATUS_UNSUPPORTED
  enumerator ESP_BT_STATUS_PARM_INVALID
  enumerator ESP_BT_STATUS_UNHANDLED
  enumerator ESP_BT_STATUS_AUTH_FAILURE
  enumerator ESP_BT_STATUS_RMT_DEV_DOWN
  enumerator ESP_BT_STATUS_AUTH_REJECTED
  enumerator ESP_BT_STATUS_INVALID_STATIC_RAND_ADDR
  enumerator ESP_BT_STATUS_PENDING
  enumerator ESP_BT_STATUS_UNACCEPT_CONN_INTERVAL
  enumerator ESP_BT_STATUS_PARAM_OUT_OF_RANGE
  enumerator ESP_BT_STATUS_TIMEOUT
  enumerator ESP_BT_STATUS_PEER_LE_DATA_LEN_UNSUPPORTED
  enumerator ESP_BT_STATUS_CONTROL_LE_DATA_LEN_UNSUPPORTED
  enumerator ESP_BT_STATUS_ERR_ILLEGAL_PARAMETER_FMT
  enumerator ESP_BT_STATUS_MEMORY_FULL
  enumerator ESP_BT_STATUS_EIR_TOO_LARGE
  enumerator ESP_BT_STATUS_HCI_SUCCESS
  enumerator ESP_BT_STATUS_HCI_ILLEGAL_COMMAND
  enumerator ESP_BT_STATUS_HCI_NO_CONNECTION
  enumerator ESP_BT_STATUS_HCI_HW_FAILURE
  enumerator ESP_BT_STATUS_HCI_PAGE_TIMEOUT
  enumerator ESP_BT_STATUS_HCI_AUTH_FAILURE
  enumerator ESP_BT_STATUS_HCI_KEY_MISSING
  enumerator ESP_BT_STATUS_HCI_MEMORY_FULL
  enumerator ESP_BT_STATUS_HCI_CONNECTION_TOUT
  enumerator ESP_BT_STATUS_HCI_MAX_NUM_OF_CONNECTIONS
  enumerator ESP_BT_STATUS_HCI_MAX_NUM_OF_SCOS
  enumerator ESP_BT_STATUS_HCI_CONNECTION_EXISTS
  enumerator ESP_BT_STATUS_HCI_COMMAND_DISALLOWED
  enumerator ESP_BT_STATUS_HCI_HOST_REJECT_RESOURCES
  enumerator ESP_BT_STATUS_HCI_HOST_REJECT_SECURITY
  enumerator ESP_BT_STATUS_HCI_HOST_REJECT_DEVICE
  enumerator ESP_BT_STATUS_HCI_HOST_TIMEOUT
  enumerator ESP_BT_STATUS_HCI_UNSUPPORTED_VALUE
  enumerator ESP_BT_STATUS_HCI_ILLEGAL_PARAMETER_FMT
  enumerator ESP_BT_STATUS_HCI_PEER_USER
  enumerator ESP_BT_STATUS_HCI_PEER_LOW_RESOURCES
  enumerator ESP_BT_STATUS_HCI_PEER_POWER_OFF
  enumerator ESP_BT_STATUS_HCI_CONN_CAUSE_LOCAL_HOST
  enumerator ESP_BT_STATUS_HCI_REPEATED_ATTEMPTS
  enumerator ESP_BT_STATUS_HCI_PAIRING_NOT_ALLOWED
  enumerator ESP_BT_STATUS_HCI_UNKNOWN_LMP_PDU
  enumerator ESP_BT_STATUS_HCI_UNSUPPORTED_REM_FEATURE
  enumerator ESP_BT_STATUS_HCI_SCO_OFFSET_REJECTED
  enumerator ESP_BT_STATUS_HCI_SCO_INTERVAL_REJECTED
  enumerator ESP_BT_STATUS_HCI_SCO_AIR_MODE
  enumerator ESP_BT_STATUS_HCI_INVALID_LMP_PARAM
  enumerator ESP_BT_STATUS_HCI_UNSPECIFIED
  enumerator ESP_BT_STATUS_HCI_UNSUPPORTED_LMP_PARAMETERS
  enumerator ESP_BT_STATUS_HCI_ROLE_CHANGE_NOT_ALLOWED
  enumerator ESP_BT_STATUS_HCI_LMP_RESPONSE_TIMEOUT
  enumerator ESP_BT_STATUS_HCI_LMP_ERR_TRANS_COLLISION
  enumerator ESP_BT_STATUS_HCI_LMP_PDU_NOT_ALLOWED
  enumerator ESP_BT_STATUS_HCI_ENCRY_MODE_NOT_ACCEPTABLE
  enumerator ESP_BT_STATUS_HCI_UNIT_KEY_USED
  enumerator ESP_BT_STATUS_HCI_QOS_NOT_SUPPORTED
  enumerator ESP_BT_STATUS_HCI_INSTANT_PASSED
  enumerator ESP_BT_STATUS_HCI_PAIRING_WITH_UNIT_KEY_NOT_SUPPORTED
  enumerator ESP_BT_STATUS_HCI_DIFF_TRANSACTION_COLLISION
  enumerator ESP_BT_STATUS_HCI_UNDEFINED_0x2B
  enumerator ESP_BT_STATUS_HCI_QOS_UNACCEPTABLE_PARAM
  enumerator ESP_BT_STATUS_HCI_QOS_REJECTED
  enumerator ESP_BT_STATUS_HCI_CHAN_CLASSIF_NOT_SUPPORTED
  enumerator ESP_BT_STATUS_HCI_INSUFFCIENT_SECURITY
  enumerator ESP_BT_STATUS_HCI_PARAM_OUT_OF_RANGE
  enumerator ESP_BT_STATUS_HCI_UNDEFINED_0x31
  enumerator ESP_BT_STATUS_HCI_ROLE_SWITCH_PENDING
  enumerator ESP_BT_STATUS_HCI_UNDEFINED_0x33
  enumerator ESP_BT_STATUS_HCI_RESERVED_SLOT_VIOLATION
  enumerator ESP_BT_STATUS_HCI_ROLE_SWITCH_FAILED
  enumerator ESP_BT_STATUS_HCI_INQ_RSP_DATA_TOO_LARGE
  enumerator ESP_BT_STATUS_HCI_SIMPLE_PAIRING_NOT_SUPPORTED
  enumerator ESP_BT_STATUS_HCI_HOST_BUSY_PAIRING
  enumerator ESP_BT_STATUS_HCI_REJ_NO_SUITABLE_CHANNEL
  enumerator ESP_BT_STATUS_HCI_CONTROLLER_BUSY
  enumerator ESP_BT_STATUS_HCI_UNACCEPT_CONN_INTERVAL
  enumerator ESP_BT_STATUS_HCI_DIRECTED_ADVERTISING_TIMEOUT
  enumerator ESP_BT_STATUS_HCI_CONN_TOUT_DUE_TO_MIC_FAILURE
  enumerator ESP_BT_STATUS_HCI_CONN_FAILED_ESTABLISHMENT
  enumerator ESP_BT_STATUS_HCI_MAC_CONNECTION_FAILED
  enumerator ESP_BT_STATUS_HCI_CCA_REJECTED
  enumerator ESP_BT_STATUS_HCI_TYPE0_SUBMAP_NOT_DEFINED
  enumerator ESP_BT_STATUS_HCI_UNKNOWN_ADV_ID
  enumerator ESP_BT_STATUS_HCI_LIMIT_REACHED
  enumerator ESP_BT_STATUS_HCI_OPT_CANCEL_BY_HOST
  enumerator ESP_BT_STATUS_HCI_PKT_TOO_LONG
  enumerator ESP_BT_STATUS_HCI_TOO_LATE
  enumerator ESP_BT_STATUS_HCI_TOO_EARLY

enum esp_bt_dev_type_t

  Bluetooth device type.

  Values:

  enumerator ESP_BT_DEVICE_TYPE_BREDR
  enumerator ESP_BT_DEVICE_TYPE_BLE
  enumerator ESP_BT_DEVICE_TYPE_DUMO

enum esp_ble_addr_type_t

  BLE device address type.

  Values:

  enumerator BLE_ADDR_TYPE_PUBLIC

    Public Device Address

  enumerator BLE_ADDR_TYPE_RANDOM

    Random Device Address. To set this address, use the function esp_ble_gap_set_rand_addr(esp_bd_addr_t rand_addr)

  enumerator BLE_ADDR_TYPE_RPA_PUBLIC

    Resolvable Private Address (RPA) with public identity address

  enumerator BLE_ADDR_TYPE_RPA_RANDOM

    Resolvable Private Address (RPA) with random identity address. To set this address, use the function esp_ble_gap_set_rand_addr(esp_bd_addr_t rand_addr)

enum esp_ble_wl_addr_type_t

  white list address type

  Values:

  enumerator BLE_WL_ADDR_TYPE_PUBLIC

    Public Device Address

  enumerator BLE_WL_ADDR_TYPE_RANDOM

    Random Device Address

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.