Skip to content

Commit

Permalink
完善ide-debug帮助文档
Browse files Browse the repository at this point in the history
  • Loading branch information
@ComerLater
ComerLater committed Jun 7, 2024
1 parent e7181e4 commit cba1980
Show file tree
Hide file tree
Showing 4 changed files with 42 additions and 202 deletions.
2 changes: 1 addition & 1 deletion docs/develop/01.快速入门/01.setup-develop-environment.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# 搭建开发环境

NextPilot 基于 [RT-Thread](https://www.rt-thread.org/) 实时操作系统而打造的，为了便捷的进行 NextPilot 项目开发，技术团队在 [RT-Thread ENV-Windows](https://www.rt-thread.org/document/site/#/development-tools/env/env) 基础上重新制作了 `nextpilot-windows-toolchain`([github](https://github.com/nextpilot/nextpilot-windows-toolchain.git) | [gitee](https://github.com/nextpilot/nextpilot-windows-toolchain.git)) 和 `nextpilot-ubuntu-toolchain`([github](https://github.com/nextpilot/nextpilot-ubuntu-toolchain.git) | [gitee](https://github.com/nextpilot/nextpilot-ubuntu-toolchain.git))，他们相当于 [RT-Thread ENV-Windows](https://github.com/RT-Thread/env-windows) 的定制升级版。
NextPilot 基于 [RT-Thread](https://www.rt-thread.org/) 实时操作系统而打造的，为了便于高效的进行 NextPilot 项目开发，技术团队在 [RT-Thread ENV-Windows](https://www.rt-thread.org/document/site/#/development-tools/env/env) 基础上重新制作了 `nextpilot-windows-toolchain`([github](https://github.com/nextpilot/nextpilot-windows-toolchain.git) | [gitee](https://github.com/nextpilot/nextpilot-windows-toolchain.git)) 和 `nextpilot-ubuntu-toolchain`([github](https://github.com/nextpilot/nextpilot-ubuntu-toolchain.git) | [gitee](https://github.com/nextpilot/nextpilot-ubuntu-toolchain.git))，他们相当于 [RT-Thread ENV-Windows](https://github.com/RT-Thread/env-windows) 的定制升级版。

`nextpilot-xxxx-toolchain` 集成或自动安装了以下工具：

Expand Down
3 changes: 2 additions & 1 deletion docs/develop/01.快速入门/02.build-code.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ git clone https://github.com/nextpilot/nextpilot-flight-control.git

## 配置项目

> 注意：该功能仅用于开发者
> 注意：该功能仅限开发者
C/C++语言项目的裁剪配置本质上通过条件编译和宏的展开来实现的，nextpilot 借助 Kconfig 这套机制更方便的实现了这一功能。

Expand Down Expand Up @@ -58,6 +58,7 @@ scons default -j8

!!! note
每个`bsp`都可能包含多个`目标（target）`，比如`default`、`fw`、`mc`等，`target`配置保存在`config/xxxx.config`文件夹，一个`xxxx.config`就是一个`target`，`xxxx.config`本质是一个`kconfig`配置保存文件。

在运行`scons`的时候，如果指定了`target`，那么会先根据`config/target.config`生成`rtconfig.h`文件，如果没有指定`target`则使用当前的`rtconfig.h`文件。

## 飞行仿真
Expand Down
235 changes: 37 additions & 198 deletions docs/develop/01.快速入门/03.ide-debug.md
View file
Original file line number Diff line number Diff line change
@@ -1,20 +1,21 @@
# 断点单步调试

NextPilot支持 MDK 和 VS Code 两种集成开发环境，推荐使用VS Code。两者都是通过scons工具生成相应的 Keil 工程和VS Code配置。
NextPilot支持 Keil5 MDK 和 VSCode 两种集成开发环境，两者都是先通过scons工具生成相应的 Keil 工程和 VSCode 配置，然后再使用 IDE 进行编译、调试、烧录等。

本节着重讲解如何基于vscode配置stm32开发的IDE环境，实现对飞控工程的开发、编译、烧写、调试。
> 注意：飞行仿真sitl/qemu只支持Vscode+Gcc，不支持keil；普通STM32程序支持Vscode和Keil，但是推荐Keil。
在使用之前，请[按照教程安装开发工具链](./1-toolchain.md)。
Vscode一款很好的编辑器，拥有极强的扩展性，因此推荐使用VScode进行代码编辑，至于编译和调试可以根据个人喜好了。

## MDK
## Keil5 MDK

### 生成Keil工程

通过scons工具直接生成keil工程，然后用MDK进行调试。
通过 scons 工具直接生成 keil 工程，然后用MDK进行开发。

```
# 切换target目录
cd nextpilot-flight-control/bsps/fcs-v4
cd nextpilot-flight-control/bsps/fcs-v1
# 生成keil工程，然后使用mdk进行调试
scons --target=mdk5
```
Expand All @@ -23,60 +24,57 @@ scons --target=mdk5

> 注意：MDK建议使用V5.38版本，编译器采用ARMCLANG v6.19，开启支持C++14。
用keil打开nextpilot-flight-control/bsps/fcs-v4/project.uvprojx，接下来就可以愉快的使用Keil进行项目的开发了。
用 keil 打开 nextpilot-flight-control/bsps/fcs-v1/project.uvprojx，接下来就可以愉快的使用Keil进行项目的开发了。

## VS Code

VS Code（全称 [Visual Studio Code](https://azure.microsoft.com/zh-cn/products/visual-studio-code/)）是一个轻量且强大的代码编辑器，支持 Windows，OS X 和 Linux。内置 JavaScript、TypeScript 和 Node.js 支持，而且拥有丰富的插件生态系统，可通过安装插件来支持 C++、C#、Python、PHP 等其他语言。NextPilot 项目推荐使用[Visual Stuio Code](https://azure.microsoft.com/zh-cn/products/visual-studio-code/)作为主要开发**编辑和调试工具**。
VS Code（全称 [Visual Studio Code](https://azure.microsoft.com/zh-cn/products/visual-studio-code/)）是一个轻量且强大的代码编辑器，支持 Windows，OS X 和 Linux。内置 JavaScript、TypeScript 和 Node.js 支持，而且拥有丰富的插件生态系统，可通过安装插件来支持 C++、C#、Python、PHP 等其他语言。

### VSC环境配置
### 安装和配置

#### 安装VS Code
下载[Visual Stuio Code](https://azure.microsoft.com/zh-cn/products/visual-studio-code/)，一路默认安装即可。然后使用vscode打开`nextpilot-flight-control.code-workspace`，如果是第一次打开会提醒您安装`推荐扩展`，一定要点`确定`哈，会自动安装以下扩展：

下载[Visual Stuio Code](https://azure.microsoft.com/zh-cn/products/visual-studio-code/)，一路默认安装即可。并且需要在 VS Code Extensions 里下载并安装必要的插件。插件安装很简单，只要在左侧工具栏点击扩展，搜索插件并点击安装即可。
- ms-ceintl.vscode-language-pack-zh-hans
- ms-vscode.cpptools
- ms-vscode.cpptools-extension-pack
- ms-vscode.cpptools-themes
- ms-python.python
- ms-python.debugpy
- ms-python.black-formatter
- ms-vscode.vscode-embedded-tools
- marus25.cortex-debug
- rt-thread.rt-thread-studio
- nordic-semiconductor.nrf-kconfig
- DavidAnson.vscode-markdownlint
- samuelcolvin.jinjahtml
- tamasfe.even-better-toml
- redhat.vscode-yaml

- c/c++，微软官方的c/c++开发插件；
- Cortex-Debug，主要用于调试，嵌入式调试需要用的插件；
- RT-Thread Studio，主要用于工程配置，rt-thread提供的vscode插件，该插件提供了必要的GUI工具，提供打开工程、编译、下载、调试等按钮，在VS Code中调用scons编译项目；
- Doxygen Documentation Generator，自动生成文件和函数注释
- git-commit-plugin，规范化编写git commit消息
- Todo Tree，添加和查看代码中的TODO
当然您也可以手动安装相应的扩展，比如：

![](./image/vscode-install-plugin.png)

安装好后确认插件为以下状态，如果不是则点击重新加载：

![](./image/vscode-plugin-status.png)

#### 配置环境变量

在使用vscode进行开发和调试之前需要生成各工程必要的配置文件，这些配置文件都在各bsp目录下的.vscode中（如setting.json、launch.json文件），为了提高工作效率，我们提供了自动化工具进行配置文件的生成。但是自动化脚本依赖两个环境变量`ENV_PATH`和`RTT_STUDIO_PATH`

这里以Windows为例讲解如何添加环境变量。 进入高级系统设置，打开环境变量，在用户变量列表中添加如下三个环境变量：

- Env_Path: ENV工具路径；
- RTT_Studio_Path: RT-Thread Studio安装路径；
- SVD_File: 对应型号芯片的svd文件路径（需要安装对应的芯片包）；

![](image\environment_variable.png)

### 硬件开发与调试
### 编译和调试

#### 打开工作区

双击项目根目录下的`nextpilot-flight-control.code-workspace`即可打开工作区。如下图所示：
双击根目录下的`nextpilot-flight-control.code-workspace`即可打开VSCode工作区。如下图所示：

![image-20230420172023916](image\vscode_open_ws.png)

#### 选择FCS工程
#### 选择工程

进行硬件开发和调试的bsp目录为target/sitl/qemu，在打开项目工作区后，点击rt-thread插件，选择qemu工程，如下图所示：
在打开工作区后，点击左侧 RT-Thread Studio插件，选择一个bsp工程，比如`qemu-vexpress-a9`，如下图所示：

![image-20230420172023916](image\vscode_fcs_project.png)

将鼠标放置到fcs工程，会自动弹出开发工具栏图标，包括了编译、烧写、调试、擦除，这些图标由RT-Thread插件提供，用于与用户进行交互，但点击这些按钮图标可能报错，因为每个开发者的计算机环境可能不一样，故我们需要对工程进行必要配置才能使用。
将鼠标放置到 qemu 工程，会自动弹出开发工具栏图标，包括了编译、烧写、调试、擦除，在使用这些功能之前，需要配置下`.vscode/setting.json`和`.vscode/launch.json`文件，不过 nextpilot 已经为您做好了这一切，您只要在`qemu-vexpress-a9`目录下运行`scons`会自动帮您生成所需的配置文件。

#### 编译
#### 编译工程

配置完成后，点击编译按钮，即可进行工程编译。

Expand All @@ -86,185 +84,26 @@ VS Code（全称 [Visual Studio Code](https://azure.microsoft.com/zh-cn/products

![](image\vscode_terminal.png)

#### 烧写
#### 烧写程序

完成编译后，点击烧写按钮，即可进行固件烧写。

![image-20230420172023916](image\vscode_download.png)

烧写打印结果如下图所示：

<img src="image\vscode_download_result.png" style="zoom:75%;" />
![](image\vscode_download_result.png)

> 要想固件正常运行，一定要提前烧写bootloader。具体请参考。
#### 调试
#### 单步调试

按调试按钮，或者按F5，可以进行调试。

![](image\vscode_debug.png)

> 特别注意，只有BUILD选项为'debug'时才能够进行调试。
>
> 注意：只有BUILD选项为'debug'时才能够进行调试。
进入调试后的效果如下图所示：

![](image\vscode_debug_ing.png)

### 自动脚本原理

使用RT-Thread Studio插件，点击编译、下载、调试按钮时，会自动运行自动化脚本，生成配置文件。自动化脚本工具所在目录为`nextpilot-flight-control/tools/building`，该目录文件介绍如下：

```shell
|-- nextpilot-flight-control/tools/building/
|-- vscode_template/
|-- xxxx.json.jinja # 配置文件模板
|-- settings_gen.py # 运行脚本，基于模板生成配置文件
```

RT-Thread Studio插件，点击编译的时候，其实是执行了`scons -j xx`命令，因此只要在Sconstruct中调用自动化脚本，就能够自动生成编译、烧写和调试所需的配置文件。

FCS工程目录下的.vscode文件夹中包含两个配置文件`launch.json`与`settings.json`，这两个文件由于在工程目录下，故仅仅对当前工程目录有效。

#### settings.json

settings.json文件主要用于配置工具链，如ENV路径、交叉编译器路径、调试下载器路径等。由于每个开发者相关工具安装路径不一样，故需要针对性修改。

**RTT-Studio插件主要配置参数解释如下：**

- "RTT_Studio.Build.Parallel_Jobs": "20"

多进程编译作业，同时编译作业数量指定为20，相当于make -j20。 【开发者根据自己计算机性能调整】

- "RTT_Studio.RTT_ROOT": "../../../rtos/rt-thread"

指定RTT根目录。【使用默认值即可】

- "RTT_Studio.Env_Location": "C:\\env-windows-v1.3.5"

指定ENV工具路径。这里ENV为单独下载的，当然也可以指定RT-Thread Studio安装目录下的（不推荐，因为版本可能较老）。 【开发者根据自己计算机软件安装路径调整】

- "RTT_Studio.Toolchain_Location": "C:\\env-windows-v1.3.5\\tools\\gnu_gcc\\arm_gcc\\mingw\\bin"

指定交叉编译工具路径。 【开发者根据自己计算机软件安装路径调整】

- "RTT_Studio.Debuger.Bin_File": "build/sitl-qemu-default.bin"

编译后用于烧写的bin。【使用默认值即可】

- "RTT_Studio.Debuger.Executable_File": "build/sitl-qemu-default.elf"

调试中需要使用的elf。【使用默认值即可】

- "RTT_Studio.Debuger.Adapter": "ST-Link"

选择调试器，这里开发调试硬件为st-link，故需要选择ST-Link，如果开发者只有JLink调试器，则需要更改为“J-Link"。 【开发者根据自己硬件调试器调整】.

- "RTT_Studio.Debuger.Gdb_Path": "C:\\env-windows-v1.3.5\\tools\\gnu_gcc\\arm_gcc\\mingw\\bin\\arm-none-eabi-gdb.exe"
设置gdb路径。【开发者根据自己硬件调试器调整】

- "RTT_Studio.Debuger.stlinkGdbServerExecutable": "D:/RT-ThreadStudio/repo/Extract/Debugger_Support_Packages/STMicroelectronics/ST-LINK_Debugger/1.6.0/ST-LINK_gdbserver.exe"

设置st-link调试服务器程序路径。【开发者根据自己硬件调试器调整】

- "RTT_Studio.Debuger.JLink.Device": "STM32F765II"

- "RTT_Studio.Debuger.jlinkGdbServerExecutable": "D:/RT-ThreadStudio/repo/Extract/Debugger_Support_Packages/SEGGER/J-Link/v7.50a/JLinkGDBServerCL.exe"

设置st-link调试服务器程序路径。【开发者根据自己硬件调试器调整】

- "RTT_Studio.Debuger.SVD_File": "C:\\Users\\alex\\AppData\\Local\\Arm\\Packs\\Keil\\STM32F7xx_DFP\\2.14.0\\CMSIS\\SVD\\STM32F765.svd"

- "RTT_Studio.Debuger.Generate_Configuration_Automatically": false

不需要自动生成launch.json文件。

**cortex-debug调试设置参数解释如下：**

- "cortex-debug.armToolchainPath": "C:\\env-windows-v1.3.5\\tools\\gnu_gcc\\arm_gcc\\mingw\\bin"

arm工具链路径。【开发者根据自己计算机软件安装路径调整】

- "cortex-debug.stlinkPath": "D:/RT-ThreadStudio/repo/Extract/Debugger_Support_Packages/STMicroelectronics/ST-LINK_Debugger/1.6.0/ST-LINK_gdbserver.exe"

stlink调试服务器路径，如果开发者调试烧写器为ST-Link时有效。【开发者根据自己计算机软件安装路径调整】

- "cortex-debug.JLinkGDBServerPath": "D:/RT-ThreadStudio/repo/Extract/Debugger_Support_Packages/SEGGER/J-Link/v7.50a/JLinkGDBServerCL.exe"

jlink调试服务器路径，如果开发者调试烧写器为J-Link时有效。【开发者根据自己计算机软件安装路径调整】

#### launch.json

launch.json文件主要用于配置调试工具，可以同时配置多种调试工具，在调试时根据实际情况选择即可。

- "name": "Cortex Debug-stlink"

- "cwd": "${workspaceFolder}"

- "executable": "./build/sitl-qemu-default.elf"

- "request": "launch"

- "type": "cortex-debug"

- "runToEntryPoint": "main"

- "servertype": "stlink"

gdb-server类型，根据调试烧写器来选择。

- "device": "STM32F765II"

- "svdFile": "C:\\Users\\alex\\AppData\\Local\\Arm\\Packs\\Keil\\STM32F7xx_DFP\\2.14.0\\CMSIS\\SVD\\STM32F765.svd"

#### 配置示例-stlink

当使用的硬件烧写下载器为stlink时，以下为配置示例：

settings.json

```json
{
/**
* RTT-Studio插件设置
*/
"RTT_Studio.Build.Parallel_Jobs": "20",
"RTT_Studio.RTT_ROOT": "../../../rtos/rt-thread",
"RTT_Studio.Env_Location": "C:\\env-windows-v1.3.5",
"RTT_Studio.Toolchain_Location": "C:\\env-windows-v1.3.5\\tools\\gnu_gcc\\arm_gcc\\mingw\\bin",
"RTT_Studio.Debuger.Bin_File": "build/sitl-qemu-default.bin",
"RTT_Studio.Debuger.Executable_File": "build/sitl-qemu-default.elf",
"RTT_Studio.Debuger.Adapter": "ST-Link",
"RTT_Studio.Debuger.Gdb_Path": "C:\\env-windows-v1.3.5\\tools\\gnu_gcc\\arm_gcc\\mingw\\bin\\arm-none-eabi-gdb.exe",
"RTT_Studio.Debuger.stlinkGdbServerExecutable": "D:/RT-ThreadStudio/repo/Extract/Debugger_Support_Packages/STMicroelectronics/ST-LINK_Debugger/1.6.0/ST-LINK_gdbserver.exe",
"RTT_Studio.Debuger.SVD_File": "C:\\Users\\alex\\AppData\\Local\\Arm\\Packs\\Keil\\STM32F7xx_DFP\\2.14.0\\CMSIS\\SVD\\STM32F765.svd",
"RTT_Studio.Debuger.Generate_Configuration_Automatically": false,
/**
* cortex-debug调试设置
*/
"cortex-debug.armToolchainPath": "C:\\env-windows-v1.3.5\\tools\\gnu_gcc\\arm_gcc\\mingw\\bin",
"cortex-debug.stlinkPath": "D:/RT-ThreadStudio/repo/Extract/Debugger_Support_Packages/STMicroelectronics/ST-LINK_Debugger/1.6.0/ST-LINK_gdbserver.exe",
}
```

launch.json

```json
{
"version": "0.2.0",
"configurations": [
{
"name": "Cortex Debug-stlink", // 给新增的调试命名，后续可以在vs code调试工具栏中选择
"cwd": "${workspaceFolder}",
"executable": "./build/sitl-qemu-default.elf", // 要调试的固件（根据实际情况选择）
"request": "launch",
"type": "cortex-debug", // 调试类型为cortex-debug
"runToEntryPoint": "main", // 启动调试后，在main函数入口暂停
"servertype": "stlink", // gdb-server类型
"device": "STM32F765II", // stm32芯片类型
"svdFile": "C:\\Users\\alex\\AppData\\Local\\Arm\\Packs\\Keil\\STM32F7xx_DFP\\2.14.0\\CMSIS\\SVD\\STM32F765.svd"
},
],
"enable": true
}
```
4 changes: 2 additions & 2 deletions docs/develop/01.快速入门/99.add-new-code.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,13 +67,13 @@ MSH_CMD_EXPORT_ALIAS(hello_world_main, hello, hello world demo);
## 添加 Kconfig 文件
```
```kconfig
menuconfig APP_USING_HELLO_WORLD
bool "hello world demo"
default n
if APP_USING_HELLO_WORLD
APP_USING_HELLO_WORLD
#
endif
```
Expand Down

0 comments on commit cba1980

Please sign in to comment.