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
btcomponent. To declare that your component depends onbt, add the following to your CMakeLists.txt:
REQUIRES btor
> 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_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 in range of minimum value and maximum value. The power level will effect the global BR/EDR TX power, such inquire, page, connection and so on. Please call the function after esp_bt_controller_enable and before any function which cause RF do TX. So you can call the function before doing discovery, profile init and so on. For example, if you want BR/EDR use the new TX power to do inquire, you should call this function before inquire. Another word, If call this function when BR/EDR is in inquire(ING), please do inquire again after call this function. Default minimum power level is ESP_PWR_LVL_N0, and maximum power level is ESP_PWR_LVL_P3.
Parameters
min_power_level -- The minimum power level
max_power_level -- The maximum power level
Returns
ESP_OK - success, other - failed
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 If the argument is not NULL, then store the corresponding value.
Parameters
min_power_level -- The minimum power level
max_power_level -- The maximum power level
Returns
ESP_OK - success, other - failed
esp_err_t esp_bredr_sco_datapath_set(esp_sco_data_path_t data_path)
Set default SCO data path Should be called after controller is enabled, and before (e)SCO link is established.
Parameters
data_path -- SCO data path
Returns
ESP_OK - success, other - failed
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. Different from previous version, there's a mode and some connection configuration in "cfg" to configure controller work mode and allocate the resource which is needed.
Returns
ESP_OK - success, other - failed
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.
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. This mode must be equal as the mode in "cfg" of esp_bt_controller_init().
Returns
ESP_OK - success, other - failed
esp_err_t esp_bt_controller_disable(void)
Disable 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
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);
Note
In case of NimBLE host, to release BSS and data memory to heap, the mode needs to be set to ESP_BT_MODE_BTDM as controller is dual mode.
Parameters
mode -- : the mode whose memory is to be released
Returns
ESP_OK - success, other - failed
esp_err_t esp_bt_sleep_enable(void)
enable bluetooth to enter modem sleep
Note that this function shall not be invoked before esp_bt_controller_enable()
There are currently two options for bluetooth modem sleep, one is ORIG mode, and another is EVED Mode. EVED Mode is intended for BLE only.
For ORIG mode: Bluetooth modem sleep is enabled in controller start up by default if CONFIG_CTRL_BTDM_MODEM_SLEEP is set and "ORIG mode" is selected. In ORIG modem sleep mode, bluetooth controller will switch off some components and pause to work every now and then, if there is no event to process; and wakeup according to the scheduled interval and resume the work. It can also wakeup earlier upon external request using function "esp_bt_controller_wakeup_request".
Returns
ESP_OK : success
other : failed
esp_err_t esp_bt_sleep_disable(void)
disable bluetooth modem sleep
Note that this function shall not be invoked before esp_bt_controller_enable()
If esp_bt_sleep_disable() is called, bluetooth controller will not be allowed to enter modem sleep;
If ORIG modem sleep mode is in use, if this function is called, bluetooth controller may not immediately wake up if it is dormant then. In this case, esp_bt_controller_wakeup_request() can be used to shorten the time for wakeup.
Returns
ESP_OK : success
other : failed
esp_err_t esp_ble_scan_dupilcate_list_flush(void)
Manually clear scan duplicate list.
Note that scan duplicate list will be automatically cleared when the maximum amount of device in the filter is reached the amount of device in the filter can be configured in menuconfig.
Note
This function name is incorrectly spelled, it will be fixed in release 5.x version.
Returns
ESP_OK : success
other : failed
void esp_wifi_bt_power_domain_on(void)
bt Wi-Fi power domain power on
void esp_wifi_bt_power_domain_off(void)
bt Wi-Fi power domain power off
Structures
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
uint16_t controller_task_stack_size
Bluetooth controller task stack size
uint8_t controller_task_prio
Bluetooth controller task priority
uint8_t hci_uart_no
If use UART1/2 as HCI IO interface, indicate UART number
uint32_t hci_uart_baudrate
If use UART1/2 as HCI IO interface, indicate UART baudrate
uint8_t scan_duplicate_mode
scan duplicate mode
uint8_t scan_duplicate_type
scan duplicate type
uint16_t normal_adv_size
Normal adv size for scan duplicate
uint16_t mesh_adv_size
Mesh adv size for scan duplicate
uint16_t send_adv_reserved_size
Controller minimum memory value
uint32_t controller_debug_flag
Controller debug log flag
uint8_t mode
Controller mode: BR/EDR, BLE or Dual Mode
uint8_t ble_max_conn
BLE maximum connection numbers
uint8_t bt_max_acl_conn
BR/EDR maximum ACL connection numbers
uint8_t bt_sco_datapath
SCO data path, i.e. HCI or PCM module
bool auto_latency
BLE auto latency, used to enhance classic BT performance
bool bt_legacy_auth_vs_evt
BR/EDR Legacy auth complete event required to protect from BIAS attack
uint8_t bt_max_sync_conn
BR/EDR maximum ACL connection numbers. Effective in menuconfig
uint8_t ble_sca
BLE low power crystal accuracy index
uint8_t pcm_role
PCM role (master & slave)
uint8_t pcm_polar
PCM polar trig (falling clk edge & rising clk edge)
bool hli
Using high level interrupt or not
uint16_t dup_list_refresh_period
Duplicate scan list refresh period
uint32_t magic
Magic number
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
ESP_BT_CONTROLLER_CONFIG_MAGIC_VAL
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
enumerator ESP_BT_CONTROLLER_STATUS_INITED
enumerator ESP_BT_CONTROLLER_STATUS_ENABLED
enumerator ESP_BT_CONTROLLER_STATUS_NUM
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_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_N14
Backward compatibility! Setting to -14dbm will actually result to -12dbm
enumerator ESP_PWR_LVL_N11
Backward compatibility! Setting to -11dbm will actually result to -9dbm
enumerator ESP_PWR_LVL_N8
Backward compatibility! Setting to -8dbm will actually result to -6dbm
enumerator ESP_PWR_LVL_N5
Backward compatibility! Setting to -5dbm will actually result to -3dbm
enumerator ESP_PWR_LVL_N2
Backward compatibility! Setting to -2dbm will actually result to 0dbm
enumerator ESP_PWR_LVL_P1
Backward compatibility! Setting to +1dbm will actually result to +3dbm
enumerator ESP_PWR_LVL_P4
Backward compatibility! Setting to +4dbm will actually result to +6dbm
enumerator ESP_PWR_LVL_P7
Backward compatibility! Setting to +7dbm will actually result to +9dbm
enum esp_sco_data_path_t
Bluetooth audio data transport path.
Values:
enumerator ESP_SCO_DATA_PATH_HCI
data over HCI transport
enumerator ESP_SCO_DATA_PATH_PCM
data over PCM interface