BR/EDR Controller Feature Configuration
Overview
ESP32-S31 uses the Orca BR/EDR Controller for Classic Bluetooth. Its capabilities are selected at build time through Kconfig options in 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 CONFIG_BT_CTRL_BR_EDR_MAX_SYNC_CONN is 0, the build system sets the effective SCO/eSCO connection count to 1. See 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
Kconfig option(s) |
LM / LMP features |
HCI commands (opcode) |
|---|---|---|
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) |
|
eSCO EV4 packet type |
No dedicated HCI command. Affects |
|
eSCO EV5 packet type |
Same as above. |
|
eSCO 2-EV3 packet type |
Same as above. |
|
eSCO 3-EV3 packet type |
Same as above. |
|
eSCO 3-slot packet types |
Same as above. |
|
Hold Mode |
HCI_Hold_Mode (0x02/0x0001)HCI_Read_Hold_Mode_Activity (0x03/0x002B)HCI_Write_Hold_Mode_Activity (0x03/0x002C) |
|
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 CONFIG_BT_CTRL_BR_EDR_CPB_RX_EN. |
|
+
CONFIG_BT_CTRL_BR_EDR_APB_EXT_BCST_ENC_EN |
Broadcast Encryption |
|
+
CONFIG_BT_CTRL_BR_EDR_APB_EXT_PCA_EN |
Piconet Clock Adjustment (PCA) |
None. Clock Adjustment is carried over LMP.
|
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) |
|
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) |
|
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) |
|
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) |
|
Direct Test Mode (DTM) |
Enables Espressif custom vendor HCI commands for RF testing (non-Bluetooth Core Spec feature). |
|
Slot Availability Mask (SAM) |
None. SAM is negotiated entirely over LMP feature bits. Partially implemented; currently used for ACL air time scheduling. |
|
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.
Kconfig option(s) |
Description |
|---|---|
Maximum BR/EDR ACL connections (1–7). Limits how many ACL links the controller can maintain. |
|
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. |
|
SCO/eSCO TX/RX buffer counts. Visible only when 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. |
|
|
Default SCO/eSCO data path. Only HCI is supported; PCM/I2S routing is not yet available. |
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. |
|
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
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. |
|
Default TX power for APB. Available when CONFIG_BT_CTRL_BR_EDR_APB_EN is enabled. |
|
Default TX power for CPB transmit and Synchronization Train. Available when CONFIG_BT_CTRL_BR_EDR_CPB_TX_EN is enabled. |
Vendor Events
Kconfig option |
Related HCI vendor event |
|---|---|
Enables the Legacy Authentication Completed vendor event to help mitigate BIAS attacks during legacy authentication. Enabled by default. |