编译和下载工程 |

概述

本章在软件安装已完成的环境上，使用 VSCode 连接 WSL，确认工具链可用，拉取官方基础工程并完成第一次编译。

🎯本页目标编译基础工程生成 `9Mod_MCPBorad.bin` 固件，并用 ST-Link 下载到开发板。

🧰前置条件① 已完成 [软件安装](./software-setup)（WSL、VSCode、工具链均就绪）② 已完成 [STM32 CMake 工程创建](./cmake-project)。

🔗相关章节工程配置完成后，进入 [emMCP 移植](./emmcp-porting) 接入 AI 通信框架。

①

第一次编译

在基础工程目录 DOCS_TEST1 下，先做一步配置，再编译（两种方式任选）。

💡 提示（必做，只需一次）：官方基础工程默认只生成 9Mod_MCPBorad.elf，烧录需要 .bin。在工程根目录的顶层文件 ~/DOCS_TEST1/CMakeLists.txt（与 9Mod_MCPBorad.ioc 同目录）末尾追加以下内容（CubeMX 不会重新生成此文件，可放心修改）：

# Generate .bin and .hex files after build
add_custom_command(TARGET ${CMAKE_PROJECT_NAME} POST_BUILD
    COMMAND ${CMAKE_OBJCOPY} -O binary $<TARGET_FILE:${CMAKE_PROJECT_NAME}> ${CMAKE_PROJECT_NAME}.bin
    COMMAND ${CMAKE_OBJCOPY} -O ihex $<TARGET_FILE:${CMAKE_PROJECT_NAME}> ${CMAKE_PROJECT_NAME}.hex
    COMMENT "Generating .bin and .hex files"
)

CMakeLists.txt 末尾追加 POST_BUILD

保存即可，之后的每次编译都会自动生成 9Mod_MCPBorad.bin。

在基础工程目录 DOCS_TEST1 下，有两种编译方式：

方法一：VSCode CMake 插件图形化编译（推荐）

点击 VSCode 左侧活动栏的 CMake 图标（CMake Tools 插件）。
在侧边栏 CMake 面板中，将构建预设（Build Preset）选择为 Debug（也可点击底部状态栏的 CMake 区域切换）。
点击 Build（编译）按钮，等待编译完成，输出面板显示成功。

方法二：命令行编译

# 1. 配置：读取 CMakePresets.json，生成 Ninja 构建脚本
cmake --preset Debug

# 2. 构建：编译链接几百个源文件为最终固件
cmake --build build/Debug

编译成功输出示例（行数因环境而异）：

[xx/xx] Linking C executable 9Mod_MCPBorad.elf
Memory region         Used Size  Region Size  %age Used
         RAM:       16xxx B        20 KB     xx%
       FLASH:       98xxx B       128 KB     xx%

确认产物：

ls -la build/Debug/

编译产物文件

确认产物：build/Debug/ 下应有 9Mod_MCPBorad.elf、9Mod_MCPBorad.bin、9Mod_MCPBorad.hex 三个文件（.bin/.hex 由 POST_BUILD 自动生成）。

产物名来自 CMakeLists.txt 的 set(CMAKE_PROJECT_NAME 9Mod_MCPBorad)，本教程所有命令均按此产物名编写。

②

下载程序到开发板（烧录）

接线：ST-Link 与开发板通过 SWD 连接，对应关系如下：

ST-Link	开发板	说明
SWDIO	PA13	数据线
SWCLK	PA14	时钟线
GND	GND	共地
3.3V	3.3V（可不接）	板子自身供电时可不接

ST-Link 接线图

打开 Seahi-Serial，配置 WSL 映射（烧录前必做）

WSL2 默认访问不到 Windows 的 USB 设备，需要先把 ST-Link 映射进 WSL：

打开 Seahi-Serial 软件（软件安装步骤⑤已装）。
在设备列表中找到 ST-Link 对应的 USB 设备（或 COM 口）。
点击映射到 WSL（挂载进 WSL），状态显示已映射即可。

映射后 WSL 内才能识别 ST-Link；若烧录时提示无法连接，先检查此步骤。

Seahi-Serial 映射 ST-Link 到 WSL

烧录（VSCode Cortex-Debug 图形化，已装插件）

在工程根目录创建 .vscode/launch.json（内容如下）：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "烧录并调试 STM32F103 (OpenOCD)",
            "cwd": "${workspaceFolder}",
            "executable": "${workspaceFolder}/build/Debug/9Mod_MCPBorad.elf",
            "request": "launch",
            "type": "cortex-debug",
            "servertype": "openocd",
            "configFiles": ["interface/stlink.cfg", "target/stm32f1x.cfg"],
            "device": "STM32F103CB",
            "gdbPath": "arm-none-eabi-gdb",
            "toolchainPrefix": "arm-none-eabi",
            "runToEntryPoint": "main"
        }
    ]
}

F5 烧录调试

在 VSCode 底部栏（状态栏）点击 “烧录并调试 STM32F103 (OpenOCD)” 按钮 → 自动启动 OpenOCD、连接 ST-Link、把固件烧入芯片。
烧录完成后程序停在 main()，点击调试控制栏的继续按钮运行程序；也可以先在代码里打断点再启动，进行在线调试。

烧录完成后，板子会运行固件：OLED 显示欢迎页、灯带渐变动画（后续章节逐步加入功能）。

烧录完成板子运行效果

③

验证下载成功

看屏幕：OLED 应显示 “欢迎使用” 与 “九章开发板” 两行文字（官方基础工程的欢迎页）。
看串口日志：用 Seahi-Serial 串口助手连接 USART1（PA9），波特率 1500000，应看到每秒刷新一次的温湿度日志：
```
[INFO] sht3x_read_task:234: sht30: 29 C,52 %
```
温度湿度数值随环境变化。出现该日志说明固件运行正常、SHT30 传感器通信正常。
串口中还可看到初始化日志：[INFO] emMCP init done、[INFO] sht3x init OK!、[INFO] ch224 init OK! 等。

以上均正常，说明下载成功，开发板已在运行基础固件。

编译报错排查

报错	原因	解决办法
`arm-none-eabi-gcc: not found`	交叉编译器未安装	`sudo apt install -y gcc-arm-none-eabi`
`CMake Error: Could not find ninja`	Ninja 未安装	`sudo apt install -y ninja-build`
`No CMAKE_C_COMPILER could be found`	工具链文件未生效	确认在项目根目录执行 cmake，CMakePresets.json 存在
`cannot find -lc` 等链接错误	newlib 链接问题	确认 `newlib_lock_glue.c` 在项目根目录
疑难编译缓存问题	缓存损坏	`rm -rf build && cmake --preset Debug && cmake --build build/Debug`

常见问题与踩坑提示

🔧 sudo apt update 很慢或失败
原因：默认软件源在国外
解决：换国内镜像源（清华/阿里云），教程里所有命令就飞快了

🔧 arm-none-eabi-gcc --version 显示 9.x
原因：Ubuntu 20.04 等老系统默认版本旧
解决：本教程用 Ubuntu 22.04（默认 10.3+）；老系统可装 xpack 版工具链

🔧 cmake: command not found
原因：没装 cmake
解决：sudo apt install -y cmake ninja-build

🔧 克隆官方仓库很慢 / 失败
原因：网络波动
解决：重试；或 git clone --depth 1 https://github.com/Ai-Thinker-Open/emMCP.git（只拉最新版本）

🔧 在非项目目录执行 cmake --preset Debug 报错
原因：预设文件在工程根目录
解决：先 cd ~/DOCS_TEST1 再执行

🔧 编译报错 No CMAKE_C_COMPILER
原因：交叉编译器没装或不在 PATH
解决：sudo apt install -y gcc-arm-none-eabi，重开终端

🔧 第一次编译很久
原因：全量编译几百个文件
解决：正常现象；之后增量编译只需几秒

🔧 改代码后想重新编译
原因：—
解决：cmake --build build/Debug 即可（无需重新 configure）

🔧 产物名不是自己的项目名
原因：CMAKE_PROJECT_NAME 与预期不一致
解决：基础工程产物名为 9Mod_MCPBorad.bin；如需改名，修改 CMakeLists.txt 的 set(CMAKE_PROJECT_NAME ...) 后重新 cmake --preset Debug

🔧 杀毒软件误删编译产物
原因：Windows Defender 误报
解决：把项目目录加入白名单，或信任 WSL 内的编译

🔧 串口/USB 映射不到 WSL（串口助手连不上 COM 口）
原因：WSL2 默认无法直接访问 Windows 串口设备
解决：使用社区工具 Seahi-Serial 进行映射：https://github.com/SeaHi-Mo/Seahi-Serial（将 COM 口挂载进 WSL，适用于串口调试与 ST-Link）

WSL 里烧录不了？

WSL2 默认访问不了 Windows 的 USB 设备（ST-Link 插 Windows）。用 Seahi-Serial（软件安装步骤⑤已装）把 ST-Link 映射进 WSL 后，即可用步骤②的方法一（Cortex-Debug 图形化）或方法二（OpenOCD 命令行）烧录。

下一步

← 上一步STM32 CMake 工程创建

📄 当前：编译和下载工程

下一步 →emMCP 移植

百度RTC使用说明

扩展功能

百度RTC使用指南

扩展功能

Linux 环境开发

Windows 环境开发

概述

编译报错排查

常见问题与踩坑提示

下一步

扩展功能

扩展功能

概述 ​

编译报错排查 ​

常见问题与踩坑提示 ​

下一步 ​

概述

编译报错排查

常见问题与踩坑提示

下一步