Controller && VHCI
Application Example
Check bluetooth/hci folder in ESP-IDF examples, which contains the following application:
This is a Bluetooth® Low Energy (Bluetooth LE) advertising demo with virtual HCI interface. Send Reset/ADV_PARAM/ADV_DATA/ADV_ENABLE HCI command for Bluetooth Low Energy advertising - bluetooth/hci/controller_vhci_ble_adv.
API Reference
Header File
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 onbt
, 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
Structures
-
struct esp_ble_addr_t
Address type and 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
Version number of the defined structure
-
uint16_t ble_ll_resolv_list_size
Size of the resolvable private address list
-
uint16_t ble_hci_evt_hi_buf_count
Count of high buffers for HCI events
-
uint16_t ble_hci_evt_lo_buf_count
Count of low buffers for HCI events
-
uint8_t ble_ll_sync_list_cnt
Number of synchronization lists
-
uint8_t ble_ll_sync_cnt
Number of synchronizations
-
uint16_t ble_ll_rsp_dup_list_count
Count of duplicated lists for scan response packets
-
uint16_t ble_ll_adv_dup_list_count
Count of duplicated lists for advertising packets
-
uint8_t ble_ll_tx_pwr_dbm
Tx power (transmit power) in dBm
-
uint64_t rtc_freq
Frequency of RTC (Real-Time Clock)
-
uint16_t ble_ll_sca
Sleep Clock Accuracy (SCA) parameter
-
uint8_t ble_ll_scan_phy_number
Number of PHYs supported for scanning
-
uint16_t ble_ll_conn_def_auth_pyld_tmo
Connection default authentication payload timeout
-
uint8_t ble_ll_jitter_usecs
Jitter time in microseconds
-
uint16_t ble_ll_sched_max_adv_pdu_usecs
Maximum time in microseconds for advertising PDU scheduling
-
uint16_t ble_ll_sched_direct_adv_max_usecs
Maximum time in microseconds for directed advertising scheduling
-
uint16_t ble_ll_sched_adv_max_usecs
Maximum time in microseconds for advertising scheduling
-
uint16_t ble_scan_rsp_data_max_len
Maximum length of scan response data
-
uint8_t ble_ll_cfg_num_hci_cmd_pkts
Number of HCI command packets that can be queued
-
uint32_t ble_ll_ctrl_proc_timeout_ms
Control processing timeout in milliseconds
-
uint16_t nimble_max_connections
Maximum number of connections supported
-
uint8_t ble_whitelist_size
Size of the white list
-
uint16_t ble_acl_buf_size
Buffer size of ACL (Asynchronous Connection-Less) data
-
uint16_t ble_acl_buf_count
Buffer count of ACL data
-
uint16_t ble_hci_evt_buf_size
Buffer size for HCI event data
-
uint16_t ble_multi_adv_instances
Number of advertising instances
-
uint16_t ble_ext_adv_max_size
Maximum size of extended advertising data
-
uint16_t controller_task_stack_size
Size of Bluetooth controller task stack
-
uint8_t controller_task_prio
Priority of the Bluetooth task
-
uint8_t controller_run_cpu
CPU number on which the Bluetooth controller task runs
-
uint8_t enable_qa_test
Enable for QA test
-
uint8_t enable_bqb_test
Enable for BQB test
-
uint8_t enable_uart_hci
Enable UART for HCI (Host Controller Interface)
-
uint8_t ble_hci_uart_port
Port of UART for HCI
-
uint32_t ble_hci_uart_baud
Baudrate of UART for HCI
-
uint8_t ble_hci_uart_data_bits
Data bits of UART for HCI
-
uint8_t ble_hci_uart_stop_bits
Stop bits of UART for HCI
-
uint8_t ble_hci_uart_flow_ctrl
Flow control of UART for HCI
-
uint8_t ble_hci_uart_uart_parity
UART parity
-
uint8_t enable_tx_cca
Enable Clear Channel Assessment (CCA) when transmitting
-
uint8_t cca_rssi_thresh
RSSI threshold for CCA
-
uint8_t sleep_en
Enable sleep functionality
-
uint8_t coex_phy_coded_tx_rx_time_limit
Coexistence PHY coded TX and RX time limit
-
uint8_t dis_scan_backoff
Disable scan backoff
-
uint8_t ble_scan_classify_filter_enable
Enable classification filter for BLE scan
-
uint8_t cca_drop_mode
CCA drop mode
-
int8_t cca_low_tx_pwr
Low TX power setting for CCA
-
uint8_t main_xtal_freq
Main crystal frequency
-
uint8_t cpu_freq_mhz
CPU frequency in megahertz
-
uint8_t ignore_wl_for_direct_adv
Ignore the white list for directed advertising
-
uint8_t enable_pcl
Enable power control
-
uint8_t csa2_select
Select CSA#2
-
uint32_t config_magic
Configuration magic value
-
uint32_t config_version
-
struct esp_vhci_host_callback
esp_vhci_host_callback used for vhci call host function to notify what host need to do
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
-
enumerator ESP_BT_MODE_IDLE
-
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
-
enumerator ESP_BT_CONTROLLER_STATUS_IDLE
-
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
-
enumerator ESP_BLE_PWR_TYPE_CONN_HDL0
-
enum esp_power_level_t
Bluetooth TX power level(index), it's just a index corresponding to power(dbm).
Values:
-
enumerator ESP_PWR_LVL_N24
Corresponding to -24dbm
-
enumerator ESP_PWR_LVL_N21
Corresponding to -21dbm
-
enumerator ESP_PWR_LVL_N18
Corresponding to -18dbm
-
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_P16
Corresponding to +18dbm, this enum variable has been deprecated
-
enumerator ESP_PWR_LVL_P17
Corresponding to +18dbm, this enum variable has been deprecated
-
enumerator ESP_PWR_LVL_P18
Corresponding to +18dbm
-
enumerator ESP_PWR_LVL_P19
Corresponding to +20dbm, this enum variable has been deprecated
-
enumerator ESP_PWR_LVL_P20
Corresponding to +20dbm
-
enumerator ESP_PWR_LVL_INVALID
Indicates an invalid value
-
enumerator ESP_PWR_LVL_N24
-
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
-
enumerator ESP_BLE_ENHANCED_PWR_TYPE_DEFAULT