📘 九章 MCP 验证板 开发环境配置教程
从开箱到开发，一站式指南 ｜ 适用板卡：9Mod_MCPBorad（STM32F103CBT6）
📖 关于九章 MCP 验证板
九章 MCP 验证板是一款专为 MCP（Model Context Protocol） 协议验证和物联网开发设计的开源硬件平台。基于安信可 Ai-WV01-32S-Kit 模组实现小智 AI 应用，通过 emMCP 库，AI 可以直接控制板载 LED、继电器、WS2812 灯条等外设，并能读取温湿度等传感器数据进行语音播报。
👥 适用人群
| 人群 |
场景 |
| 🎓 电子爱好者 |
学习嵌入式开发和物联网技术 |
| 🔧 硬件开发者 |
快速原型开发和产品验证 |
| 🤖 AI 工程师 |
验证 AI 模型与硬件设备的交互 |
| 📚 教育场景 |
物联网和嵌入式教学实验 |
🗺️ 目录
一、开发环境总览
🔗 核心技术栈
| 层级 |
技术 |
说明 |
| 🖥️ 操作系统 |
Windows 11 + WSL2 (Ubuntu 22.04) |
WSL2 提供原生 Linux 内核 |
| 🔧 编译器 |
arm-none-eabi-gcc 10.3.1 |
ARM Cortex-M 交叉编译 |
| 🐛 调试器 |
gdb-multiarch + OpenOCD |
通过 ST-Link 实现 SWD 调试 |
| 📦 构建 |
CMake 3.22 + Ninja |
快速增量编译 |
| 🏗️ HAL 库 |
STM32F1xx HAL + FreeRTOS |
硬件抽象 + 实时操作系统 |
| 🖥️ 显示 |
SSD1306 OLED + GT20L16 字库 |
128×64 中文显示 |
| 🤖 AI |
emMCP + Ai-WV01-32S-Kit |
UART-MCP 协议交互 |
二、硬件接线
⚡ 快速参考
| 信号 |
ST-Link |
板子丝印 |
必须 |
| 数据 |
SWDIO |
PA13 |
✅ |
| 时钟 |
SWCLK |
PA14 |
✅ |
| 地 |
GND |
GND |
✅ |
| 电源 |
3.3V |
VDD |
❌ |
⚠️ 板子必须通过 Type-C 口独立供电。ST-Link 的 3.3V 电流不足以驱动整板。
三、WSL2 环境搭建
WSL2 是 Windows 自带的 Linux 虚拟机内核，不需要装双系统或 VMware。
📖 安装教程：WSL2 完整安装与使用教程
3.1 一键安装 ARM 工具链
sudo apt update && sudo apt install -y \
cmake \
ninja-build \
gcc-arm-none-eabi \
binutils-arm-none-eabi \
gdb-multiarch \
openocd
3.2 各组件角色说明
| 包名 |
一句话作用 |
验证命令 |
cmake |
构建系统，管"怎么编译" |
cmake --version |
ninja-build |
比 make 快 3~5 倍的构建器 |
ninja --version |
gcc-arm-none-eabi |
ARM 交叉编译器 |
arm-none-eabi-gcc --version |
binutils-arm-none-eabi |
objdump / nm 等工具 |
arm-none-eabi-objdump --version |
gdb-multiarch |
多架构 GDB 调试器 |
gdb-multiarch --version |
openocd |
连接 ST-Link 的 GDB 服务器 |
openocd --version |
💡 为什么用 gdb-multiarch？
Ubuntu 22.04 的 gcc-arm-none-eabi 包不附带 GDB。gdb-multiarch 支持 ARM 架构且已预装，效果完全一样。
四、USB 设备穿透
STM32 板子和 ST-Link 插在 Windows 上，WSL2 默认看不到 USB 设备。
使用 SeaHi Serial（GUI 工具）一键完成映射。
4.1 安装 SeaHi Serial
📥 GitHub：SeaHi-Mo/Seahi-Serial
SeaHi Serial 是便捷式的 USB 映射工具，比 usbipd 更简单——不需要命令行，GUI 勾选即可。
4.2 操作步骤
4.3 验证挂载（WSL 端）
lsusb
预期看到：
Bus 001 Device 004: ID 1a86:55d3 QinHeng Electronics USB Single Serial
Bus 001 Device 005: ID 0483:3748 STMicroelectronics STM32 STLink
4.4 设备识别表
| 设备 |
VID:PID |
WSL 节点 |
用途 |
| CH343 串口 |
1a86:55d3 |
/dev/ttyACM0 |
printf 串口输出 |
| ST-Link V2 |
0483:3748 |
libusb（用户态） |
SWD 烧录 + 调试 |
五、VS Code 插件安装
⚠️ 全部装在 WSL 端。在 VS Code 左侧 Extensions 面板搜索安装，确保右下角有 "Install in WSL: Ubuntu" 字样。
5.1 必备清单
| 序号 |
插件 ID |
插件名 |
一句话作用 |
必装 |
| 1 |
ms-vscode-remote.remote-wsl |
WSL |
让 VS Code 进入 WSL2 |
✅ |
| 2 |
ms-vscode.cmake-tools |
CMake Tools |
一键编译（F7） |
✅ |
| 3 |
marus25.cortex-debug |
Cortex-Debug |
一键烧录 + 断点调试（F5） |
✅ |
| 4 |
STMicroelectronics.stm32-vscode-extension |
STM32CubeIDE for VS Code |
打开 .ioc、MCU 选择、自带工具链 |
✅ |
5.2 插件关系图
| 分类 |
插件 |
数量 |
| 🔴 必须手动装 |
WSL + CMake Tools + Cortex-Debug + STM32 |
4 个 |
| 🟢 自动附带 |
STM32 扩展的 4 个依赖（core/build-cmake/analyzer/bundles） |
0 个 |
六、项目配置
6.1 获取源码
git clone https://github.com/Ai-Thinker-Open/emMCP.git
6.2 打开项目
⚠️ 必须打开具体项目文件夹，不能打开仓库根目录！
File → Open Folder → /home/xemowo/emMCP/example/9Mod_MCPBorad
6.3 确认 MCU 型号
| 步骤 |
操作 |
| 1 |
双击左侧**9Mod_MCPBorad.ioc** |
| 2 |
Pinout & Configuration 标签页顶部确认芯片 |
| 3 |
型号：STM32F103CBT6（128KB Flash） |
一般不需要改，项目默认就是正确的 MCU。
6.4 配置 Cortex-Debug（.vscode/launch.json）
{
"version": "0.2.0",
"configurations": [
{
"name": "🔵 Debug STM32F103 (OpenOCD)",
"cwd": "${workspaceFolder}",
"executable": "${command:cmake.launchTargetPath}",
"request": "launch",
"type": "cortex-debug",
"servertype": "openocd",
"configFiles": [
"interface/stlink.cfg",
"target/stm32f1x.cfg"
],
"device": "STM32F103CB",
"gdbPath": "gdb-multiarch",
"toolchainPrefix": "arm-none-eabi",
"svdFile": "",
"runToEntryPoint": "main"
}
]
}
6.5 配置项说明
| 配置项 |
值 |
为什么这样填 |
servertype |
"openocd" |
用 OpenOCD 作为 GDB Server 桥接 ST-Link |
configFiles |
stlink.cfg + stm32f1x.cfg |
告诉 OpenOCD：调试器型号 + 芯片系列 |
device |
"STM32F103CB" |
芯片型号（去掉 T6 后缀） |
gdbPath |
"gdb-multiarch" |
Ubuntu 22.04 不自带 gdb-arm-none-eabi |
toolchainPrefix |
"arm-none-eabi" |
修复 objdump/nm 符号解析警告 |
runToEntryPoint |
"main" |
烧录后自动停在 main() 第一行 |
配置完毕后，底部状态栏应出现 CMake preset 和调试按钮。
七、编译 & 烧录 & 调试
7.1 日常开发三步走
7.2 操作详解
🏗️ 编译
Ctrl+Shift+P → CMake: Configure → 选 Debug
Ctrl+Shift+P → CMake: Build（或直接 F7）
编译成功标志：
🔌 烧录
F5 → 选择 "🔵 Debug STM32F103 (OpenOCD)"
🐛 调试
烧录完成后自动停在 main() 函数第一行：
7.3 快捷键一览
| 操作 |
快捷键 |
说明 |
| 编译 |
F7 |
增量编译 |
| 烧录+调试 |
F5 |
一键烧录并进入调试 |
| 继续运行 |
F5 |
从断点处继续执行 |
| 单步跳过 |
F10 |
Step Over |
| 单步进入 |
F11 |
Step Into |
| 停止调试 |
Shift+F5 |
断开与芯片的连接 |
7.4 编译产物
build/Debug/
├── 9Mod_MCPBorad.elf ← ELF 文件（含符号表，用于调试）
├── 9Mod_MCPBorad.bin ← 纯二进制固件
├── 9Mod_MCPBorad.hex ← Intel Hex 格式固件
└── ...
⚠️ .elf 是 ARM 固件，在 Linux 下直接运行会报错 Exec format error，这是正常的——它只能跑在 STM32 芯片上。
7.5 验证运行
编译烧录成功后，OLED 屏幕应出现显示：
💡 修改 OLED 显示内容：Core/Src/freertos.c 第 254~255 行
axk_ssd1306_show_utf8_str(32, 0, "你的名字");
axk_ssd1306_show_utf8_str(24, 3, "九章开发板");
内置 GT20L16 中文字库芯片，show_utf8_str() 直接支持中文 UTF-8。
八、设备配网与运行
8.1 配网流程（语音交互）
板子断电再上电（冷启动）
│
▼
"你好小安" ← 对板子说话
│
▼
"你好呀" ← 板子回复（说明唤醒成功）
│
▼
"开始配网" ← 对板子说话
│
▼
"开启配网， ← 板子回复
请使用小程序
配置 WiFi"
8.2 微信小程序配网
① 搜索小程序 → ② 扫描设备 → ③ 输入 WiFi → ④ 配网成功
① 搜索小程序
微信搜「AI 硬件智能体」 |
② 扫描设备
小程序自动发现 |
③ 输入 WiFi
仅支持 2.4G 网络 |
④ 配网成功
等待连接确认 |
 |
 |
 |
 |
⑤ 板子断电重上电 → ⑥ OLED 显示验证码 → ⑦ 小程序输入验证码完成绑定
⑤ 断电重启
板子重新上电，等待连接 WiFi |
⑥ 获取验证码
OLED 屏幕显示 6 位验证码 |
⑦ 完成绑定
小程序输入验证码，绑定成功 |
| — |
 |
 |
8.3 小程序功能
配网完成后，通过「AI 硬件智能体」小程序可以：
| 功能 |
说明 |
| 📋 设备状态 |
查看设备在线/离线 |
| 🔄 OTA 升级 |
无线固件更新 |
| 🤖 AI 智能体 |
配置工具注册、语音风格 |
| 🔧 恢复出厂 |
重置设备 |
九、改代码快速索引
🔍 想改什么，去这里找
| 你想改的 |
文件位置 |
改什么 |
| 🖥️ OLED 显示内容 |
Core/Src/freertos.c 第 254 行 |
axk_ssd1306_show_utf8_str() 的字符串参数 |
| 📟 启用 printf |
Core/Src/main.c → USER CODE 4 |
添加 __io_putchar() 函数 |
| 🔧 添加 MCP 工具 |
Core/Src/freertos.c |
emMCP API 注册新工具 |
| 📌 MCU 型号 / 引脚 |
9Mod_MCPBorad.ioc |
STM32CubeMX 图形界面修改 |
| ⚡ SPI 速率 / 模式 |
Bsp/spi/stm32f10x_bsp_spi.c |
SPI 初始化参数 |
| ⏱️ FreeRTOS 任务 |
Core/Src/freertos.c |
任务创建、优先级、栈大小 |
| 🚨 中断处理 |
Core/Src/stm32f1xx_it.c |
各外设中断回调 |
十、常用命令速查
11.1 一键环境检查
echo "========== 编译器 ==========" && arm-none-eabi-gcc --version | head -1
echo "========== 调试器 ==========" && gdb-multiarch --version | head -1
echo "========== 烧录工具 =========" && openocd --version | head -1
echo "========== 构建系统 =========" && cmake --version | head -1
echo "========== USB 设备 ==========" && lsusb
echo "========== 串口设备 =========" && ls /dev/ttyACM* /dev/ttyUSB* 2>/dev/null || echo "(无)"
11.2 命令行烧录（备用）
cd /home/xemowo/emMCP/example/9Mod_MCPBorad
openocd -f openocd.cfg \
-c "program build/Debug/9Mod_MCPBorad.elf verify reset exit"
11.3 故障排查表
| 😱 现象 |
🔍 原因 |
✅ 解决 |
openocd: open failed |
ST-Link 未映射到 WSL |
SeaHi Serial 重新勾选映射 |
GDB executable not found |
Cortex-Debug 找不到 GDB |
launch.json 配 gdbPath: gdb-multiarch |
nm-multiarch ENOENT |
符号工具名错误（仅警告） |
launch.json 配 toolchainPrefix: arm-none-eabi |
Permission denied 读写串口 |
用户不在 dialout 组 |
sudo usermod -aG dialout $USER |
.elf: Exec format error |
在电脑上执行 ARM 固件 |
正常现象，用 openocd 烧录即可 |
VS Code 不识别 .ioc |
插件未装或装错端 |
确认 STM32 扩展装在 WSL 端 |
| OLED 屏幕不亮 |
代码未烧录或 SPI 未初始化 |
重新 F5 烧录 |
| SeaHi Serial 看不到设备 |
驱动未装 |
管理员运行 stlink_winusb_install.bat |
11.4 快捷键速查卡
┌─────────────────────────────────────────┐
│ F5 → 烧录 + 启动调试 │
│ F7 → 编译项目 │
│ F10 → 单步跳过 │
│ F11 → 单步进入函数 │
│ Shift+F5 → 停止调试 │
│ Ctrl+` → 打开终端 │
│ Ctrl+Shift+P → 命令面板（万能入口） │
└─────────────────────────────────────────┘
十一、项目结构
12.1 完整目录树
9Mod_MCPBorad/
│
├── 📁 Core/ # 🎯 用户代码
├── 📁 Drivers/ # 📚 STM32 HAL 库
├── 📁 Middlewares/ # 🔧 中间件
├── 📁 Bsp/ # 🔌 板级支持包
├── 📁 components/ # 🧩 外设组件库
├── 📁 cmake/ # ⚙️ CMake 工具链
├── 📁 .vscode/ # 🛠️ VS Code 配置
└── 📁 build/ # 📦 编译产物
12.2 核心文件一句话总结
main.c ──→ 硬件初始化 + 启动 FreeRTOS 调度器
freertos.c ──→ 业务逻辑 + OLED 显示 + MCP 工具注册
syscalls.c ──→ printf 重定向到串口（需补 __io_putchar）
axk_*.c ──→ OLED 驱动 + 中文字库
stm32f10x_it.c ──→ 中断处理（串口接收/定时器等）
📅 文档版本：v1.0
📅 更新日期：2026-07-08
🛠️ 适用板卡：九章 MCP 验证板（9Mod_MCPBorad）｜MCU：STM32F103CBT6
💻 开发环境：Windows 11 + WSL2 (Ubuntu 22.04) + VS Code
📦 项目仓库：github.com/Ai-Thinker-Open/emMCP
