Skip to content

Commit

Permalink
docs: add Chinese documents
Browse files Browse the repository at this point in the history
  • Loading branch information
ArcticLampyrid committed Oct 5, 2024
1 parent f97ff5d commit 9927b79
Show file tree
Hide file tree
Showing 4 changed files with 154 additions and 1 deletion.
40 changes: 40 additions & 0 deletions docs/README-zh.md
Original file line number Diff line number Diff line change
@@ -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 设计的命令行界面,允许通过终端命令直接和脚本化控制。

<div>

<img align="right" src="https://cdn.jsdelivr.net/gh/slint-ui/slint/logo/madewithslint/madewithslint-logo-dark/madewithslint-logo-dark.svg" alt="图形用户界面使用 Slint 构建。">

### 图形用户界面 (GUI)
该图形用户界面封装了 CLI 的功能,提供了更用户友好和更直观的交互方式。

</div>

## 动机
尽管 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) 许可发布。
4 changes: 4 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
105 changes: 105 additions & 0 deletions docs/Tutorial-zh.md
Original file line number Diff line number Diff line change
@@ -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` 进行调试。
6 changes: 5 additions & 1 deletion docs/Tutorial.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 9927b79

Please sign in to comment.