Merge branch 'docs/add_ble_get_started_eng_2024102310_v5.3' into 'rel…

…ease/v5.3' Docs: Added BLE English version of BLE Get Started (v5.3) See merge request espressif/esp-idf!34386
espressif · Oct 23, 2024 · 70a7de7 · 70a7de7
2 parents 8d472cf + a8f6e53
commit 70a7de7
Show file tree

Hide file tree

Showing 8 changed files with 2,457 additions and 99 deletions.
diff --git a/docs/en/api-guides/ble/get-started/ble-connection.rst b/docs/en/api-guides/ble/get-started/ble-connection.rst
diff --git a/docs/en/api-guides/ble/get-started/ble-data-exchange.rst b/docs/en/api-guides/ble/get-started/ble-data-exchange.rst
diff --git a/docs/en/api-guides/ble/get-started/ble-device-discovery.rst b/docs/en/api-guides/ble/get-started/ble-device-discovery.rst
diff --git a/docs/en/api-guides/ble/get-started/ble-introduction.rst b/docs/en/api-guides/ble/get-started/ble-introduction.rst
diff --git a/docs/zh_CN/api-guides/ble/get-started/ble-connection.rst b/docs/zh_CN/api-guides/ble/get-started/ble-connection.rst
@@ -11,7 +11,7 @@
 
 - 学习连接的基本概念
 - 学习连接相关的参数
-- 学习 NimBLE_Connection 例程的代码结构
+- 学习 :example:`NimBLE_Connection <bluetooth/ble_get_started/nimble/NimBLE_Connection>` 例程的代码结构
 
 
 连接的基本概念
@@ -23,7 +23,7 @@
 
 *在 Bluetooth LE 5.0 引入扩展广播特性以后， Legacy ADV 和 Extended ADV 对应的连接建立过程略有差异，下以 Legacy ADV 对应的连接建立过程为例。*
 
-当扫描者在某一个广播信道接收到一个广播数据包时，若该广播者是可连接的，那么扫描者可以在同一广播信道发送连接请求 (Connection Request)。对于广播者来说，它可以设置 *接受列表 (Accept List)* 以过滤不受信任的设备，或接受任一扫描者的连接请求。随后，广播者转变为外围设备，扫描者转变为中央设备，两者之间可以在数据信道进行双向通信。
+当扫描者在某一个广播信道接收到一个广播数据包时，若该广播者是可连接的，那么扫描者可以在同一广播信道发送连接请求 (Connection Request)。对于广播者来说，它可以设置 *接受列表 (Filter Accept List)* 以过滤不受信任的设备，或接受任一扫描者的连接请求。随后，广播者转变为外围设备，扫描者转变为中央设备，两者之间可以在数据信道进行双向通信。
 
 如 :ref:`扫描请求与扫描响应 <scan_request_and_scan_response>` 所述，广播者在每一个信道的广播结束以后，都会短暂进入 RX 模式，以接收可能的扫描请求。实际上，这个 RX 过程中还可以接受连接请求。所以对于扫描者来说，发送连接请求的时间窗口和发送扫描请求的时间窗口是类似的。
 
@@ -73,7 +73,7 @@
 
 外围设备延迟 (Peripheral Latency) 规定了外围设备在无需发送数据的前提下，最多可忽略的连接事件数量。
 
-为了理解这个连接参数的作用，让我们以蓝牙鼠标为例，分析其应用场景。用户在使用键盘的过程中，鼠标并没有需要发送的有效数据，此时最好降低数据包发送的频率以节省电量；在使用鼠标的过程中，我们希望鼠标能够尽可能快地发送数据，以降低使用延迟。也就是说，蓝牙鼠标的数据发送是间歇性高频率的。此时，如果仅靠连接间隔参数进行连接调节，则那么较低的连接间隔会导致高能耗，较高的连接间隔会导致高延迟。
+为了理解这个连接参数的作用，让我们以蓝牙鼠标为例。用户在使用键盘的过程中，鼠标并没有需要发送的有效数据，此时最好降低数据包发送的频率以节省电量；在使用鼠标的过程中，我们希望鼠标能够尽可能快地发送数据，以降低使用延迟。也就是说，蓝牙鼠标的数据发送是间歇性高频率的。此时，如果仅靠连接间隔参数进行连接调节，则那么较低的连接间隔会导致高能耗，较高的连接间隔会导致高延迟。
 
 在这种场景下，外围设备延迟机制将是一个完美的解决方案。为了降低蓝牙鼠标的延迟，我们可以将连接间隔设为一个较小的值，例如 10 ms ，那么在密集使用时数据交换频率可达 100 Hz ；随后，我们将外围设备延迟设定为 100 ，那么蓝牙鼠标在不使用的状态下，实际的数据交换频率可降低至 1 Hz 。通过这种设计，我们在不调整连接参数的前提下，实现了可变的数据交换频率，在最大程度上提升了用户体验。
 
@@ -132,17 +132,17 @@ MTU 可以设定为更大的值，例如 140 字节。在 Bluetooth LE 4.2 以
 例程实践
 -------------------------------------------
 
-在掌握了连接的相关知识以后，接下来让我们结合 NimBLE_Connection 例程代码，学习如何使用 NimBLE 协议栈构建一个简单的外围设备，对学到的知识进行实践。
+在掌握了连接的相关知识以后，接下来让我们结合 :example:`NimBLE_Connection <bluetooth/ble_get_started/nimble/NimBLE_Connection>` 例程代码，学习如何使用 NimBLE 协议栈构建一个简单的外围设备，对学到的知识进行实践。
 
 
 前提条件
 ^^^^^^^^^^^^^^^
 
-1. 一块支持 Bluetooth LE 的 {IDF_TARGET_NAME} 开发板
+1. 一块 {IDF_TARGET_NAME} 开发板
 2. ESP-IDF 开发环境
-3. 在手机上安装 nRF Connect for Mobile 应用程序
+3. 在手机上安装 **nRF Connect for Mobile** 应用程序
 
-若你尚未完成 ESP-IDF 开发环境的配置，请参考 :doc:`API 参考 <../../../get-started/index>`。
+若你尚未完成 ESP-IDF 开发环境的配置，请参考 :doc:`IDF 快速入门 <../../../get-started/index>`。
 
 
 动手试试
@@ -173,7 +173,7 @@ MTU 可以设定为更大的值，例如 140 字节。在 Bluetooth LE 4.2 以
 
     $ idf.py set-target <chip-name>
 
-你应该能看到命令行以
+你应该能看到以下命令行
 
 .. code-block:: shell
 
@@ -188,7 +188,7 @@ MTU 可以设定为更大的值，例如 140 字节。在 Bluetooth LE 4.2 以
 
     $ idf.py flash monitor
 
-你应该能看到命令行以
+你应该能看到以下命令行以
 
 .. code-block:: shell
 
@@ -201,7 +201,7 @@ MTU 可以设定为更大的值，例如 140 字节。在 Bluetooth LE 4.2 以
 连接，然后断开
 ##############################
 
-打开手机上的 nRF Connect for Mobile 程序，在 SCANNER 标签页中下拉刷新，找到 NimBLE_CONN 设备，如下图所示
+打开手机上的 **nRF Connect for Mobile** 程序，在 **SCANNER** 标签页中下拉刷新，找到 NimBLE_CONN 设备，如下图所示
 
 .. figure:: ../../../../_static/ble/ble-connection-device-list.jpg
     :align: center
@@ -211,17 +211,17 @@ MTU 可以设定为更大的值，例如 140 字节。在 Bluetooth LE 4.2 以
 
 若设备列表较长，建议以 NimBLE 为关键字进行设备名过滤，快速找到 NimBLE_CONN 设备。
 
-与 :ref:`NimBLE_Beacon <nimble_beacon_details>` 相比，可以观察到大部分广播数据是一致的，但多了一项 `Advertising Interval` 数据，其值为 500 ms ；在 `CONNECT` 按钮下方，确实也可以观察到广播间隔为 510 ms 左右。
+与 :ref:`NimBLE_Beacon <nimble_beacon_details>` 相比，可以观察到大部分广播数据是一致的，但多了一项 `Advertising Interval` 数据，其值为 500 ms ；在 **CONNECT** 按钮下方，确实也可以观察到广播间隔为 510 ms 左右。
 
-点击 `CONNECT` 按钮连接到设备，在手机上应能够看到 GAP 服务，如下
+点击 **CONNECT** 按钮连接到设备，在手机上应能够看到 GAP 服务，如下
 
 .. figure:: ../../../../_static/ble/ble-connection-connected.jpg
     :align: center
     :scale: 30%
 
     连接到 NimBLE_CONN 设备
 
-此时应该还能观察到开发板上的 LED 亮起。点击 `DISCONNECT`，断开与设备的连接，此时应能观察到开发板上的 LED 熄灭。
+此时应该还能观察到开发板上的 LED 亮起。点击 **DISCONNECT**，断开与设备的连接，此时应能观察到开发板上的 LED 熄灭。
 
 若你的开发板上没有电源指示灯以外的 LED ，你应该能在日志输出中观察到对应的状态指示。
 
@@ -279,7 +279,7 @@ MTU 可以设定为更大的值，例如 140 字节。在 Bluetooth LE 4.2 以
 
 .. _nimble_connection_project_structure:
 
-NimBLE_Connection 的根目录结构与 :ref:`NimBLE_Beacon <nimble_beacon_project_structure>` 完全一致，不过在完成了固件的构建以后，你可能会观察到根目录下多了一个 `managed_components` 目录，里面含有固件构建时自动引入的依赖；本例中为 `led_strip` 组件，用于控制开发板的 LED。该依赖项在 `main/idf_component.yml` 文件中被引入。
+:example:`NimBLE_Connection <bluetooth/ble_get_started/nimble/NimBLE_Connection>` 的根目录结构与 :ref:`NimBLE_Beacon <nimble_beacon_project_structure>` 完全一致，不过在完成了固件的构建以后，你可能会观察到根目录下多了一个 `managed_components` 目录，里面含有固件构建时自动引入的依赖；本例中为 `led_strip` 组件，用于控制开发板的 LED。该依赖项在 `main/idf_component.yml` 文件中被引入。
 
 另外，在 `main` 文件夹中引入了 LED 控制相关的源代码。
 
@@ -472,6 +472,6 @@ GAP 事件处理
 总结
 ----------------
 
-通过本教程，你了解了连接的基本概念，并通过 NimBLE_Connection 例程掌握了使用 NimBLE 主机层协议栈构建 Bluetooth LE 外围设备的方法。
+通过本教程，你了解了连接的基本概念，并通过 :example:`NimBLE_Connection <bluetooth/ble_get_started/nimble/NimBLE_Connection>` 例程掌握了使用 NimBLE 主机层协议栈构建 Bluetooth LE 外围设备的方法。
 
 你可以尝试对例程中的参数进行修改，并在日志输出中观察修改结果。例如，你可以修改外围设备延迟或连接超时参数，观察连接参数的修改是否能够触发连接更新事件。
diff --git a/docs/zh_CN/api-guides/ble/get-started/ble-data-exchange.rst b/docs/zh_CN/api-guides/ble/get-started/ble-data-exchange.rst
@@ -3,15 +3,15 @@
 
 :link_to_translation:`en:[English]`
 
-本文档为低功耗蓝牙 (Bluetooth Low Energy, Bluetooth LE) 入门教程其四，旨在对 Bluetooth LE 连接中的数据交换过程进行简要介绍。随后，本教程会结合 NimBLE_GATT_Server 例程，基于 NimBLE 主机层协议栈，对 GATT 服务器的代码实现进行介绍。
+本文档为低功耗蓝牙 (Bluetooth Low Energy, Bluetooth LE) 入门教程其四，旨在对 Bluetooth LE 连接中的数据交换过程进行简要介绍。随后，本教程会结合 :example:`NimBLE_GATT_Server <bluetooth/ble_get_started/nimble/NimBLE_GATT_Server>` 例程，基于 NimBLE 主机层协议栈，对 GATT 服务器的代码实现进行介绍。
 
 
 学习目标
 ---------------------------
 
 - 学习特征数据和服务的数据结构细节
 - 学习 GATT 的不同数据访问操作
-- 学习 NimBLE_GATT_Server 例程的代码结构
+- 学习 :example:`NimBLE_GATT_Server <bluetooth/ble_get_started/nimble/NimBLE_GATT_Server>` 例程的代码结构
 
 
 GATT 数据特征与服务
@@ -203,7 +203,7 @@ CCCD 的 UUID 是 `0x2902`，属性值中仅含 2 比特信息。第一个比特
 
 .. _attribute_table:
 
-下面以 NimBLE_GATT_Server 为例，展示一个 GATT 服务器可能的属性表形态。例程中含有两个服务，分别是 Heart Rate Service 和 Automation IO Service ；前者含有一个 Heart Rate Measurement 特征数据，后者含有一个 LED 特征数据。整个 GATT 服务器有属性表如下
+下面以 :example:`NimBLE_GATT_Server <bluetooth/ble_get_started/nimble/NimBLE_GATT_Server>` 为例，展示一个 GATT 服务器可能的属性表形态。例程中含有两个服务，分别是 Heart Rate Service 和 Automation IO Service ；前者含有一个 Heart Rate Measurement 特征数据，后者含有一个 LED 特征数据。整个 GATT 服务器有属性表如下
 
 +-------------+------------------------------------------+-----------------+-------------------------------------------------+----------------------------+
 | Handle      | UUID                                     | Permissions     | Value                                           | Attribute Type             |
@@ -232,7 +232,9 @@ CCCD 的 UUID 是 `0x2902`，属性值中仅含 2 比特信息。第一个比特
 |             |                                          |                 +-------------------------------------------------+                            |
 |             |                                          |                 | UUID = `0x00001525-1212-EFDE-1523-785FEABCD123` |                            |
 +-------------+------------------------------------------+-----------------+-------------------------------------------------+----------------------------+
-| 6           | `0x00001525-1212-EFDE-1523-785FEABCD123` | Write-only      | LED status                                      | Characteristic Value       |
+| 6           | `0x00001525-1212-EFDE-`                  |Write-only       | LED status                                      |Characteristic Value        |
+|             | `1523-785FE`                             |                 |                                                 |                            |
+|             | `ABCD123`                                |                 |                                                 |                            |
 +-------------+------------------------------------------+-----------------+-------------------------------------------------+----------------------------+
 
 GATT 客户端在与 GATT 服务器初次建立通信时，会从 GATT 服务器拉取属性表中的元信息，从而获取 GATT 服务器上可用的服务以及数据特征。这一过程被称为 *服务发现 (Service Discovery)*。
@@ -243,61 +245,58 @@ GATT 数据操作
 
 .. _gatt_data_operation:
 
-数据操作指的是对 GATT 服务器上的特征数据进行访问的操作，主要可以分为
+数据操作指的是对 GATT 服务器上的特征数据进行访问的操作，主要可以分为以下两类：
 
 1. 由客户端发起的操作
 2. 由服务器发起的操作
 
-两类。
-
 
 由客户端发起的操作
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 由客户端发起的操作有以下三种
 
-1. 读 (Read)
-2. 写 (Write)
-3. 写（无需响应） (Write without response)
-
-读操作比较简单，单纯是从 GATT 服务器上拉取某一特征数据的当前值。
-
-写操作分两种。普通的写操作要求 GATT 服务器在收到客户端的写请求以及对应数据以后，进行确认响应；快速写操作则不需要服务器进行确认响应。
+- **读 (Read)**
+    - 从 GATT 服务器上拉取某一特征数据的当前值。
+- **写 (Write)**
+    - 普通的写操作要求 GATT 服务器在收到客户端的写请求以及对应数据以后，进行确认响应。
+- **写（无需响应） (Write without response)**
+    - 快速写操作则不需要服务器进行确认响应。
 
 
 由服务器发起的操作
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 由服务器发起的操作分两种
 
-1. 通知 (Notify)
-2. 指示 (Indicate)
-
-通知和指示都是 GATT 服务器主动向客户端推送数据的操作，区别在于通知无需客户端回复确认响应，而指示需要。所以，指示的数据推送速度比通知慢。
+- **通知 (Notify)**
+    - 通知是 GATT 服务器主动向客户端推送数据的操作，不需要客户端回复确认响应。
+- **指示 (Indicate)**
+    - 与通知相似，区别在于指示需要客户端回复确认，因此数据推送速度比通知慢。
 
 虽然通知和指示都是由服务器发起的操作，但是服务器发起操作的前提是，客户端启用了通知或指示。所以，本质上 GATT 的数据交换过程总是以客户端请求数据开始。
 
 
 例程实践
 -------------------------------------------
 
-在掌握了 GATT 数据交换的相关知识以后，接下来让我们结合 NimBLE_GATT_Server 例程代码，学习如何使用 NimBLE 协议栈构建一个简单的 GATT 服务器，对学到的知识进行实践。
+在掌握了 GATT 数据交换的相关知识以后，接下来让我们结合 :example:`NimBLE_GATT_Server <bluetooth/ble_get_started/nimble/NimBLE_GATT_Server>` 例程代码，学习如何使用 NimBLE 协议栈构建一个简单的 GATT 服务器，对学到的知识进行实践。
 
 
 前提条件
 ^^^^^^^^^^^^^^^
 
-1. 一块支持 Bluetooth LE 的 {IDF_TARGET_NAME} 开发板
+1. 一块 {IDF_TARGET_NAME} 开发板
 2. ESP-IDF 开发环境
 3. 在手机上安装 nRF Connect for Mobile 应用程序
 
-若你尚未完成 ESP-IDF 开发环境的配置，请参考 :doc:`API 参考 <../../../get-started/index>`。
+若你尚未完成 ESP-IDF 开发环境的配置，请参考 :doc:`IDF 快速入门 <../../../get-started/index>`。
 
 
 动手试试
 ^^^^^^^^^^^^^^^^^^
 
-请参考 :ref:`动手试试 <nimble_gatt_server_practice>` 。
+请参考 :ref:`BLE 介绍 动手试试 <nimble_gatt_server_practice>` 。
 
 
 代码详解
@@ -307,7 +306,7 @@ GATT 数据操作
 工程结构综述
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-NimBLE_GATT_Server 的根目录结构与 :ref:`NimBLE_Connection <nimble_connection_project_structure>` 完全一致。另外，在 `main` 文件夹中引入了与 GATT 服务以及模拟心率生成相关的源代码。
+:example:`NimBLE_GATT_Server <bluetooth/ble_get_started/nimble/NimBLE_GATT_Server>` 的根目录结构与 :ref:`NimBLE_Connection <nimble_connection_project_structure>` 完全一致。另外，在 `main` 文件夹中引入了与 GATT 服务以及模拟心率生成相关的源代码。
 
 
 程序行为综述
@@ -659,6 +658,4 @@ LED 特征数据的访问通过 `led_chr_access` 回调函数管理，相关代
 总结
 ----------------------------
 
-通过本教程，你了解了如何通过服务表创建 GATT 服务以及相应的特征数据，并掌握了 GATT 特征数据的访问管理方式，包括读、写和订阅操作的实现。你可以在 NimBLE_GATT_Server 例程的基础上，开发更加复杂的 GATT 服务应用。
-
-
+通过本教程，你了解了如何通过服务表创建 GATT 服务以及相应的特征数据，并掌握了 GATT 特征数据的访问管理方式，包括读、写和订阅操作的实现。你可以在 :example:`NimBLE_GATT_Server <bluetooth/ble_get_started/nimble/NimBLE_GATT_Server>` 例程的基础上，开发更加复杂的 GATT 服务应用。