Controller & HCI

[中文]

API Reference

Header File

  • components/bt/include/esp32c6/include/esp_bt.h

  • This header file can be included with:

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

esp_err_t esp_ble_tx_power_set(esp_ble_power_type_t power_type, esp_power_level_t power_level)

Set BLE TX power Connection Tx power should only be set after connection created.

Parameters:

  • power_type -- : The type of which tx power, could set Advertising/Connection/Default and etc

  • power_level -- Power level(index) corresponding to absolute value(dbm)

Returns:

ESP_OK - success, other - failed

esp_power_level_t esp_ble_tx_power_get(esp_ble_power_type_t power_type)

Get BLE TX power Connection Tx power should only be get after connection created.

Parameters:

power_type -- : The type of which tx power, could set Advertising/Connection/Default and etc

Returns:

>= 0 - Power level, < 0 - Invalid

esp_err_t esp_ble_tx_power_set_enhanced(esp_ble_enhanced_power_type_t power_type, uint16_t handle, esp_power_level_t power_level)

ENHANCED API for Setting BLE TX power Connection Tx power should only be set after connection created.

Parameters:

  • power_type -- : The enhanced type of which tx power, could set Advertising/Connection/Default and etc.

  • handle -- : The handle of Advertising or Connection and the value 0 for other enhanced power types.

  • power_level -- Power level(index) corresponding to absolute value(dbm)

Returns:

ESP_OK - success, other - failed

esp_power_level_t esp_ble_tx_power_get_enhanced(esp_ble_enhanced_power_type_t power_type, uint16_t handle)

ENHANCED API of Getting BLE TX power Connection Tx power should only be get after connection created.

Parameters:

  • power_type -- : The enhanced type of which tx power, could set Advertising/Connection/Default and etc

  • handle -- : The handle of Advertising or Connection and the value 0 for other enhanced power types.

Returns:

>= 0 - Power level, < 0 - Invalid

esp_err_t esp_bt_controller_init(esp_bt_controller_config_t *cfg)

Initialize BT controller to allocate task and other resource. This function should be called only once, before any other BT functions are called.

Parameters:

cfg -- Initial configuration of BT controller.

Returns:

ESP_OK - success, other - failed

esp_bt_controller_status_t esp_bt_controller_get_status(void)

Get BT controller is initialised/de-initialised/enabled/disabled.

Returns:

status value

esp_err_t esp_bt_controller_deinit(void)

De-initialize BT controller to free resource and delete task. You should stop advertising and scanning, as well as disconnect all existing connections before de-initializing BT controller.

This function should be called only once, after any other BT functions are called. This function is not whole completed, esp_bt_controller_init cannot called after this function.

Returns:

ESP_OK - success, other - failed

esp_err_t esp_bt_controller_enable(esp_bt_mode_t mode)

Enable BT controller. Due to a known issue, you cannot call esp_bt_controller_enable() a second time to change the controller mode dynamically. To change controller mode, call esp_bt_controller_disable() and then call esp_bt_controller_enable() with the new mode.

Parameters:

mode -- : the mode(BLE/BT/BTDM) to enable. For compatible of API, retain this argument.

Returns:

ESP_OK - success, other - failed

esp_err_t esp_bt_controller_disable(void)

Disable BT controller.

Returns:

ESP_OK - success, other - failed

bool esp_vhci_host_check_send_available(void)

esp_vhci_host_check_send_available used for check actively if the host can send packet to controller or not.

Returns:

true for ready to send, false means cannot send packet

void esp_vhci_host_send_packet(uint8_t *data, uint16_t len)

esp_vhci_host_send_packet host send packet to controller

Should not call this function from within a critical section or when the scheduler is suspended.

Parameters:

  • data -- the packet point

  • len -- the packet length

esp_err_t esp_vhci_host_register_callback(const esp_vhci_host_callback_t *callback)

esp_vhci_host_register_callback register the vhci reference callback struct defined by vhci_host_callback structure.

Parameters:

callback -- esp_vhci_host_callback type variable

Returns:

ESP_OK - success, ESP_FAIL - failed

esp_err_t esp_bt_controller_mem_release(esp_bt_mode_t mode)

esp_bt_controller_mem_release release the controller memory as per the mode

This function releases the BSS, data and other sections of the controller to heap. The total size is about 70k bytes.

esp_bt_controller_mem_release(mode) should be called only before esp_bt_controller_init() or after esp_bt_controller_deinit().

Note that once BT controller memory is released, the process cannot be reversed. It means you cannot use the bluetooth mode which you have released by this function.

If your firmware will later upgrade the Bluetooth controller mode (BLE -> BT Classic or disabled -> enabled) then do not call this function.

If the app calls esp_bt_controller_enable(ESP_BT_MODE_BLE) to use BLE only then it is safe to call esp_bt_controller_mem_release(ESP_BT_MODE_CLASSIC_BT) at initialization time to free unused BT Classic memory.

If the mode is ESP_BT_MODE_BTDM, then it may be useful to call API esp_bt_mem_release(ESP_BT_MODE_BTDM) instead, which internally calls esp_bt_controller_mem_release(ESP_BT_MODE_BTDM) and additionally releases the BSS and data consumed by the BT/BLE host stack to heap. For more details about usage please refer to the documentation of esp_bt_mem_release() function

Parameters:

mode -- : the mode want to release memory

Returns:

ESP_OK - success, other - failed

esp_err_t esp_bt_mem_release(esp_bt_mode_t mode)

esp_bt_mem_release release controller memory and BSS and data section of the BT/BLE host stack as per the mode

This function first releases controller memory by internally calling esp_bt_controller_mem_release(). Additionally, if the mode is set to ESP_BT_MODE_BTDM, it also releases the BSS and data consumed by the BT/BLE host stack to heap

Note that once BT memory is released, the process cannot be reversed. It means you cannot use the bluetooth mode which you have released by this function.

If your firmware will later upgrade the Bluetooth controller mode (BLE -> BT Classic or disabled -> enabled) then do not call this function.

If you never intend to use bluetooth in a current boot-up cycle, you can call esp_bt_mem_release(ESP_BT_MODE_BTDM) before esp_bt_controller_init or after esp_bt_controller_deinit.

For example, if a user only uses bluetooth for setting the WiFi configuration, and does not use bluetooth in the rest of the product operation". In such cases, after receiving the WiFi configuration, you can disable/deinit bluetooth and release its memory. Below is the sequence of APIs to be called for such scenarios: 

 esp_bluedroid_disable();
 esp_bluedroid_deinit();
 esp_bt_controller_disable();
 esp_bt_controller_deinit();
 esp_bt_mem_release(ESP_BT_MODE_BTDM);

Parameters:

mode -- : the mode whose memory is to be released

Returns:

ESP_OK - success, other - failed

int esp_ble_hw_get_static_addr(esp_ble_addr_t *addr)

Returns random static address or -1 if not present.

Returns:

ESP_OK - success, other - failed

modem_clock_lpclk_src_t esp_bt_get_lpclk_src(void)
void esp_bt_set_lpclk_src(modem_clock_lpclk_src_t clk_src)
uint32_t esp_bt_get_lpclk_freq(void)
void esp_bt_set_lpclk_freq(uint32_t clk_freq)

Structures

struct esp_ble_addr_t

Address type and address value.

Public Members

uint8_t type

Type of the Bluetooth address (public, random, etc.)

uint8_t val[6]

Array containing the 6-byte Bluetooth address value

struct esp_bt_controller_config_t

Controller config options, depend on config mask. Config mask indicate which functions enabled, this means some options or parameters of some functions enabled by config mask.

Public Members

uint32_t config_version

Configuration version

uint16_t ble_ll_resolv_list_size

Size of the BLE resolving list

uint16_t ble_hci_evt_hi_buf_count

Number of high priority HCI event buffers

uint16_t ble_hci_evt_lo_buf_count

Number of low priority HCI event buffers

uint8_t ble_ll_sync_list_cnt

Number of entries in the BLE sync list

uint8_t ble_ll_sync_cnt

Number of BLE sync instances

uint16_t ble_ll_rsp_dup_list_count

Size of the BLE response duplicate list

uint16_t ble_ll_adv_dup_list_count

Size of the BLE advertising duplicate list

uint8_t ble_ll_tx_pwr_dbm

BLE transmit power in dBm

uint64_t rtc_freq

RTC (Real-Time Clock) frequency

uint16_t ble_ll_sca

BLE sleep clock accuracy in ppm

uint8_t ble_ll_scan_phy_number

Number of BLE scanning physical layers

uint16_t ble_ll_conn_def_auth_pyld_tmo

BLE connection default authentication payload timeout

uint8_t ble_ll_jitter_usecs

BLE link layer jitter in microseconds

uint16_t ble_ll_sched_max_adv_pdu_usecs

BLE scheduler maximum advertising PDU duration in microseconds

uint16_t ble_ll_sched_direct_adv_max_usecs

BLE scheduler maximum direct advertising duration in microseconds

uint16_t ble_ll_sched_adv_max_usecs

BLE scheduler maximum advertising duration in microseconds

uint16_t ble_scan_rsp_data_max_len

Maximum length of BLE scan response data

uint8_t ble_ll_cfg_num_hci_cmd_pkts

Number of BLE LL configuration HCI command packets

uint32_t ble_ll_ctrl_proc_timeout_ms

BLE link layer controller process timeout in milliseconds

uint16_t nimble_max_connections

Maximum number of concurrent BLE connections

uint8_t ble_whitelist_size

Size of the BLE whitelist

uint16_t ble_acl_buf_size

Size of the BLE ACL data buffer

uint16_t ble_acl_buf_count

Number of BLE ACL data buffers

uint16_t ble_hci_evt_buf_size

Size of the BLE HCI event buffer

uint16_t ble_multi_adv_instances

Number of BLE multi-advertising instances

uint16_t ble_ext_adv_max_size

Maximum size of BLE extended advertising data

uint16_t controller_task_stack_size

Controller task stack size

uint8_t controller_task_prio

Controller task priority

uint8_t controller_run_cpu

CPU core on which the controller runs

uint8_t enable_qa_test

Enable quality assurance (QA) testing

uint8_t enable_bqb_test

Enable Bluetooth Qualification Test (BQB) testing

uint8_t enable_tx_cca

Enable Transmit Clear Channel Assessment (TX CCA)

uint8_t cca_rssi_thresh

RSSI threshold for Transmit Clear Channel Assessment (CCA)

uint8_t sleep_en

Enable sleep mode

uint8_t coex_phy_coded_tx_rx_time_limit

PHY coded transmission and reception time limit for coexistence

uint8_t dis_scan_backoff

Disable scan backoff

uint8_t ble_scan_classify_filter_enable

Enable BLE scan classify filter

uint8_t cca_drop_mode

CCA drop mode

int8_t cca_low_tx_pwr

CCA low transmit power

uint8_t main_xtal_freq

Main crystal frequency

uint8_t cpu_freq_mhz

CPU frequency in megahertz (MHz)

uint8_t ignore_wl_for_direct_adv

Ignore the whitelist for direct advertising

uint8_t enable_pcl

Enable power control

uint8_t csa2_select

Select CSA#2

uint8_t enable_csr

Enable CSR

uint8_t ble_aa_check

True if adds a verification step for the Access Address within the CONNECT_IND PDU; false otherwise. Configurable in menuconfig

uint8_t ble_llcp_disc_flag

Flag indicating whether the Controller disconnects after Instant Passed (0x28) error occurs. Configurable in menuconfig.

  • The Controller does not disconnect after Instant Passed (0x28) by default.

uint16_t scan_backoff_upperlimitmax

The value of upperlimitmax is 2^n, The maximum value is 256

uint8_t ble_chan_ass_en

Enable / disable BLE channel assessment. Configurable in menuconfig.

  • 0 - Disable

  • 1 - Enable (default)

uint8_t ble_data_lenth_zero_aux

Enable / disable auxiliary packets when the extended ADV data length is zero. Configurable in menuconfig.

  • 0 - Disable (default)

  • 1 - Enable

uint8_t vhci_enabled

VHCI mode is enabled

uint8_t ptr_check_enabled

Enable boundary check for internal memory.

uint8_t ble_adv_tx_options

The options for Extended advertising sending.

uint8_t skip_unnecessary_checks_en

The option to skip non-fatal state checks and perform extra handling for fatal checks.

uint8_t fast_conn_data_tx_en

The option for fast transmission of connection data

  • 0 - Disable

  • 1 - Enable (default)

int8_t ch39_txpwr

BLE transmit power (in dBm) used for BLE advertising on channel 39.

uint32_t config_magic

Magic number for configuration validation

struct esp_vhci_host_callback

esp_vhci_host_callback used for vhci call host function to notify what host need to do

Public Members

void (*notify_host_send_available)(void)

callback used to notify that the host can send packet to controller

int (*notify_host_recv)(uint8_t *data, uint16_t len)

callback used to notify that the controller has a packet to send to the host

Macros

CONFIG_VERSION
CONFIG_MAGIC
BT_CONTROLLER_INIT_CONFIG_DEFAULT()

Type Definitions

typedef struct esp_vhci_host_callback esp_vhci_host_callback_t

esp_vhci_host_callback used for vhci call host function to notify what host need to do

Enumerations

enum esp_bt_mode_t

Bluetooth mode for controller enable/disable.

Values:

enumerator ESP_BT_MODE_IDLE

Bluetooth is not running

enumerator ESP_BT_MODE_BLE

Run BLE mode

enumerator ESP_BT_MODE_CLASSIC_BT

Run Classic BT mode

enumerator ESP_BT_MODE_BTDM

Run dual mode

enum esp_bt_controller_status_t

Bluetooth controller enable/disable/initialised/de-initialised status.

Values:

enumerator ESP_BT_CONTROLLER_STATUS_IDLE

Controller is in idle state

enumerator ESP_BT_CONTROLLER_STATUS_INITED

Controller is in initialising state

enumerator ESP_BT_CONTROLLER_STATUS_ENABLED

Controller is in enabled state

enumerator ESP_BT_CONTROLLER_STATUS_NUM

Controller is in disabled state

enum esp_ble_power_type_t

BLE tx power type ESP_BLE_PWR_TYPE_CONN_HDL0-8: for each connection, and only be set after connection completed. when disconnect, the correspond TX power is not effected. ESP_BLE_PWR_TYPE_ADV : for advertising/scan response. ESP_BLE_PWR_TYPE_SCAN : for scan. ESP_BLE_PWR_TYPE_DEFAULT : if each connection's TX power is not set, it will use this default value. if neither in scan mode nor in adv mode, it will use this default value. If none of power type is set, system will use ESP_PWR_LVL_P3 as default for ADV/SCAN/CONN0-9.

Values:

enumerator ESP_BLE_PWR_TYPE_CONN_HDL0

For connection handle 0

enumerator ESP_BLE_PWR_TYPE_CONN_HDL1

For connection handle 1

enumerator ESP_BLE_PWR_TYPE_CONN_HDL2

For connection handle 2

enumerator ESP_BLE_PWR_TYPE_CONN_HDL3

For connection handle 3

enumerator ESP_BLE_PWR_TYPE_CONN_HDL4

For connection handle 4

enumerator ESP_BLE_PWR_TYPE_CONN_HDL5

For connection handle 5

enumerator ESP_BLE_PWR_TYPE_CONN_HDL6

For connection handle 6

enumerator ESP_BLE_PWR_TYPE_CONN_HDL7

For connection handle 7

enumerator ESP_BLE_PWR_TYPE_CONN_HDL8

For connection handle 8

enumerator ESP_BLE_PWR_TYPE_ADV

For advertising

enumerator ESP_BLE_PWR_TYPE_SCAN

For scan

enumerator ESP_BLE_PWR_TYPE_DEFAULT

For default, if not set other, it will use default value

enumerator ESP_BLE_PWR_TYPE_NUM

TYPE numbers

enum esp_power_level_t

Bluetooth TX power level(index), it's just a index corresponding to power(dbm).

Values:

enumerator ESP_PWR_LVL_N15

Corresponding to -15dbm

enumerator ESP_PWR_LVL_N12

Corresponding to -12dbm

enumerator ESP_PWR_LVL_N9

Corresponding to -9dbm

enumerator ESP_PWR_LVL_N6

Corresponding to -6dbm

enumerator ESP_PWR_LVL_N3

Corresponding to -3dbm

enumerator ESP_PWR_LVL_N0

Corresponding to 0dbm

enumerator ESP_PWR_LVL_P3

Corresponding to +3dbm

enumerator ESP_PWR_LVL_P6

Corresponding to +6dbm

enumerator ESP_PWR_LVL_P9

Corresponding to +9dbm

enumerator ESP_PWR_LVL_P12

Corresponding to +12dbm

enumerator ESP_PWR_LVL_P15

Corresponding to +15dbm

enumerator ESP_PWR_LVL_P18

Corresponding to +18dbm

enumerator ESP_PWR_LVL_P20

Corresponding to +20dbm

enumerator ESP_PWR_LVL_INVALID

Indicates an invalid value

enum esp_ble_enhanced_power_type_t

The enhanced type of which tx power, could set Advertising/Connection/Default and etc.

Values:

enumerator ESP_BLE_ENHANCED_PWR_TYPE_DEFAULT
enumerator ESP_BLE_ENHANCED_PWR_TYPE_ADV
enumerator ESP_BLE_ENHANCED_PWR_TYPE_SCAN
enumerator ESP_BLE_ENHANCED_PWR_TYPE_INIT
enumerator ESP_BLE_ENHANCED_PWR_TYPE_CONN
enumerator ESP_BLE_ENHANCED_PWR_TYPE_MAX
enum esp_ble_log_buf_t

Select buffers.

Values:

enumerator ESP_BLE_LOG_BUF_HCI
enumerator ESP_BLE_LOG_BUF_CONTROLLER

HCI Vendor-specific (VS) Commands

Espressif's HCI VS commands are exclusively designed for use with Espressif's Bluetooth Host stack or internal debugging purposes. Application developers should not initialize or invoke these VS commands in their applications. Please refer to HCI Vendor-specific (VS) Commands for detailed information.

Was this page helpful?