Fedora 嵌入式开发环境全栈配置指南

写在前面

这篇文章记录我在 Fedora 44 上把一整套嵌入式开发环境搭起来的过程。目标平台是 STM32F103C8T6，调试器有 ST-Link V2 和 J-Link。

覆盖范围：

每一节的结构都一样：先说明这是什么、为什么需要，再安装，最后验证。验证尽量做到”实际编译出东西”，而不是只看版本号。

工具链官方链接

本文涉及的工具，官方地址集中列在这里，方便查阅：

所有链接于 2026-09-20 实测可访问。ST 官网有反爬机制，命令行 curl 可能返回异常状态码，浏览器访问正常。

版本管理工具

说明

为什么单独讲这个：这套工具链对运行时版本有要求——Rust 嵌入式的 rustup target 需要特定版本的目标支持，AI 工具链的 npx skills 需要 Node ≥ 18。Fedora 仓库里的版本往往跟不上，所以实际部署时通常靠版本管理器。

本文用到两个：

下一篇会用到另外两个：sdkman（Java，跑 Freerouting）和 uv（Python）。本文用不到，所以不讲——需要的话看《用 AI 设计一块 STM32 板子》。

安装

1
# rustup —— Rust 工具链（第五节用）
2
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
3

4
# nvm —— Node 版本管理（第九节用）
5
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
6
nvm install 24

Fedora 原生方案（不用版本管理器时）：

1
sudo dnf install nodejs npm

配置写在哪

两个管理器的配置文件不一样，这是排查”命令找不到”的第一站：

实际配置内容（本机实测）：

1
. "$HOME/.cargo/env"

~/.cargo/env 是 rustup 自动生成的：

1
#!/bin/sh
2
case ":${PATH}:" in
3
    *:"$HOME/.cargo/bin":*) ;;
4
    *) export PATH="$HOME/.cargo/bin:$PATH" ;;
5
esac

1
export NVM_DIR="$HOME/.nvm"
2
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
3
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

验证

装完要知道哪个在生效——which 的路径就是答案：

1
which rustc && rustc --version
2
# /home/zizimiku/.cargo/bin/rustc
3
# rustc 1.98.1 (48a229cea 2026-09-01)
4

5
which node && node --version
6
# /home/zizimiku/.nvm/versions/node/v24.14.0/bin/node
7
# v24.14.0
8

9
which npx
10
# /home/zizimiku/.nvm/versions/node/v24.14.0/bin/npx

确认 rustup 的默认工具链：

1
cat ~/.rustup/settings.toml
2
# default_toolchain = "stable-x86_64-unknown-linux-gnu"

常用命令

rustup target add 是本文第五节的关键命令——Rust 嵌入式开发必须装对应的交叉编译目标（如 thumbv7m-none-eabi 对应 Cortex-M3）。

一、主机编译工具链

说明

这是所有开发的基础。写 C/C++ 代码、构建项目，都依赖这几个工具：

嵌入式开发里，主机工具链负责编译工具本身（比如编译 OpenOCD），而目标代码要用交叉编译器（下一节）。两者不能混。

安装

Fedora 41 之后 DNF5 成为默认包管理器，软件包组的名称从”显示名”改成了”组 ID”——这是第一个坑：

下面代码块里的删除线表示我最初尝试过但会失败的命令，绿色增补行是最终可用的写法；终端标题也标明了这段命令对应的文件或验证步骤。

1
# ❌ 旧语法，Fedora 44 上会失败
2
sudo dnf group install "Development Tools"
3
# Failed to resolve the transaction:
4
# No match for argument: Development Tools
5

6
# ✅ 新语法，注意 @ 前缀
7
sudo dnf install @development-tools

单独安装其余的（这些不在 development-tools 组里）：

1
sudo dnf install gcc gcc-c++ clang make cmake ninja-build gdb

注意：Fedora 上 C++ 编译器的包名是 gcc-c++，不是 g++。

验证

先看版本：

1
gcc --version      # gcc (GCC) 16.2.1
2
g++ --version      # g++ (GCC) 16.2.1
3
clang --version    # clang version 22.1.8
4
make --version     # GNU Make 4.4.1
5
cmake --version    # cmake version 4.3.0
6
ninja --version    # 1.13.2
7
gdb --version      # GNU gdb 17.2

再实际编译运行一个程序——这才是真的验证：

1
cd /tmp && cat > t.c <<'EOF'
2
#include <stdio.h>
3
int main(){ printf("hello\n"); return 0; }
4
EOF
5

6
gcc t.c -o t && ./t
7
# hello

看到 hello 就说明主机工具链可用。

二、ARM 交叉编译工具链

说明

为什么要”交叉”：你的电脑是 x86_64 架构，而 STM32 是 ARM Cortex-M 内核。x86 的 gcc 编译出来的程序在 STM32 上跑不了。所以需要一套在 x86 上运行、但生成 ARM 机器码的编译器，这就是”交叉编译器”。

命名规则是 架构-厂商-系统-ABI：

1
arm - none - eabi
2
 │     │      │
3
 │     │      └─ EABI：嵌入式应用二进制接口
4
 │     └──────── none：无操作系统（裸机）
5
 └────────────── arm：ARM 架构

常用的配套工具：

安装

1
sudo dnf install arm-none-eabi-gcc-cs arm-none-eabi-gcc-cs-c++ \
2
                 arm-none-eabi-binutils arm-none-eabi-newlib

包名注意：Fedora 里这个包叫 arm-none-eabi-gcc-cs（带 -cs 后缀，表示 CodeSourcery 版本），不是简单的 arm-none-eabi-gcc。

验证

1
arm-none-eabi-gcc --version
2
# arm-none-eabi-gcc (Fedora 15.2.0-4.fc44) 15.2.0

实际编译一个 Cortex-M3 目标文件：

1
cat > arm.c <<'EOF'
2
int main(void){ volatile int i=0; while(1){ i++; } return 0; }
3
EOF
4

5
arm-none-eabi-gcc -mcpu=cortex-m3 -mthumb -c arm.c -o arm.o
6
arm-none-eabi-size arm.o
7
#    text    data     bss     dec     hex filename
8
#      18       0       0      18      12 arm.o

编译通过、能用 size 看到占用，说明工具链完整。

注意：Fedora 仓库没有 arm-none-eabi-gdb。但系统自带的 gdb 已经编译了多目标支持：

1
gdb --configuration | grep enable-targets
2
# --enable-targets=...,arm-linux-gnu

所以调试 ARM 目标不需要额外装 gdb。

三、烧录与调试工具

说明

代码编译出来是 .elf / .bin，需要通过调试探针写进芯片的 Flash。不同探针对应不同工具。

三者关系：

• ST-Link 用户：st-flash 最省事，openocd 更灵活
• J-Link 用户：只能用 SEGGER 官方软件（OpenOCD 也支持，但功能少）
• 调试都要走 GDB：st-util / JLinkGDBServer / openocd 提供一个 GDB Server 端口，然后 gdb 连上去

安装

ST-Link 和 OpenOCD（Fedora 仓库直接有）：

1
sudo dnf install stlink openocd picocom

J-Link（商业软件，不在仓库里）：

从 segger.com/downloads/jlink 下载。这里有个大坑：

1
# ❌ 这样下到的是 27KB 的 HTML 页面，不是安装包
2
wget https://www.segger.com/downloads/jlink/JLink_Linux_x86_64.rpm
3
file JLink_Linux_x86_64.rpm
4
# HTML document, ASCII text
5

6
# ✅ 真实的文件名带版本号
7
# JLink_Linux_V978_x86_64.rpm   (73MB)

原因是 SEGGER 要求你先在页面上同意许可协议。命令行直接请求只会拿到那个协议页。

正确的做法是在浏览器里下载，然后：

1
# 先验证文件类型
2
file ~/Downloads/JLink_Linux_V978_x86_64.rpm
3
# RPM v3.0 bin i386/x86_64 jlink-9.78.0-1
4

5
sudo dnf install -y ~/Downloads/JLink_Linux_V978_x86_64.rpm

验证

版本检查：

1
st-flash --version    # v1.8.0
2
openocd --version     # Open On-Chip Debugger 0.12.0
3
JLinkExe              # SEGGER J-Link Commander V9.78
4
picocom --version     # picocom v2024-07

硬件探测（插上探针后）——这是最有价值的验证，因为能自动识别芯片型号：

1
st-info --probe
2
# Found 1 stlink programmers
3
#   version:    V2J29S7
4
#   serial:     E1007200D0D2139393740544
5
#   flash:      65536 (pagesize: 1024)
6
#   sram:       20480
7
#   chipid:     0x410
8
#   dev-type:   STM32F1xx_MD

dev-type: STM32F1xx_MD 直接告诉你这是 STM32F1 系列中容量芯片，Flash 64KB / RAM 20KB。

udev 权限：J-Link 的 RPM 包会自动装 /etc/udev/rules.d/99-jlink.rules，普通用户即可访问探针，不需要 sudo。详见下一节。

四、udev 权限配置（通用基础）

说明

udev 是什么：Linux 的设备管理器，负责在设备插入 USB 时创建 /dev/ 下的设备节点并设置权限。

为什么嵌入式开发必须配它：调试探针（ST-Link、J-Link）、USB 转串口、逻辑分析仪都是 USB 设备。默认情况下普通用户没有读写权限，只能 sudo 访问——但 sudo gdb、sudo st-flash 很难用，而且图形化 IDE 根本不会用 sudo。

症状：插了探针，工具却说找不到。

1
st-info --probe
2
# Couldn't find any ST-Link devices
3

4
probe-rs list
5
# No debug probes were found.
6
# WARN: If your probe is plugged in but not listed, it is most likely a permissions problem.

设备其实在那儿（lsusb 能看到），只是没权限打开。

udev 规则的结构

规则文件放在 /etc/udev/rules.d/，每行一条规则。看一条实际的：

1
ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", MODE="660", GROUP="plugdev", TAG+="uaccess"

拆解：

另一份规则用的是不同策略：

1
ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="ea[67][013]", MODE:="0666", ...

MODE:="0666" 是所有用户可读写（注意 := 是强制赋值，会覆盖之前的值）。更宽松，但不够精细。

两种策略的取舍：TAG+="uaccess" 更安全（只有登录用户能用），MODE:="0666" 更省事（任何用户都能用，包括 root 跑的服务）。

查设备 ID

想知道你的设备该配什么规则，先查它的 Vendor/Product ID：

1
lsusb
2
# Bus 001 Device 014: ID 0483:3748 STMicroelectronics ST-LINK/V2
3
#                     └──┬──┘ └─┬──┘
4
#                     idVendor  idProduct

常用的几个：

也可以直接看内核日志：

1
dmesg | grep -iE "usb|tty" | tail -20

三份规则的关系

我装了三个工具链，各自带一份 udev 规则，它们覆盖不同设备、可以共存：

关键点：69-probe-rs.rules 覆盖了 111 个设备，包括 ST-Link 和 J-Link。所以即使你不用 probe-rs，装它也能一次性解决大部分探针的权限问题。

数字前缀（69 / 99）是加载顺序，数字小的先加载。如果多条规则匹配同一设备，后面的会覆盖前面的。

安装

J-Link：装 RPM 包时自动完成，不用手动操作。

probe-rs（推荐，覆盖最广）：

1
curl -o /tmp/69-probe-rs.rules https://probe.rs/files/69-probe-rs.rules
2
sudo cp /tmp/69-probe-rs.rules /etc/udev/rules.d/
3

4
# 重新加载规则
5
sudo udevadm control --reload
6
sudo udevadm trigger

PlatformIO：

1
curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core/develop/platformio/assets/system/99-platformio-udev.rules \
2
  | sudo tee /etc/udev/rules.d/99-platformio-udev.rules
3

4
sudo udevadm control --reload-rules
5
sudo udevadm trigger

OpenOCD（Zephyr SDK 自带一份）：

1
sudo cp ~/zephyr-sdk-1.0.1/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules \
2
  /etc/udev/rules.d/
3
sudo udevadm control --reload && sudo udevadm trigger

手写一条（如果你的设备不在任何规则里）：

1
sudo tee /etc/udev/rules.d/99-my-device.rules <<'EOF'
2
# 把 0483:3748 换成你设备的 ID
3
SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", MODE="0666"
4
EOF
5

6
sudo udevadm control --reload && sudo udevadm trigger

验证

第 1 层：规则文件已就位

1
ls /etc/udev/rules.d/ | grep -iE "jlink|probe|platformio|openocd"
2
# 69-probe-rs.rules
3
# 99-jlink.rules
4
# 99-platformio-udev.rules

第 2 层：规则语法正确

1
sudo udevadm control --reload
2
# 无输出 = 语法正常；有报错会明确指出哪一行

第 3 层：设备权限正确 ⭐

插上探针后，查它的实际权限：

1
# 找到设备节点
2
lsusb | grep -i stlink
3
# Bus 001 Device 014: ID 0483:3748 STMicroelectronics ST-LINK/V2
4

5
# 查权限（busnum:devnum 对应上面那个 001:014）
6
ls -l /dev/bus/usb/001/014
7
# crw-rw-rw- 1 root root ... → 0666，所有用户可访问 ✅
8
# crw-rw-r-- 1 root root ... → 只有 root 能写 ❌

第 4 层：工具能真正访问

1
st-info --probe
2
# Found 1 stlink programmers
3
#   dev-type: STM32F1xx_MD          ← 能读到芯片信息，说明权限没问题

备选方案：dialout 组

除了 udev 规则，另一种做法是把用户加进 dialout 组（串口设备的传统属组）：

1
sudo usermod -a -G dialout $USER

但这里有个大坑（我踩过）：

1
sudo usermod -a -G dialout $USER
2
groups
3
# zizimiku wheel kvm docker        ← 看不到 dialout！

这是正常现象。 usermod 修改的是账户的组归属（写入 /etc/group），但当前已登录的会话不会自动刷新。source ~/.zshrc 也没用——组权限是登录会话级别的，由登录时创建进程时确定。

必须完全退出终端并重新登录（注销或重启）：

1
# 重新登录后
2
groups
3
# zizimiku wheel dialout kvm docker   ← 这才对

或者临时在当前 shell 生效：

1
newgrp dialout      # 只对当前终端有效

udev 规则 vs dialout 组：

结论：优先用 udev 规则。dialout 只作为补充（某些老工具只认组权限）。

排查清单

如果配了规则还是不工作：

1. 重新插拔设备 — udev 规则只对新插入的设备生效，已插入的要拔了重插（或 sudo udevadm trigger）
2. 确认规则真的被加载 — sudo udevadm test /dev/bus/usb/001/014 2>&1 | grep -i mode
3. 检查 brltty 抢占 — Fedora 上 brltty 服务会抢占某些 USB 串口设备，导致 /dev/ttyUSB* 不出现：

   1
   sudo systemctl stop brltty-udev.service
   2
   sudo systemctl mask brltty-udev.service

4. 看内核是否识别 — sudo dmesg | tail -20，如果内核日志里都没有设备，那是硬件/线缆问题，不是权限问题
5. 确认不是被别的进程占用 — Keil、STM32CubeProgrammer 等会独占探针

五、Rust 嵌入式开发

说明

Rust 在嵌入式领域的优势是编译期内存安全——没有空指针、没有数据竞争、不需要 GC。生态里最成熟的框架是 Embassy，它把 async/await 带进裸机，用编译期状态机替代传统 RTOS 的任务调度。

核心工具：

Rust 用 target 表示编译目标。嵌入式常用的：

安装

1
# 1. 系统依赖（probe-rs 需要 libusb 和 libudev）
2
sudo dnf install libusbx-devel libftdi-devel libudev-devel openssl-devel perl gcc
3

4
# 2. Rust 工具链
5
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
6
source $HOME/.cargo/env
7

8
# 3. 烧录调试工具（编译时间较长）
9
cargo install probe-rs-tools
10

11
# 4. 辅助工具
12
cargo install flip-link
13
rustup component add llvm-tools
14
cargo install cargo-binutils

probe-rs 的 udev 规则（不加普通用户无法访问探针）：

1
curl -o /tmp/69-probe-rs.rules https://probe.rs/files/69-probe-rs.rules
2
sudo cp /tmp/69-probe-rs.rules /etc/udev/rules.d/
3
sudo udevadm control --reload
4
sudo udevadm trigger

添加编译目标：

1
rustup target add thumbv7m-none-eabi        # Cortex-M3
2
rustup target add thumbv6m-none-eabi        # Cortex-M0+
3
rustup target add thumbv7em-none-eabihf     # Cortex-M4F
4
rustup target add thumbv8m.main-none-eabihf # Cortex-M33

验证

版本：

1
rustc --version      # rustc 1.98.1
2
cargo --version      # cargo 1.98.1
3
probe-rs --version   # probe-rs 0.32.0
4
rustup target list --installed
5
# thumbv7m-none-eabi
6
# thumbv6m-none-eabi
7
# ...

实际编译（这才是关键）：

1
cat > rust.rs <<'EOF'
2
#![no_std]
3
#![no_main]
4
#[panic_handler]
5
fn p(_: &core::panic::PanicInfo) -> ! { loop {} }
6
#[no_mangle]
7
pub extern "C" fn _start() -> ! { loop {} }
8
EOF
9

10
rustc --target thumbv7m-none-eabi --crate-type staticlib rust.rs -o librust.a
11
ls -lh librust.a
12
# -rw-r--r-- 1 user user 7.7M librust.a

能生成 ARM 静态库，说明 target 和工具链都正常。

探测探针：

1
probe-rs list
2
# 插上探针时应该显示 "STLink V2" 或 "J-Link"

ESP32 补充

Xtensa 架构的 ESP32 不被 Rust 标准工具链支持，需要乐鑫的定制版本：

1
cargo install espup --locked
2
espup install

安装后会生成 ~/export-esp.sh，需要每次 shell 启动时加载。zsh 用户：

1
cat $HOME/export-esp.sh >> ~/.zshrc

文件内容大致是：

1
export LIBCLANG_PATH=".../esp-clang/lib"
2
export PATH=".../xtensa-esp-elf/bin:$PATH"

验证：

1
espup --version   # espup 0.17.1

六、Zephyr RTOS

说明

Zephyr 是什么：一个开源的实时操作系统（RTOS），支持几百种开发板，模块化程度高，适合正经的 IoT 产品。

它和裸机开发的区别在于：自带内核、线程调度、设备驱动模型、设备树（Device Tree）配置系统。代价是环境配置比裸机复杂得多。

Zephyr 的架构是 west 工作区：

1
~/zephyrproject/          ← 工作区根（有 .west 目录标识）
2
├── .west/                ← west 的元数据
3
├── zephyr/               ← Zephyr 源码
4
├── modules/              ← 各个依赖模块（HAL、加密库等）
5
├── tools/
6
└── myprojects/           ← 你自己的项目放这里

west 是它的元构建工具，必须在工作区内运行（会逐级向上找 .west）。

关键概念：Zephyr SDK。这是一个包含所有架构交叉编译器的套装包。没有它，Zephyr 一行代码都编译不了。这是最容易出问题的环节，下面详细讲。

安装

步骤 1：安装系统依赖

1
# 注意 DNF5 的组名格式
2
sudo dnf install @development-tools @c-development
3

4
sudo dnf install git cmake ninja-build gperf ccache dfu-util dtc wget \
5
  python3-pip python3-tkinter xz file glibc-devel.i686 libstdc++-devel.i686

步骤 2：创建 west 工作区

1
python3 -m venv ~/zephyrproject/.venv
2
source ~/zephyrproject/.venv/bin/activate
3

4
pip install west
5
west init ~/zephyrproject
6
cd ~/zephyrproject
7
west update              # 拉取所有模块，比较慢
8
west zephyr-export       # 导出 CMake 包
9
pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt

踩坑记录：如果先跑 west zephyr-export 再装 Python 依赖，会报：

1
ModuleNotFoundError: No module named 'jsonschema'

紧接着还会跟一个 AttributeError: 'NoneType' object has no attribute 'err'——那是 west 自身的 bug，报告错误时又抛了新异常，把真正的错误盖住了。正确顺序是先 pip install，再 export。

步骤 3：安装 Zephyr SDK ⭐

这是最容易踩坑的一步。三个坑：

坑 1：版本必须匹配

1
cat ~/zephyrproject/zephyr/SDK_VERSION
2
# 1.0.1

SDK 版本要和工作区要求一致，否则编译会报错。

坑 2：文件名带 _gnu 后缀

1
# ❌ 404
2
zephyr-sdk-1.0.1_linux-x86_64.tar.xz
3

4
# ✅ 正确
5
zephyr-sdk-1.0.1_linux-x86_64_gnu.tar.xz

坑 3：下载容易中断，必须校验大小

1
cd ~
2
curl -L --retry 5 -C - -o zephyr-sdk-1.0.1_linux-x86_64_gnu.tar.xz \
3
  https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.1/zephyr-sdk-1.0.1_linux-x86_64_gnu.tar.xz

下载后一定要检查大小：

1
ls -lh zephyr-sdk-1.0.1_linux-x86_64_gnu.tar.xz
2
# 应该约 2.0GB

我第一次只下到 62MB，解压时报：

1
xz: (stdin): Unexpected end of input
2
tar: Unexpected EOF in archive

坑 4：setup.sh 会卡死 ⭐⭐

解压后要运行 setup.sh 注册工具链：

1
tar xf zephyr-sdk-1.0.1_linux-x86_64_gnu.tar.xz
2
cd zephyr-sdk-1.0.1
3
./setup.sh

但如果用非交互方式运行（比如重定向输入），脚本会陷入死循环，CPU 100% 空转。

原因在脚本的 ask_yn 函数：

1
ask_yn()
2
{
3
  local reply
4
  while true; do
5
    read -r -p "$1 [y/n]? " reply    # 从 /dev/null 读取 → 立即 EOF
6
    case "${reply}" in
7
      Y* | y*)  return 0 ;;
8
      N* | n*)  return 1 ;;
9
      *)        echo "Invalid choice '${reply}'" ;;   # 空响应 → 死循环
10
    esac
11
  done
12
}

read 读到 EOF 返回空字符串，case 匹配到 * 分支，打印提示后再次循环——永久空转。

我观察到的情况：

1
ps -o pid,etime,time,%cpu,cmd -p <pid>
2
#  154267  21:14  21:03  99.1  bash ./setup.sh
3
# 运行 21 分钟，CPU 时间 21 分钟，占用 99.1%

正解：用 yes 预先喂入所有确认为 y：

1
yes | ./setup.sh

验证

SDK 安装的验证要分四层，逐层排除：

第 1 层：目录结构完整

1
ls ~/zephyr-sdk-1.0.1/
2
# 应该包含：cmake/  gnu/  hosttools/  llvm/  sysroots/  setup.sh  sdk_version

第 2 层：ARM 工具链存在

1
ls ~/zephyr-sdk-1.0.1/gnu/
2
# 会列出所有架构，关键是包含 arm-zephyr-eabi
3
# aarch64-zephyr-elf  arc-zephyr-elf  arm-zephyr-eabi  riscv64-zephyr-elf ...

第 3 层：编译器能运行

1
~/zephyr-sdk-1.0.1/gnu/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc --version
2
# arm-zephyr-eabi-gcc (Zephyr SDK 1.0.1) 14.3.0

第 4 层：CMake 注册成功

1
ls ~/.cmake/packages/Zephyr-sdk/
2
# 应该有一个哈希文件名的文件

第 5 层（终极）：实际编译

1
cd ~/zephyrproject
2
source .venv/bin/activate
3
west build -b stm32f4_disco zephyr/samples/basic/blinky

成功输出：

1
[161/161] Linking C executable zephyr/zephyr.elf
2
Memory region         Used Size  Region Size  %age Used
3
           FLASH:       18056 B         1 MB      1.72%
4
             RAM:        4608 B       128 KB      3.52%
5
Generating files from zephyr/zephyr.elf for board: stm32f4_disco/stm32f407xx

161 个编译单元全部通过，生成了 zephyr.elf——这才算真正装好了。

输出末尾如果出现 BrokenPipeError，那是 | head 导致的（head 读够就关管道），不是错误。

使用

1
cd ~/zephyrproject
2
source .venv/bin/activate              # 新终端必须重新激活
3

4
# 编译自己的项目
5
cd myprojects/myapp
6
west build -b stm32f4_disco .
7

8
# 烧录
9
west flash

工作区规则：

• ✅ 可以在 ~/zephyrproject 的任何子目录运行 west
• ❌ 在工作区外运行会报 unknown command "boards"

建议把所有自己的项目放在工作区内的一个总目录里（如 myprojects/），这样 west 开箱即用，不需要额外环境变量。

七、PlatformIO

说明

PlatformIO 是嵌入式的一体化开发平台：你声明目标板，它自动下载对应的交叉编译器、框架、库，然后统一构建。支持的芯片从 AVR、ESP32、STM32 到 RISC-V 都有。

优点：省心。不用自己折腾工具链版本、不用手写 Makefile。 缺点：封装层厚，出问题时排查到底层比较麻烦。

它和前面几种方式的关系：

安装

官方推荐用安装脚本，但 Fedora 仓库里就有包，用 dnf 更简单也更安全（不用 curl | python 执行远程脚本）：

1
sudo dnf install platformio

这会连带装好 python3-platformio 等依赖。

两种安装方式的差异（重要）：

方式	pio 位置	需要配 PATH 吗
dnf install platformio	/usr/bin/pio	❌ 不需要，系统路径里就有
官方安装脚本	~/.platformio/penv/bin/pio	✅ 需要加到 shell 配置

网上大部分教程（包括 AI 助手给的）默认是官方脚本方式，会告诉你加这一行：

1
echo 'export PATH="$HOME/.platformio/penv/bin:$PATH"' >> ~/.zshrc

如果你用 dnf 装的，这行是多余的——~/.platformio/penv/bin 这个目录根本不存在，加了无害但没用。识别方法：

1
which pio
2
# /usr/bin/pio          → dnf 装的，不需要那行 PATH
3
# /home/user/.platformio/penv/bin/pio  → 脚本装的，需要

我自己就踩了这个坑：先按教程加了 PATH，后来改用 dnf，那行一直留着没删。

验证

1
pio --version
2
# PlatformIO Core, version 6.1.19

实际编译——先初始化一个 STM32 项目：

1
mkdir ~/pio-test && cd ~/pio-test
2
pio project init --board bluepill_f103c8

这一步会自动下载 STM32 平台包和工具链（几百 MB，第一次比较慢）：

1
Tool Manager: framework-arduinoststm32@4.30000.0 has been installed!
2
Tool Manager: tool-scons@4.40801.0 has been installed!
3
Project has been successfully initialized!

写一个闪灯程序：

1
cat > src/main.cpp <<'EOF'
2
#include <Arduino.h>
3
void setup(){ pinMode(PC13, OUTPUT); }
4
void loop(){ digitalWrite(PC13, !digitalRead(PC13)); delay(500); }
5
EOF

编译：

1
pio run

成功输出：

1
Linking .pio/build/bluepill_f103c8/firmware.elf
2
RAM:   [          ]   4.2% (used 852 bytes from 20480 bytes)
3
Flash: [=         ]  14.5% (used 9528 bytes from 65536 bytes)
4
Building .pio/build/bluepill_f103c8/firmware.bin
5
========================= [SUCCESS] Took 5.52 seconds =========================

烧录（需要 udev 规则）：

1
# 一次性配置
2
curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core/develop/platformio/assets/system/99-platformio-udev.rules \
3
  | sudo tee /etc/udev/rules.d/99-platformio-udev.rules
4
sudo udevadm control --reload-rules && sudo udevadm trigger
5

6
# 烧录 + 串口监视
7
pio run -t upload
8
pio device monitor

八、STM32CubeMX

说明

STM32CubeMX 是 ST 官方的图形化配置工具。你在界面上点选引脚、配置时钟树、勾选外设，它生成对应的初始化 C 代码——省去手写寄存器配置的工作量。

它的定位和前面几个不同：前面是编译/烧录工具，CubeMX 是代码生成器。它支持生成 STM32CubeIDE、IAR、Keil 三种工程，也能只导出初始化代码用在自定义构建系统里。

安装

从 st.com 下载（需要 ST 账号登录）：

1
SetupSTM32CubeMX-6.18.1-Lin-x86_64.zip   # 633MB

解压得到自解压安装器：

1
unzip SetupSTM32CubeMX-6.18.1-Lin-x86_64.zip
2
# 得到 SetupSTM32CubeMX-6.18_1  (548MB)
3

4
chmod 777 SetupSTM32CubeMX-6.18_1
5
./SetupSTM32CubeMX-6.18_1

几个要点：

• 这是图形化安装向导，没有静默安装参数，必须在有图形环境的机器上运行
• 自带 JRE（Temurin 21），不需要系统额外装 Java，也不使用系统的 Java
• 不需要 sudo（除非装到 /opt）；装到家目录更省事，避免权限问题

验证

1
ls ~/STM32CubeMX/
2
# db  help  jre  olddb  plugins

看到 jre/ 目录说明自带的 Java 运行时也在。

九、AI 辅助工具配置

说明

嵌入式开发里 AI 助手能帮上忙的地方：查寄存器、解释编译错误、生成外设初始化代码、写 Makefile、排查启动问题。

但默认状态下 AI 并不懂你的芯片和工具链。需要两样东西来扩展它——这两者容易混淆，先分清：

简单说：插件给 AI 装工具，skills 给 AI 装知识。

本次配置涉及的具体工具：

插件安装

Claude Code 有插件市场机制：

1
# 查看已配置的市场
2
claude plugin marketplace list
3

4
# 更新市场索引
5
claude plugin marketplace update
6

7
# 安装插件
8
claude plugin install <插件名>

我装了 19 个插件，包括：

踩坑：github 插件连的是 api.githubcopilot.com，需要 GitHub Copilot 订阅才能用。如果只有普通 GitHub 账号，会报：

1
Error POSTing to endpoint: bad request: Authorization header is badly formatted

因为它的配置要求环境变量 GITHUB_PERSONAL_ACCESS_TOKEN，而普通 PAT 对 Copilot 端点无效。

Skills 安装

Skills 是模块化的领域知识包，用 skills CLI 管理：

1
# 搜索
2
npx skills find stm32
3
npx skills find embedded
4

5
# 安装（-g 全局，-y 跳过确认）
6
npx skills add <owner/repo@skill> -g -y
7

8
# 更新全部
9
npx skills update

我找到并安装了 leokemp223/embed-ai-tool（GitHub 933 stars），它提供了 24 个覆盖嵌入式全流程的 skills：

workflow 这个最有用——它能串联多个 skill 完成流水线，比如”编译 → 烧录 → 串口监控”一条命令。

验证

1
# 插件
2
claude plugin list
3

4
# Skills
5
ls ~/.claude/skills/          # 全局
6
ls <项目>/.agents/skills/     # 项目级

踩坑：embed-ai-tool 不支持全局安装，必须装在项目级。用 -g 会报：

1
PromptScript does not support global skill installation

embed-ai-tool 的安装与配置详解

上面提到的 embed-ai-tool 有 24 个 skill，装机过程涉及几个概念，值得单独说清楚。

安装

1
# 在项目根目录下执行（不要加 -g）
2
cd ~/code/stm32/UJN_test
3
npx skills add leokemp223/embed-ai-tool -y

安装过程会在项目里生成三个位置：

1
项目根/
2
├── .agents/skills/          ← ① 实际存放处（24 个 skill）
3
│   ├── build-cmake/
4
│   ├── flash-jlink/
5
│   ├── workflow/
6
│   └── ...
7
├── .claude/skills/          ← ② 符号链接（让 Claude Code 能发现）
8
│   └── build-cmake -> ../../.agents/skills/build-cmake
9
└── skills-lock.json         ← ③ 锁定文件（记录来源和哈希）

为什么要这么做？ 这是为了兼容多个 AI 工具：

• .agents/skills/ 是通用约定——GitHub Copilot、OpenCode、Zed、Amp 等 +15 个工具都读这个目录
• .claude/skills/ 是符号链接——Claude Code 只认这个路径，链接过去就能共用同一份文件
• 好处：不用为每个工具维护一份副本，更新一处全部生效

skills-lock.json 的作用

这个文件记录每个 skill 的来源和内容哈希：

1
{
2
  "version": 1,
3
  "skills": {
4
    "build-cmake": {
5
      "source": "leokemp223/embed-ai-tool",
6
      "sourceType": "github",
7
      "skillPath": "skills/build-cmake/SKILL.md",
8
      "computedHash": "93247950e539591b34a580a7d088ac6f29e893a9d10069f283bc35c757f5d169"
9
    }
10
  }
11
}

它让 npx skills update 能判断哪些 skill 有更新——只重新拉取哈希变了的，不用全部重下。

单个 skill 的内部结构

每个 skill 是一个目录，典型结构：

1
.agents/skills/flash-jlink/
2
├── SKILL.md                 ← 主文件：告诉 AI 这个技能做什么、怎么用
3
├── scripts/
4
│   └── jlink_flasher.py     ← 可执行脚本，AI 会调用它
5
├── references/
6
│   └── usage.md             ← 详细参数说明
7
└── agents/
8
    └── openai.yaml          ← 其他 AI 工具的适配配置

SKILL.md 的格式是带 frontmatter 的 Markdown：

1
---
2
name: flash-jlink
3
description: 当需要使用 SEGGER J-Link 探针烧录固件，或启动 RTT 日志捕获时使用。
4
---
5

6
# 正文：适用场景、必要输入、依赖、执行步骤

关键点：description 字段决定了 AI 什么时候会加载这个 skill。所以这些 description 都写得很具体（“当需要…时使用”），而不是泛泛的”J-Link 相关”。

24 个 skill 一览

最有价值的是 workflow

workflow 能把你手动敲的一串命令变成一句话：

1
# 手动流程
2
make -j$(nproc)
3
st-flash --reset write build/firmware.bin 0x08000000
4
picocom -b 115200 /dev/ttyUSB0
5

6
# 用 workflow skill
7
"编译这个 CMake 工程，烧录到板子，然后打开串口监控"

它会自动判断用哪个 build skill、哪个 flash skill，并串联起来。

验证

1
# 确认 24 个都在
2
ls .agents/skills/ | wc -l
3
# 24
4

5
# 确认符号链接有效（Claude Code 能否看到）
6
ls -la .claude/skills/ | head -3
7
# build-cmake -> ../../.agents/skills/build-cmake
8

9
# 确认锁定文件
10
cat skills-lock.json | head -5

在 Claude Code 里，用 /skills 或者直接问”我有哪些 skills”就能看到它们被加载了。

更新

1
npx skills update          # 更新全部
2
npx skills check           # 只检查不更新

因为装了 skills-lock.json，更新是增量的——只拉哈希变化的部分。

十、实战：Keil 工程迁移到 GCC

前面都是环境配置，这一节是真正的技术活。

说明

要解决的问题：手上有个 Windows 上用 Keil 写的工程，想搬到 Linux 上用 GCC 编译。

涉及的几个概念：

根本障碍：Keil 用 ARMASM 汇编器，GCC 用 GNU as，启动文件语法完全不兼容。

Keil 的启动文件：

1
Stack_Size      EQU     0x00000400
2
                AREA    STACK, NOINIT, READWRITE, ALIGN=3

GCC 完全不认识 EQU 和 AREA。所以必须重写启动文件，并补上 GCC 需要的链接脚本和 Makefile。

从 Keil 工程里挖配置

好在 .uvprojx 是 XML 格式，配置都能抠出来：

1
grep -oE "<Define>[^<]*</Define>" Project.uvprojx
2
# <Define>USE_STDPERIPH_DRIVER</Define>
3

4
grep -oE "<IncludePath>[^<]*</IncludePath>" Project.uvprojx
5
# .\Start;.\Library;.\User;.\System
6

7
grep -oE "<FileName>[^<]*\.s</FileName>" Project.uvprojx
8
# startup_stm32f10x_md.s

得到三条关键信息：

• 宏定义：USE_STDPERIPH_DRIVER（还要手工补 STM32F10X_MD，因为 F103C8T6 是中容量）
• 头文件路径：Start、Library、User、System
• 启动文件：startup_stm32f10x_md.s（md = medium density）

手写链接脚本

STM32F103C8T6 有 64K Flash 和 20K RAM：

1
ENTRY(Reset_Handler)
2

3
MEMORY
4
{
5
  FLASH (rx)  : ORIGIN = 0x08000000, LENGTH = 64K
6
  RAM   (rwx) : ORIGIN = 0x20000000, LENGTH = 20K
7
}
8

9
_estack = ORIGIN(RAM) + LENGTH(RAM);
10

11
SECTIONS
12
{
13
  .isr_vector :
14
  {
15
    . = ALIGN(4);
16
    KEEP(*(.isr_vector))     /* 中断向量表必须在最前面 */
17
    . = ALIGN(4);
18
  } > FLASH
19

20
  .text :
21
  {
22
    *(.text*)
23
    *(.rodata*)
24
    . = ALIGN(4);
25
    _etext = .;
26
  } > FLASH
27

28
  .data :
29
  {
30
    . = ALIGN(4);
31
    _sdata = .;
32
    *(.data*)
33
    . = ALIGN(4);
34
    _edata = .;
35
  } > RAM AT> FLASH          /* 加载地址在 FLASH，运行地址在 RAM */
36
  _sidata = LOADADDR(.data);
37

38
  .bss (NOLOAD) :
39
  {
40
    . = ALIGN(4);
41
    _sbss = .;
42
    *(.bss*)
43
    *(COMMON)
44
    . = ALIGN(4);
45
    _ebss = .;
46
  } > RAM
47
}

手写 GNU 启动文件

1
    .syntax unified
2
    .cpu cortex-m3
3
    .thumb
4

5
.section .isr_vector, "a", %progbits
6
    .word _estack
7
    .word Reset_Handler
8
    .word NMI_Handler
9
    .word HardFault_Handler
10
    ; ... 其余中断向量
11

12
.section .text
13
    .thumb
14
    .global Reset_Handler
15
    .thumb_func              ; ← 关键，下一节详细说
16
Reset_Handler:
17
    ldr sp, =_estack
18
    bl SystemInit
19

20
    ; 把 .data 段从 FLASH 复制到 RAM
21
    ldr r0, =_sdata
22
    ldr r1, =_edata
23
    ldr r2, =_sidata
24
1:  cmp r0, r1
25
    bcs 2f
26
    ldr r3, [r2], #4
27
    str r3, [r0], #4
28
    b 1b
29

30
2:  ; 清零 .bss 段
31
    ldr r0, =_sbss
32
    ldr r1, =_ebss
33
    movs r3, #0
34
3:  cmp r0, r1
35
    bcs 4f
36
    str r3, [r0], #4
37
    b 3b
38

39
4:  bl main
40
    b .

Makefile

1
CPU   := -mcpu=cortex-m3 -mthumb
2
DEFS  := -DSTM32F10X_MD -DUSE_STDPERIPH_DRIVER
3
CFLAGS := $(CPU) $(DEFS) -IStart -ILibrary -IUser -ISystem \
4
          -std=c99 -Wall -O1 -g3 -ffunction-sections -fdata-sections
5
LDFLAGS := $(CPU) -Tgcc/stm32_flash.ld --specs=nosys.specs -Wl,--gc-sections

编译过程中的小坑：第一次编译报

1
undefined reference to `Default_Handler'

因为向量表引用了 Default_Handler 但没定义它。补上：

1
    .weak Default_Handler
2
    .type Default_Handler, %function
3
Default_Handler:
4
    b .

修复后编译通过：

1
make -j$(nproc)
2
#    text    data     bss     dec     hex
3
#    1304       0       0    1304     518

1.3KB 固件，Flash 只用了 2%。

十一、最大的坑：.thumb_func

症状：烧录成功，但板子毫无反应

1
st-flash --reset write build/STM32_test.bin 0x08000000
2
# Flash written and verified! jolly good!

烧录和校验都通过，复位也执行了。但板子完全没有反应——按键没反应，灯不亮，连闪一下都没有。

作为对照，把 Keil 原本编译的 .axf 转成二进制烧进去：

1
arm-none-eabi-objcopy -O binary Objects/Project.axf build/Project_keil.bin
2
st-flash --reset write build/Project_keil.bin 0x08000000

板子正常工作。说明硬件和接线都没问题，问题出在我编译的固件上。

排查：用十六进制对比向量表

1
xxd -e -g4 build/STM32_test.bin | head -1     # GCC 版
2
xxd -e -g4 build/Project_keil.bin | head -1   # Keil 版

对比第二个字（Reset_Handler 地址）：

差异就在最低位。

原理：Cortex-M 与 Thumb 位

Cortex-M 内核只能执行 Thumb 指令集，不支持 ARM 指令集。向量表里每个函数地址的最低位被用作模式标志：

• 最低位 = 1 → 进入 Thumb 模式 ✅
• 最低位 = 0 → 进入 ARM 模式 → Cortex-M 不支持 → 上电立刻 HardFault

所以我的固件一上电就崩了，main() 根本没机会执行，现象就是”完全没反应”。

根因：GNU 汇编器的一个陷阱

Keil 的 ARMASM 会自动置位这个标志。而 GNU 汇编器里，.thumb 伪指令只影响指令编码，不改变符号属性：

1
    .thumb              ; 告诉汇编器用 Thumb 指令编码
2
    .global Reset_Handler
3
    .thumb_func         ; 这个才给符号打上 Thumb 标记
4
Reset_Handler:

少了 .thumb_func，Reset_Handler 就被当成普通（ARM 模式）函数，链接器写进向量表时末位就是 0。

修复

这里用增补标记突出唯一需要补上的 .thumb_func 行；它改变的是符号属性，不是指令本身。

1
    .global Reset_Handler
2
    .thumb_func          ; 加上这一行
3
Reset_Handler:

重新编译后检查向量表：

1
xxd -e -g4 build/STM32_test.bin | head -1
2
# 00000000: 20005000 080004c5
3

4
# Reset_Handler: 0x080004C5 -> 最低位=1 ✅ Thumb

末位从 0 变成 1 了。

诚实说明：以上是软件层面的验证（向量表二进制确认）。这个修复后的固件没有在硬件上完成复验——写作时调试探针反复从 USB 总线掉线（st-flash 报 Couldn't find any ST-Link devices），一直没能稳定连上。

.thumb_func 缺失导致 Cortex-M 上电即 HardFault 是确定的行为，向量表末位的变化也已实测确认。但”板子恢复正常”这句我没有验证过，所以不写。

补充：实际上所有中断服务函数都需要 .thumb_func。如果不想逐个加，可以在文件开头用宏批量处理，或者依赖编译器生成的 C 函数——GCC 编 C 代码时会自动加这个标记，只有手写汇编才需要操心。

十二、最终环境总览

所有工具链的实测验证结果：

日常开发流程

裸机 + Makefile：

1
make -j$(nproc)
2
make flash-stlink     # 或 make flash-jlink

Zephyr：

1
cd ~/zephyrproject && source .venv/bin/activate
2
cd myprojects/myapp && west build -b <board> . && west flash

PlatformIO：

1
pio run -t upload && pio device monitor

十三、踩坑清单

按”值得记住”排序：

1. .thumb_func ⭐⭐⭐ — Cortex-M 手写汇编的必修课。缺了它固件会静默失败，所有工具都报成功，只有板子自己知道它崩了。排查用十六进制对比向量表。

2. Zephyr setup.sh 死循环 ⭐⭐ — 非交互运行时 read 读到 EOF 会陷入 99% CPU 空转。用 yes | ./setup.sh 解决。

3. SEGGER 官网下载认准带版本号的文件名 ⭐⭐ — 不带版本号的多半是 27KB 的 HTML 协议页。

4. Fedora 41+ 的 DNF5 改了组名格式 — 要用 @development-tools 而不是 "Development Tools"。

5. Zephyr SDK 文件名必须带 _gnu — 少这个后缀就是 404。下载后必须校验大小（约 2GB）。

6. 改用户组后必须重新登录 — source ~/.zshrc 不起作用，组权限是登录会话级别的。udev 规则没这个问题，优先用 udev。

7. udev 规则只对新插入的设备生效 — 已插着的设备要拔了重插，或者 sudo udevadm trigger。

8. Zephyr 的安装顺序 — 先 west packages pip --install 再 west zephyr-export，顺序反了会报 jsonschema 缺失，而且错误信息会被 west 自身的 bug 掩盖。

9. GitHub Copilot 插件需要订阅 — 普通 PAT 对 api.githubcopilot.com 无效。

10. PlatformIO 的 PATH 取决于安装方式 — dnf 装在 /usr/bin（不需要配 PATH），官方脚本装在 ~/.platformio/penv/bin（需要配）。照抄教程容易多配一行无效的。

结语

整套环境配下来，最耗时的不是安装本身，而是定位那些”工具都报告成功、但实际不工作”的问题。

.thumb_func 那个坑最典型：编译成功、烧录成功、校验通过——所有环节都是绿的，但板子就是不动。如果不是把两份固件做十六进制对比，很容易往硬件方向排查。

这也是为什么这篇文章里每个环节都强调实际验证，而不只是看版本号：能编译出东西，才算真的装好了。