docs: Improve Bluetooth API homepage

Author: weikelu

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

@@ -1,36 +1,91 @@
-Bluetooth® API
-**************
+Bluetooth\ :sup:`®` API
+*****************************
 
 :link_to_translation:`zh_CN:[中文]`
 
+This section provides the API reference for Bluetooth components supported in ESP-IDF. ESP-IDF supports two host stacks: **Bluedroid** and **NimBLE**.
+
+- **Bluedroid** (the default stack): Supports both Bluetooth Classic and Bluetooth LE. Recommended for applications that require both technologies.
+- **NimBLE**: A lightweight stack for Bluetooth LE only. Ideal for resource-constrained applications due to smaller code size and memory usage.
+
+Use the navigation links below to explore API documentation and application examples.
+
+----
+
+**Controller Interface API**
+
+The low-level interface between the Bluetooth host stack and the controller.
+
+.. toctree::
+    :maxdepth: 1
+
+    controller_vhci
+
+
+**Bluedroid Stack API**
+
+The default host stack in ESP-IDF, supporting both Bluetooth Classic and Bluetooth LE.
+
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
 
     bt_common
-    bt_le
     :SOC_BT_CLASSIC_SUPPORTED: classic_bt
-    controller_vhci
-    :SOC_BLE_MESH_SUPPORTED: esp-ble-mesh
+    bt_le
+
+For architecture and feature overviews, refer to the following documents in API Guides:
+
+.. only:: SOC_BT_CLASSIC_SUPPORTED
+
+    :doc:`../../api-guides/bt-architecture/index`, :doc:`../../api-guides/classic-bt/index`, :doc:`../../api-guides/ble/index`
+
+.. only:: not SOC_BT_CLASSIC_SUPPORTED
+
+    :doc:`../../api-guides/bt-architecture/index`, :doc:`../../api-guides/ble/index`
+
+**NimBLE Stack API**
+
+A lightweight host stack for Bluetooth LE.
+
+.. toctree::
+    :maxdepth: 1
+
     nimble/index
 
-ESP-IDF currently supports two host stacks. The Bluedroid based stack (default) supports classic Bluetooth as well as Bluetooth Low Energy (Bluetooth LE). On the other hand, Apache NimBLE based stack is Bluetooth Low Energy only. For users to make a choice:
+For additional details and API reference from the upstream documentation, refer to `Apache Mynewt NimBLE User Guide <https://mynewt.apache.org/latest/network/index.html>`_.
+
+.. only:: SOC_BLE_MESH_SUPPORTED
+
+    **ESP-BLE-MESH API**
 
-* For usecases involving classic Bluetooth as well as Bluetooth Low Energy, Bluedroid should be used.
-* For Bluetooth Low Energy-only usecases, using NimBLE is recommended. It is less demanding in terms of code footprint and runtime memory, making it suitable for such scenarios.
+    Implements Bluetooth LE Mesh networking.
 
-.. only:: esp32
+    .. toctree::
+        :maxdepth: 1
 
-    For the overview of the ESP32 Bluetooth stack architecture, follow the links below:
+        esp-ble-mesh
 
-       * `ESP32 Bluetooth Architecture (PDF) <https://espressif.com/sites/default/files/documentation/esp32_bluetooth_architecture_en.pdf>`_
+----
 
-Code examples for this API section are provided in the :example:`bluetooth/bluedroid` directory of ESP-IDF examples.
+Examples and Tutorials
+---------------------------
 
-The following examples contain detailed walkthroughs:
+Explore examples and tutorials in the ESP-IDF examples directory:
+
+- **Bluedroid**: :example:`bluetooth/bluedroid`
+- **NimBLE**: :example:`bluetooth/nimble`
+
+Step-by-step tutorials for developing with the Bluedroid stack:
 
 * :example_file:`GATT Client Example Walkthrough <bluetooth/bluedroid/ble/gatt_client/tutorial/Gatt_Client_Example_Walkthrough.md>`
 * :example_file:`GATT Server Service Table Example Walkthrough <bluetooth/bluedroid/ble/gatt_server_service_table/tutorial/Gatt_Server_Service_Table_Example_Walkthrough.md>`
 * :example_file:`GATT Server Example Walkthrough <bluetooth/bluedroid/ble/gatt_server/tutorial/Gatt_Server_Example_Walkthrough.md>`
 * :example_file:`GATT Security Client Example Walkthrough <bluetooth/bluedroid/ble/gatt_security_client/tutorial/Gatt_Security_Client_Example_Walkthrough.md>`
 * :example_file:`GATT Security Server Example Walkthrough <bluetooth/bluedroid/ble/gatt_security_server/tutorial/Gatt_Security_Server_Example_Walkthrough.md>`
 * :example_file:`GATT Client Multi-connection Example Walkthrough <bluetooth/bluedroid/ble/gattc_multi_connect/tutorial/Gatt_Client_Multi_Connection_Example_Walkthrough.md>`
+
+Step-by-step tutorials for developing with the NimBLE stack:
+
+* :example_file:`Bluetooth LE Central Example Walkthrough <bluetooth/nimble/blecent/tutorial/blecent_walkthrough.md>`
+* :example_file:`Bluetooth LE Heart Rate Example Walkthrough <bluetooth/nimble/blehr/tutorial/blehr_walkthrough.md>`
+* :example_file:`Bluetooth LE Peripheral Example Walkthrough <bluetooth/nimble/bleprph/tutorial/bleprph_walkthrough.md>`

docs/zh_CN/api-reference/bluetooth/index.rst

@@ -1,36 +1,91 @@
-蓝牙 API
-*************
+蓝牙\ :sup:`®` API
+***********************
 
 :link_to_translation:`en:[English]`
 
+本章节提供 ESP-IDF 中蓝牙的 API 参考。ESP-IDF 支持两种主机协议栈：**Bluedroid** 和 **NimBLE**。
+
+- **Bluedroid** （默认协议栈）：支持经典蓝牙和低功耗蓝牙，适用于同时使用这两种技术的应用场景。
+- **NimBLE**：仅支持低功耗蓝牙，因代码体积小、内存占用低，适合资源受限的应用。
+
+可通过下方链接查看相应的 API 文档和示例应用。
+
+----
+
+**控制器接口 API**
+
+蓝牙主机协议栈与控制器之间的底层接口。
+
+.. toctree::
+    :maxdepth: 1
+
+    controller_vhci
+
+
+**Bluedroid 协议栈 API**
+
+ESP-IDF 默认的主机协议栈，支持经典蓝牙和低功耗蓝牙。
+
+.. toctree::
+    :maxdepth: 1
+
+    bt_common
+    :SOC_BT_CLASSIC_SUPPORTED: classic_bt
+    bt_le
+
+有关蓝牙架构和功能的详细信息，请参阅 API 指南中的以下文档：
+
+.. only:: SOC_BT_CLASSIC_SUPPORTED
+
+    :doc:`../../api-guides/bt-architecture/index`、 :doc:`../../api-guides/classic-bt/index`、 :doc:`../../api-guides/ble/index`
+
+.. only:: not SOC_BT_CLASSIC_SUPPORTED
+
+    :doc:`../../api-guides/bt-architecture/index`、 :doc:`../../api-guides/ble/index`
+
+**NimBLE 协议栈 API**
+
+专为低功耗蓝牙设计的轻量级主机协议栈。
+
 .. toctree::
-   :maxdepth: 2
+    :maxdepth: 1
+
+    nimble/index
+
+更多详细信息和上游文档的 API 参考，请参阅 `Apache Mynewt NimBLE 用户指南 <https://mynewt.apache.org/latest/network/index.html>`_。
+
+.. only:: SOC_BLE_MESH_SUPPORTED
 
-   bt_common
-   bt_le
-   :SOC_BT_CLASSIC_SUPPORTED: classic_bt
-   controller_vhci
-   :SOC_BLE_MESH_SUPPORTED: esp-ble-mesh
-   nimble/index
+    **ESP-BLE-MESH API**
 
-ESP-IDF 目前支持两个主机堆栈。基于 Bluedroid 的堆栈（默认）支持传统蓝牙和低功耗蓝牙 (Bluetooth® LE)，而基于 Apache NimBLE 的堆栈仅支持低功耗蓝牙。用户可参考如下信息进行选择：
+    实现低功耗蓝牙 Mesh 网络功能。
 
-* 对于同时涉及传统蓝牙和低功耗蓝牙的用例，应该选用 Bluedroid。
-* 对于仅涉及低功耗蓝牙的用例，建议选用 NimBLE。在代码占用和运行时，NimBLE 对内存的要求较低，因此适用于此类场景。
+    .. toctree::
+        :maxdepth: 1
 
-.. only:: esp32
+        esp-ble-mesh
 
-    请点击下方链接，查看 ESP32 蓝牙架构：
+----
 
-      * `ESP32 蓝牙架构 (PDF) <https://espressif.com/sites/default/files/documentation/esp32_bluetooth_architecture_cn.pdf>`_
+示例与教程
+------------
 
-蓝牙 API 的示例代码存放于 ESP-IDF 示例项目的 :example:`bluetooth/bluedroid` 目录下。
+ESP-IDF 提供了丰富的示例代码和实践教程，路径见 examples 目录：
 
-下面的示例给出了详细介绍：
+- **Bluedroid**: :example:`bluetooth/bluedroid`
+- **NimBLE**: :example:`bluetooth/nimble`
+
+使用 Bluedroid 协议栈进行开发的分步示例教程：
 
 * :example_file:`GATT 客户端示例 <bluetooth/bluedroid/ble/gatt_client/tutorial/Gatt_Client_Example_Walkthrough.md>`
 * :example_file:`GATT 服务端服务表格示例 <bluetooth/bluedroid/ble/gatt_server_service_table/tutorial/Gatt_Server_Service_Table_Example_Walkthrough.md>`
 * :example_file:`GATT 服务端示例 <bluetooth/bluedroid/ble/gatt_server/tutorial/Gatt_Server_Example_Walkthrough.md>`
 * :example_file:`GATT 客户端安全性示例 <bluetooth/bluedroid/ble/gatt_security_client/tutorial/Gatt_Security_Client_Example_Walkthrough.md>`
 * :example_file:`GATT 服务端安全性示例 <bluetooth/bluedroid/ble/gatt_security_server/tutorial/Gatt_Security_Server_Example_Walkthrough.md>`
 * :example_file:`GATT 客户端多连接示例 <bluetooth/bluedroid/ble/gattc_multi_connect/tutorial/Gatt_Client_Multi_Connection_Example_Walkthrough.md>`
+
+使用 NimBLE 协议栈进行开发的分步示例教程：
+
+* :example_file:`低功耗蓝牙中心设备示例 <bluetooth/nimble/blecent/tutorial/blecent_walkthrough.md>`
+* :example_file:`低功耗蓝牙心率示例 <bluetooth/nimble/blehr/tutorial/blehr_walkthrough.md>`
+* :example_file:`低功耗蓝牙外围设备示例 <bluetooth/nimble/bleprph/tutorial/bleprph_walkthrough.md>`