# 控制器 （Controller）& HCI

[English]

## API 参考

### Header File

- components/bt/include/esp32s31/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_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.

  参数:

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

  参数:

    power_type -- : The type of which tx power, could set Advertising/Connection/Default and etc

  返回:

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

  参数:

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

  返回:

    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.

  参数:

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

  返回:

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

  参数:

    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.

  返回:

    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.

  返回:

    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.

  返回:

    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.

  参数:

    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().

  返回:

    ESP_OK - success, other - failed

esp_err_t esp_bt_controller_disable(void)

  Disable BT controller.

  返回:

    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.

  返回:

    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.

  参数:

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

  参数:

    callback -- esp_vhci_host_callback type variable

  返回:

    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

  参数:

    mode -- : the mode want to release memory

  返回:

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

  参数:

    mode -- : the mode whose memory is to be released

  返回:

    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.

  返回:

    ESP_OK - success, other - failed

### Structures

struct esp_ble_addr_t

  Address type and address value.

  Public Members

  uint8_t type

    Type of the Bluetooth address (public, random, etc.)

  uint8_t val[6]

    Array containing the 6-byte Bluetooth address value

struct orca_mempool_ops

  mempool operations used in BR/EDR controller

  Public Members

  orca_mempool_t (*create_with_pool)(void *mem, size_t pool_bytes, size_t max_bytes)

    mempool construction

  void (*destroy)(orca_mempool_t mempool)

    mempool destruction

  void *(*malloc)(orca_mempool_t mempool, size_t size)

    allocate memory from mempool

  void (*free)(orca_mempool_t mempool, void *ptr)

    release memory

struct esp_bredr_controller_config_t

  BR/EDR controller configuration options.

  Public Members

  uint32_t bredr_version

    version number of the defined structure

  uint8_t sleep_mode

    controller sleep mode

  uint8_t bt_test_mode_en

    enable br/edr test mode

  uint8_t acl_cca_en

    Enable BR/EDR ACL Transmit Clear Channel Assessment (TX CCA)

  int8_t cca_rssi_thr

    BR/EDR RSSI threshold for Transmit Clear Channel Assessment (CCA)

  uint8_t max_acl_conn

    Maximum number of BR/EDR ACL connections. Configurable in menuconfig

  uint8_t max_sync_conn

    Maximum number of BR/EDR synchronous connections. Configurable in menuconfig

  uint8_t cpb_tx_link_num

    BR/EDR CPB TX link number

  uint8_t cpb_rx_link_num

    BR/EDR CPB RX link number

  uint8_t bt_sco_datapath

    SCO data path, i.e. HCI(0) or PCM(1)

  uint8_t hci_tl_type

    HCI transport layer, UART, VHCI, etc

  void *hci_tl_funcs

    hci transport functions used, must be set when hci_tl_type is UART

  uint32_t cfg_mask

    reserved

  uint32_t hw_target_code

    hardware target

  int8_t acl_min_tx_pwr

    Default transmit power for ACL minimum

  int8_t acl_max_tx_pwr

    Default transmit power for ACL maximum

  int8_t apb_tx_pwr

    Default transmit power for APB

  int8_t page_tx_pwr

    Default transmit power for Page

  int8_t pscan_tx_pwr

    Default transmit power for Page Scan

  int8_t iscan_tx_pwr

    Default transmit power for Inquiry Scan

  int8_t cpb_tx_pwr

    Default transmit power for CPB TX

  int8_t strain_tx_pwr

    Default transmit power for Synchronization Train

  uint8_t rf_hw_type

    RF hardware type

  uint8_t static_aclu_tx_buf_nb

    Static ACL-U TX buffer number

  uint8_t dynamic_aclu_tx_buf_nb

    Dynamic ACL-U TX buffer number

  uint8_t aclu_rx_buf_nb

    ACL-U RX buffer number

  uint8_t sync_tx_buf_nb

    SCO TX buffer number

  uint8_t sync_rx_buf_nb

    SCO RX buffer number

  uint8_t esco_ev4_supp

    eSCO support EV4 packet type

  uint8_t esco_ev5_supp

    eSCO support EV5 packet type

  uint8_t esco_ev3_2_supp

    eSCO support 2-EV3 packet type

  uint8_t esco_ev3_3_supp

    eSCO support 3-EV3 packet type

  uint8_t esco_3_slots_supp

    eSCO support 2-EV5 and/or 3-EV5 packet type

  uint8_t bt_legacy_auth_vs_evt

    1 if BR/EDR Legacy Authentication Vendor Specific Event is enabled, which is required to protect from BIAS attack; 0 otherwise. Configurable in menuconfig

  uint8_t inq_filter_en

    Enable inquiry result filter

  uint8_t dtm_en

    BR/EDR direct test mode

  uint32_t mempool_size

    Required mempool size used in BR/EDR controller

  struct orca_mempool_ops *mempool_ops

    mempool operations used in BR/EDR controller

  uint32_t bredr_magic

    Magic number

struct esp_btdm_controller_config_t

  BTDM controller common configuration options.

  Public Members

  uint32_t version

    Version number of the defined structure

  uint16_t task_stack_size

    Size of Bluetooth controller task stack

  uint8_t task_prio

    Priority of the Bluetooth controller task

  uint8_t task_run_cpu

    CPU number on which the Bluetooth controller task runs

  uint8_t hci_cmd_num

    HCI command buffer number

  uint8_t hci_conn_num

    HCI level connection number

  uint8_t sleep_en

    Enable sleep functionality

  uint8_t version_num

    Hardware version number of this chip

  uint8_t bluetooth_mode

    Controller mode: BR/EDR, BLE or Dual Mode

  uint32_t magic

    Magic number for configuration validation

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, to be removed

  uint8_t controller_task_prio

    Priority of the Bluetooth task, to be removed

  uint8_t controller_run_cpu

    CPU number on which the Bluetooth controller task runs, to be removed

  uint8_t enable_qa_test

    Enable for QA test

  uint8_t enable_bqb_test

    Enable for BQB test

  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 ignore_wl_for_direct_adv

    Ignore the white list for directed advertising

  uint8_t enable_pcl

    Enable power control

  uint8_t csa2_select

    Select CSA2

  uint8_t enable_csr

    Enable connection subrate

  int8_t backoff_rssi

    Set the lowest rssi threshold for backoff

  bool iso_enabled

    Enable ISO

  bool iso_bqb_test

    Enable ISO BQB test

  bool iso_fra_unseg

    Enable ISO FRA unsegmented

  bool iso_nsfc_en

    Enable ISO NSCF

  uint8_t iso_nsfc_num

    Number of ISO NSCF

  uint8_t iso_buf_count

    Number of ISO buffer

  uint16_t iso_buf_size

    Size of ISO buffer

  uint8_t iso_big_count

    Number of ISO big

  uint16_t iso_bis_count

    Number of ISO bis

  uint8_t iso_bis_per_big

    Number of ISO bis per big

  uint8_t iso_cig_count

    Number of ISO cig

  uint16_t iso_cis_count

    Number of ISO cis

  uint8_t iso_cis_per_cig

    Number of ISO cis per cig

  uint32_t config_magic

    Configuration magic value

  struct esp_bt_controller_config_t ble

    Bluetooth LE controller configuration options.

    Bluetooth LE controller configuration options

  esp_bredr_controller_config_t bredr

    Bluetooth Classic controller configuration options.

    Bluetooth Classic controller configuration options

  esp_btdm_controller_config_t btdm

    Bluetooth controller common configuration options.

    Bluetooth controller common configuration options

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

BLE_CONFIG_VERSION

BLE_CONFIG_MAGIC

BTDM_CONFIG_VERSION

BTDM_CONFIG_MAGIC_VALUE

BTDM_CONTROLLER_MODE_EFF

DEFAULT_BT_LE_ISO_ENABLED

DEFAULT_BT_LE_ISO_FRA_UNSEG

DEFAULT_BT_LE_ISO_NSFC_EN

DEFAULT_BT_LE_ISO_NSFC_NUM

DEFAULT_BT_LE_ISO_BUF_COUNT

DEFAULT_BT_LE_ISO_BUF_SIZE

DEFAULT_BT_LE_ISO_BIG

DEFAULT_BT_LE_ISO_BIS

DEFAULT_BT_LE_ISO_BIS_PER_BIG

DEFAULT_BT_LE_ISO_CIG

DEFAULT_BT_LE_ISO_CIS

DEFAULT_BT_LE_ISO_CIS_PER_CIG

### Type Definitions

typedef void *orca_mempool_t

  mempool handle type used in BR/EDR controller

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

    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

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_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 +16dbm

  enumerator ESP_PWR_LVL_P17

    Corresponding to +17dbm

  enumerator ESP_PWR_LVL_P18

    Corresponding to +18dbm

  enumerator ESP_PWR_LVL_P19

    Corresponding to +19dbm

  enumerator ESP_PWR_LVL_P20

    Corresponding to +20dbm

  enumerator ESP_PWR_LVL_INVALID

    Indicates an invalid value

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

enum esp_sco_data_path_t

  BR/EDR 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

enum esp_ble_log_buf_t

  Select buffers.

  Values:

  enumerator ESP_BLE_LOG_BUF_HCI
  enumerator ESP_BLE_LOG_BUF_CONTROLLER

## 乐鑫自定义 HCI 命令

乐鑫自定义 HCI 命令专为 Espressif 的蓝牙主机协议栈或内部调试用途设计。应用程序开发者 不应 在其应用程序中初始化或调用这些命令。有关这些命令的详细信息，请参阅 乐鑫自定义 HCI 命令。

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。