Controller && VHCI
Application Examples
bluetooth/hci/ble_adv_scan_combined demonstrates how to use Bluetooth capabilities for advertising and scanning with a virtual Host Controller Interface (HCI). This example shows how to implement some host functionalities without a host and displays scanned advertising reports from other devices.
bluetooth/hci/controller_hci_uart_esp32 demonstrates how to configure the Bluetooth LE Controller's HCI to communicate over UART on ESP32, enabling communication with an external Bluetooth host stack.
bluetooth/hci/controller_vhci_ble_adv demonstrates how to use the ESP-IDF VHCI ble_advertising app to perform advertising without a host and display received HCI events from the controller.
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.
Note
Connection TX power should only be set after the connection is established.
- Parameters
power_type -- [in] The type of TX power. It could be Advertising, Connection, Default, etc.
power_level -- [in] Power level (index) corresponding to the absolute value (dBm)
- Returns
ESP_OK: Success
ESP_ERR_INVALID_ARG: Invalid argument
-
esp_power_level_t esp_ble_tx_power_get(esp_ble_power_type_t power_type)
Get BLE TX power.
Note
Connection TX power should only be retrieved after the connection is established.
- Parameters
power_type -- [in] The type of TX power. It could be Advertising/Connection/Default and etc.
- Returns
Power level
-
esp_err_t esp_bredr_tx_power_set(esp_power_level_t min_power_level, esp_power_level_t max_power_level)
Set BR/EDR TX power.
BR/EDR power control will use the power within the range of minimum value and maximum value. The power level will affect the global BR/EDR TX power for operations such as inquiry, page, and connection.
Note
Please call this function after
esp_bt_controller_enable()
and before any functions that cause RF transmission, such as performing discovery, profile initialization, and so on.For BR/EDR to use the new TX power for inquiry, call this function before starting an inquiry. If BR/EDR is already inquiring, restart the inquiry after calling this function.
- Parameters
min_power_level -- [in] The minimum power level. The default value is
ESP_PWR_LVL_N0
.max_power_level -- [in] The maximum power level. The default value is
ESP_PWR_LVL_P3
.
- Returns
ESP_OK: Success
ESP_ERR_INVALID_ARG: Invalid argument
ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state
-
esp_err_t esp_bredr_tx_power_get(esp_power_level_t *min_power_level, esp_power_level_t *max_power_level)
Get BR/EDR TX power.
The corresponding power levels will be stored into the arguments.
- Parameters
min_power_level -- [out] Pointer to store the minimum power level
max_power_level -- [out] The maximum power level
- Returns
ESP_OK: Success
ESP_ERR_INVALID_ARG: Invalid argument
-
esp_err_t esp_bredr_sco_datapath_set(esp_sco_data_path_t data_path)
Set default SCO data path.
Note
This function should be called after the Controller is enabled, and before (e)SCO link is established.
- Parameters
data_path -- [in] SCO data path
- Returns
ESP_OK: Success
ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state
-
esp_err_t esp_bt_controller_init(esp_bt_controller_config_t *cfg)
Initialize the Bluetooth Controller to allocate tasks and other resources.
Note
This function should be called only once, before any other Bluetooth functions.
- Parameters
cfg -- [in] Initial Bluetooth Controller configuration
- Returns
ESP_OK: Success
ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state
-
esp_err_t esp_bt_controller_deinit(void)
De-initialize Bluetooth Controller to free resources and delete tasks.
Note
You should stop advertising and scanning, and disconnect all existing connections before de-initializing Bluetooth Controller.
This function should be called only once, after any other Bluetooth functions.
- Returns
ESP_OK: Success
ESP_ERR_INVALID_ARG: Invalid argument
ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state
ESP_ERR_NO_MEM: Out of memory
-
esp_err_t esp_bt_controller_enable(esp_bt_mode_t mode)
Enable Bluetooth Controller.
For API compatibility, retain this argument. This mode must match the mode specified in the
cfg
ofesp_bt_controller_init()
.Note
Bluetooth Controller cannot be enabled in
ESP_BT_CONTROLLER_STATUS_IDLE
status. It has to be initialized first.Due to a known issue, you cannot call
esp_bt_controller_enable()
for the second time to change the Controller mode dynamically. To change the Controller mode, callesp_bt_controller_disable()
and then callesp_bt_controller_enable()
with the new mode.
- Parameters
mode -- [in] The Bluetooth Controller mode (BLE/Classic Bluetooth/BTDM) to enable
- Returns
ESP_OK: Success
ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state
-
esp_err_t esp_bt_controller_disable(void)
Disable Bluetooth Controller.
- Returns
ESP_OK: Success
ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state
-
esp_bt_controller_status_t esp_bt_controller_get_status(void)
Get Bluetooth Controller status.
- Returns
ESP_BT_CONTROLLER_STATUS_IDLE: The Controller is not initialized or has been de-initialized.
ESP_BT_CONTROLLER_STATUS_INITED: The Controller has been initialized, but not enabled or has been disabled.
ESP_BT_CONTROLLER_STATUS_ENABLED: The Controller has been initialized and enabled.
-
bool esp_vhci_host_check_send_available(void)
Check whether the Controller is ready to receive the packet.
If the return value is True, the Host can send the packet to the Controller.
Note
This function should be called before each
esp_vhci_host_send_packet()
.- Returns
True if the Controller is ready to receive packets; false otherwise
-
void esp_vhci_host_send_packet(uint8_t *data, uint16_t len)
Send the packet to the Controller.
Note
This function shall not be called within a critical section or when the scheduler is suspended.
This function should be called only if
esp_vhci_host_check_send_available()
returns True.
- Parameters
data -- [in] Pointer to the packet data
len -- [in] The packet length
-
esp_err_t esp_vhci_host_register_callback(const esp_vhci_host_callback_t *callback)
Register the VHCI callback funations defined in
esp_vhci_host_callback
structure.- Parameters
callback -- [in]
esp_vhci_host_callback
type variable- Returns
ESP_OK: Success
ESP_FAIL: Failure
-
esp_err_t esp_bt_controller_mem_release(esp_bt_mode_t mode)
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 70 KB.
If you never intend to use Bluetooth in a current boot-up cycle, calling
esp_bt_controller_mem_release(ESP_BT_MODE_BTDM)
could release the BSS and data consumed by both Classic Bluetooth and BLE Controller to heap.If you intend to use BLE only, calling
esp_bt_controller_mem_release(ESP_BT_MODE_CLASSIC_BT)
could release the BSS and data consumed by Classic Bluetooth Controller. You can then continue using BLE.If you intend to use Classic Bluetooth only, calling
esp_bt_controller_mem_release(ESP_BT_MODE_BLE)
could release the BSS and data consumed by BLE Controller. You can then continue using Classic Bluetooth.Note
This function is optional and should be called only if you want to free up memory for other components.
This function should only be called when the controller is in
ESP_BT_CONTROLLER_STATUS_IDLE
status.Once Bluetooth Controller memory is released, the process cannot be reversed. This means you cannot use the Bluetooth Controller mode that you have released using this function.
If your firmware will upgrade the Bluetooth Controller mode later (such as switching from BLE to Classic Bluetooth or from disabled to enabled), then do not call this function.
- Parameters
mode -- [in] The Bluetooth Controller mode
- Returns
ESP_OK: Success
ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state
ESP_ERR_NOT_FOUND: Requested resource not found
-
esp_err_t esp_bt_mem_release(esp_bt_mode_t mode)
Release the Controller memory, BSS and data section of the Classic Bluetooth/BLE Host stack as per the mode.
This function first releases Controller memory by internally calling
esp_bt_controller_mem_release()
, then releases Host memory.If you never intend to use Bluetooth in a current boot-up cycle, calling
esp_bt_mem_release(ESP_BT_MODE_BTDM)
could release the BSS and data consumed by both Classic Bluetooth and BLE stack to heap.If you intend to use BLE only, calling
esp_bt_mem_release(ESP_BT_MODE_CLASSIC_BT)
could release the BSS and data consumed by Classic Bluetooth. You can then continue using BLE.If you intend to use Classic Bluetooth only, calling
esp_bt_mem_release(ESP_BT_MODE_BLE)
could release the BSS and data consumed by BLE. You can then continue using Classic Bluetooth.For example, if you only use Bluetooth for setting the Wi-Fi configuration, and do not use Bluetooth in the rest of the product operation, after receiving the Wi-Fi configuration, you can disable/de-init 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);
Note
This function is optional and should be called only if you want to free up memory for other components.
This function should only be called when the controller is in
ESP_BT_CONTROLLER_STATUS_IDLE
status.Once Bluetooth Controller memory is released, the process cannot be reversed. This means you cannot use the Bluetooth Controller mode that you have released using this function.
If your firmware will upgrade the Bluetooth Controller mode later (such as switching from BLE to Classic Bluetooth or from disabled to enabled), then do not call this function.
- Parameters
mode -- [in] The Bluetooth Controller mode
- Returns
ESP_OK: Success
ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state
ESP_ERR_NOT_FOUND: Requested resource not found
-
esp_err_t esp_bt_sleep_enable(void)
Enable Bluetooth modem sleep.
There are currently two options for Bluetooth modem sleep: ORIG mode and EVED mode. The latter is intended for BLE only. The modem sleep mode could be configured in menuconfig.
In ORIG mode, if there is no event to process, the Bluetooth Controller will periodically switch off some components and pause operation, then wake up according to the scheduled interval and resume work. It can also wakeup earlier upon external request using function
esp_bt_controller_wakeup_request()
.Note
This function shall not be invoked before
esp_bt_controller_enable()
.- Returns
ESP_OK: Success
ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state
ESP_ERR_NOT_SUPPORTED: Operation or feature not supported
-
esp_err_t esp_bt_sleep_disable(void)
Disable Bluetooth modem sleep.
Note
Bluetooth Controller will not be allowed to enter modem sleep after calling this function.
In ORIG modem sleep mode, calling this function may not immediately wake up the Controller if it is currently dormant. In this case,
esp_bt_controller_wakeup_request()
can be used to shorten the wake-up time.This function shall not be invoked before
esp_bt_controller_enable()
.
- Returns
ESP_OK: Success
ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state
ESP_ERR_NOT_SUPPORTED: Operation or feature not supported
-
esp_err_t esp_ble_scan_dupilcate_list_flush(void)
Manually clear the scan duplicate list.
Note
This function name is incorrectly spelled, it will be fixed in release 5.x version.
The scan duplicate list will be automatically cleared when the maximum amount of devices in the filter is reached. The amount of devices in the filter can be configured in menuconfig.
- Returns
ESP_OK: Success
ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state
-
void esp_wifi_bt_power_domain_on(void)
Power on Bluetooth Wi-Fi power domain.
Note
This function is not recommended to use due to potential risk.
-
void esp_wifi_bt_power_domain_off(void)
Power off Bluetooth Wi-Fi power domain.
Note
This function is not recommended to use due to potential risk.
Structures
-
struct esp_bt_controller_config_t
Bluetooth Controller config options.
Note
For parameters configurable in menuconfig, please refer to menuconfig for details on range and default values.
It is not recommended to modify the default values of
controller_task_stack_size
andcontroller_task_prio
.
Public Members
-
uint16_t controller_task_stack_size
Bluetooth Controller task stack size in bytes
-
uint8_t controller_task_prio
Bluetooth Controller task priority
-
uint8_t hci_uart_no
Indicates UART number if using UART1/2 as HCI I/O interface. Configurable in menuconfig
-
uint32_t hci_uart_baudrate
Indicates UART baudrate if using UART1/2 as HCI I/O interface. Configurable in menuconfig
-
uint8_t scan_duplicate_mode
Scan duplicate filtering mode. Configurable in menuconfig
-
uint8_t scan_duplicate_type
Scan duplicate filtering type. Configurable in menuconfig
-
uint16_t normal_adv_size
Maximum number of devices in scan duplicate filtering list. Configurable in menuconfig
-
uint16_t mesh_adv_size
Maximum number of Mesh advertising packets in scan duplicate filtering list. Configurable in menuconfig
-
uint16_t send_adv_reserved_size
Controller minimum memory value in bytes. Internal use only
-
uint32_t controller_debug_flag
Controller debug log flag. Internal use only
-
uint8_t mode
Controller mode:
1: BLE mode
2: Classic Bluetooth mode
3: Dual mode
Others: Invalid
Configurable in menuconfig
-
uint8_t ble_max_conn
Maximum number of BLE connections. Configurable in menuconfig
-
uint8_t bt_max_acl_conn
Maximum number of BR/EDR ACL connections. Configurable in menuconfig
-
uint8_t bt_sco_datapath
SCO data path, i.e. HCI or PCM module. Configurable in menuconfig
-
bool auto_latency
True if BLE auto latency is enabled, used to enhance Classic Bluetooth performance; false otherwise. Configurable in menuconfig
-
bool bt_legacy_auth_vs_evt
True if BR/EDR Legacy Authentication Vendor Specific Event is enabled, which is required to protect from BIAS attack; false otherwise. Configurable in menuconfig
-
uint8_t bt_max_sync_conn
Maximum number of BR/EDR synchronous connections. Configurable in menuconfig
-
uint8_t ble_sca
BLE low power crystal accuracy index. Configurable in menuconfig
-
uint8_t pcm_role
PCM role (master & slave). Configurable in menuconfig
-
uint8_t pcm_polar
PCM polar trig (falling clk edge & rising clk edge). Configurable in menuconfig
-
uint8_t pcm_fsyncshp
Physical shape of the PCM Frame Synchronization signal (stereo mode & mono mode). Configurable in menuconfig
-
bool hli
True if using high level interrupt; false otherwise. Configurable in menuconfig
-
uint16_t dup_list_refresh_period
Scan duplicate filtering list refresh period in seconds. Configurable in menuconfig
-
bool ble_scan_backoff
True if BLE scan backoff is enabled; false otherwise. Configurable in menuconfig
-
uint8_t ble_llcp_disc_flag
BLE disconnect flag when instant passed. Configurable in menuconfig
-
uint32_t magic
Magic number
-
struct esp_vhci_host_callback
Vendor HCI (VHCI) callback functions to notify the Host on the next operation.
Macros
-
ESP_BT_CONTROLLER_CONFIG_MAGIC_VAL
Internal use only.
Note
Please do not modify this value
-
BT_CONTROLLER_INIT_CONFIG_DEFAULT()
Default Bluetooth Controller configuration.
Type Definitions
-
typedef struct esp_vhci_host_callback esp_vhci_host_callback_t
Vendor HCI (VHCI) callback functions to notify the Host on the next operation.
Enumerations
-
enum esp_bt_mode_t
Bluetooth Controller mode.
Values:
-
enumerator ESP_BT_MODE_IDLE
Bluetooth is not operating.
-
enumerator ESP_BT_MODE_BLE
Bluetooth is operating in BLE mode.
-
enumerator ESP_BT_MODE_CLASSIC_BT
Bluetooth is operating in Classic Bluetooth mode.
-
enumerator ESP_BT_MODE_BTDM
Bluetooth is operating in Dual mode.
-
enumerator ESP_BT_MODE_IDLE
-
enum esp_ble_sca_t
BLE sleep clock accuracy (SCA)
Note
Currently only ESP_BLE_SCA_500PPM and ESP_BLE_SCA_250PPM are supported.
Values:
-
enumerator ESP_BLE_SCA_500PPM
BLE SCA at 500 ppm
-
enumerator ESP_BLE_SCA_250PPM
BLE SCA at 250 ppm
-
enumerator ESP_BLE_SCA_150PPM
BLE SCA at 150 ppm
-
enumerator ESP_BLE_SCA_100PPM
BLE SCA at 100 ppm
-
enumerator ESP_BLE_SCA_75PPM
BLE SCA at 75 ppm
-
enumerator ESP_BLE_SCA_50PPM
BLE SCA at 50 ppm
-
enumerator ESP_BLE_SCA_30PPM
BLE SCA at 30 ppm
-
enumerator ESP_BLE_SCA_20PPM
BLE SCA at 20 ppm
-
enumerator ESP_BLE_SCA_500PPM
-
enum esp_bt_controller_status_t
Bluetooth Controller status.
Values:
-
enumerator ESP_BT_CONTROLLER_STATUS_IDLE
The Controller is not initialized or has been de-initialized.
-
enumerator ESP_BT_CONTROLLER_STATUS_INITED
The Controller has been initialized, but not enabled or has been disabled.
-
enumerator ESP_BT_CONTROLLER_STATUS_ENABLED
The Controller has been initialized and enabled.
-
enumerator ESP_BT_CONTROLLER_STATUS_NUM
Number of Controller statuses
-
enumerator ESP_BT_CONTROLLER_STATUS_IDLE
-
enum esp_ble_power_type_t
BLE TX power type.
Note
The connection TX power can only be set after the connection is established. After disconnecting, the corresponding TX power will not be affected.
ESP_BLE_PWR_TYPE_DEFAULT
can be used to set the TX power for power types that have not been set before. It will not affect the TX power values which have been set for the ADV/SCAN/CONN0-8 power types.If none of power type is set, the system will use
ESP_PWR_LVL_P3
as default for all power types.
Values:
-
enumerator ESP_BLE_PWR_TYPE_CONN_HDL0
TX power for connection handle 0
-
enumerator ESP_BLE_PWR_TYPE_CONN_HDL1
TX power for connection handle 1
-
enumerator ESP_BLE_PWR_TYPE_CONN_HDL2
TX power for connection handle 2
-
enumerator ESP_BLE_PWR_TYPE_CONN_HDL3
TX power for connection handle 3
-
enumerator ESP_BLE_PWR_TYPE_CONN_HDL4
TX power for connection handle 4
-
enumerator ESP_BLE_PWR_TYPE_CONN_HDL5
TX power for connection handle 5
-
enumerator ESP_BLE_PWR_TYPE_CONN_HDL6
TX power for connection handle 6
-
enumerator ESP_BLE_PWR_TYPE_CONN_HDL7
TX power for connection handle 7
-
enumerator ESP_BLE_PWR_TYPE_CONN_HDL8
TX power for connection handle 8
-
enumerator ESP_BLE_PWR_TYPE_ADV
TX power for advertising
-
enumerator ESP_BLE_PWR_TYPE_SCAN
TX power for scan
-
enumerator ESP_BLE_PWR_TYPE_DEFAULT
Default TX power type, which can be used to set the TX power for power types that have not been set before.
-
enumerator ESP_BLE_PWR_TYPE_NUM
Number of types
-
enum esp_power_level_t
Bluetooth TX power level (index). Each index corresponds to a specific power value in dBm.
Values:
-
enumerator ESP_PWR_LVL_N12
Corresponding to -12 dBm
-
enumerator ESP_PWR_LVL_N9
Corresponding to -9 dBm
-
enumerator ESP_PWR_LVL_N6
Corresponding to -6 dBm
-
enumerator ESP_PWR_LVL_N3
Corresponding to -3 dBm
-
enumerator ESP_PWR_LVL_N0
Corresponding to 0 dBm
-
enumerator ESP_PWR_LVL_P3
Corresponding to +3 dBm
-
enumerator ESP_PWR_LVL_P6
Corresponding to +6 dBm
-
enumerator ESP_PWR_LVL_P9
Corresponding to +9 dBm
-
enumerator ESP_PWR_LVL_N14
Backward compatibility! Setting to -14 dBm will actually result in -12 dBm
-
enumerator ESP_PWR_LVL_N11
Backward compatibility! Setting to -11 dBm will actually result in -9 dBm
-
enumerator ESP_PWR_LVL_N8
Backward compatibility! Setting to -8 dBm will actually result in -6 dBm
-
enumerator ESP_PWR_LVL_N5
Backward compatibility! Setting to -5 dBm will actually result in -3 dBm
-
enumerator ESP_PWR_LVL_N2
Backward compatibility! Setting to -2 dBm will actually result in 0 dBm
-
enumerator ESP_PWR_LVL_P1
Backward compatibility! Setting to +1 dBm will actually result in +3 dBm
-
enumerator ESP_PWR_LVL_P4
Backward compatibility! Setting to +4 dBm will actually result in +6 dBm
-
enumerator ESP_PWR_LVL_P7
Backward compatibility! Setting to +7 dBm will actually result in +9 dBm
-
enumerator ESP_PWR_LVL_N12