# Controller & HCI

[中文]

## Application Examples

- bluetooth/hci/controller_hci_uart_esp32c3_and_esp32s3 demonstrates how to configure the Bluetooth LE Controller's HCI to communicate over UART on ESP32-S3, enabling communication with an external Bluetooth host stack.

## API Reference

### Header File

- components/bt/include/esp32c3/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_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_NOT_SUPPORTED: Invalid Bluetooth Controller mode

    - ESP_ERR_INVALID_ARG: Invalid arguments

    - ESP_ERR_NO_MEM: Out of memory

    - ESP_FAIL: Failure due to other reasons

esp_err_t esp_bt_controller_deinit(void)

  De-initialize Bluetooth Controller to free resources and delete tasks.

  Note

  1. You should stop advertising and scanning, and disconnect all existing connections before de-initializing Bluetooth Controller.

  2. This function should be called only once, after any other Bluetooth functions.

  Returns:

    - ESP_OK: Success

    - ESP_ERR_INVALID_ARG: Invalid arguments

    - 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` of `esp_bt_controller_init()`.

  Note

  1. Bluetooth Controller cannot be enabled in `ESP_BT_CONTROLLER_STATUS_IDLE` status. It has to be initialized first.

  2. 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, call `esp_bt_controller_disable()` and then call `esp_bt_controller_enable()` with the new mode.

  Parameters:

    mode -- [in] The Bluetooth Controller mode to enable

  Returns:

    - ESP_OK: Success

    - ESP_ERR_INVALID_STATE: Invalid Bluetooth Controller state

    - ESP_ERR_INVALID_ARG: Invalid arguments

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.

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_BLE)` could release the BSS and data consumed by BLE Controller to heap.

  Note

  1. This function is optional and should be called only if you want to free up memory for other components.

  2. This function should only be called when the Controller is in `ESP_BT_CONTROLLER_STATUS_IDLE` status.

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

  4. If your firmware will upgrade the Bluetooth Controller mode later (such as 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 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_BLE)` could release the BSS and data consumed by BLE stack to heap.

  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_BLE);

  Note

  1. This function is optional and should be called only if you want to free up memory for other components.

  2. This function should only be called when the Controller is in `ESP_BT_CONTROLLER_STATUS_IDLE` status.

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

  4. If your firmware will upgrade the Bluetooth Controller mode later (such as 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

  1. Bluetooth Controller will not be allowed to enter modem sleep after calling this function.

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

  3. 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_bt_sleep_clock_t esp_bt_get_lpclk_src(void)

  Get the Bluetooth sleep clock source.

  Note

  This function shall not be invoked before `esp_bt_controller_init()`.

  Returns:

    clock source used in Bluetooth low power mode

bool esp_bt_controller_is_sleeping(void)

  Check if the Bluetooth Controller is currently in sleep mode when modem sleep is enabled.

  Note

  1. This function shall not be invoked before `esp_bt_controller_enable()`.

  2. This function is supposed to be used ORIG mode of modem sleep.

  Returns:

    - True if the Controller is in modem sleep state; false otherwise.

void esp_bt_controller_wakeup_request(void)

  Request the Controller to wakeup from sleeping state during sleep mode.

  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 frequency of the former as the bluetooth low power clock source.

  Note

  1. This function shall not be invoked before `esp_bt_controller_enable()`.

  2. This function is supposed to be used ORIG mode of modem sleep.

  3. After this request, the Bluetooth Controller can re-enter sleep as long as modem sleep remains enabled.

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 for the specified power type.

  It is recommended to use `esp_ble_tx_power_set_enhanced` to set TX power for individual advertising and connection handle.

  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, or Default.

    - power_level -- [in] Power level (index) corresponding to the absolute value (dBm)

  Returns:

    - ESP_OK: Success

    - ESP_ERR_NOT_SUPPORTED: Invalid TX power type

    - ESP_FAIL: Failure due to other reasons

esp_power_level_t esp_ble_tx_power_get(esp_ble_power_type_t power_type)

  Get BLE TX power of the specified power type.

  It is recommended to use `esp_ble_tx_power_get_enhanced` to get TX power of individual advertising and connection handle.

  Note

  1. Connection TX power should only be retrieved after the connection is established.

  2. If an invalid power type is provided, this API returns `ESP_PWR_LVL_INVALID`.

  Parameters:

    power_type -- [in] The type of TX power. It could be Advertising/Connection/Default and etc.

  Returns:

    - Power level

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)

  Set BLE TX power for the specified Advertising or Connection handle.

  For the TX power type: `ESP_BLE_ENHANCED_PWR_TYPE_DEFAULT`, `ESP_BLE_ENHANCED_PWR_TYPE_SCAN`, `ESP_BLE_ENHANCED_PWR_TYPE_INIT`, this API will ignore the input handle number, and set 0 internally.

  For the TX power type: `ESP_BLE_ENHANCED_PWR_TYPE_ADV` and `ESP_BLE_ENHANCED_PWR_TYPE_CONN`， this API will set the TX power for the target handle.

  Note

  1. Connection TX power should only be set after connection created.

  Parameters:

    - power_type -- [in] The type of TX power

    - handle -- [in] The handle of Advertising or Connection

    - power_level -- [in] Power level (index) corresponding to absolute value (dBm)

  Returns:

    - ESP_OK: Success

    - ESP_ERR_NOT_SUPPORTED: Invalid TX power type

    - ESP_FAIL: Failure due to other reasons

esp_power_level_t esp_ble_tx_power_get_enhanced(esp_ble_enhanced_power_type_t power_type, uint16_t handle)

  Get BLE TX power of the specified Advertising or Connection handle.

  For the TX power type: `ESP_BLE_ENHANCED_PWR_TYPE_DEFAULT`, `ESP_BLE_ENHANCED_PWR_TYPE_SCAN`, `ESP_BLE_ENHANCED_PWR_TYPE_INIT`, this API will ignore the input handle number.

  For the TX power type: `ESP_BLE_ENHANCED_PWR_TYPE_ADV` and `ESP_BLE_ENHANCED_PWR_TYPE_CONN`， this API will return the TX power of the target handle.

  Note

  1. Connection Tx power should only be get after connection created.

  2. If an invalid power type is provided, this API returns `ESP_PWR_LVL_INVALID`.

  Parameters:

    - power_type -- [in] The type of TX power

    - handle -- [in] The handle of Advertising or Connection and the value 0 for other enhanced power types

  Returns:

    Power level

int esp_bt_h4tl_eif_io_event_notify(int event)

  Notify Bluetooth Controller task to process the event upon TX or RX done.

  Note

  1. This function shall not be invoked before `esp_bt_controller_enable()`.

  2. This function can be called in both ISR and non-ISR context.

  3. This function ignored the passed `event` value currently

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

  1. This function shall not be called within a critical section or when the scheduler is suspended.

  2. 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 functions defined in `esp_vhci_host_callback` structure.

  Parameters:

    callback -- [in] `esp_vhci_host_callback` type variable

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

void esp_ble_controller_log_dump_all(bool output)

### Structures

struct esp_bt_hci_tl_t

  Controller HCI transport layer function structure.

  Note

  This structure must be registered when HCI transport layer is UART

  Public Members

  uint32_t _magic

    Magic number

  uint32_t _version

    Version number of the defined structure

  uint32_t _reserved

    Reserved for future use

  int (*_open)(void)

    HCI transport layer open function

  void (*_close)(void)

    HCI transport layer close function

  void (*_finish_transfers)(void)

    HCI transport layer finish transfers function

  void (*_recv)(uint8_t *buf, uint32_t len, esp_bt_hci_tl_callback_t callback, void *arg)

    HCI transport layer receive function

  void (*_send)(uint8_t *buf, uint32_t len, esp_bt_hci_tl_callback_t callback, void *arg)

    HCI transport layer send function

  bool (*_flow_off)(void)

    HCI transport layer flow off function

  void (*_flow_on)(void)

    HCI transport layer flow on function

struct esp_bt_controller_config_t

  Bluetooth Controller config options.

  Note

  1. For parameters configurable through menuconfig, it is recommended to adjust them via the menuconfig interface. Please refer to menuconfig for details on the range and default values.

  2. It is not recommended to modify the values for parameters which are not configurable through menuconfig.

  Public Members

  uint32_t magic

    Magic number

  uint32_t version

    version number of the defined structure

  uint16_t controller_task_stack_size

    Bluetooth Controller task stack size in bytes

  uint8_t controller_task_prio

    Bluetooth Controller task priority

  uint8_t controller_task_run_cpu

    CPU number that Bluetooth Controller task runs on. Configurable in menuconfig.

    - 0 - CPU 0 (default)

    - 1 - CPU 1

  uint8_t bluetooth_mode

    BLE mode

  uint8_t ble_max_act

    The maximum number of BLE instance. Configurable in menuconfig.

    - Range: 1 - 10

    - Default: 6

  uint8_t sleep_mode

    Modem sleep mode. Configurable in menuconfig.

    - 0 - Disable (default)

    - 1 - Enable

  uint8_t sleep_clock

    Modem sleep clock source. Configurable in menuconfig.

  uint8_t ble_st_acl_tx_buf_nb

    Static ACL TX buffer numbers. Configurable in menuconfig.

    - Range: 0 - 12

    - Default: 0

  uint8_t ble_hw_cca_check

    Deprecated

  uint16_t ble_adv_dup_filt_max

    The maximum number of extended duplicate scan filter. Configurable in menuconfig.

    - Range: 1 - 500

    - Default: 30

  bool coex_param_en

    Deprecated

  uint8_t ce_len_type

    Connection event length determination method. Configurable in menuconfig.

    - 0 - Original (default)

    - 1 - use `CE_LEN` parameter from HCI commands

    - 2 - Espressif vendor defined method

  bool coex_use_hooks

    Deprecated

  uint8_t hci_tl_type

    HCI transport layer type. Configurable in menuconfig.

    - 0 - URAT

    - 1 - Virtual HCI (default)

  esp_bt_hci_tl_t *hci_tl_funcs

    HCI transport functions used. It must be set when `hci_tl_type` is UART.

  uint8_t txant_dft

    Default TX antenna. Configurable in menuconfig.

    - 0 - Antenna 0 (default)

    - 1 - Antenna 1

  uint8_t rxant_dft

    Default RX antenna. Configurable in menuconfig.

    - 0 - Antenna 0 (default)

    - 1 - Antenna 1

  uint8_t txpwr_dft

    Default TX power. Please refer to `esp_power_level_t` for supported power level. Configurable in menuconfig.

    - Default : `ESP_PWR_LVL_P9` +9 dBm.

  uint32_t cfg_mask

    Configuration mask to set specific options

  uint8_t scan_duplicate_mode

    Scan duplicate filtering mode. Configurable in menuconfig.

    - 0 - Normal scan duplicate filtering mode (default)

    - 1 - Special scan duplicate filtering mode for BLE Mesh

  uint8_t scan_duplicate_type

    Scan duplicate filtering type. If `scan_duplicate_mode` is set to 1, this parameter will be ignored. Configurable in menuconfig.

    - 0 - Filter scan duplicates by device address only (default)

    - 1 - Filter scan duplicates by advertising data only, even if they originate from different devices.

    - 2 - Filter scan duplicated by device address and advertising data.

  uint16_t normal_adv_size

    Maximum number of devices in scan duplicate filtering list. Configurable in menuconfig.

    - Range: 10 - 1000

    - Default: 100

  uint16_t mesh_adv_size

    Maximum number of Mesh advertising packets in scan duplicate filtering list. Configurable in menuconfig.

    - Range: 10 - 1000

    - Default: 100

  uint8_t coex_phy_coded_tx_rx_time_limit

    Enable / disable the maximum TX/RX time limit for Coded-PHY connections in coexistence with Wi-Fi scenarios. Configurable in menuconfig.

    - 0 - Disable (default)

    - 1 - Enable

  uint32_t hw_target_code

    Hardware target. Internal use only. Please do not modify this value.

  uint8_t slave_ce_len_min

    Slave minimum connection event length: 5. Please do not modify this value.

  uint8_t hw_recorrect_en

    Enable / disable uncoded phy / coded phy hardware re-correction. Configurable in menuconfig.

  uint8_t cca_thresh

    Hardware-triggered CCA threshold. Configurable in menuconfig.

    - Range: 20 - 100

    - Default: 20

  uint16_t scan_backoff_upperlimitmax

    Enable / disable active scan backoff. Configurable in menuconfig.

    - 0 - Disable (default)

    - 1 - Enable

  uint16_t dup_list_refresh_period

    Scan duplicate filtering list refresh period in seconds. Configurable in menuconfig

    - Range: 0 - 100 seconds

    - Default: 0 second

  bool ble_50_feat_supp

    True if BLE 5.0 features are enabled; false otherwise. This option depends on whether the Host enable the 5.0 features.

  uint8_t ble_cca_mode

    BLE CCA mode. Configurable in menuconfig

    - 0 - Disable (default)

    - 1 - Hardware-triggered CCA

    - 2 - Software-based CCA (experimental)

  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 ble_chan_ass_en

    Enable / disable BLE channel assessment. Configurable in menuconfig.

    - 0 - Disable

    - 1 - Enable (default)

  uint8_t ble_ping_en

    Enable / disable BLE ping procedure. Configurable in menuconfig.

    - 0 - Disable

    - 1 - Enable (default)

  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.

  bool run_in_flash

    True if the Controller code is in flash (flash model); false otherwise (default). Configurable in menuconfig.

  bool dtm_en

    True if the DTM feature is enabled; false otherwise (default). Configurable in menuconfig.

  bool enc_en

    True if the encryption feature is enabled (default); false otherwise. Configurable in menuconfig.

  bool qa_test

    True if the QA test feature is enabled; false otherwise (default). Configurable in menuconfig.

  bool connect_en

    True if the connection feature is enabled (default); false otherwise. Configurable in menuconfig.

  bool scan_en

    True if the scan feature is enabled (default); false otherwise. Configurable in menuconfig.

  bool ble_aa_check

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

  bool adv_en

    True if the ADV feature is enabled (default); false otherwise. Configurable in menuconfig.

struct esp_vhci_host_callback

  Virtual HCI (VHCI) callback functions to notify the Host on the next operation.

  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_CTRL_CONFIG_MAGIC_VAL

  Internal use only.

  Note

  Please do not modify this value

ESP_BT_CTRL_CONFIG_VERSION

  Internal use only.

  Note

  Please do not modify this value

ESP_BT_HCI_TL_MAGIC_VALUE

  Internal use only.

  Note

  Please do not modify this value

ESP_BT_HCI_TL_VERSION

  Internal use only.

  Note

  Please do not modify this value

ESP_BT_HCI_TL_STATUS_OK

  HCI_TL TX/RX operation status OK

BT_CONTROLLER_INIT_CONFIG_DEFAULT()

### Type Definitions

typedef void (*esp_bt_hci_tl_callback_t)(void *arg, uint8_t status)

  Callback function for HCI Transport Layer send/receive operations.

typedef struct esp_vhci_host_callback esp_vhci_host_callback_t

  Virtual 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

    Unsupported mode

  enumerator ESP_BT_MODE_BTDM

    Unsupported mode

enum esp_bt_ctrl_hci_tl_t

  BLE Controller HCI transport layer type.

  Values:

  enumerator ESP_BT_CTRL_HCI_TL_UART

    HCI UART h4 transport layer

  enumerator ESP_BT_CTRL_HCI_TL_VHCI

    Virtual HCI interface

enum esp_ble_ce_len_t

  BLE connection event length computation type.

  Values:

  enumerator ESP_BLE_CE_LEN_TYPE_ORIG

    original

  enumerator ESP_BLE_CE_LEN_TYPE_CE

    use `CE_LEN` parameter from HCI commands

  enumerator ESP_BLE_CE_LEN_TYPE_SD

    Espressif vendor defined

enum esp_bt_sleep_mode_t

  Bluetooth modem sleep mode.

  Values:

  enumerator ESP_BT_SLEEP_MODE_NONE

    Disable modem sleep

  enumerator ESP_BT_SLEEP_MODE_1

    Enable modem sleep

enum esp_bt_sleep_clock_t

  Bluetooth modem sleep clock source.

  Note

  If the modem sleep mode is enabled, `ESP_BT_SLEEP_CLOCK_MAIN_XTAL` is the default option and `ESP_BT_SLEEP_CLOCK_NONE` will become an invalid option.

  Values:

  enumerator ESP_BT_SLEEP_CLOCK_NONE

    Sleep clock not configured

  enumerator ESP_BT_SLEEP_CLOCK_MAIN_XTAL

    SoC main crystal

  enumerator ESP_BT_SLEEP_CLOCK_EXT_32K_XTAL

    External 32.768kHz crystal

  enumerator ESP_BT_SLEEP_CLOCK_RTC_SLOW

    Internal 136kHz RC oscillator

  enumerator ESP_BT_SLEEP_CLOCK_FPGA_32K

    Hardwired 32KHz clock temporarily used for FPGA

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

enum esp_ble_power_type_t

  BLE TX power type.

  This TX power type is used for the API `esp_ble_tx_power_set()` and `esp_ble_tx_power_get()`.

  Note

  1. The connection TX power can only be set after the connection is established. After disconnecting, the corresponding TX power will not be affected.

  2. `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.

  3. 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 state handle 0

  enumerator ESP_BLE_PWR_TYPE_CONN_HDL1

    TX power for Connection state handle 1

  enumerator ESP_BLE_PWR_TYPE_CONN_HDL2

    TX power for Connection state handle 2

  enumerator ESP_BLE_PWR_TYPE_CONN_HDL3

    TX power for Connection state handle 3

  enumerator ESP_BLE_PWR_TYPE_CONN_HDL4

    TX power for Connection state handle 4

  enumerator ESP_BLE_PWR_TYPE_CONN_HDL5

    TX power for Connection state handle 5

  enumerator ESP_BLE_PWR_TYPE_CONN_HDL6

    TX power for Connection state handle 6

  enumerator ESP_BLE_PWR_TYPE_CONN_HDL7

    TX power for Connection state handle 7

  enumerator ESP_BLE_PWR_TYPE_CONN_HDL8

    TX power for Connection state handle 8

  enumerator ESP_BLE_PWR_TYPE_ADV

    TX power for Advertising state

  enumerator ESP_BLE_PWR_TYPE_SCAN

    TX power for Scanning state

  enumerator ESP_BLE_PWR_TYPE_DEFAULT

    TX power for states that have not been set before

  enumerator ESP_BLE_PWR_TYPE_NUM

    Reserved

enum esp_ble_enhanced_power_type_t

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

  This TX power type is used for the API `esp_ble_tx_power_set_enhanced()` and `esp_ble_tx_power_get_enhanced()`.

  Note

  1. The connection TX power can only be set after the connection is established. After disconnecting, the corresponding TX power will not be affected.

  2. `ESP_BLE_ENHANCED_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/INIT/CONN power types.

  3. 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_ENHANCED_PWR_TYPE_DEFAULT

    TX power for states that have not been set before

  enumerator ESP_BLE_ENHANCED_PWR_TYPE_ADV

    TX power for Advertising state

  enumerator ESP_BLE_ENHANCED_PWR_TYPE_SCAN

    TX power for Scanning state

  enumerator ESP_BLE_ENHANCED_PWR_TYPE_INIT

    TX power for Initiating state

  enumerator ESP_BLE_ENHANCED_PWR_TYPE_CONN

    TX power for Connection state

  enumerator ESP_BLE_ENHANCED_PWR_TYPE_MAX

    Reserved

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_N24

    Corresponding to -24 dBm

  enumerator ESP_PWR_LVL_N21

    Corresponding to -21 dBm

  enumerator ESP_PWR_LVL_N18

    Corresponding to -18 dBm

  enumerator ESP_PWR_LVL_N15

    Corresponding to -15 dBm

  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_P12

    Corresponding to +12 dBm

  enumerator ESP_PWR_LVL_P15

    Corresponding to +15 dBm

  enumerator ESP_PWR_LVL_P18

    Corresponding to +18 dBm

  enumerator ESP_PWR_LVL_P20

    Corresponding to +20 dBm

  enumerator ESP_PWR_LVL_P21

    Deprecated

  enumerator ESP_PWR_LVL_INVALID

    Indicates an invalid value

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?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.