Merge branch 'feature/hfp_lc3' into 'master'

Feature/hfp lc3 See merge request espressif/esp-idf!50037
2026-09-22 13:01:16 +03:00 · 2026-09-03 14:44:47 +08:00
parent c71e574ebf 25ca329650
commit 7f1b8d002e
43 changed files with 1491 additions and 186 deletions
--- a/docs/conf_common.py
+++ b/docs/conf_common.py
@@ -103,6 +103,7 @@ CLASSIC_BT_DOCS = [
    'migration-guides/release-5.x/5.3/bluetooth-classic.rst',
    'migration-guides/release-5.x/5.4/bluetooth-classic.rst',
    'migration-guides/release-6.x/6.0/bluetooth-classic.rst',
+    'migration-guides/release-6.x/6.2/bluetooth-classic.rst',
 ]

 BLUFI_DOCS = ['api-guides/ble/blufi.rst', 'api-reference/bluetooth/esp_blufi.rst']
--- a/docs/en/migration-guides/release-6.x/6.2/bluetooth-classic.rst
+++ b/docs/en/migration-guides/release-6.x/6.2/bluetooth-classic.rst
@@ -0,0 +1,65 @@
+Bluetooth Classic
+=================
+
+:link_to_translation:`zh_CN:[中文]`
+
+Bluedroid
+---------
+
+    The following Bluedroid APIs have been changed:
+
+    - :component_file:`/bt/host/bluedroid/api/include/api/esp_hf_defs.h`
+
+        - Type ``esp_hf_wbs_config_t`` is replaced by ``esp_hf_codec_mode_t``. The new type identifies the negotiated codec (CVSD, mSBC, or LC3-SWB), not a Wideband Speech on/off flag. ``esp_hf_wbs_config_t`` is kept as a deprecated alias of ``esp_hf_codec_mode_t``.
+        - Enumerators are renamed. Numeric values 0 / 1 / 2 are unchanged. The old ``ESP_HF_WBS_*`` names remain as macros that alias the new enumerators:
+
+            .. list-table::
+               :header-rows: 1
+               :widths: 40 40 20
+
+               * - Old enumerator
+                 - New enumerator
+                 - Value
+               * - ``ESP_HF_WBS_NONE``
+                 - ``ESP_HF_CODEC_NONE``
+                 - 0
+               * - ``ESP_HF_WBS_NO``
+                 - ``ESP_HF_CODEC_CVSD``
+                 - 1
+               * - ``ESP_HF_WBS_YES``
+                 - ``ESP_HF_CODEC_MSBC``
+                 - 2
+               * - —
+                 - ``ESP_HF_CODEC_LC3``
+                 - 3
+
+        - Existing ``switch`` statements and comparisons that use ``ESP_HF_WBS_NO`` or ``ESP_HF_WBS_YES`` still compile. Prefer the new names in new code.
+
+        - ``ESP_HF_CODEC_NONE`` means no codec has been negotiated, or the preference is reset to the stack default. It does not mean that CVSD is unavailable. ``ESP_HF_CODEC_CVSD`` is the selected narrowband codec, whether Wideband Speech is unsupported, disabled, or the link fell back from mSBC / LC3.
+
+        - ``ESP_HF_CODEC_LC3`` is new. Code that indexes a three-entry table with the codec value must add an LC3 entry or a default branch.
+
+        - Do not use ``esp_hf_codec_mode_t`` as a capability bitmap. Peer codec capabilities are reported separately as ``ESP_HF_CODEC_CAP_CVSD`` / ``ESP_HF_CODEC_CAP_MSBC`` / ``ESP_HF_CODEC_CAP_LC3`` in ``ESP_HF_BAC_RESPONSE_EVT``.
+
+        - Audio connection state ``ESP_HF_AUDIO_STATE_CONNECTED_LC3`` is added for an established LC3-SWB link, alongside the existing ``ESP_HF_AUDIO_STATE_CONNECTED`` (CVSD) and ``ESP_HF_AUDIO_STATE_CONNECTED_MSBC`` values.
+
+    - :component_file:`/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h`
+
+        - ``esp_hf_ag_set_codec()`` now takes ``esp_hf_codec_mode_t``. Pass ``ESP_HF_CODEC_CVSD``, ``ESP_HF_CODEC_MSBC``, ``ESP_HF_CODEC_LC3``, or ``ESP_HF_CODEC_NONE`` to restore the stack default.
+
+        - ``ESP_HF_WBS_RESPONSE_EVT`` (``wbs_rep``): field ``codec`` is now ``esp_hf_codec_mode_t``. The field name ``codec`` is unchanged. A ``status`` field (``esp_bt_status_t``) is added to report whether the request succeeded.
+
+        - ``ESP_HF_BCS_RESPONSE_EVT`` (``bcs_rep``): field ``mode`` is now ``esp_hf_codec_mode_t``. The field name ``mode`` is unchanged.
+
+    Suggested replacements:
+
+    .. code-block:: c
+
+        // Before
+        esp_hf_ag_set_codec(bda, ESP_HF_WBS_YES);
+        if (param->bcs_rep.mode == ESP_HF_WBS_NO) { /* CVSD */ }
+
+        // After
+        esp_hf_ag_set_codec(bda, ESP_HF_CODEC_MSBC);
+        if (param->bcs_rep.mode == ESP_HF_CODEC_CVSD) { /* CVSD */ }
+        else if (param->bcs_rep.mode == ESP_HF_CODEC_LC3) { /* LC3-SWB */ }
--- a/docs/en/migration-guides/release-6.x/6.2/index.rst
+++ b/docs/en/migration-guides/release-6.x/6.2/index.rst
@@ -6,5 +6,6 @@ Migration from 6.1 to 6.2
 .. toctree::
    :maxdepth: 1

+    :SOC_BT_CLASSIC_SUPPORTED: bluetooth-classic
    security
    system
--- a/docs/zh_CN/migration-guides/release-6.x/6.2/bluetooth-classic.rst
+++ b/docs/zh_CN/migration-guides/release-6.x/6.2/bluetooth-classic.rst
@@ -0,0 +1,66 @@
+经典蓝牙
+========
+
+:link_to_translation:`en:[English]`
+
+Bluedroid
+---------
+
+    以下 Bluedroid API 已变更：
+
+    - :component_file:`/bt/host/bluedroid/api/include/api/esp_hf_defs.h`
+
+        - 类型 ``esp_hf_wbs_config_t`` 已替换为 ``esp_hf_codec_mode_t``，新的公开类型表示协商得到的编解码（CVSD， mSBC 或 LC3-SWB），而不再是“是否开启宽带语音”的开关。``esp_hf_wbs_config_t`` 保留为 ``esp_hf_codec_mode_t`` 的废弃别名。
+
+        - 枚举名已重命名，数值 0 / 1 / 2 保持不变。旧的 ``ESP_HF_WBS_*`` 名称仍作为宏别名指向新枚举：
+
+            .. list-table::
+               :header-rows: 1
+               :widths: 40 40 20
+
+               * - 旧枚举
+                 - 新枚举
+                 - 取值
+               * - ``ESP_HF_WBS_NONE``
+                 - ``ESP_HF_CODEC_NONE``
+                 - 0
+               * - ``ESP_HF_WBS_NO``
+                 - ``ESP_HF_CODEC_CVSD``
+                 - 1
+               * - ``ESP_HF_WBS_YES``
+                 - ``ESP_HF_CODEC_MSBC``
+                 - 2
+               * - —
+                 - ``ESP_HF_CODEC_LC3``
+                 - 3
+
+        - 现有对 ``ESP_HF_WBS_NO`` / ``ESP_HF_WBS_YES`` 的 ``switch`` 或比较仍可编译。新代码请使用新名称。
+
+        - ``ESP_HF_CODEC_NONE`` 表示尚未协商编解码，或将偏好重置为协议栈默认值，并不表示不能使用 CVSD。``ESP_HF_CODEC_CVSD`` 表示当前选中的是窄带编解码，可能是对端不支持宽带、未开启宽带，或从 mSBC / LC3 回退。
+
+        - ``ESP_HF_CODEC_LC3`` 为新增取值。若代码用编解码值去下标访问只有 3 项的表，需补充 LC3 项或增加 default 分支。
+
+        - 不要把 ``esp_hf_codec_mode_t`` 当作能力位图。对端编解码能力通过 ``ESP_HF_BAC_RESPONSE_EVT`` 中的 ``ESP_HF_CODEC_CAP_CVSD`` / ``ESP_HF_CODEC_CAP_MSBC`` / ``ESP_HF_CODEC_CAP_LC3`` 单独上报。
+
+        - 音频连接状态新增 ``ESP_HF_AUDIO_STATE_CONNECTED_LC3``，用于表示已建立的 LC3-SWB 链路，与现有的 ``ESP_HF_AUDIO_STATE_CONNECTED`` （CVSD）和 ``ESP_HF_AUDIO_STATE_CONNECTED_MSBC`` 并列。
+
+    - :component_file:`/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h`
+
+        - ``esp_hf_ag_set_codec()`` 的参数类型改为 ``esp_hf_codec_mode_t``。传入 ``ESP_HF_CODEC_CVSD``、``ESP_HF_CODEC_MSBC``、``ESP_HF_CODEC_LC3``，或 ``ESP_HF_CODEC_NONE`` 以恢复协议栈默认偏好。
+
+        - ``ESP_HF_WBS_RESPONSE_EVT`` （``wbs_rep``）：字段 ``codec`` 的类型改为 ``esp_hf_codec_mode_t``。字段名 ``codec`` 未改。新增 ``status`` 字段（``esp_bt_status_t``），用于报告请求是否成功。
+
+        - ``ESP_HF_BCS_RESPONSE_EVT`` （``bcs_rep``）：字段 ``mode`` 的类型改为 ``esp_hf_codec_mode_t``。字段名 ``mode`` 未改。
+
+    建议替换：
+
+    .. code-block:: c
+
+        // 修改前
+        esp_hf_ag_set_codec(bda, ESP_HF_WBS_YES);
+        if (param->bcs_rep.mode == ESP_HF_WBS_NO) { /* CVSD */ }
+
+        // 修改后
+        esp_hf_ag_set_codec(bda, ESP_HF_CODEC_MSBC);
+        if (param->bcs_rep.mode == ESP_HF_CODEC_CVSD) { /* CVSD */ }
+        else if (param->bcs_rep.mode == ESP_HF_CODEC_LC3) { /* LC3-SWB */ }
--- a/docs/zh_CN/migration-guides/release-6.x/6.2/index.rst
+++ b/docs/zh_CN/migration-guides/release-6.x/6.2/index.rst
@@ -6,5 +6,6 @@
 .. toctree::
    :maxdepth: 1

+    :SOC_BT_CLASSIC_SUPPORTED: bluetooth-classic
    security
    system