Merge branch 'docs/migration_guides_bt_classic' into 'master'

docs: Add SoC conditional flag for Bluetooth Classic in migration guides Closes DOC-11554 See merge request espressif/esp-idf!41440
2025-10-02 10:00:57 +02:00 · 2025-08-26 14:37:45 +08:00
parent cc37708f98 222560ade4
commit 14f2d9e6cf
18 changed files with 60 additions and 30 deletions
--- a/docs/conf_common.py
+++ b/docs/conf_common.py
@@ -25,6 +25,7 @@ BT_DOCS = [
    'api-reference/bluetooth/bt_vhci.rst',
    'api-reference/bluetooth/controller_vhci.rst',
    'api-reference/bluetooth/index.rst',
+    'migration-guides/release-5.x/5.4/bt_common.rst',
 ]

 BLE_DOCS = [
@@ -74,6 +75,10 @@ CLASSIC_BT_DOCS = [
    'api-reference/bluetooth/esp_spp.rst',
    'api-reference/bluetooth/esp_gap_bt.rst',
    'migration-guides/release-5.x/5.0/bluetooth-classic.rst',
+    'migration-guides/release-5.x/5.2/bluetooth-classic.rst',
+    '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',
 ]

 BLUFI_DOCS = ['api-guides/ble/blufi.rst', 'api-reference/bluetooth/esp_blufi.rst']
@@ -90,6 +95,8 @@ WIFI_DOCS = [
    'api-reference/provisioning/provisioning.rst',
    'api-reference/provisioning/wifi_provisioning.rst',
    'migration-guides/release-5.x/5.2/wifi.rst',
+    'migration-guides/release-5.x/5.4/wifi.rst',
+    'migration-guides/release-5.x/5.5/wifi.rst',
 ]

 IEEE802154_DOCS = ['migration-guides/release-5.x/5.1/ieee802154.rst', 'migration-guides/release-5.x/5.2/ieee802154.rst']
--- a/docs/en/migration-guides/release-5.x/5.2/index.rst
+++ b/docs/en/migration-guides/release-5.x/5.2/index.rst
@@ -13,4 +13,4 @@ Migration from 5.1 to 5.2
    storage
    system
    :SOC_WIFI_SUPPORTED: wifi
-    bluetooth-classic
+    :SOC_BT_CLASSIC_SUPPORTED: bluetooth-classic
--- a/docs/en/migration-guides/release-5.x/5.3/index.rst
+++ b/docs/en/migration-guides/release-5.x/5.3/index.rst
@@ -6,7 +6,7 @@ Migration from 5.2 to 5.3
 .. toctree::
    :maxdepth: 1

-    bluetooth-classic
+    :SOC_BT_CLASSIC_SUPPORTED: bluetooth-classic
    gcc
    peripherals
    protocols
--- a/docs/en/migration-guides/release-5.x/5.4/bluetooth-classic.rst
+++ b/docs/en/migration-guides/release-5.x/5.4/bluetooth-classic.rst
@@ -12,8 +12,3 @@ Bluedroid
    - :component_file:`/bt/host/bluedroid/api/include/api/esp_sdp_api.h`

        - Field ``user2_ptr_len`` and ``user2_ptr`` is deprecated in structure ``esp_bluetooth_sdp_hdr_overlay_t``, since they are not used in SDP record creation or searching.
-
-Bluetooth Common APIs
---------------------
-
-.. include:: ./bt_common.rst
--- a/docs/en/migration-guides/release-5.x/5.4/bt_common.rst
+++ b/docs/en/migration-guides/release-5.x/5.4/bt_common.rst
@@ -1,7 +1,16 @@
+Bluetooth Common
+====================
+
+:link_to_translation:`zh_CN:[中文]`
+
+The following Bluetooth Common header declarations have been moved:
+
 .. only:: esp32

    - :component_file:`/bt/include/esp32/include/esp_bt.h`

+        - Move the declarations of ``esp_wifi_bt_power_domain_on`` and ``esp_wifi_bt_power_domain_off`` from ``esp_bt.h`` to ``esp_phy_init.h``, since they belong to component ``esp_phy`` and are not expected to be used by customer.
+
 .. only:: esp32c3 or esp32s3

    - :component_file:`/bt/include/esp32c3/include/esp_bt.h`
--- a/docs/en/migration-guides/release-5.x/5.4/index.rst
+++ b/docs/en/migration-guides/release-5.x/5.4/index.rst
@@ -8,7 +8,8 @@ Migration from 5.3 to 5.4

    gcc
    system
-    bluetooth-classic
+    :SOC_BT_CLASSIC_SUPPORTED: bluetooth-classic
+    :SOC_BT_SUPPORTED: bt_common
    storage
-    wifi
+    :SOC_WIFI_SUPPORTED: wifi
    protocols
--- a/docs/en/migration-guides/release-5.x/5.5/index.rst
+++ b/docs/en/migration-guides/release-5.x/5.5/index.rst
@@ -10,4 +10,4 @@ Migration from 5.4 to 5.5
    system
    peripherals
    protocols
-    wifi
+    :SOC_WIFI_SUPPORTED: wifi
--- a/docs/en/migration-guides/release-6.x/6.0/index.rst
+++ b/docs/en/migration-guides/release-6.x/6.0/index.rst
@@ -6,7 +6,7 @@ Migration from 5.5 to 6.0
 .. toctree::
    :maxdepth: 1

-    bluetooth-classic
+    :SOC_BT_CLASSIC_SUPPORTED: bluetooth-classic
    build-system
    peripherals
    provisioning
--- a/docs/zh_CN/migration-guides/release-5.x/5.2/index.rst
+++ b/docs/zh_CN/migration-guides/release-5.x/5.2/index.rst
@@ -13,4 +13,4 @@
    storage
    system
    :SOC_WIFI_SUPPORTED: wifi
-    bluetooth-classic
+    :SOC_BT_CLASSIC_SUPPORTED: bluetooth-classic
--- a/docs/zh_CN/migration-guides/release-5.x/5.3/index.rst
+++ b/docs/zh_CN/migration-guides/release-5.x/5.3/index.rst
@@ -6,7 +6,7 @@
 .. toctree::
    :maxdepth: 1

-    bluetooth-classic
+    :SOC_BT_CLASSIC_SUPPORTED: bluetooth-classic
    gcc
    peripherals
    protocols
--- a/docs/zh_CN/migration-guides/release-5.x/5.4/bluetooth-classic.rst
+++ b/docs/zh_CN/migration-guides/release-5.x/5.4/bluetooth-classic.rst
@@ -12,8 +12,3 @@ Bluedroid
    - :component_file:`/bt/host/bluedroid/api/include/api/esp_sdp_api.h`

        - 结构体 ``esp_bluetooth_sdp_hdr_overlay_t`` 中的字段 ``user2_ptr_len`` 和 ``user2_ptr`` 被弃用，因为 SDP 的 API 或者事件中不会用到该字段。
-
-Bluetooth Common APIs
---------------------
-
-.. include:: ./bt_common.rst
--- a/docs/zh_CN/migration-guides/release-5.x/5.4/bt_common.rst
+++ b/docs/zh_CN/migration-guides/release-5.x/5.4/bt_common.rst
@@ -1,7 +1,16 @@
+蓝牙通用
+===================
+
+:link_to_translation:`en:[English]`
+
+以下属于蓝牙通用的头文件声明已移动：
+
 .. only:: esp32

    - :component_file:`/bt/include/esp32/include/esp_bt.h`

+        - 将 ``esp_wifi_bt_power_domain_on`` 和 ``esp_wifi_bt_power_domain_off`` 的声明从 ``esp_bt.h`` 移至 ``esp_phy_init.h`` ， 因为它们属于组件 ``esp_phy`` 并且不希望被客户使用。
+
 .. only:: esp32c3 or esp32s3

    - :component_file:`/bt/include/esp32c3/include/esp_bt.h`
--- a/docs/zh_CN/migration-guides/release-5.x/5.4/index.rst
+++ b/docs/zh_CN/migration-guides/release-5.x/5.4/index.rst
@@ -8,7 +8,8 @@

    gcc
    system
-    bluetooth-classic
+    :SOC_BT_CLASSIC_SUPPORTED: bluetooth-classic
+    :SOC_BT_SUPPORTED: bt_common
    storage
-    wifi
+    :SOC_WIFI_SUPPORTED: wifi
    protocols
--- a/docs/zh_CN/migration-guides/release-5.x/5.4/protocols.rst
+++ b/docs/zh_CN/migration-guides/release-5.x/5.4/protocols.rst
@@ -1 +1,14 @@
-.. include:: ../../../../en/migration-guides/release-5.x/5.4/protocols.rst
+协议
+=========
+
+:link_to_translation:`en:[English]`
+
+HTTPS 服务器
+---------------
+
+证书选择钩子
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+在 ESP HTTPS 服务器中，如需启用证书选择钩子功能，现在需要启用 :ref:`CONFIG_ESP_HTTPS_SERVER_CERT_SELECT_HOOK`，而不是 :ref:`CONFIG_ESP_TLS_SERVER_CERT_SELECT_HOOK`。
+
+新的 :ref:`CONFIG_ESP_HTTPS_SERVER_CERT_SELECT_HOOK` 选项会自动选择 :ref:`CONFIG_ESP_TLS_SERVER_CERT_SELECT_HOOK`。
--- a/docs/zh_CN/migration-guides/release-5.x/5.5/index.rst
+++ b/docs/zh_CN/migration-guides/release-5.x/5.5/index.rst
@@ -10,4 +10,4 @@
    system
    peripherals
    protocols
-    wifi
+    :SOC_WIFI_SUPPORTED: wifi
--- a/docs/zh_CN/migration-guides/release-5.x/5.5/peripherals.rst
+++ b/docs/zh_CN/migration-guides/release-5.x/5.5/peripherals.rst
@@ -1,17 +1,17 @@
-Peripherals
+外设
 ===========

-:link_to_translation:`zh_CN:[中文]`
+:link_to_translation:`en:[English]`

 .. only:: SOC_TOUCH_SENSOR_SUPPORTED

-    Touch Sensor
+    触摸传感器
    ------------

-    电容式触摸传感器的驱动已更新为 :doc:`Capacitive Touch Sensor <../../../api-reference/peripherals/cap_touch_sens>`.
+    电容式触摸传感器的驱动已更新为 :doc:`Capacitive Touch Sensor <../../../api-reference/peripherals/cap_touch_sens>`。

-    - The new driver is in ``esp_driver_touch_sens`` component and the include path is ``driver/touch_sens.h``.
-    - The legacy driver is still available in the previous include path ``driver/touch_sensor.h``.
+    - 新的驱动位于 ``esp_driver_touch_sens`` 组件中，包含路径为 ``driver/touch_sens.h``。
+    - 旧版驱动仍然可用，其包含路径为 ``driver/touch_sensor.h``。

    尽管我们推荐使用新的驱动 API， 旧版驱动仍然可用，其头文件引用路径为 ``driver/touch_sensor.h``。但是，引用 ``driver/touch_sensor.h`` 会默认触发如下编译警告，可通过配置 Kconfig 选项 :ref:`CONFIG_TOUCH_SUPPRESS_DEPRECATE_WARN` 关闭该警告。

--- a/docs/zh_CN/migration-guides/release-6.x/6.0/bluetooth-classic.rst
+++ b/docs/zh_CN/migration-guides/release-6.x/6.0/bluetooth-classic.rst
@@ -1,4 +1,4 @@
-Bluetooth Classic
+经典蓝牙
 =================

 :link_to_translation:`en:[English]`
--- a/docs/zh_CN/migration-guides/release-6.x/6.0/index.rst
+++ b/docs/zh_CN/migration-guides/release-6.x/6.0/index.rst
@@ -6,7 +6,7 @@
 .. toctree::
    :maxdepth: 1

-    bluetooth-classic
+    :SOC_BT_CLASSIC_SUPPORTED: bluetooth-classic
    build-system
    peripherals
    provisioning