update to f7ce2e7

.gitignore

@@ -5,3 +5,5 @@ cfg.toml
 __pycache__
 .DS_Store
 .embuild/
+.vale
+.vale.ini

README.md

@@ -1,6 +1,6 @@
 这里是 https://github.com/esp-rs/std-training 的简体中文翻译
 
-目前进度：已经翻译完成，跟踪到 f8865a2
+目前进度：已经翻译完成，跟踪到 f7ce2e7
 
 ---
 

book/src/01_intro.md

@@ -25,7 +25,7 @@
 
 如果你订阅了其中一项培训，乐鑫将直接为你提供一块开发板。
 
-我们的重点主要在 [ESP32-C3](https://www.espressif.com/en/products/socs/esp32-c3) 平台，一个基于 [RISC-V](https://riscv.org/) 的，具有强大物联网功能的微控制器，集成 Wi-Fi 和 Bluetooth 5 (LE) 功能，以及适用于复杂应用的大容量 RAM 和 Flash。 本教程的大部分内容也适用于 Espressif 使用的其他架构（Xtensa），特别是 [ESP32-S3](https://www.espressif.com/en/products/socs/esp32-s3)。 对于底层访问，原理上是一样的，但实际的硬件访问会各有不同——请根据需要参阅技术参考手册（[C3](https://www.espressif.com/sites/default/files/documentation/esp32-c3_technical_reference_manual_en.pdf)，[S3](https://www.espressif.com/sites/default/files/documentation/esp32-s3_technical_reference_manual_en.pdf)）或[其他可用的技术文档](https://www.espressif.com/en/support/documents/technical-documents)。
+我们的重点主要在 [ESP32-C3](https://www.espressif.com/en/products/socs/esp32-c3) 平台，一个基于 [`RISC-V`](https://riscv.org/) 的，具有强大物联网功能的微控制器，集成 Wi-Fi 和 Bluetooth 5 (LE) 功能，以及适用于复杂应用的大容量 RAM 和 Flash。 本教程的大部分内容也适用于 Espressif 使用的其他架构（`Xtensa`），特别是 [ESP32-S3](https://www.espressif.com/en/products/socs/esp32-s3)。 对于底层访问，原理上是一样的，但实际的硬件访问会各有不同——请根据需要参阅技术参考手册（[C3](https://www.espressif.com/sites/default/files/documentation/esp32-c3_technical_reference_manual_en.pdf)，[S3](https://www.espressif.com/sites/default/files/documentation/esp32-s3_technical_reference_manual_en.pdf)）或[其他可用的技术文档](https://www.espressif.com/en/support/documents/technical-documents)。
 
 ## Rust 知识
 

book/src/02_1_hardware.md

@@ -7,7 +7,7 @@
 **Windows**：一个 USB 串行设备（COM 端口），在设备管理器的“端口”部分。
 
 **Linux**：`lsusb` 下的一个 USB 设备。
-这个设备的 VID（vendor ID）为 `303a`，PID（product ID）为 `1001`——`lsusb` 的输出中会省略 `0x` 前缀：
+这个设备的 VID（Vendor ID）为 `303a`，PID（Product ID）为 `1001`——`lsusb` 的输出中会省略 `0x` 前缀：
 
 ``` console
 $ lsusb | grep USB

book/src/02_2_software.md

@@ -2,7 +2,7 @@
 
 按照以下步骤完成 ESP32-C3 平台工具的默认安装。
 
-🔎 如果想要自定义安装（例如，从源码构建组件，或者添加对 Xtensa 目标的支持），请参阅 *Rust on ESP* 一书的 [Rust on ESP targets](https://esp-rs.github.io/book/installation/index.html) 章节。
+🔎 如果想要自定义安装（例如，从源码构建组件，或者添加对 `Xtensa` 目标的支持），请参阅 *Rust on ESP* 一书的 [Rust on ESP targets](https://esp-rs.github.io/book/installation/index.html) 章节。
 
 ## Rust 工具链
 
@@ -17,12 +17,12 @@ rustup toolchain install nightly-2023-02-28 --component rust-src
 ```
 
 🔎 Rust 能够交叉编译到任何支持的目标架构（参见 `rustup 目标列表`）。默认情况下，仅会安装本机的架构。
-从 2022 年 1 月起，如果要编译到 Xtensa 架构（不是本材料的一部分），需要一个 Rust 编译器的分支。
+从 2022 年 1 月起，如果要编译到 `Xtensa` 架构（不是本材料的一部分），需要一个 Rust 编译器的分支。
 
 ## Espressif 工具链
 
 需要几个工具：
-- [`cargo-espflash`](https://github.com/esp-rs/espflash/tree/main/cargo-espflash) - 上传固件到微控制器，打开串口监视器，cargo 集成
+- [`cargo-espflash`](https://github.com/esp-rs/espflash/tree/main/cargo-espflash) - 上传固件到微控制器，打开串口监视器，Cargo 集成
 - [`espflash`](https://github.com/esp-rs/espflash/tree/main/espflash) - 上传固件到微控制器，打开串口监视器
 - [`ldproxy`](https://github.com/esp-rs/embuild/tree/master/ldproxy) - Espressif 构建工具链的依赖
 
@@ -41,7 +41,7 @@ cargo install cargo-espflash espflash ldproxy
 ```console
 sudo apt install llvm-dev libclang-dev clang
 ```
-### macOS
+### `macOS`
 
 当使用 Homebrew 包管理器时，这也是我们推荐的方式：
 ```console
@@ -116,7 +116,7 @@ docker run --mount type=bind,source="$(pwd)",target=/workspace,consistency=cache
 * [`lldb`](https://github.com/vadimcn/vscode-lldb) 基于 LLDB 的本机调试器扩展
 * [`crates`](https://github.com/serayuzgur/crates) 帮助管理 Rust 依赖项
 
-### VS Code 和 Devcontainer
+### VS Code 和 Dev container
 
 有助于在 Docker 容器内开发的一个 VS Code 扩展是 [`Remote Containers`](https://github.com/Microsoft/vscode-remote-release)。
 它使用与 [Docker 配置](#docker)相同的 Dockerfile，构建镜像并从 VS Code 中建立连接。

book/src/02_3_repository.md

@@ -28,7 +28,7 @@ cd r:\
 
 ## 关于配置的说明
 
-比起将证书或其他敏感信息直接放在源代码中，在本教程中，我们会使用 [toml-cfg](https://github.com/jamesmunns/toml-cfg) 作为一种更方便、更安全的替代方法。配置信息会存储在相应包的根目录中名为 `cfg.toml` 的文件中
+比起将证书或其他敏感信息直接放在源代码中，在本教程中，我们会使用 [`toml-cfg`](https://github.com/jamesmunns/toml-cfg) 作为一种更方便、更安全的替代方法。配置信息会存储在相应包的根目录中名为 `cfg.toml` 的文件中
 
 该配置中只包含一个与包同名（`Cargo.toml` 中的 `name = "your-package"`）的 section 标题，具体配置因项目而异：
 

book/src/02_4_hello_board.md

@@ -1,4 +1,4 @@
-# Hello, board!
+# Hello, Board!
 
 现在我们已准备好进行一致性检查了！
 
@@ -12,7 +12,7 @@ cd intro/hardware-check
 
 ✅ 将 `cfg.toml.example` 复制到 `cfg.toml`（在同一目录中），将实际的 SSID 和 PSK 写入其中：
 
-> ⚠️ [ESP32-C3 不支持 5GHz 频段](https://www.espressif.com/en/news/ESP32-C3_Wi-Fi_Certified#:~:text=ESP32%2DC3%20is%20a%20safe,wide%20range%20of%20IoT%20applications)，你需要确保你使用的 WiFi 具有可用的 2.4GHz 频段。
+> ⚠️ [ESP32-C3 不支持 5 GHz 频段](https://www.espressif.com/en/news/ESP32-C3_Wi-Fi_Certified#:~:text=ESP32%2DC3%20is%20a%20safe,wide%20range%20of%20IoT%20applications)，你需要确保你使用的 Wi-Fi 具有可用的 2.4 GHz 频段。
 
 ```console
 $ cp cfg.toml.example cfg.toml
@@ -56,7 +56,7 @@ I (4427) wifi::wifi: Wifi connected!
 > - 用 `espflash` 构建项目并烧写：`cargo build --release && espflash target/riscv32imc-esp-espidf/release/hardware-check`
 > 为方便起见，这个改动已经应用于本教程的所有项目。
 
-板上的 LED 应在启动时变为黄色，然后根据是否成功建立 Wifi 连接，变为红色（错误），或交替闪烁绿色和蓝色（成功）。如果出现 Wifi 错误，诊断消息也会显示在下面，例如：
+板上的 LED 应在启动时变为黄色，然后根据是否成功建立 Wi-fi 连接，变为红色（错误），或交替闪烁绿色和蓝色（成功）。如果出现 Wi-fi 错误，诊断消息也会显示在下面，例如：
 
 ```console
 Error: could not connect to Wi-Fi network: ESP_ERR_TIMEOUT

book/src/03_0_intro_workshop.md

@@ -3,7 +3,7 @@
 入门教程包含基础的嵌入式开发教学。
 在此教程的结尾，我们将能够与外界环境交互，包括与板上的传感器通讯。入门教程的内容包括：
 - 项目概览
-- 用 cargo generate 生成一个项目。
+- 用 `cargo-generate` 生成一个项目。
 - 编写一个 HTTP 客户端。
 - 编写一个 HTTP 服务器。
 - 编写一个 MQTT 客户端，它能够：

book/src/03_1_project_orga.md

@@ -1,11 +1,11 @@
 # 项目结构
 
-## esp-rs crates
+## `esp-rs` Crate
 
 不像大多数其他嵌入式平台，Espressif 支持 Rust 标准库。其中最值得关注的是，你可以任意使用大小可变的集合，例如 `Vec` 或 `HashMap`，以及基于 `Box` 的通用堆存储。你还可以自由地创建新线程，并使用 `Arc` 和 `Mutex` 等同步原语在它们之间安全地共享数据。
 尽管如此，内存在嵌入式系统上仍然是一种稀缺资源，因此需要注意不要耗尽它——尤其是，使用线程的代价可能会很高。
 
-Espressif 的开源物联网开发框架 [ESP-IDF](https://github.com/espressif/esp-idf) 提供了 WiFi、HTTP 客户端/服务器、MQTT、OTA 更新、日志记录等服务。esp-idf 主要是用 C 编写的，因此将它以规范的、分离的 crate 的形式提供给 Rust：
+Espressif 的开源物联网开发框架 [ESP-IDF](https://github.com/espressif/esp-idf) 提供了 Wi-Fi、HTTP 客户端/服务器、MQTT、OTA 更新、日志记录等服务。esp-idf 主要是用 C 编写的，因此将它以规范的、分离的 crate 的形式提供给 Rust：
 - 一个 `sys` crate 提供了实际的 `unsafe` 绑定（[esp-idf-sys](https://github.com/esp-rs/esp-idf-sys)）
 - 一个高级的 crate 提供了安全易用的 Rust 抽象（[esp-idf-svc](https://github.com/esp-rs/esp-idf-svc/)）
 
@@ -21,7 +21,7 @@ Rust on ESP Book 的 [ecosystem 章节](https://esp-rs.github.io/book/overview/u
 
 ## Package 布局
 
-与使用 `cargo new` 创建的常规 Rust 项目相比，我们还需要一些额外的文件和参数。本教程中的示例和练习都已经配置好，要创建新项目，建议使用基于 [cargo-generate](./03_2_cargo_generate.md) 向导的方法。
+与使用 `cargo new` 创建的常规 Rust 项目相比，我们还需要一些额外的文件和参数。本教程中的示例和练习都已经配置好，要创建新项目，建议使用基于 [`cargo-generate`](./03_2_cargo_generate.md) 向导的方法。
 
 🔎 本页的其余部分是可选知识，在你希望更改项目的某些方面时可以派上用场。
 
@@ -47,4 +47,4 @@ anyhow = "=1.0.71"
 
 - `build.rs` - [Cargo 构建脚本](https://doc.rust-lang.org/cargo/reference/build-scripts.html)。这里设置构建所需的环境变量。
 - `.cargo/config.toml` - 设置目标架构、自定义 runner 来烧写和监视设备、控制构建细节。如果有需要的话，可以在此处覆盖 `ESP_IDF_TOOLS_INSTALL_DIR`。
-- `sdkconfig.defaults` - 覆盖 ESP-IDF 的特定参数，例如堆栈大小、日志级别……
+- `sdkconfig.defaults` - 覆盖 ESP-IDF 的特定参数，例如堆栈大小、日志级别等。

book/src/03_2_cargo_generate.md

@@ -41,7 +41,7 @@ cargo generate https://github.com/esp-rs/esp-idf-template cargo
 `Cargo.toml` 包含依赖项 [导入所有依赖项](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html)。
 
 
-可选，但是推荐：为了节省硬盘空间和下载时间，把[工具链路径设置为全局（global）](https://github.com/esp-rs/esp-idf-sys#esp_idf_tools_install_dir-esp_idf_tools_install_dir)——否则每一个新项目/工作空间都会安装一个自己的工具链实例：
+可选，但是推荐：为了节省硬盘空间和下载时间，把[工具链路径设置为全局（global）](https://github.com/esp-rs/esp-idf-sys#esp_idf_tools_install_dir-esp_idf_tools_install_dir)。否则每一个新项目/工作空间都会安装一个自己的工具链实例：
 
 
 ✅ 打开 `hello-world/.cargo/config.toml` 并添加下面几行到 `[env]` section 的底部。保持其他内容不变。
@@ -81,6 +81,6 @@ Hello, world!
 
 ## Troubleshooting
 - 如果 `cargo run` 卡在了 `Connecting...` 上，可能是因为有另一个监视进程在运行（例如，在刚刚的 `hardware-check` 中打开的）。尝试找到并终止它。如果还是不行，尝试重新连接板子的 USB 线缆。
-- `⛔ Git Error: authentication required`：你的 git 可能被配置为将 `https` github URL 替换成 `ssh`。检查全局 `~/.git/config` 中的 `insteadOf` 部分并禁用它们。
+- `⛔ Git Error: authentication required`：你的 git 可能配置为将 `https` Github URL 替换成 `ssh`。检查全局 `~/.git/config` 中的 `insteadOf` 部分并禁用它们。
 
 [^hint]: 通过在循环中`休眠`而不是忙等待，将控制权交还给底层操作系统。（使用 `std::thread::sleep`）

book/src/03_4_http_server.md

@@ -4,7 +4,7 @@
 
 ## 配置
 
-`intro/http-server/` 中有已准备好的项目框架。它会建立 WiFi 连接，但你需要将其配置为使用 `cfg.toml` 中的网络凭据。
+`intro/http-server/` 中有已准备好的项目框架。它会建立 Wi-Fi 连接，但你需要将其配置为使用 `cfg.toml` 中的网络凭据。
 
 `intro/http-server/examples/https-server.rs` 包含一个解答。你可以用下面的命令运行它：
 
@@ -25,7 +25,7 @@ I (3862) esp_netif_handlers: sta ip: 192.168.178.54, mask: ...
 Server awaiting connection
 ```
 
-`sta ip` 指的是 WiFi 术语站点（station），代表连接到接入点（access point）的接口。这就是你需要输入浏览器的地址（或其他 HTTP 客户端，如 `curl`）。
+`sta ip` 指的是 Wi-Fi 术语站点（station），代表连接到接入点（access point）的接口。这就是你需要输入浏览器的地址（或其他 HTTP 客户端，如 `curl`）。
 
 > 🔎 ESP-IDF 会尝试在本地网络中注册主机名 `espressif`，因此使用 `http://espressif/` 代替 `http://<sta ip>/` 通常也可以。
 >
@@ -68,4 +68,4 @@ server.fn_handler(path, Method::Get, |request| {
 ## Troubleshooting
 
 - `httpd_txrx: httpd_resp_send_err` 可以通过重启解决。如果不起作用，可以使用 `cargo clean`。
-- 确保你的电脑和开发板使用的是相同的 Wifi 网络。
+- 确保你的电脑和开发板使用的是相同的 Wi-Fi 网络。

book/src/03_5_1_mqtt.md

@@ -16,7 +16,6 @@ MQTT 消息由两部分组成——主题（topic）和 payload。
 主题的作用与电子邮件中的主题，或文件柜上的标签相同。而 payload 包含实际的数据。payload 数据的格式没有规定，最常见的是 JSON。
 
 🔎 最新版本的 MQTT 标准（MQTT 5）支持内容的类型元数据。
-
 发送 MQTT 消息时，需要指定一个[服务质量（QoS）](https://en.wikipedia.org/wiki/MQTT#Quality_of_service)，表示这个消息会被传输：
 - 最多一次。
 - 至少一次。

book/src/03_5_2_mqtt.md

@@ -11,7 +11,7 @@
 这个客户端也会生成随机的 RGB 颜色，并把它们发布到一个主题下。
 **这只与练习的第二部分相关**。
 
-⚠️ 与 http 练习类似，你需要在 `cfg.toml` 中为**两个程序**配置连接凭证。除了 WiFi 凭证，还需要添加 MQTT 服务器的信息。查看 `cfg.toml.example` 来了解需要的设置。请记住 `cfg.toml` 文件中括号里的名称就是 `Cargo.toml` 中的包名。
+⚠️ 与 HTTP 练习类似，你需要在 `cfg.toml` 中为**两个程序**配置连接凭证。除了 Wi-Fi 凭证，还需要添加 MQTT 服务器的信息。查看 `cfg.toml.example` 来了解需要的设置。请记住 `cfg.toml` 文件中括号里的名称就是 `Cargo.toml` 中的包名。
 
 练习的结构如下图所示。在这一部分中，我们将重点关注温度主题。
 
@@ -51,7 +51,7 @@ Board temperature: 33.32°C
 使用以下内容构造它：
 - 消息代理的 URL，如果需要的话，还包含连接凭据
 - `esp_idf_svc::mqtt::client::MqttClientConfiguration` 类型的配置信息
-- 与 http 服务器练习类似的处理程序闭包
+- 与 HTTP 服务器练习类似的处理程序闭包
 
 ```rust
 

book/src/03_5_3_mqtt.md

@@ -81,6 +81,7 @@ match message.details() {
 ## 额外的任务
 
 ### 实现具有分层主题的 MQTT
+
 ✅ 如果你已经完成了所有其他工作，可以考虑实现这个任务。我们不提供完整的解答，因为这是用于测试你自己能走多远。
 
 检查 `common/lib/mqtt-messages`：

book/src/04_2_low_level_io.md

@@ -17,7 +17,7 @@ ESP-IDF 主要是用 C 编写的，因此将它以规范的、分离的 crate 
 - 一个高级的 crate 提供了安全易用的 Rust 抽象（[esp-idf-svc](https://github.com/esp-rs/esp-idf-svc/)）
 
 最后一部分是底层硬件访问，仍以分离的形式提供：
-- [esp-idf-hal](https://github.com/esp-rs/esp-idf-hal) 实现了硬件无关的 [embedded-hal](https://github.com/rust-embedded/embedded-hal) traits，例如模数转换、数字 I/O 引脚、SPI 通信。正如它的名字所暗示的，它依赖于 ESP-IDF。
+- [`esp-idf-hal`](https://github.com/esp-rs/esp-idf-hal) 实现了硬件无关的 [`embedded-hal`](https://github.com/rust-embedded/embedded-hal) traits，例如模数转换、数字 I/O 引脚、SPI 通信。正如它的名字所暗示的，它依赖于 ESP-IDF。
 
 _The Rust on ESP Book_ 的 [ecosystem 章节](https://esp-rs.github.io/book/overview/using-the-standard-library.html) 提供了更多信息。
 

book/src/04_3_0_i2c.md

@@ -8,7 +8,7 @@
 
 I²C *事务*由一条或多条*消息*组成。每条*消息*都包含一个*起始信号*、一些*字*，最后是一个*结束信号*（如果有后续消息，则为另一个*起始信号*）。每个字都是八位，后面跟着一个 ACK（0）或 NACK（1）位，由接收方发送，以指示是否正确接收和理解该字。第一个字指示此消息的目标设备的 7 位地址，以及表示要从设备读取还是写入的位。如果总线上没有具有此地址的设备，第一个字后面自然会得到一个 NACK（因为没有设备将 SDA 线驱动为低电平以生成 ACK 位），于是你就可以知道此设备不存在。
 
-SCL 上的时钟频率通常为 400 kHz，但也支持更慢和更快的速度（标准速度为 100kHz-400kHz-1MHz）。在我们的练习中，将配置为 400 kHz（`<MasterConfig as Default>::default().baudrate(400.kHz().into())`）。
+SCL 上的时钟频率通常为 400 kHz，但也支持更慢和更快的速度（标准速度为 100 kHz-400 kHz-1 MHz）。在我们的练习中，将配置为 400 kHz（`<MasterConfig as Default>::default().baudrate(400.kHz().into())`）。
 
 
 
@@ -33,8 +33,8 @@ SCL 上的时钟频率通常为 400 kHz，但也支持更慢和更快的速度
 | 15.  |                      | EEPROM 地址 +2 上的数据字节 |
 | 16.  | NAK（即结束读取）    |                             |
 | 17.  | 结束信号             |                             |
-### I²C 信号图
 
+### I²C 信号图
 
 <p style="text-align:center;"><img src="./assets/I2C_data_transfer.svg" width="100%"></p>
 

book/src/04_3_1_i2c.md

@@ -41,7 +41,7 @@ cargo doc --open
 | SDA    | GPIO10 |
 | SCL    | GPIO8  |
 
-✅ 借助刚刚生成的文档，创建一个 I²C 外设的实例。频率使用 400kHz。
+✅ 借助刚刚生成的文档，创建一个 I²C 外设的实例。频率使用 400 kHz。
 
 ✅ 使用驱动 crate `shtcx`，创建一个 SHTC3 传感器实例，将 I²C 实例传递给它们。查看文档以获取指导。
 

book/src/04_3_2_i2c.md

@@ -104,7 +104,7 @@ where
 
 ### 🔎 有关外设寄存器的一般信息
 
-寄存器可以有不同的含义；本质上，它们是**一个可以存储值的位置**。
+寄存器可以有不同的含义，本质上，它们是**一个可以存储值的位置**。
 
 在这个特定的上下文中，我们使用的是一个外部设备（因为它是一个传感器，即使与主控芯片在同一块 PCB 上）。它可通过 I2C 寻址，我们在读取和写入其寄存器的地址。每个地址都标识了唯一的一个位置，其中包含了一些信息。在这种情况下，我们想要的是包含当前温度的位置的地址。
 

book/src/04_3_3_i2c.md

@@ -36,7 +36,7 @@
 
 <Details>
     <Summary>解答</Summary>
-原因在于 I²C 协议的特性：我们需要先在 I²C 总线上写一个命令，来指定我们想要读取哪个寄存器。
+原因在于 I²C 协议的特性。我们需要先在 I²C 总线上写一个命令，来指定我们想要读取哪个寄存器。
 </Details>
 
 ✅ 给传感器实例定义 `read_register` 和 `write_register` 方法。使用 `embedded-hal` crate 提供的方法。它们将作为更具体的方法的基础，并作为一个抽象层，用于适配具有 8 位寄存器的传感器。这意味着，读取和写入的数据都是无符号8位的整数。这些辅助方法可以保持私有，因为我们不需要从这个 crate 外访问它们。