espressif/esp-idf
1
0
Fork 1
mirror of https://github.com/espressif/esp-idf.git synced 2025-08-03 12:44:33 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'docs/improve_bluetooth_api_homepage' into 'master'

Browse Source 
docs: Improve Bluetooth API homepage

Closes DOC-10814

See merge request espressif/esp-idf!38645
This commit is contained in:
Lu Wei Ke
2025-05-09 17:42:48 +08:00
parent d01a19330f fe873acdab
commit a99c984f38
2 changed files with 141 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
docs/en/api-reference/bluetooth/index.rst
View File

@@ -1,32 +1,81 @@
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: 2
:maxdepth: 1
controller_vhci
**Bluedroid Stack API**
The default host stack in ESP-IDF, supporting both Bluetooth Classic and Bluetooth LE.
.. toctree::
: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>`_.
* 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.
.. only:: SOC_BLE_MESH_SUPPORTED
.. only:: esp32
**ESP-BLE-MESH API**
For the overview of the ESP32 Bluetooth stack architecture, follow the links below:
Implements Bluetooth LE Mesh networking.
* `ESP32 Bluetooth Architecture (PDF) <https://espressif.com/sites/default/files/documentation/esp32_bluetooth_architecture_en.pdf>`_
.. toctree::
:maxdepth: 1
Code examples for this API section are provided in the :example:`bluetooth/bluedroid` directory of ESP-IDF examples.
esp-ble-mesh
The following examples contain detailed walkthroughs:
----
Examples and Tutorials
---------------------------
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>`
@@ -34,3 +83,9 @@ The following examples contain detailed walkthroughs:
* :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>`

89
docs/zh_CN/api-reference/bluetooth/index.rst
View File

@@ -1,32 +1,81 @@
蓝牙 API
*************
蓝牙\ :sup:`®` API
***********************
:link_to_translation:`en:[English]`
本章节提供 ESP-IDF 中蓝牙的 API 参考。ESP-IDF 支持两种主机协议栈：**Bluedroid** 和 **NimBLE**。
- **Bluedroid** （默认协议栈）：支持经典蓝牙和低功耗蓝牙，适用于同时使用这两种技术的应用场景。
- **NimBLE**：仅支持低功耗蓝牙，因代码体积小、内存占用低，适合资源受限的应用。
可通过下方链接查看相应的 API 文档和示例应用。
----
**控制器接口 API**
蓝牙主机协议栈与控制器之间的底层接口。
.. toctree::
:maxdepth: 2
:maxdepth: 1
bt_common
bt_le
:SOC_BT_CLASSIC_SUPPORTED: classic_bt
controller_vhci
:SOC_BLE_MESH_SUPPORTED: esp-ble-mesh
nimble/index
controller_vhci
ESP-IDF 目前支持两个主机堆栈。基于 Bluedroid 的堆栈（默认）支持传统蓝牙和低功耗蓝牙 (Bluetooth® LE)，而基于 Apache NimBLE 的堆栈仅支持低功耗蓝牙。用户可参考如下信息进行选择：
* 对于同时涉及传统蓝牙和低功耗蓝牙的用例，应该选用 Bluedroid。
* 对于仅涉及低功耗蓝牙的用例，建议选用 NimBLE。在代码占用和运行时，NimBLE 对内存的要求较低，因此适用于此类场景。
**Bluedroid 协议栈 API**
.. only:: esp32
ESP-IDF 默认的主机协议栈，支持经典蓝牙和低功耗蓝牙。
请点击下方链接，查看 ESP32 蓝牙架构：
.. toctree::
:maxdepth: 1
* `ESP32 蓝牙架构 (PDF) <https://espressif.com/sites/default/files/documentation/esp32_bluetooth_architecture_cn.pdf>`_
bt_common
:SOC_BT_CLASSIC_SUPPORTED: classic_bt
bt_le
蓝牙 API 的示例代码存放于 ESP-IDF 示例项目的 :example:`bluetooth/bluedroid` 目录下。
有关蓝牙架构和功能的详细信息，请参阅 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: 1
nimble/index
更多详细信息和上游文档的 API 参考，请参阅 `Apache Mynewt NimBLE 用户指南 <https://mynewt.apache.org/latest/network/index.html>`_。
.. only:: SOC_BLE_MESH_SUPPORTED
**ESP-BLE-MESH API**
实现低功耗蓝牙 Mesh 网络功能。
.. toctree::
:maxdepth: 1
esp-ble-mesh
----
示例与教程
------------
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>`
@@ -34,3 +83,9 @@ ESP-IDF 目前支持两个主机堆栈。基于 Bluedroid 的堆栈（默认）
* :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>`