Merge branch 'docs/reorganize_bluetooth_api_guides' into 'master'

docs(ble): Reorganized the bluetooth API guide structure

See merge request espressif/esp-idf!32131

docs/conf_common.py

@@ -16,21 +16,23 @@ from esp_docs.conf_docs import *  # noqa: F403,F401
 if os.environ.get('IDF_PATH') is None:
     raise RuntimeError('IDF_PATH should be set, run export.sh before building docs')
 
-BT_DOCS = ['api-guides/bluetooth.rst',
-           'api-reference/bluetooth/bt_le.rst',
-           'api-reference/bluetooth/esp_bt_defs.rst',
+BT_DOCS = ['api-reference/bluetooth/esp_bt_defs.rst',
            'api-reference/bluetooth/esp_bt_device.rst',
            'api-reference/bluetooth/esp_bt_main.rst',
            'api-reference/bluetooth/bt_common.rst',
            'api-reference/bluetooth/controller_vhci.rst',
-           'api-reference/bluetooth/esp_gap_ble.rst',
-           'api-reference/bluetooth/esp_gatt_defs.rst',
-           'api-reference/bluetooth/esp_gatts.rst',
-           'api-reference/bluetooth/esp_gattc.rst',
-           'api-reference/bluetooth/index.rst',
-           'api-reference/bluetooth/nimble/index.rst']
+           'api-reference/bluetooth/index.rst']
+
+BLE_DOCS = ['api-reference/bluetooth/bt_le.rst',
+            'api-guides/ble/index.rst',
+            'api-guides/ble/overview.rst',
+            'api-reference/bluetooth/esp_gap_ble.rst',
+            'api-reference/bluetooth/esp_gatt_defs.rst',
+            'api-reference/bluetooth/esp_gatts.rst',
+            'api-reference/bluetooth/esp_gattc.rst',
+            'api-reference/bluetooth/nimble/index.rst',
+            'migration-guides/release-5.x/5.0/bluetooth-low-energy.rst']
 
-BLE_DOCS = ['migration-guides/release-5.x/5.0/bluetooth-low-energy.rst']
 
 BLE_MESH_DOCS = ['api-guides/esp-ble-mesh/ble-mesh-index.rst',
                  'api-guides/esp-ble-mesh/ble-mesh-feature-list.rst',
@@ -39,7 +41,9 @@ BLE_MESH_DOCS = ['api-guides/esp-ble-mesh/ble-mesh-index.rst',
                  'api-guides/esp-ble-mesh/ble-mesh-faq.rst',
                  'api-reference/bluetooth/esp-ble-mesh.rst']
 
-CLASSIC_BT_DOCS = ['api-reference/bluetooth/classic_bt.rst',
+CLASSIC_BT_DOCS = ['api-guides/classic-bt/index.rst',
+                   'api-guides/classic-bt/overview.rst',
+                   'api-reference/bluetooth/classic_bt.rst',
                    'api-reference/bluetooth/esp_a2dp.rst',
                    'api-reference/bluetooth/esp_avrc.rst',
                    'api-reference/bluetooth/esp_hidd.rst',
@@ -53,7 +57,7 @@ CLASSIC_BT_DOCS = ['api-reference/bluetooth/classic_bt.rst',
                    'api-reference/bluetooth/esp_gap_bt.rst',
                    'migration-guides/release-5.x/5.0/bluetooth-classic.rst']
 
-BLUFI_DOCS = ['api-guides/blufi.rst',
+BLUFI_DOCS = ['api-guides/ble/blufi.rst',
               'api-reference/bluetooth/esp_blufi.rst']
 
 WIFI_DOCS = ['api-guides/low-power-mode/low-power-mode-wifi.rst',

docs/en/api-guides/ble/blufi.rst

@@ -1,10 +1,10 @@
 BluFi
-^^^^^
+^^^^^^
 
-:link_to_translation:`zh_CN:[中文]`
+:link_to_translation:`en:[English]`
 
 Overview
---------
+----------
 
 The BluFi for {IDF_TARGET_NAME} is a Wi-Fi network configuration function via Bluetooth channel. It provides a secure protocol to pass Wi-Fi configuration and credentials to {IDF_TARGET_NAME}. Using this information, {IDF_TARGET_NAME} can then connect to an AP or establish a SoftAP.
 
@@ -13,7 +13,7 @@ Fragmenting, data encryption, and checksum verification in the BluFi layer are t
 You can customize symmetric encryption, asymmetric encryption, and checksum support customization. Here we use the DH algorithm for key negotiation, 128-AES algorithm for data encryption, and CRC16 algorithm for checksum verification.
 
 The BluFi Flow
----------------
+----------------
 
 The BluFi networking flow includes the configuration of the SoftAP and Station.
 
@@ -46,7 +46,7 @@ The following uses Station as an example to illustrate the core parts of the pro
     2. The data lengths before and after symmetric encryption/decryption must stay the same. It also supports in-place encryption and decryption.
 
 The Flow Chart of BluFi
---------------------------
+-------------------------
 
 .. seqdiag::
     :caption: BluFi Flow Chart
@@ -75,7 +75,7 @@ The Flow Chart of BluFi
 .. _frame_formats:
 
 The Frame Formats Defined in BluFi
------------------------------------
+------------------------------------
 
 The frame formats for the communication between the mobile phone App and {IDF_TARGET_NAME} are defined as follows:
 
@@ -431,7 +431,7 @@ The format of ACK Frame:
    The **CheckSum** field takes two bytes, which is used to check "sequence + data length + clear text data".
 
 The Security Implementation of {IDF_TARGET_NAME}
-------------------------------------------------
+--------------------------------------------------
 
 1. Securing Data
 
@@ -482,7 +482,7 @@ The data to be encrypted and decrypted must be in the same length. The IV8 is an
 This function is used to compute CheckSum and return a value of CheckSum. BluFi uses the returned value to compare the CheckSum of the frame.
 
 GATT Related Instructions
--------------------------
+----------------------------
 
 UUID
 >>>>>

docs/en/api-guides/ble/index.rst

@@ -0,0 +1,23 @@
+#######################
+Bluetooth® Low Energy
+#######################
+
+:link_to_translation:`zh_CN:[中文]`
+
+*********
+Overview
+*********
+.. toctree::
+   :maxdepth: 1
+
+   overview
+
+**********
+Profile
+**********
+
+.. toctree::
+   :maxdepth: 2
+
+   :SOC_BLE_MESH_SUPPORTED: ../esp-ble-mesh/ble-mesh-index
+   :SOC_BLUFI_SUPPORTED: blufi

docs/en/api-guides/ble/overview.rst

@@ -1,9 +1,9 @@
-Bluetooth® Overview
-===================
+Introduction
+=============
 
 :link_to_translation:`zh_CN:[中文]`
 
-This document provides an architecture overview of the Bluetooth stack in ESP-IDF and some quick links to related documents and application examples.
+This document provides an architecture overview of the Bluetooth Low Energy (Bluetooth LE) stack in ESP-IDF and some quick links to related documents and application examples.
 
 .. only:: esp32
 
@@ -17,36 +17,36 @@ This document provides an architecture overview of the Bluetooth stack in ESP-ID
 
     {IDF_TARGET_NAME} supports Bluetooth 5.0 (LE) and is certified for Bluetooth LE 5.3.
 
-The Bluetooth stack in ESP-IDF is a layered architecture that enables Bluetooth functionality on {IDF_TARGET_NAME} chip series. The table below shows its architecture.
+The Bluetooth LE stack in ESP-IDF is a layered architecture that enables Bluetooth functionality on {IDF_TARGET_NAME} chip series. The table below shows its architecture.
 
 .. only:: esp32 or esp32s3 or esp32c3 or esp32c6
 
-    .. figure:: ../../_static/bluetooth-architecture.png
+    .. figure:: ../../../_static/bluetooth-architecture.png
         :align: center
         :scale: 90%
-        :alt: {IDF_TARGET_NAME} Bluetooth Stack Architecture
+        :alt: {IDF_TARGET_NAME} Bluetooth LE Stack Architecture
 
-        {IDF_TARGET_NAME} Bluetooth Stack Architecture
+        {IDF_TARGET_NAME} Bluetooth LE Stack Architecture
 
 .. only:: esp32c2
 
-    .. figure:: ../../_static/bluetooth-architecture-no-ble-mesh.png
+    .. figure:: ../../../_static/bluetooth-architecture-no-ble-mesh.png
         :align: center
         :scale: 90%
-        :alt: {IDF_TARGET_NAME} Bluetooth Stack Architecture
+        :alt: {IDF_TARGET_NAME} Bluetooth LE Stack Architecture
 
-        {IDF_TARGET_NAME} Bluetooth Stack Architecture
+        {IDF_TARGET_NAME} Bluetooth LE Stack Architecture
 
 .. only:: esp32h2
 
-    .. figure:: ../../_static/bluetooth-architecture-no-blufi.png
+    .. figure:: ../../../_static/bluetooth-architecture-no-blufi.png
         :align: center
         :scale: 90%
-        :alt: {IDF_TARGET_NAME} Bluetooth Stack Architecture
+        :alt: {IDF_TARGET_NAME} Bluetooth LE Stack Architecture
 
-        {IDF_TARGET_NAME} Bluetooth Stack Architecture
+        {IDF_TARGET_NAME} Bluetooth LE Stack Architecture
 
-The table below shows whether the Bluetooth modules are supported in a specific chip series.
+The table below shows whether the Bluetooth LE modules are supported in a specific chip series.
 
 .. list-table::
     :width: 100%
@@ -110,7 +110,7 @@ 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.
 
-- :doc:`API reference <../api-reference/bluetooth/controller_vhci>`
+- :doc:`API reference <../../api-reference/bluetooth/controller_vhci>`
 - :example:`Application examples <bluetooth/hci>`
 
 
@@ -129,7 +129,7 @@ There are two hosts, ESP-Bluedroid and ESP-NimBLE. The major difference between
 ESP-Bluedroid
 ^^^^^^^^^^^^^
 
-ESP-Bluedroid is a modified version of the native Android Bluetooth stack, Bluedroid. It consists of two layers: the Bluetooth Upper Layer (BTU) and the Bluetooth Transport Controller layer (BTC). The BTU layer is responsible for processing bottom layer Bluetooth protocols such as L2CAP, GATT/ATT, SMP, GAP, and other profiles. The BTU layer provides an interface prefixed with "bta". The BTC layer is mainly responsible for providing a supported interface, prefixed with "esp", to the application layer, processing GATT-based profiles and handling miscellaneous tasks. All the APIs are located in the ESP_API layer. Developers should use the Bluetooth APIs prefixed with "esp".
+ESP-Bluedroid is a modified version of the native Android Bluetooth stack, Bluedroid. It consists of two layers: the Bluetooth Upper Layer (BTU) and the Bluetooth Transport Controller layer (BTC). The BTU layer is responsible for processing bottom layer Bluetooth protocols such as L2CAP, GATT/ATT, SMP, GAP, and other profiles. The BTU layer provides an interface prefixed with "bta". The BTC layer is mainly responsible for providing a supported interface, prefixed with "esp", to the application layer, processing GATT-based profiles and handling miscellaneous tasks. All the APIs are located in the ESP_API layer. Developers should use the Bluetooth Low Energy APIs prefixed with "esp".
 
 .. only:: esp32
 
@@ -141,15 +141,17 @@ ESP-Bluedroid is a modified version of the native Android Bluetooth stack, Blued
 
 - API references
 
-  - :doc:`../api-reference/bluetooth/bt_common`
-  - :doc:`Bluetooth LE <../api-reference/bluetooth/bt_le>`
+  - :doc:`../../api-reference/bluetooth/bt_common`
+  - :doc:`Bluetooth LE <../../api-reference/bluetooth/bt_le>`
 
-  .. only:: esp32
+.. only:: esp32
 
-    - :doc:`../api-reference/bluetooth/classic_bt`
+    - :example:`Bluetooth LE 4.2 Application Examples <bluetooth/bluedroid/ble>`
 
-- :example:`Application examples <bluetooth/bluedroid>`
+.. only:: not esp32
 
+    - :example:`Bluetooth LE 4.2 Application Examples <bluetooth/bluedroid/ble>`
+    - :example:`Bluetooth LE 5.0 Application Examples <bluetooth/bluedroid/ble_50>`
 
 ESP-NimBLE
 ^^^^^^^^^^
@@ -162,7 +164,7 @@ ESP-NimBLE supports Bluetooth LE only. Classic Bluetooth is not supported.
 - API references
 
   - `NimBLE API references <https://mynewt.apache.org/latest/network/ble_hs/ble_hs.html>`__
-  - :doc:`ESP-NimBLE API references for initialization <../api-reference/bluetooth/nimble/index>`
+  - :doc:`ESP-NimBLE API references for initialization <../../api-reference/bluetooth/nimble/index>`
 
 - :example:`Application examples <bluetooth/nimble>`
 
@@ -180,7 +182,7 @@ Above the host stacks are the profile implementations by Espressif and some comm
 
   Built on top of Zephyr Bluetooth Mesh stack, the ESP-BLE-MESH implementation supports device provisioning and node control. It also supports such node features as Proxy, Relay, Low power and Friend.
 
-  - :doc:`ESP-BLE-MESH documentation <esp-ble-mesh/ble-mesh-index>`: feature list, get started, architecture, description of application examples, frequently asked questions, etc.
+  - :doc:`ESP-BLE-MESH documentation <../esp-ble-mesh/ble-mesh-index>`: feature list, get started, architecture, description of application examples, frequently asked questions, etc.
   - :example:`Application examples <bluetooth/esp_ble_mesh>`
 
 
@@ -198,4 +200,4 @@ Above the host stacks are the profile implementations by Espressif and some comm
 Applications
 ------------
 
-At the uppermost layer are applications. You can build your own applications on top of the ESP-Bluedroid and ESP-NimBLE stacks, leveraging the provided APIs and profiles to create Bluetooth-enabled applications tailored to specific use cases.
+At the uppermost layer are applications. You can build your own applications on top of the ESP-Bluedroid and ESP-NimBLE stacks, leveraging the provided APIs and profiles to create Bluetooth LE-enabled applications tailored to specific use cases.

docs/en/api-guides/classic-bt/index.rst

@@ -0,0 +1,13 @@
+#######################
+Bluetooth® Classic
+#######################
+
+:link_to_translation:`zh_CN:[中文]`
+
+*********
+Overview
+*********
+.. toctree::
+   :maxdepth: 2
+
+   overview

docs/en/api-guides/classic-bt/overview.rst

@@ -0,0 +1,80 @@
+Introduction
+=============
+
+:link_to_translation:`zh_CN:[中文]`
+
+This document provides an architecture overview of the Bluetooth Classic stack in ESP-IDF and some quick links to related documents and application examples.
+
+.. only:: esp32
+
+    {IDF_TARGET_NAME} supports Dual-Mode Bluetooth 4.2.
+
+The Bluetooth Classic stack in ESP-IDF is a layered architecture that enables Bluetooth functionality on {IDF_TARGET_NAME} chip series. The table below shows its architecture.
+
+.. only:: esp32
+
+    .. 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
+
+The table below shows whether the Bluetooth Classic Controller are supported in a specific chip series.
+
+.. list-table::
+    :width: 100%
+    :widths: auto
+    :header-rows: 1
+
+    * - Chip Series
+      - Controller
+    * - ESP32
+      - Y
+    * - ESP32-S2
+      - \–
+    * - ESP32-S3
+      - \–
+    * - ESP32-C2
+      - \–
+    * - ESP32-C3
+      - \-
+    * - ESP32-C6
+      - \-
+    * - ESP32-H2
+      - \-
+
+The following sections briefly describe each layer and provide quick links to the related documents and application examples.
+
+
+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.
+
+- :doc:`API reference <../../api-reference/bluetooth/controller_vhci>`
+- :example:`Application examples <bluetooth/hci/controller_hci_uart_esp32>`
+
+
+Hosts
+-----
+
+There is one host, ESP-Bluedroid, supporting Classic Bluetooth in IDF.
+
+
+ESP-Bluedroid
+^^^^^^^^^^^^^
+
+ESP-Bluedroid is a modified version of the native Android Bluetooth stack, Bluedroid. It consists of two layers: the Bluetooth Upper Layer (BTU) and the Bluetooth Transport Controller layer (BTC). The BTU layer is responsible for processing bottom layer Bluetooth protocols such as L2CAP and other profiles. The BTU layer provides an interface prefixed with "bta". The BTC layer is mainly responsible for providing a supported interface, prefixed with "esp", to the application layer and handling miscellaneous tasks. All the APIs are located in the ESP_API layer. Developers should use the Classic Bluetooth APIs prefixed with "esp".
+
+- API references
+
+  - :doc:`../../api-reference/bluetooth/bt_common`
+  - :doc:`../../api-reference/bluetooth/classic_bt`
+- :example:`Application examples <bluetooth/bluedroid/classic_bt>`
+
+
+Applications
+------------
+
+At the uppermost layer are applications. You can build your own applications on top of the ESP-Bluedroid stacks, leveraging the provided APIs and profiles to create Bluetooth Classic applications tailored to specific use cases.

docs/en/api-guides/esp-ble-mesh/ble-mesh-architecture.rst

@@ -1,5 +1,5 @@
-ESP-BLE-MESH Architecture
-=========================
+Architecture
+=============
 
 :link_to_translation:`zh_CN:[中文]`
 

docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst

@@ -1,5 +1,5 @@
-ESP-BLE-MESH FAQ
-================
+FAQ
+=====
 
 :link_to_translation:`zh_CN:[中文]`
 
@@ -532,7 +532,7 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m
 
     .. only:: esp32
 
-        The :doc:`ESP32-DevKitC <../../hw-reference/esp32/get-started-devkitc>` board without PSRAM can run properly but the throughput of it is low since it has no PSRAM. When Bluetooth and Wi-Fi coexist, the throughput of ESP32-DevKitC with PSRAM can be stabilized to more than 1 Mbps.
+        The :doc:`ESP32-DevKitC <../../../hw-reference/esp32/get-started-devkitc>` board without PSRAM can run properly but the throughput of it is low since it has no PSRAM. When Bluetooth and Wi-Fi coexist, the throughput of ESP32-DevKitC with PSRAM can be stabilized to more than 1 Mbps.
 
     Some configurations in menuconfig shall be enabled to support PSRAM.
 

docs/en/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst

@@ -1,5 +1,5 @@
-ESP-BLE-MESH Feature List
-=========================
+Feature List
+=============
 
 :link_to_translation:`zh_CN:[中文]`
 

docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst

@@ -25,8 +25,8 @@ ESP-BLE-MESH is implemented and certified based on the latest Mesh Profile v1.0.
 
 .. _getting-started-with-ble-mesh:
 
-Getting Started with ESP-BLE-MESH
-=================================
+Getting Started
+=================
 
 This section is intended to help you get started with ESP-BLE-MESH for the hardware based on the {IDF_TARGET_NAME} chip by Espressif.
 
@@ -210,8 +210,8 @@ The following screenshot shows different board with different color on.
 
 .. _esp-ble-mesh-examples:
 
-ESP-BLE-MESH Examples
-=====================
+Examples
+=========
 
 * :example_file:`OnOff Server <bluetooth/esp_ble_mesh/onoff_models/onoff_server/tutorial/BLE_Mesh_Node_OnOff_Server_Example_Walkthrough.md>` - shows the use of ESP-BLE-MESH as a node having a Configuration Server model and a Generic OnOff Server model. A ESP-BLE-MESH Provisioner can then provision the unprovisioned device and control a RGB LED representing on/off state, see :example:`example code <bluetooth/esp_ble_mesh/onoff_models/onoff_server>`.
 
@@ -230,15 +230,15 @@ ESP-BLE-MESH Examples
 
 .. _esp-ble-mesh-demo-videos:
 
-ESP-BLE-MESH Demo Videos
-========================
+Demo Videos
+============
 
 * `Espressif Fast Provisioning using ESP-BLE-MESH App <https://dl.espressif.com/BLE/public/ESP32_BLE_Mesh_Fast_Provision.mp4>`_
 * `Espressif ESP-BLE-MESH and Wi-Fi Coexistence <https://dl.espressif.com/BLE/public/ESP_BLE_MESH_WIFI_Coexistence.mp4>`_
 
 
-ESP-BLE-MESH FAQ
-================
+FAQ
+====
 
 * :ref:`ble-mesh-faq-provisioner-development`
 * :ref:`ble-mesh-faq-node-development`

docs/en/api-guides/esp-ble-mesh/ble-mesh-terminology.rst

@@ -1,5 +1,5 @@
-ESP-BLE-MESH Terminology
-========================
+Terminology
+============
 
 :link_to_translation:`zh_CN:[中文]`
 

docs/en/api-guides/index.rst

@@ -7,8 +7,9 @@ API Guides
 
    app_trace
    startup
-   :SOC_BLUFI_SUPPORTED: blufi
-   :SOC_BT_SUPPORTED: bluetooth
+   :SOC_BT_CLASSIC_SUPPORTED: classic-bt/index
+   :SOC_BLE_SUPPORTED: ble/index
+   :SOC_BLE_MESH_SUPPORTED: esp-ble-mesh/ble-mesh-index
    bootloader
    build-system
    :SOC_SUPPORT_COEXISTENCE: coexist
@@ -20,7 +21,6 @@ API Guides
    :SOC_RTC_MEM_SUPPORTED: deep-sleep-stub
    :SOC_USB_OTG_SUPPORTED and not esp32p4: dfu
    error-handling
-   :SOC_BLE_MESH_SUPPORTED: esp-ble-mesh/ble-mesh-index
    :SOC_WIFI_MESH_SUPPORT: esp-wifi-mesh
    :SOC_SPIRAM_SUPPORTED: external-ram
    fatal-errors

docs/en/api-reference/bluetooth/classic_bt.rst

@@ -1,8 +1,8 @@
-Classic Bluetooth®
-==================
+Bluetooth® Classic
+===================
 
 .. toctree::
-   :caption: Classic Bluetooth
+   :caption: Bluetooth Classic
 
    Bluetooth GAP <esp_gap_bt>
    Bluetooth A2DP <esp_a2dp>

docs/en/api-reference/bluetooth/esp-ble-mesh.rst

@@ -225,4 +225,3 @@ Composition and Metadata
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. include-build-file:: inc/esp_ble_mesh_cm_data_api.inc
-

docs/zh_CN/api-guides/ble/blufi.rst

@@ -1,10 +1,10 @@
 BluFi
-^^^^^
+^^^^^^
 
 :link_to_translation:`en:[English]`
 
 概览
------
+--------
 
 BluFi 是一项基于蓝牙通道的 Wi-Fi 网络配置功能，适用于 {IDF_TARGET_NAME}。它通过安全协议将 Wi-Fi 的 SSID、密码等配置信息传输到 {IDF_TARGET_NAME}。基于这些信息，{IDF_TARGET_NAME} 可进而连接到 AP 或建立 SoftAP。
 
@@ -13,7 +13,7 @@ BluFi 流程的关键部分包括数据的分片、加密以及校验和验证
 用户可按需自定义用于对称加密、非对称加密以及校验的算法。此处，我们采用 DH 算法进行密钥协商，128-AES 算法用于数据加密，CRC16 算法用于校验和验证。
 
 BluFi 流程
-----------
+-----------
 
 BluFi 配网流程包含配置 SoftAP 和配置 Station 两部分。
 
@@ -46,7 +46,7 @@ BluFi 配网流程包含配置 SoftAP 和配置 Station 两部分。
     2. 进行对称加密和解密时，加密和解密前后的数据长度必须一致。支持原地加密和解密。
 
 BluFi 流程图
----------------
+------------
 
 .. seqdiag::
     :caption: BluFi Flow Chart
@@ -75,7 +75,7 @@ BluFi 流程图
 .. _frame_formats:
 
 BluFi 中定义的帧格式
-----------------------------
+---------------------
 
 手机应用程序与 {IDF_TARGET_NAME} 之间的 BluFi 通信格式定义如下：
 
@@ -431,7 +431,7 @@ ACK 帧格式 (8 bit)：
    此字段占两个字节，用来校验序列、数据长度以及明文。
 
 {IDF_TARGET_NAME} 端的安全实现
-----------------------------------
+-----------------------------
 
 1. 数据安全
 

docs/zh_CN/api-guides/ble/index.rst

@@ -0,0 +1,23 @@
+################
+低功耗蓝牙®
+################
+
+:link_to_translation:`en:[English]`
+
+*****
+概览
+*****
+.. toctree::
+   :maxdepth: 1
+
+   overview
+
+**********
+蓝牙规范
+**********
+
+.. toctree::
+   :maxdepth: 2
+
+   :SOC_BLE_MESH_SUPPORTED: ../esp-ble-mesh/ble-mesh-index
+   :SOC_BLUFI_SUPPORTED: blufi

docs/zh_CN/api-guides/ble/overview.rst

@@ -1,9 +1,9 @@
-蓝牙®概述
-=========
+介绍
+=======
 
 :link_to_translation:`en:[English]`
 
-此文档概述了 ESP-IDF 中蓝牙协议栈的架构，并提供了一些相关文档和应用示例的快速链接。
+此文档概述了 ESP-IDF 中低功耗蓝牙协议栈的架构，并提供了一些相关文档和应用示例的快速链接。
 
 .. only:: esp32
 
@@ -17,11 +17,11 @@
 
     {IDF_TARGET_NAME} 支持蓝牙 5.0 (LE)，并且已经获得蓝牙 LE 5.3 认证。
 
-ESP-IDF 中的蓝牙协议栈是一个分层架构，可在 {IDF_TARGET_NAME} 系列芯片上实现蓝牙功能，详见下。
+ESP-IDF 中的低功耗蓝牙协议栈是一个分层架构，可在 {IDF_TARGET_NAME} 系列芯片上实现低功耗蓝牙功能，详见下。
 
 .. only:: esp32 or esp32s3 or esp32c3 or esp32c6
 
-    .. figure:: ../../_static/bluetooth-architecture.png
+    .. figure:: ../../../_static/bluetooth-architecture.png
         :align: center
         :scale: 90%
         :alt: {IDF_TARGET_NAME} 蓝牙协议栈架构
@@ -30,7 +30,7 @@ ESP-IDF 中的蓝牙协议栈是一个分层架构，可在 {IDF_TARGET_NAME}
 
 .. only:: esp32c2
 
-    .. figure:: ../../_static/bluetooth-architecture-no-ble-mesh.png
+    .. figure:: ../../../_static/bluetooth-architecture-no-ble-mesh.png
         :align: center
         :scale: 90%
         :alt: {IDF_TARGET_NAME} 蓝牙协议栈架构
@@ -39,14 +39,14 @@ ESP-IDF 中的蓝牙协议栈是一个分层架构，可在 {IDF_TARGET_NAME}
 
 .. only:: esp32h2
 
-    .. figure:: ../../_static/bluetooth-architecture-no-blufi.png
+    .. figure:: ../../../_static/bluetooth-architecture-no-blufi.png
         :align: center
         :scale: 90%
         :alt: {IDF_TARGET_NAME} 蓝牙协议栈架构
 
         {IDF_TARGET_NAME} 蓝牙协议栈架构
 
-参考下表可知特定芯片是否支持蓝牙模块。
+参考下表可知特定芯片是否支持低功耗蓝牙模块。
 
 .. list-table::
     :width: 100%
@@ -110,12 +110,12 @@ ESP 蓝牙控制器
 
 底层为 ESP 蓝牙控制器，包含 PHY、基带、链路控制器、链路管理器、设备管理器和 HCI 等各种模块。该层管理硬件接口和链路，以库的形式提供功能，并通过 API 访问，且直接与硬件和低级别蓝牙协议交互。
 
-- :doc:`API 参考 <../api-reference/bluetooth/controller_vhci>`
+- :doc:`API 参考 <../../api-reference/bluetooth/controller_vhci>`
 - :example:`应用示例 <bluetooth/hci>`
 
 
-主机
-----
+ESP 蓝牙主机
+-------------
 
 有 ESP-Bluedroid 和 ESP-NimBLE 两个主机，其主要区别如下：
 
@@ -129,7 +129,7 @@ ESP 蓝牙控制器
 ESP-Bluedroid
 ^^^^^^^^^^^^^
 
-ESP-Bluedroid 是原生 Android 蓝牙协议栈 Bluedroid 的修改版，由两层组成：蓝牙上层 (BTU) 和蓝牙传输控制器层 (BTC)。BTU 层负责处理 L2CAP、GATT/ATT、SMP、GAP 等底层蓝牙协议以及其他配置文件，提供以 "bta" 为前缀的接口。BTC 层主要负责向应用层提供以 "esp" 为前缀的支持接口，并处理基于 GATT 的配置文件以及其他任务。所有的 API 都位于 ESP_API 层，开发者应使用以 "esp" 为前缀的蓝牙 API。
+ESP-Bluedroid 是原生 Android 蓝牙协议栈 Bluedroid 的修改版，由两层组成：蓝牙上层 (BTU) 和蓝牙传输控制器层 (BTC)。BTU 层负责处理 L2CAP、GATT/ATT、SMP、GAP 等底层蓝牙协议以及其他配置文件，提供以 "bta" 为前缀的接口。BTC 层主要负责向应用层提供以 "esp" 为前缀的支持接口，并处理基于 GATT 的配置文件以及其他任务。所有的 API 都位于 ESP_API 层，开发者应使用以 "esp" 为前缀的低功耗蓝牙 API。
 
 .. only:: esp32
 
@@ -141,15 +141,17 @@ ESP-Bluedroid 是原生 Android 蓝牙协议栈 Bluedroid 的修改版，由两
 
 - API 参考
 
-  - :doc:`../api-reference/bluetooth/bt_common`
-  - :doc:`低功耗蓝牙 <../api-reference/bluetooth/bt_le>`
+  - :doc:`../../api-reference/bluetooth/bt_common`
+  - :doc:`低功耗蓝牙 <../../api-reference/bluetooth/bt_le>`
 
-  .. only:: esp32
+.. only:: esp32
 
-    - :doc:`../api-reference/bluetooth/classic_bt`
+    - :example:`低功耗蓝牙 4.2 应用程序示例 <bluetooth/bluedroid/ble>`
 
-- :example:`应用程序示例 <bluetooth/bluedroid>`
+.. only:: not esp32
 
+    - :example:`低功耗蓝牙 4.2 应用程序示例 <bluetooth/bluedroid/ble>`
+    - :example:`低功耗蓝牙 5.0 应用程序示例 <bluetooth/bluedroid/ble_50>`
 
 ESP-NimBLE
 ^^^^^^^^^^
@@ -162,15 +164,15 @@ ESP-NimBLE 仅支持低功耗蓝牙，不支持经典蓝牙。
 - API 参考
 
   - `NimBLE API 参考 <https://mynewt.apache.org/latest/network/ble_hs/ble_hs.html>`__
-  - :doc:`ESP-NimBLE 初始化 API 参考 initialization <../api-reference/bluetooth/nimble/index>`
+  - :doc:`ESP-NimBLE 初始化 API 参考 initialization <../../api-reference/bluetooth/nimble/index>`
 
 - :example:`应用程序示例 <bluetooth/nimble>`
 
 
-配置文件
+蓝牙规范
 --------
 
-主机协议层之上是 Espressif 的配置文件实现和一些常见的配置文件。根据具体配置，这些配置文件可以在 ESP-Bluedroid 或 ESP-NimBLE 上运行。
+主机协议层之上是 Espressif 的蓝牙规范和一些常见的蓝牙规范。根据具体配置，这些规范可以在 ESP-Bluedroid 或 ESP-NimBLE 上运行。
 
 
 .. only:: SOC_BLE_MESH_SUPPORTED
@@ -180,7 +182,7 @@ ESP-NimBLE 仅支持低功耗蓝牙，不支持经典蓝牙。
 
   ESP-BLE-MESH 基于 Zephyr 蓝牙 Mesh 协议栈，其实现支持设备配网和节点控制，还支持代理、中继、低功耗和朋友等节点功能。
 
-  - :doc:`ESP-BLE-MESH 文档 <esp-ble-mesh/ble-mesh-index>`：功能列表、快速入门、架构、应用示例描述、常见问题等。
+  - :doc:`ESP-BLE-MESH 文档 <../esp-ble-mesh/ble-mesh-index>`：功能列表、快速入门、架构、应用示例描述、常见问题等。
   - :example:`应用示例 <bluetooth/esp_ble_mesh>`
 
 
@@ -198,4 +200,4 @@ ESP-NimBLE 仅支持低功耗蓝牙，不支持经典蓝牙。
 应用
 ----
 
-最上层是应用层。利用上述 API 和配置文件，可以在 ESP-Bluedroid 和 ESP-NimBLE 协议栈之上创建特定用例的蓝牙应用程序。
+最上层是应用层。利用上述 API 和蓝牙规范，可以在 ESP-Bluedroid 和 ESP-NimBLE 协议栈之上创建特定用例的低功耗蓝牙应用程序。

docs/zh_CN/api-guides/classic-bt/index.rst

@@ -0,0 +1,13 @@
+###########
+经典蓝牙®
+###########
+
+:link_to_translation:`en:[English]`
+
+*****
+概览
+*****
+.. toctree::
+   :maxdepth: 2
+
+   overview

docs/zh_CN/api-guides/classic-bt/overview.rst

@@ -0,0 +1,80 @@
+介绍
+=======
+
+:link_to_translation:`en:[English]`
+
+此文档概述了 ESP-IDF 中经典蓝牙协议栈的架构，并提供了一些相关文档和应用示例的快速链接。
+
+.. only:: esp32
+
+    {IDF_TARGET_NAME} 支持双模蓝牙 4.2，并且已经获得双模蓝牙 4.2 认证。
+
+ESP-IDF 中的经典蓝牙协议栈是一个分层架构，可在 {IDF_TARGET_NAME} 系列芯片上实现经典蓝牙功能，详见下。
+
+.. only:: esp32
+
+    .. figure:: ../../../_static/classic-bluetooth-architecture.png
+        :align: center
+        :scale: 90%
+        :alt: {IDF_TARGET_NAME} 经典蓝牙协议栈架构
+
+        {IDF_TARGET_NAME} 经典蓝牙协议栈架构
+
+参考下表可知特定芯片是否支持经典蓝牙控制器。
+
+.. list-table::
+    :width: 100%
+    :widths: auto
+    :header-rows: 1
+
+    * - 芯片系列
+      - 控制器
+    * - ESP32
+      - Y
+    * - ESP32-S2
+      - \–
+    * - ESP32-S3
+      - \–
+    * - ESP32-C2
+      - \-
+    * - ESP32-C3
+      - \-
+    * - ESP32-C6
+      - \-
+    * - ESP32-H2
+      - \-
+
+以下各节简要介绍了每个层，并提供了相关文档和应用示例的快速链接。
+
+
+ESP 蓝牙控制器
+--------------
+
+底层为 ESP 蓝牙控制器，包含 PHY、基带、链路控制器、链路管理器、设备管理器和 HCI 等各种模块。该层管理硬件接口和链路，以库的形式提供功能，并通过 API 访问，且直接与硬件和低级别蓝牙协议交互。
+
+- :doc:`API 参考 <../../api-reference/bluetooth/controller_vhci>`
+- :example:`应用示例 <bluetooth/hci/controller_hci_uart_esp32>`
+
+
+ESP 蓝牙主机
+-------------
+
+IDF 中的ESP-Bluedroid 主机支持经典蓝牙。
+
+
+ESP-Bluedroid
+^^^^^^^^^^^^^
+
+ESP-Bluedroid 是原生 Android 蓝牙协议栈 Bluedroid 的修改版，由两层组成：蓝牙上层 (BTU) 和蓝牙传输控制器层 (BTC)。BTU 层负责处理 L2CAP 等底层蓝牙协议以及其他配置文件，提供以 "bta" 为前缀的接口。BTC 层主要负责向应用层提供以 "esp" 为前缀的支持接口，并处理其他任务。所有的 API 都位于 ESP_API 层，开发者应使用以 "esp" 为前缀的经典蓝牙 API。
+
+- API 参考
+
+  - :doc:`../../api-reference/bluetooth/bt_common`
+  - :doc:`经典蓝牙 <../../api-reference/bluetooth/classic_bt>`
+- :example:`应用程序示例 <bluetooth/bluedroid/classic_bt>`
+
+
+应用
+----
+
+最上层是应用层。利用上述 API 和蓝牙规范，可以在 ESP-Bluedroid 协议栈之上创建特定用例的经典蓝牙应用程序。

docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-index.rst

@@ -25,8 +25,8 @@ ESP-BLE-MESH 的实现和认证基于最新的 `Mesh Profile v1.0.1 <https://www
 
 .. _getting-started-with-ble-mesh:
 
-ESP-BLE-MESH 快速入门
-=====================
+快速入门
+========
 
 该章节旨在帮助你基于乐鑫的 ESP32 开发板搭建 ESP-BLE-MESH 网络。
 
@@ -210,8 +210,8 @@ Step 5. 运行网络
 
 .. _esp-ble-mesh-examples:
 
-ESP-BLE-MESH 示例
-===================
+示例
+=====
 
 * :example_file:`开关节点 <bluetooth/esp_ble_mesh/onoff_models/onoff_server/tutorial/BLE_Mesh_Node_OnOff_Server_Example_Walkthrough.md>` - 展示了将 ESP-BLE-MESH 作为拥有 Configuration Server model 和 Generic OnOff Server model 的节点设备的用法。然后，ESP-BLE-MESH Provisioner 可以配网设备，控制表示开/关状态的 RGB 灯，示例请见 :example:`example code <bluetooth/esp_ble_mesh/onoff_models/onoff_server>`。
 
@@ -230,15 +230,15 @@ ESP-BLE-MESH 示例
 
 .. _esp-ble-mesh-demo-videos:
 
-ESP-BLE-MESH 演示视频
-======================
+演示视频
+========
 
 * `Espressif Fast Provisioning using ESP-BLE-MESH App <https://dl.espressif.com/BLE/public/ESP32_BLE_Mesh_Fast_Provision.mp4>`_
 * `Espressif ESP-BLE-MESH and Wi-Fi Coexistence <https://dl.espressif.com/BLE/public/ESP_BLE_MESH_WIFI_Coexistence.mp4>`_
 
 
-ESP-BLE-MESH 常见问题手册
-=========================
+常见问题手册
+=============
 
 * :ref:`ble-mesh-faq-provisioner-development`
 * :ref:`ble-mesh-faq-node-development`

docs/zh_CN/api-guides/index.rst

@@ -7,8 +7,9 @@ API 指南
 
    app_trace
    startup
-   :SOC_BLUFI_SUPPORTED: blufi
-   :SOC_BT_SUPPORTED: bluetooth
+   :SOC_BT_CLASSIC_SUPPORTED: classic-bt/index
+   :SOC_BLE_SUPPORTED: ble/index
+   :SOC_BLE_MESH_SUPPORTED: esp-ble-mesh/ble-mesh-index
    bootloader
    build-system
    :SOC_SUPPORT_COEXISTENCE: coexist
@@ -20,7 +21,6 @@ API 指南
    :SOC_RTC_MEM_SUPPORTED: deep-sleep-stub
    :SOC_USB_OTG_SUPPORTED and not esp32p4: dfu
    error-handling
-   :SOC_BLE_MESH_SUPPORTED: esp-ble-mesh/ble-mesh-index
    :SOC_WIFI_MESH_SUPPORT: esp-wifi-mesh
    :SOC_SPIRAM_SUPPORTED: external-ram
    fatal-errors