Controller && VHCI

Overview

Instructions

Application Example

Check bluetooth folder in ESP-IDF examples, which contains the following application:

  • This is a BLE advertising demo with virtual HCI interface. Send Reset/ADV_PARAM/ADV_DATA/ADV_ENABLE HCI command for BLE advertising - bluetooth/ble_adv.

API Reference

Header File

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.

Return
ESP_OK - success, other - failed
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)

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.

Return
>= 0 - Power level, < 0 - Invalid
Parameters
  • power_type: : The type of which tx power, could set Advertising/Connection/Default and etc

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 can before do discover, beofre 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.

Return
ESP_OK - success, other - failed
Parameters
  • min_power_level: The minimum power level
  • max_power_level: The maximum power level

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.

Return
ESP_OK - success, other - failed
Parameters
  • min_power_level: The minimum power level
  • max_power_level: The maximum power level

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

Return
ESP_OK - success, other - failed
Parameters
  • data_path: SCO data path

esp_err_t esp_bt_controller_init(esp_bt_controller_config_t *cfg)

Initialize BT controller to allocate task and other resource.

Return
ESP_OK - success, other - failed
Parameters
  • cfg: Initial configuration of BT controller. This function should be called only once, before any other BT functions are called.

esp_err_t esp_bt_controller_deinit(void)

De-initialize BT controller to free resource and delete task.

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.

Return
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.

Return
ESP_OK - success, other - failed
Parameters
  • mode: : the mode(BLE/BT/BTDM) to enable.

esp_err_t esp_bt_controller_disable(void)

Disable BT controller.

Return
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.

Return
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.

Return
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

void esp_vhci_host_register_callback(const esp_vhci_host_callback_t *callback)

esp_vhci_host_register_callback register the vhci referece callback, the call back struct defined by vhci_host_callback structure.

Parameters

esp_err_t esp_bt_controller_mem_release(esp_bt_mode_t mode)

esp_bt_controller_mem_release release the memory by mode, if never use the bluetooth mode it can release the .bss, .data and other section 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 can not 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 initialisation time to free unused BT Classic memory.

If user never use bluetooth controller, could call esp_bt_controller_mem_release(ESP_BT_MODE_BTDM) before esp_bt_controller_init or after esp_bt_controller_deinit.

For example, user only use bluetooth to config SSID and PASSWORD of WIFI, after config, will never use bluetooth. Then, could call esp_bt_controller_mem_release(ESP_BT_MODE_BTDM) after esp_bt_controller_deinit.

Return
ESP_OK - success, other - failed
Parameters
  • mode: : the mode want to release memory

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_BTDM_CONTROLLER_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”.

Return
  • 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.

Return
  • ESP_OK : success
  • other : failed

bool esp_bt_controller_is_sleeping(void)

to check whether bluetooth controller is sleeping at the instant, if modem sleep is enabled

Note that this function shall not be invoked before esp_bt_controller_enable() This function is supposed to be used ORIG mode of modem sleep

Return
true if in modem sleep state, false otherwise

void esp_bt_controller_wakeup_request(void)

request controller to wakeup from sleeping state during sleep mode

Note that this function shall not be invoked before esp_bt_controller_enable() Note that this function is supposed to be used ORIG mode of modem sleep Note that after this request, bluetooth controller may again enter sleep as long as the modem sleep is enabled

Profiling shows that it takes several milliseconds to wakeup from modem sleep after this request. Generally it takes longer if 32kHz XTAL is used than the main XTAL, due to the lower frequncy of the former as the bluetooth low power clock source.

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

If use UART1/2 as HCI IO interface, indicate UART baudrate

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 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

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:

ESP_BT_MODE_IDLE = 0x00

Bluetooth is not running

ESP_BT_MODE_BLE = 0x01

Run BLE mode

ESP_BT_MODE_CLASSIC_BT = 0x02

Run Classic BT mode

ESP_BT_MODE_BTDM = 0x03

Run dual mode

enum esp_bt_controller_status_t

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

Values:

ESP_BT_CONTROLLER_STATUS_IDLE = 0
ESP_BT_CONTROLLER_STATUS_INITED
ESP_BT_CONTROLLER_STATUS_ENABLED
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:

ESP_BLE_PWR_TYPE_CONN_HDL0 = 0

For connection handle 0

ESP_BLE_PWR_TYPE_CONN_HDL1 = 1

For connection handle 1

ESP_BLE_PWR_TYPE_CONN_HDL2 = 2

For connection handle 2

ESP_BLE_PWR_TYPE_CONN_HDL3 = 3

For connection handle 3

ESP_BLE_PWR_TYPE_CONN_HDL4 = 4

For connection handle 4

ESP_BLE_PWR_TYPE_CONN_HDL5 = 5

For connection handle 5

ESP_BLE_PWR_TYPE_CONN_HDL6 = 6

For connection handle 6

ESP_BLE_PWR_TYPE_CONN_HDL7 = 7

For connection handle 7

ESP_BLE_PWR_TYPE_CONN_HDL8 = 8

For connection handle 8

ESP_BLE_PWR_TYPE_ADV = 9

For advertising

ESP_BLE_PWR_TYPE_SCAN = 10

For scan

ESP_BLE_PWR_TYPE_DEFAULT = 11

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

ESP_BLE_PWR_TYPE_NUM = 12

TYPE numbers

enum esp_power_level_t

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

Values:

ESP_PWR_LVL_N12 = 0

Corresponding to -12dbm

ESP_PWR_LVL_N9 = 1

Corresponding to -9dbm

ESP_PWR_LVL_N6 = 2

Corresponding to -6dbm

ESP_PWR_LVL_N3 = 3

Corresponding to -3dbm

ESP_PWR_LVL_N0 = 4

Corresponding to 0dbm

ESP_PWR_LVL_P3 = 5

Corresponding to +3dbm

ESP_PWR_LVL_P6 = 6

Corresponding to +6dbm

ESP_PWR_LVL_P9 = 7

Corresponding to +9dbm

ESP_PWR_LVL_N14 = ESP_PWR_LVL_N12

Backward compatibility! Setting to -14dbm will actually result to -12dbm

ESP_PWR_LVL_N11 = ESP_PWR_LVL_N9

Backward compatibility! Setting to -11dbm will actually result to -9dbm

ESP_PWR_LVL_N8 = ESP_PWR_LVL_N6

Backward compatibility! Setting to -8dbm will actually result to -6dbm

ESP_PWR_LVL_N5 = ESP_PWR_LVL_N3

Backward compatibility! Setting to -5dbm will actually result to -3dbm

ESP_PWR_LVL_N2 = ESP_PWR_LVL_N0

Backward compatibility! Setting to -2dbm will actually result to 0dbm

ESP_PWR_LVL_P1 = ESP_PWR_LVL_P3

Backward compatibility! Setting to +1dbm will actually result to +3dbm

ESP_PWR_LVL_P4 = ESP_PWR_LVL_P6

Backward compatibility! Setting to +4dbm will actually result to +6dbm

ESP_PWR_LVL_P7 = ESP_PWR_LVL_P9

Backward compatibility! Setting to +7dbm will actually result to +9dbm

enum esp_sco_data_path_t

Bluetooth audio data transport path.

Values:

ESP_SCO_DATA_PATH_HCI = 0

data over HCI transport

ESP_SCO_DATA_PATH_PCM = 1

data over PCM interface