Merge branch 'docs/hci_feature_config' into 'master'

docs(bt): Add docs file to describe the correspondence between the controller Kconfig options and related LM features and HCI commands See merge request espressif/esp-idf!52153
2026-10-18 19:43:17 +03:00 · 2026-09-28 15:58:06 +08:00
parent d27917f9c1 80d6bf3952
commit a2b536be9c
11 changed files with 414 additions and 16 deletions
@@ -1727,6 +1727,10 @@ config SOC_BT_CLASSIC_SUPPORTED
    bool
    default y

+config SOC_ORCA_BREDR_CONTROLLER
+    bool
+    default y
+
 config SOC_BLE_SUPPORTED
    bool
    default y
@@ -649,6 +649,7 @@

 /*---------------------------------- Bluetooth CAPS ----------------------------------*/
 #define SOC_BT_CLASSIC_SUPPORTED                    (1)     /*!< Support Bluetooth Classic hardware */
+#define SOC_ORCA_BREDR_CONTROLLER                   (1)     /*!< Support Espressif Orca BR/EDR controller */
 #define SOC_BLE_SUPPORTED                           (1)     /*!< Support Bluetooth Low Energy hardware */
 #define SOC_BLE_MESH_SUPPORTED                      (1)     /*!< Support BLE MESH */
 #define SOC_BLE_ISO_SUPPORTED                       (1)     /*!< Support BLE ISO */
@@ -109,6 +109,10 @@ CLASSIC_BT_DOCS = [
    'migration-guides/release-6.x/6.2/bluetooth-classic.rst',
 ]

+ORCA_BREDR_CONTROLLER_DOCS = [
+    'api-guides/classic-bt/esp-bredr-controller-kconfig.rst',
+]
+
 BLUFI_DOCS = ['api-guides/ble/blufi.rst', 'api-reference/bluetooth/esp_blufi.rst']

 WIFI_DOCS = [
@@ -379,6 +383,7 @@ conditional_include_dict = {
    'SOC_BLUFI_SUPPORTED': BLUFI_DOCS,
    'SOC_WIFI_SUPPORTED': WIFI_DOCS,
    'SOC_BT_CLASSIC_SUPPORTED': CLASSIC_BT_DOCS,
+    'SOC_ORCA_BREDR_CONTROLLER': ORCA_BREDR_CONTROLLER_DOCS,
    'SOC_IEEE802154_SUPPORTED': IEEE802154_DOCS,
    'SOC_SUPPORT_COEXISTENCE': COEXISTENCE_DOCS,
    'SOC_PSRAM_DMA_CAPABLE': MM_SYNC_DOCS,
@@ -0,0 +1,175 @@
+BR/EDR Controller Feature Configuration
+=======================================
+
+:link_to_translation:`zh_CN:[中文]`
+
+Overview
+--------
+
+{IDF_TARGET_NAME} uses the **Orca BR/EDR Controller** for Classic Bluetooth. Its capabilities are selected at build time through Kconfig options in :component_file:`bt/porting_btdm/controller/bredr/Kconfig.in`. Options fall into two groups:
+
+- **Feature options**: gate Link Manager (LM/LMP) features and the HCI commands that implement them. Disabled features are not registered in the controller; related HCI commands return **Unknown HCI Command** (``0x01``).
+- **Resource and tuning options**: set connection limits, buffer counts, default TX power, CCA, and similar parameters. They do not register or unregister HCI commands by themselves.
+
+Configuration path:
+
+**Component config** > **Bluetooth** > **Controller Options** > **BR/EDR Controller Options**
+
+.. note::
+
+   When ESP-Bluedroid HFP is enabled and :ref:`CONFIG_BT_CTRL_BR_EDR_MAX_SYNC_CONN` is ``0``, the build system sets the effective SCO/eSCO connection count to ``1``. See :component_file:`bt/porting_btdm/controller/bredr/include/bredr_user_cfg.h`.
+
+When BR/EDR is enabled (**BR/EDR Only** or **Dual Mode**), standard commands for inquiry, ACL connection, pairing, encryption, sniff, role switch, scan/page, AFH, EIR, and informational queries are available without enabling the optional feature options below.
+
+HCI names and opcodes follow the Bluetooth Core Specification. The table lists opcodes as Opcode Group Field (OGF) and Opcode Command Field (OCF) pairs, e.g., ``0x01/0x0028``. Espressif vendor commands use OGF ``0x3F``.
+
+Feature Options, LM Features, and HCI Commands
+----------------------------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 28 42
+
+   * - Kconfig option(s)
+     - LM / LMP features
+     - HCI commands (opcode)
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_MAX_SYNC_CONN` > 0
+     - SCO link; eSCO (EV3)
+     - | ``HCI_Setup_Synchronous_Connection`` (``0x01/0x0028``)
+       | ``HCI_Accept_Synchronous_Connection_Request`` (``0x01/0x0029``)
+       | ``HCI_Reject_Synchronous_Connection_Request`` (``0x01/0x002A``)
+       | ``HCI_Enhanced_Setup_Synchronous_Connection`` (``0x01/0x003D``)
+       | ``HCI_Enhanced_Accept_Synchronous_Connection_Request`` (``0x01/0x003E``)
+       | ``HCI_Read_Voice_Setting`` (``0x03/0x0025``)
+       | ``HCI_Write_Voice_Setting`` (``0x03/0x0026``)
+       | ``HCI_Read_Synchronous_Flow_Control_Enable`` (``0x03/0x002E``)
+       | ``HCI_Write_Synchronous_Flow_Control_Enable`` (``0x03/0x002F``)
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_ESCO_EV4_SUPP`
+     - eSCO EV4 packet type
+     - No dedicated HCI command. Affects ``HCI_Read_Local_Extended_Features`` (``0x04/0x0004``). Visible only when :ref:`CONFIG_BT_CTRL_BR_EDR_MAX_SYNC_CONN` > 0.
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_ESCO_EV5_SUPP`
+     - eSCO EV5 packet type
+     - Same as above.
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_ESCO_EV3_2_SUPP`
+     - eSCO 2-EV3 packet type
+     - Same as above.
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_ESCO_EV3_3_SUPP`
+     - eSCO 3-EV3 packet type
+     - Same as above.
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_ESCO_3_SLOTS_SUPP`
+     - eSCO 3-slot packet types
+     - Same as above.
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_HOLD_EN`
+     - Hold Mode
+     - | ``HCI_Hold_Mode`` (``0x02/0x0001``)
+       | ``HCI_Read_Hold_Mode_Activity`` (``0x03/0x002B``)
+       | ``HCI_Write_Hold_Mode_Activity`` (``0x03/0x002C``)
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_APB_EN`
+     - Active Peripheral Broadcast (APB); truncated page support at LM
+     - No dedicated HCI command for APB alone. Truncated page / CSB receive HCI commands are registered by :ref:`CONFIG_BT_CTRL_BR_EDR_CPB_RX_EN`.
+   * - | :ref:`CONFIG_BT_CTRL_BR_EDR_APB_EXT_EN`
+       | + ``CONFIG_BT_CTRL_BR_EDR_APB_EXT_BCST_ENC_EN``
+     - Broadcast Encryption
+     - ``HCI_Link_Key_Selection`` (``0x01/0x0017``), same as ``HCI_Master_Link_Key``
+   * - | :ref:`CONFIG_BT_CTRL_BR_EDR_APB_EXT_EN`
+       | + ``CONFIG_BT_CTRL_BR_EDR_APB_EXT_PCA_EN``
+     - Piconet Clock Adjustment (PCA)
+     - | None. Clock Adjustment is carried over LMP.
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_CPB_TX_EN`
+     - Synchronization train (master); Connectionless Peripheral Broadcast – Transmit
+     - | ``HCI_Set_Connectionless_Peripheral_Broadcast`` (``0x01/0x0041``)
+       | ``HCI_Start_Synchronization_Train`` (``0x01/0x0043``)
+       | ``HCI_Set_Reserved_LT_ADDR`` (``0x03/0x0074``)
+       | ``HCI_Delete_Reserved_LT_ADDR`` (``0x03/0x0075``)
+       | ``HCI_Set_Connectionless_Peripheral_Broadcast_Data`` (``0x03/0x0076``)
+       | ``HCI_Read_Synchronization_Train_Parameters`` (``0x03/0x0077``)
+       | ``HCI_Write_Synchronization_Train_Parameters`` (``0x03/0x0078``)
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_CPB_RX_EN`
+     - Synchronization scan; Connectionless Peripheral Broadcast – Receive
+     - | ``HCI_Truncated_Page`` (``0x01/0x003F``)
+       | ``HCI_Truncated_Page_Cancel`` (``0x01/0x0040``)
+       | ``HCI_Set_Connectionless_Peripheral_Broadcast_Receive`` (``0x01/0x0042``)
+       | ``HCI_Receive_Synchronization_Train`` (``0x01/0x0044``)
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_LK_STORE_EN`
+     - Controller link key storage (RAM only)
+     - | ``HCI_Read_Stored_Link_Key`` (``0x03/0x000D``)
+       | ``HCI_Write_Stored_Link_Key`` (``0x03/0x0011``)
+       | ``HCI_Delete_Stored_Link_Key`` (``0x03/0x0012``)
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_TEST_MODE_EN`
+     - Test Mode
+     - | ``HCI_Read_Loopback_Mode`` (``0x06/0x0001``)
+       | ``HCI_Write_Loopback_Mode`` (``0x06/0x0002``)
+       | ``HCI_Enable_Device_Under_Test_Mode`` (``0x06/0x0003``)
+       | ``HCI_Write_Simple_Pairing_Debug_Mode`` (``0x06/0x0004``)
+       | ``HCI_Write_Secure_Connections_Test_Mode`` (``0x06/0x000A``)
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_DTM_EN`
+     - Direct Test Mode (DTM)
+     - Enables Espressif custom vendor HCI commands for RF testing (non-Bluetooth Core Spec feature).
+   * - | :ref:`CONFIG_BT_CTRL_BR_EDR_SAM_EN`
+       | *(requires* :ref:`CONFIG_IDF_EXPERIMENTAL_FEATURES` *)*
+     - Slot Availability Mask (SAM)
+     - None. SAM is negotiated entirely over LMP feature bits. Partially implemented; currently used for ACL air time scheduling.
+   * - | :ref:`CONFIG_BT_CTRL_BR_EDR_MWS_EN`
+       | *(requires* :ref:`CONFIG_BT_CTRL_BR_EDR_SAM_EN` *)*
+     - Mobile Wireless Standards (MWS) coexistence
+     - | ``HCI_Set_External_Frame_Configuration`` (``0x03/0x006F``)
+       | ``HCI_Set_MWS_PATTERN_Configuration`` (``0x03/0x0073``)
+       | Partially implemented; only the commands above are supported.
+
+Resource and Tuning Options
+---------------------------
+
+These options configure controller capacity and RF defaults. They do not enable or disable LM feature bits or HCI command tables by themselves.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 36 64
+
+   * - Kconfig option(s)
+     - Description
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_MAX_ACL_CONN`
+     - Maximum BR/EDR ACL connections (1–7). Limits how many ACL links the controller can maintain.
+   * - | :ref:`CONFIG_BT_CTRL_BR_EDR_ACLU_TX_BUF_NB`
+       | :ref:`CONFIG_BT_CTRL_BR_EDR_DYNAMIC_ACLU_TX_BUF_NB`
+       | :ref:`CONFIG_BT_CTRL_BR_EDR_ACLU_RX_BUF_NB`
+     - | ACL-U TX/RX buffer counts.
+       | ``ACLU_TX_BUF_NB`` is the total ACL-U TX buffer count and is reflected in the ``HCI_Read_Buffer_Size`` response.
+       | ``DYNAMIC_ACLU_TX_BUF_NB`` is taken from that total. If non-zero, those buffers are allocated from the heap when needed at runtime instead of during controller initialization; unused dynamic buffers save memory, but allocating them on demand may slow the controller.
+       | ``ACLU_RX_BUF_NB`` is the ACL-U RX buffer count.
+   * - | :ref:`CONFIG_BT_CTRL_BR_EDR_STATIC_SYNC_TX_BUF_NB`
+       | :ref:`CONFIG_BT_CTRL_BR_EDR_DYNAMIC_SYNC_TX_BUF_NB`
+       | :ref:`CONFIG_BT_CTRL_BR_EDR_STATIC_SYNC_RX_BUF_NB`
+       | :ref:`CONFIG_BT_CTRL_BR_EDR_SYNC_RX_BUF_NB_PER_LINK`
+     - | SCO/eSCO TX/RX buffer counts. Visible only when :ref:`CONFIG_BT_CTRL_BR_EDR_MAX_SYNC_CONN` > 0. Defaults for the static counts scale with the max sync connection count.
+       | Static TX buffers are allocated at controller initialization and shared by all sync links. Dynamic TX buffers are allocated when the first sync link is established and freed after the last sync link releases them.
+       | ``SYNC_RX_BUF_NB_PER_LINK`` is the average RX buffer count per link (static + dynamic). If static RX buffers are fewer than ``SYNC_RX_BUF_NB_PER_LINK`` × active sync links, the RX pool grows or shrinks as links are created or torn down. Set it to ``0`` to disable dynamic sync RX buffers.
+   * - ``CONFIG_BT_CTRL_BR_EDR_SCO_DATA_PATH_HCI``
+     - Default SCO/eSCO data path. Only HCI is supported; PCM/I2S routing is not yet available.
+   * - | :ref:`CONFIG_BT_CTRL_BR_EDR_TX_CCA_ENABLED`
+       | + :ref:`CONFIG_BT_CTRL_BR_EDR_CCA_RSSI_THRESH`
+     - TX Clear Channel Assessment. When enabled, the controller may cancel a transmission if the measured signal is stronger than the CCA threshold (unit: -1 dBm). No dedicated HCI command.
+   * - | :ref:`CONFIG_BT_CTRL_BR_EDR_TX_PWR_ACL_MIN`
+       | :ref:`CONFIG_BT_CTRL_BR_EDR_TX_PWR_ACL_MAX`
+       | :ref:`CONFIG_BT_CTRL_BR_EDR_TX_PWR_PAGE`
+       | :ref:`CONFIG_BT_CTRL_BR_EDR_TX_PWR_PSCAN`
+       | :ref:`CONFIG_BT_CTRL_BR_EDR_TX_PWR_ISCAN`
+     - | Default TX power levels (dBm) for ACL, Page, Page Scan, and Inquiry Scan.
+       | The actual chip-supported TX power range can be obtained with the function :cpp:func:`esp_bredr_tx_power_range_get`. Values outside that range are rejected.
+       | ACL link power can be adjusted on peer LMP power-control requests. The initial ACL power is taken from ``TX_PWR_PAGE`` (Central) or ``TX_PWR_PSCAN`` (Peripheral); keep those within the ACL min/max range when possible.
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_TX_PWR_APB`
+     - Default TX power for APB. Available when :ref:`CONFIG_BT_CTRL_BR_EDR_APB_EN` is enabled.
+   * - | :ref:`CONFIG_BT_CTRL_BR_EDR_TX_PWR_CPB`
+       | :ref:`CONFIG_BT_CTRL_BR_EDR_TX_PWR_STRAIN`
+     - Default TX power for CPB transmit and Synchronization Train. Available when :ref:`CONFIG_BT_CTRL_BR_EDR_CPB_TX_EN` is enabled.
+
+Vendor Events
+-------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 36 64
+
+   * - Kconfig option
+     - Related HCI vendor event
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_LEGACY_AUTH_VENDOR_EVT`
+     - Enables the Legacy Authentication Completed vendor event to help mitigate BIAS attacks during legacy authentication. Enabled by default.
@@ -10,3 +10,4 @@ Bluetooth\ :sup:`®` Classic

   overview
   profiles-protocols
+   :SOC_ORCA_BREDR_CONTROLLER: esp-bredr-controller-kconfig
@@ -11,14 +11,12 @@ This document provides an architecture overview of the Bluetooth Classic stack i

 The Bluetooth Classic stack in ESP-IDF is a layered architecture that enables Bluetooth functionality on {IDF_TARGET_NAME} chip series. The figure below shows its architecture.

-.. only:: esp32
+.. figure:: ../../../_static/classic-bluetooth-architecture.png
+    :align: center
+    :scale: 90%
+    :alt: {IDF_TARGET_NAME} Bluetooth Classic Stack Architecture

-    .. figure:: ../../../_static/classic-bluetooth-architecture.png
-        :align: center
-        :scale: 90%
-        :alt: {IDF_TARGET_NAME} Bluetooth Classic Stack Architecture
-
-        {IDF_TARGET_NAME} Bluetooth Classic Stack Architecture
+    {IDF_TARGET_NAME} Bluetooth Classic Stack Architecture


 The following sections briefly describe each layer and provide quick links to the related documents and application examples.
@@ -29,8 +27,15 @@ ESP Bluetooth Controller

 At the bottom layer is ESP Bluetooth Controller, which encompasses various modules such as PHY, Baseband, Link Controller, Link Manager, Device Manager, and HCI. It handles hardware interface management and link management. It provides functions in the form of libraries and is accessible through APIs. This layer directly interacts with the hardware and low-level Bluetooth protocols.

+.. only:: SOC_ORCA_BREDR_CONTROLLER
+
+    On {IDF_TARGET_NAME}, optional features of the Orca BR/EDR Controller are selected at build time via Kconfig. See :doc:`esp-bredr-controller-kconfig`.
+
 - :doc:`API reference <../../api-reference/bluetooth/controller_vhci>`
- :example:`Application examples <bluetooth/hci/controller_hci_uart_esp32>`
+
+.. only:: esp32
+
+    - :example:`Application examples <bluetooth/hci/controller_hci_uart_esp32>`


 Hosts
@@ -11,3 +11,16 @@ Bluedroid
    - ``BT_ENC_KEY_SIZE_CTRL_ENABLED`` is deprecated and will be removed in a future release.

        The host now uses the standard ``HCI_Set_Min_Encryption_Key_Size`` command when the controller reports support for it via ``HCI_Read_Local_Supported_Commands``. A new ``CONFIG_BT_CLASSIC_ENABLE_ENC_KEY_SIZE_CTRL_VSC`` option has been added to enable the Espressif vendor-specific command as a fallback when the standard command is not supported.
+
+.. only:: SOC_ORCA_BREDR_CONTROLLER
+
+    BR/EDR Controller Feature Configuration
+    ---------------------------------------
+
+    Different from ESP32, ESP32-S31 adopts a new Bluetooth Classic controller solution, named Orca BR/EDR Controller. The new solution provides different user options in Kconfig.
+
+    Please note the following:
+
+    - Controller options live under **Component config** > **Bluetooth** > **Controller Options** > **BR/EDR Controller Options**. They are not interchangeable with the ESP32 options.
+    - Optional LM/LMP features must be enabled explicitly in Kconfig. Disabled features are not registered; related HCI commands return **Unknown HCI Command** (``0x01``).
+    - See :doc:`../../../api-guides/classic-bt/esp-bredr-controller-kconfig` for the mapping of Kconfig options to LMP features and HCI commands.
@@ -0,0 +1,175 @@
+BR/EDR 控制器功能配置
+=====================
+
+:link_to_translation:`en:[English]`
+
+概述
+----
+
+{IDF_TARGET_NAME} 的经典蓝牙使用 **Orca BR/EDR Controller**。其功能通过 :component_file:`bt/porting_btdm/controller/bredr/Kconfig.in` 中的 Kconfig 选项在编译期选择。选项分为两类：
+
+- **功能选项**：控制 Link Manager (LM/LMP) 特性以及对应 HCI 命令的注册。未使能的功能不会注册到控制器，相关 HCI 命令将返回 ``Unknown HCI Command`` (``0x01``)。
+- **资源与调优选项**：配置连接数上限、缓冲区数量、默认发射功率、CCA 等参数，本身不会注册或注销 HCI 命令。
+
+配置路径：
+
+**Component config** > **Bluetooth** > **Controller Options** > **BR/EDR Controller Options**
+
+.. note::
+
+   使用 ESP-Bluedroid 且使能 HFP 时，若 :ref:`CONFIG_BT_CTRL_BR_EDR_MAX_SYNC_CONN` 为 ``0``，系统会将实际 SCO/eSCO 连接数设为 ``1``。详见 :component_file:`bt/porting_btdm/controller/bredr/include/bredr_user_cfg.h`。
+
+在 BR/EDR 已使能（``BR/EDR Only`` 或 ``Dual Mode``）时，Inquiry、ACL 建链、配对、加密、Sniff、角色切换、Scan/Page、AFH、EIR 及信息查询等标准命令无需下方可选功能选项即可使用。
+
+HCI 名称与 Opcode 遵循 Bluetooth Core Specification。表中标准命令以 Opcode Group Field (OGF) 和 Opcode Command Field (OCF) 成对给出，例如 ``0x01/0x0028``。乐鑫厂商命令使用 OGF ``0x3F``。
+
+功能选项、LM 特性与 HCI 命令
+----------------------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 28 42
+
+   * - Kconfig 选项
+     - LM / LMP 特性
+     - HCI 命令 (Opcode)
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_MAX_SYNC_CONN` > 0
+     - SCO link；eSCO (EV3)
+     - | ``HCI_Setup_Synchronous_Connection`` (``0x01/0x0028``)
+       | ``HCI_Accept_Synchronous_Connection_Request`` (``0x01/0x0029``)
+       | ``HCI_Reject_Synchronous_Connection_Request`` (``0x01/0x002A``)
+       | ``HCI_Enhanced_Setup_Synchronous_Connection`` (``0x01/0x003D``)
+       | ``HCI_Enhanced_Accept_Synchronous_Connection_Request`` (``0x01/0x003E``)
+       | ``HCI_Read_Voice_Setting`` (``0x03/0x0025``)
+       | ``HCI_Write_Voice_Setting`` (``0x03/0x0026``)
+       | ``HCI_Read_Synchronous_Flow_Control_Enable`` (``0x03/0x002E``)
+       | ``HCI_Write_Synchronous_Flow_Control_Enable`` (``0x03/0x002F``)
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_ESCO_EV4_SUPP`
+     - eSCO EV4 包类型
+     - 无独立 HCI 命令。影响 ``HCI_Read_Local_Extended_Features`` (``0x04/0x0004``)。仅在 :ref:`CONFIG_BT_CTRL_BR_EDR_MAX_SYNC_CONN` > 0 时可见。
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_ESCO_EV5_SUPP`
+     - eSCO EV5 包类型
+     - 同上。
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_ESCO_EV3_2_SUPP`
+     - eSCO 2-EV3 包类型
+     - 同上。
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_ESCO_EV3_3_SUPP`
+     - eSCO 3-EV3 包类型
+     - 同上。
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_ESCO_3_SLOTS_SUPP`
+     - eSCO 3-slot 包类型
+     - 同上。
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_HOLD_EN`
+     - Hold Mode
+     - | ``HCI_Hold_Mode`` (``0x02/0x0001``)
+       | ``HCI_Read_Hold_Mode_Activity`` (``0x03/0x002B``)
+       | ``HCI_Write_Hold_Mode_Activity`` (``0x03/0x002C``)
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_APB_EN`
+     - Active Peripheral Broadcast (APB)；LM 层 truncated page 支持
+     - APB 本身无独立 HCI 命令。Truncated page / CSB 接收相关 HCI 由 :ref:`CONFIG_BT_CTRL_BR_EDR_CPB_RX_EN` 注册。
+   * - | :ref:`CONFIG_BT_CTRL_BR_EDR_APB_EXT_EN`
+       | + ``CONFIG_BT_CTRL_BR_EDR_APB_EXT_BCST_ENC_EN``
+     - Broadcast Encryption
+     - ``HCI_Link_Key_Selection`` (``0x01/0x0017``)，同 ``HCI_Master_Link_Key``
+   * - | :ref:`CONFIG_BT_CTRL_BR_EDR_APB_EXT_EN`
+       | + ``CONFIG_BT_CTRL_BR_EDR_APB_EXT_PCA_EN``
+     - Piconet Clock Adjustment (PCA)
+     - 无。Clock Adjustment 通过 LMP 实现。
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_CPB_TX_EN`
+     - Synchronization train (master)；Connectionless Peripheral Broadcast – Transmit
+     - | ``HCI_Set_Connectionless_Peripheral_Broadcast`` (``0x01/0x0041``)
+       | ``HCI_Start_Synchronization_Train`` (``0x01/0x0043``)
+       | ``HCI_Set_Reserved_LT_ADDR`` (``0x03/0x0074``)
+       | ``HCI_Delete_Reserved_LT_ADDR`` (``0x03/0x0075``)
+       | ``HCI_Set_Connectionless_Peripheral_Broadcast_Data`` (``0x03/0x0076``)
+       | ``HCI_Read_Synchronization_Train_Parameters`` (``0x03/0x0077``)
+       | ``HCI_Write_Synchronization_Train_Parameters`` (``0x03/0x0078``)
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_CPB_RX_EN`
+     - Synchronization scan；Connectionless Peripheral Broadcast – Receive
+     - | ``HCI_Truncated_Page`` (``0x01/0x003F``)
+       | ``HCI_Truncated_Page_Cancel`` (``0x01/0x0040``)
+       | ``HCI_Set_Connectionless_Peripheral_Broadcast_Receive`` (``0x01/0x0042``)
+       | ``HCI_Receive_Synchronization_Train`` (``0x01/0x0044``)
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_LK_STORE_EN`
+     - 控制器链路密钥存储（目前仅支持 RAM）
+     - | ``HCI_Read_Stored_Link_Key`` (``0x03/0x000D``)
+       | ``HCI_Write_Stored_Link_Key`` (``0x03/0x0011``)
+       | ``HCI_Delete_Stored_Link_Key`` (``0x03/0x0012``)
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_TEST_MODE_EN`
+     - Test Mode
+     - | ``HCI_Read_Loopback_Mode`` (``0x06/0x0001``)
+       | ``HCI_Write_Loopback_Mode`` (``0x06/0x0002``)
+       | ``HCI_Enable_Device_Under_Test_Mode`` (``0x06/0x0003``)
+       | ``HCI_Write_Simple_Pairing_Debug_Mode`` (``0x06/0x0004``)
+       | ``HCI_Write_Secure_Connections_Test_Mode`` (``0x06/0x000A``)
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_DTM_EN`
+     - Direct Test Mode (DTM)
+     - 使能乐鑫自定义的 RF 测试指令（非 Bluetooth Core Spec 特性）。
+   * - | :ref:`CONFIG_BT_CTRL_BR_EDR_SAM_EN`
+       | 需要 :ref:`CONFIG_IDF_EXPERIMENTAL_FEATURES`。
+     - Slot Availability Mask (SAM)
+     - 无。SAM 通过 LMP feature bits 协商。部分实现，目前用于 ACL 空口时间调度。
+   * - | :ref:`CONFIG_BT_CTRL_BR_EDR_MWS_EN`
+       | 依赖 :ref:`CONFIG_BT_CTRL_BR_EDR_SAM_EN`。
+     - Mobile Wireless Standards (MWS) 共存
+     - | ``HCI_Set_External_Frame_Configuration`` (``0x03/0x006F``)
+       | ``HCI_Set_MWS_PATTERN_Configuration`` (``0x03/0x0073``)
+       | 部分实现，仅支持上述命令。
+
+资源与调优选项
+--------------
+
+以下选项配置控制器容量与射频默认参数，本身不会使能或关闭 LM feature bits，也不会单独注册/注销 HCI 命令。
+
+.. list-table::
+   :header-rows: 1
+   :widths: 36 64
+
+   * - Kconfig 选项
+     - 说明
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_MAX_ACL_CONN`
+     - BR/EDR ACL 最大连接数 (1–7)，限制控制器可维护的 ACL 链路数量。
+   * - | :ref:`CONFIG_BT_CTRL_BR_EDR_ACLU_TX_BUF_NB`
+       | :ref:`CONFIG_BT_CTRL_BR_EDR_DYNAMIC_ACLU_TX_BUF_NB`
+       | :ref:`CONFIG_BT_CTRL_BR_EDR_ACLU_RX_BUF_NB`
+     - | ACL-U TX/RX buffer 数目。
+       | ``ACLU_TX_BUF_NB`` 为 ACL-U TX buffer 总数，会体现在 ``HCI_Read_Buffer_Size`` 的返回结果中。
+       | ``DYNAMIC_ACLU_TX_BUF_NB`` 从该总数中划出。若配置为非 0，这部分 buffer 会在运行中需要时从 heap 中分配，而非在控制器初始化时预分配；在运行中未使用时可减少内存占用，但用到时可能会拖慢控制器执行速度。
+       | ``ACLU_RX_BUF_NB`` 为 ACL-U RX buffer 数目。
+   * - | :ref:`CONFIG_BT_CTRL_BR_EDR_STATIC_SYNC_TX_BUF_NB`
+       | :ref:`CONFIG_BT_CTRL_BR_EDR_DYNAMIC_SYNC_TX_BUF_NB`
+       | :ref:`CONFIG_BT_CTRL_BR_EDR_STATIC_SYNC_RX_BUF_NB`
+       | :ref:`CONFIG_BT_CTRL_BR_EDR_SYNC_RX_BUF_NB_PER_LINK`
+     - | SCO/eSCO TX/RX buffer 数目。仅在 :ref:`CONFIG_BT_CTRL_BR_EDR_MAX_SYNC_CONN` > 0 时可见；静态 buffer 默认值随最大同步连接数变化。
+       | 静态 TX buffer 在控制器初始化时分配，由所有 sync 链路共享。动态 TX buffer 在第一条 sync 链路建立时分配，并在最后一条 sync 链路释放相关 buffer 后回收。
+       | ``SYNC_RX_BUF_NB_PER_LINK`` 为每条链路的平均 RX buffer 数目（静态 + 动态）。若静态 RX buffer 少于 ``SYNC_RX_BUF_NB_PER_LINK`` × 当前 sync 链路数，则会随链路增减动态扩缩 RX pool。设为 ``0`` 可禁用动态 sync RX buffer。
+   * - ``CONFIG_BT_CTRL_BR_EDR_SCO_DATA_PATH_HCI``
+     - SCO/eSCO 默认数据通路。目前仅支持 HCI；PCM/I2S 路由尚不可用。
+   * - | :ref:`CONFIG_BT_CTRL_BR_EDR_TX_CCA_ENABLED`
+       | + :ref:`CONFIG_BT_CTRL_BR_EDR_CCA_RSSI_THRESH`
+     - TX Clear Channel Assessment。使能后，若检测到的信号强度高于 CCA 阈值（单位：-1 dBm），控制器可取消本次发送。无独立 HCI 命令。
+   * - | :ref:`CONFIG_BT_CTRL_BR_EDR_TX_PWR_ACL_MIN`
+       | :ref:`CONFIG_BT_CTRL_BR_EDR_TX_PWR_ACL_MAX`
+       | :ref:`CONFIG_BT_CTRL_BR_EDR_TX_PWR_PAGE`
+       | :ref:`CONFIG_BT_CTRL_BR_EDR_TX_PWR_PSCAN`
+       | :ref:`CONFIG_BT_CTRL_BR_EDR_TX_PWR_ISCAN`
+     - | ACL、Page、Page Scan、Inquiry Scan 的默认发射功率 (dBm)。
+       | 芯片实际支持的发射功率范围可通过函数 :cpp:func:`esp_bredr_tx_power_range_get` 获取；超出该范围的配置会被拒绝。
+       | ACL 链路功率可随对端 LMP 功率控制请求调整。ACL 初始功率继承自 ``TX_PWR_PAGE`` (Central) 或 ``TX_PWR_PSCAN`` (Peripheral)，建议将二者配置在 ACL 最小/最大范围内。
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_TX_PWR_APB`
+     - APB 默认发射功率。需使能 :ref:`CONFIG_BT_CTRL_BR_EDR_APB_EN`。
+   * - | :ref:`CONFIG_BT_CTRL_BR_EDR_TX_PWR_CPB`
+       | :ref:`CONFIG_BT_CTRL_BR_EDR_TX_PWR_STRAIN`
+     - CPB 与 Synchronization Train 的默认发射功率。需使能 :ref:`CONFIG_BT_CTRL_BR_EDR_CPB_TX_EN`。
+
+Vendor Events
+-------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 36 64
+
+   * - Kconfig 选项
+     - 相关 HCI vendor event
+   * - :ref:`CONFIG_BT_CTRL_BR_EDR_LEGACY_AUTH_VENDOR_EVT`
+     - 使能 Legacy Authentication Completed Vendor Event，以帮助缓解 Legacy 认证过程中的 BIAS 攻击。默认使能。
@@ -10,3 +10,4 @@

   overview
   profiles-protocols
+   :SOC_ORCA_BREDR_CONTROLLER: esp-bredr-controller-kconfig
@@ -11,14 +11,12 @@

 ESP-IDF 中的经典蓝牙协议栈是一个分层架构，可在 {IDF_TARGET_NAME} 系列芯片上实现经典蓝牙功能，详见下图。

-.. only:: esp32
+.. figure:: ../../../_static/classic-bluetooth-architecture.png
+    :align: center
+    :scale: 90%
+    :alt: {IDF_TARGET_NAME} 经典蓝牙协议栈架构

-    .. figure:: ../../../_static/classic-bluetooth-architecture.png
-        :align: center
-        :scale: 90%
-        :alt: {IDF_TARGET_NAME} 经典蓝牙协议栈架构
-
-        {IDF_TARGET_NAME} 经典蓝牙协议栈架构
+    {IDF_TARGET_NAME} 经典蓝牙协议栈架构


 以下各节简要介绍了每个层，并提供了相关文档和应用示例的快速链接。
@@ -29,8 +27,15 @@ ESP 蓝牙控制器

 底层为 ESP 蓝牙控制器，包含 PHY、基带、链路控制器、链路管理器、设备管理器和 HCI 等各种模块。该层管理硬件接口和链路，以库的形式提供功能，并通过 API 访问，且直接与硬件和低级别蓝牙协议交互。

+.. only:: SOC_ORCA_BREDR_CONTROLLER
+
+    在 {IDF_TARGET_NAME} 上，Orca BR/EDR Controller 的可选功能可通过 Kconfig 在编译期选择。详见 :doc:`esp-bredr-controller-kconfig`。
+
 - :doc:`API 参考 <../../api-reference/bluetooth/controller_vhci>`
- :example:`应用示例 <bluetooth/hci/controller_hci_uart_esp32>`
+
+.. only:: esp32
+
+    - :example:`应用示例 <bluetooth/hci/controller_hci_uart_esp32>`


 ESP 蓝牙主机
@@ -11,3 +11,16 @@ Bluedroid
    - ``BT_ENC_KEY_SIZE_CTRL_ENABLED`` 已弃用，并将在后续版本中删除。

        Host 现在会在控制器通过 ``HCI_Read_Local_Supported_Commands`` 报告支持时，使用标准 ``HCI_Set_Min_Encryption_Key_Size`` 命令。新增 ``CONFIG_BT_CLASSIC_ENABLE_ENC_KEY_SIZE_CTRL_VSC`` 用于在标准命令不受支持时启用乐鑫厂商命令作为回退。
+
+.. only:: SOC_ORCA_BREDR_CONTROLLER
+
+    BR/EDR 控制器功能配置
+    ---------------------
+
+    与 ESP32 不同，ESP32-S31 采用全新的经典蓝牙控制器方案，名为 Orca BR/EDR Controller。新方案在 Kconfig 中提供了不同的用户配置选项。
+
+    请注意以下事项：
+
+    - 控制器相关选项位于 **Component config** > **Bluetooth** > **Controller Options** > **BR/EDR Controller Options**，与 ESP32 选项不通用。
+    - 可选 LM/LMP 功能需在 Kconfig 中显式使能。未使能的功能不会注册，相关 HCI 命令将返回 **Unknown HCI Command** (``0x01``)。
+    - Kconfig 选项与 LMP 特性、HCI 命令的对应关系见 :doc:`../../../api-guides/classic-bt/esp-bredr-controller-kconfig`。