From 9927b798610d884605553e71ba7384a03f08d46f Mon Sep 17 00:00:00 2001 From: ArcticLampyrid Date: Sun, 6 Oct 2024 02:41:43 +0800 Subject: [PATCH] docs: add Chinese documents --- docs/README-zh.md | 40 +++++++++++++++++ docs/README.md | 4 ++ docs/Tutorial-zh.md | 105 ++++++++++++++++++++++++++++++++++++++++++++ docs/Tutorial.md | 6 ++- 4 files changed, 154 insertions(+), 1 deletion(-) create mode 100644 docs/README-zh.md create mode 100644 docs/Tutorial-zh.md diff --git a/docs/README-zh.md b/docs/README-zh.md new file mode 100644 index 0000000..66a9e4d --- /dev/null +++ b/docs/README-zh.md @@ -0,0 +1,40 @@ +# STM32Tesseract +Choose your language: +- [English](https://github.com/ArcticLampyrid/stm32tesseract/blob/main/docs/README.md) +- [简体中文](https://github.com/ArcticLampyrid/stm32tesseract/blob/main/docs/README-zh.md) + +STM32Tesseract 是一个旨在将 STM32CubeMX 生成的代码与现代 IDE 和构建系统无缝集成的工具。 + +## 组件 + +### 命令行界面 (CLI) +这是为 STM32Tesseract 设计的命令行界面，允许通过终端命令直接和脚本化控制。 + +
+ +图形用户界面使用 Slint 构建。 + +### 图形用户界面 (GUI) +该图形用户界面封装了 CLI 的功能，提供了更用户友好和更直观的交互方式。 + +
+ +## 动机 +尽管 STM32CubeMX 是一个出色的 STM32 项目初始化工具，但它在支持现代、用户友好型工具链方面经常显得不足。STM32Tesseract 旨在弥补这一缺口，通过促进与现代 IDE 和构建系统的集成来增强开发体验。 + +## 功能 +- **CMake 集成**：轻松与 CMake 集成，简化构建过程。 +- **构建环境设置**：提供一个简单的方法来配置构建环境。 +- **VSCode 项目设置**：简化在 Visual Studio Code 中设置项目的过程。 +- **CLion 项目设置**：轻松配置 CLion 项目。 + +## 使用方法 +详细说明请参见 [教程](https://github.com/ArcticLampyrid/stm32tesseract/blob/main/docs/Tutorial-zh.md)。 + +## 构建 +*注意：以下说明仅适用于 STM32Tesseract 开发人员。* + +STM32Tesseract 使用 Cargo 作为其构建系统。要构建项目，请在项目根目录下执行 `cargo build`。 + +## 许可 +STM32Tesseract 根据 [BSD 3-Clause License](https://github.com/ArcticLampyrid/stm32tesseract/blob/main/LICENSE.md) 许可发布。 diff --git a/docs/README.md b/docs/README.md index 872e6dd..60284d6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,8 @@ # STM32Tesseract +Choose your language: +- [English](https://github.com/ArcticLampyrid/stm32tesseract/blob/main/docs/README.md) +- [简体中文](https://github.com/ArcticLampyrid/stm32tesseract/blob/main/docs/README-zh.md) + STM32Tesseract is a utility designed to seamlessly integrate STM32CubeMX-generated code with contemporary IDEs and build systems. ## Components diff --git a/docs/Tutorial-zh.md b/docs/Tutorial-zh.md new file mode 100644 index 0000000..2ce5cfc --- /dev/null +++ b/docs/Tutorial-zh.md @@ -0,0 +1,105 @@ +# STM32Tesseract 教程 +Choose your language: +- [English](https://github.com/ArcticLampyrid/stm32tesseract/blob/main/docs/Tutorial.md) +- [简体中文](https://github.com/ArcticLampyrid/stm32tesseract/blob/main/docs/Tutorial-zh.md) + +## 配置构建环境 +1. 启动 `stm32tesseract-gui`。 +2. 进入 `Environment` 标签。 +3. 点击 `Up` 按钮以初始化构建环境。 +4. 程序将自动下载必要的工具链并配置环境变量。 +5. ***重启电脑以激活新的环境变量。*** + +_注意：可能需要管理员权限。_ + +## 生成项目 +1. 使用 STM32CubeMX 创建一个项目。 +2. 进入 `Project Manager > Project > Project Settings > Toolchain / IDE > STM32CubeIDE`。 + ![示例：选择 STM32CubeIDE 工具链](SelectSTM32CubeIDEToolchain.png) +3. 使用 STM32CubeMX 生成代码。 +4. 打开 `stm32tesseract-gui`。 +5. 切换到 `Tesseract` 标签。 +6. 选择 `.cproject` 文件。 +7. 点击 `Act` 按钮启动项目生成。 + ![示例：操作 .cproject 文件](STM32Tesseract-Act.png) +8. CMake 项目以及 VSCode 和 CLion 的配置文件将生成在 `.cproject` 文件所在的目录中。 + +## 使用生成的项目 +### VSCode +#### 构建项目 +1. 在 VSCode 中打开项目目录。 +2. 安装推荐的扩展。 +3. 打开命令面板并执行 `CMake: Select Configure Preset`，然后选择一个选项（例如 `gcc`）。 +4. 再次打开命令面板并执行 `CMake: Select Build Preset`，然后选择一个选项（例如 `MinSizeRel`）。 +5. 执行 `CMake: Build`（或按 F7）以构建项目。 + +#### 运行项目 +1. 打开命令面板并执行 `Tasks: Run Task`。 +2. 选择 `Download (OpenOCD)` 将程序上传到板子上。 +3. 如果你使用的是 ST-Link 而不是 CMSIS-DAP，请修改 `openocd.cfg` 中的配置。 + +_提醒：_ +- **避免使用 CMake Tools 状态栏中的启动按钮，可能会有问题。** + +#### 调试 +1. 打开运行和调试面板。 +2. 选择 `Debug (OpenOCD)` 或 `Debug (JLink)`。 +3. 对于使用 ST-Link 的用户，请修改 `openocd.cfg` 中的配置。 +4. JLink 用户需在 `launch.json` 中定义 JLink GDB 服务器的路径。 + +_提醒：_ +- **避免使用 CMake Tools 状态栏中的调试按钮，可能会有问题。** +- 常用设备的 SVD 文件已预配置，故外设寄存器可以在运行和调试面板中查看。 + +### CLion +#### 初始设置 +如果首次使用 CLion： + +1. 进入 `File > Settings` 或使用快捷键 `Ctrl + Alt + S`。 +2. 前往 `Build, Execution, Deployment > Embedded Development`。 +3. 定义 OpenOCD 可执行文件和 STM32CubeMX 可执行文件的路径。 + ![示例：设置 OpenOCD 和 STM32CubeMX](CLionEmbeddedDevelopmentSettings.png) +4. 点击 `Apply` 然后 `OK`。 + +#### 构建项目 +1. 在 CLion 中打开项目目录。 +2. 点击 `Build` 或按 `Ctrl + F9`。 + +#### 运行项目 +1. 选择运行配置：`OCD {项目名称}`。 +2. 点击 `Run` 或按 `Shift + F10`。 +3. ST-Link 用户需要修改 `openocd.cfg` 中的配置。 + +#### 调试 +1. 选择运行配置：`OCD {项目名称}` 或 `JLink`。 +2. 点击 `Debug` 或按 `Shift + F9`。 +3. ST-Link 用户需要调整 `openocd.cfg` 中的配置。 +4. JLink 用户需通过编辑运行配置指定 JLink GDB 服务器路径。 + ![示例：编辑运行配置](CLionEditRunConfigurations.png) + ![示例：设置 JLink 路径](CLionEditJLinkPath.png) + +_注意：CLion 不会自动配置 SVD 文件。需手动下载并加载 SVD 文件以查看外设寄存器。_ + +## 配置 OpenOCD +默认的 OpenOCD 配置是为 CMSIS-DAP 设置的。使用 ST-Link 的用户需要修改 `openocd.cfg`。 + +替换： +```cfg +source [find interface/cmsis-dap.cfg] # CMSIS-DAP +``` +为以下之一，取决于你的 ST-Link 版本： +```cfg +source [find interface/stlink.cfg] # ST-Link V1 +source [find interface/stlink-v2.cfg] # ST-Link V2 +source [find interface/stlink-v3.cfg] # ST-Link V3 +``` + +## 选择构建预设 +可用的构建预设： + +- `Debug`：用于调试。 +- `Release`：为速度优化，没有调试信息。 +- `MinSizeRel`：为较小体积优化。 +- `RelWithDebInfo`：优化的发布版本，带有调试信息。 + +例如，选择 `MinSizeRel` 来减少程序大小，或选择 `Debug`/`RelWithDebInfo` 进行调试。 \ No newline at end of file diff --git a/docs/Tutorial.md b/docs/Tutorial.md index 1624519..7cd39bc 100644 --- a/docs/Tutorial.md +++ b/docs/Tutorial.md @@ -1,4 +1,8 @@ # STM32Tesseract Tutorial +Choose your language: +- [English](https://github.com/ArcticLampyrid/stm32tesseract/blob/main/docs/Tutorial.md) +- [简体中文](https://github.com/ArcticLampyrid/stm32tesseract/blob/main/docs/Tutorial-zh.md) + ## Setting Up the Build Environment 1. Launch `stm32tesseract-gui`. 2. Navigate to the `Environment` tab. @@ -45,7 +49,7 @@ _Reminders:_ _Reminders:_ - **Refrain from using the debug button on CMake Tools' status bar due to potential issues.** -- SVD files for command devices are pre-configured. Peripheral registers can be viewed in the Run and Debug panel. +- SVD files for common devices are pre-configured. Peripheral registers can be viewed in the Run and Debug panel. ### CLion #### Initial Setup