Zephyr SDK 1.0.1 安装指南：在STM32F103C8T6上运行实时操作系统-育师

如果你正在寻找一个能替代 FreeRTOS、RT-Thread 的现代化实时操作系统，并且希望它能原生支持你手头那块经典的“蓝色药丸”STM32F103C8T6开发板，那么 Zephyr RTOS 很可能就是你下一个需要认真评估的选择。

但当你兴冲冲地打开 Zephyr 官网，准备大干一场时，很可能会被它的开发环境搭建过程“劝退”。它不像 Keil 或 STM32CubeIDE 那样提供一个集成的安装包，而是依赖一整套基于命令行的工具链，其中最关键、也最容易出问题的环节，就是Zephyr SDK的安装与配置。很多人卡在这一步，误以为 Zephyr 门槛极高，最终无奈放弃。

这篇文章要解决的核心问题，就是如何干净利落地完成 Zephyr SDK 1.0.1 版本的安装，并以此为基础，在 STM32F103C8T6 最小系统板上跑通你的第一个 Zephyr 应用程序。我们将避开官方文档中可能存在的“跳步”和隐含假设，用一个完整的、可复现的案例，带你从零开始，直到点灯成功。你会发现，一旦跨过 SDK 安装这个“坎”，Zephyr 强大的模块化、高度可配置性和对大量硬件（支持超过 190 款 STM32 板卡）的原生支持，将为你打开嵌入式开发的新大门。

1. 为什么是 Zephyr？它解决了什么痛点？

在开始动手之前，我们需要先明确 Zephyr 的价值。你可能会问：已经有 FreeRTOS、RT-Thread 这些成熟方案了，为什么还要折腾 Zephyr？

Zephyr 的核心优势在于其高度模块化、高度可配置性和强大的硬件抽象层。它不是一个“一体式”的固件，而是一个由数百个独立模块（Kconfig 配置项）组成的“乐高积木”系统。这意味着你可以为资源极其有限的设备（比如只有 8KB RAM 的 MCU）裁剪出一个极简内核，也可以为功能复杂的设备（如带 WiFi/BLE 的 SoC）构建一个功能丰富的系统，而它们共享同一套代码库和开发流程。

对于 STM32F103C8T6 这类经典 Cortex-M3 芯片，Zephyr 的优势具体体现在：

统一的开发体验：无论你开发的是 STM32、Nordic nRF52 还是 ESP32，使用的工具链（west）、构建系统（CMake）和配置方式（Kconfig）是完全一致的。这极大降低了学习多种平台的成本。
丰富的驱动和组件：Zephyr 社区提供了大量经过验证的驱动（GPIO、UART、I2C、SPI、ADC 等）和高级组件（文件系统、网络协议栈、蓝牙栈等）。你不需要从零开始写驱动，更多时候是进行配置和集成。
强大的配置系统：通过menuconfig或guiconfig图形化界面，你可以直观地启用/禁用任何功能，并自动解决依赖关系，避免了手动修改头文件带来的混乱和错误。
面向未来的安全性：Zephyr 在设计之初就考虑了安全特性，如内存保护、线程隔离等，这对于需要连接网络的物联网设备尤为重要。

而Zephyr SDK，正是解锁这一切的“钥匙”。它不是一个 IDE，而是一个包含了交叉编译工具链（GCC）、OpenOCD（调试）、QEMU（模拟）等所有必要工具的集合包。安装并正确配置 SDK，是后续所有开发工作的基石。

2. 环境准备：明确你的“战场”

在开始安装前，请确保你的开发环境符合以下要求。我们将以Windows 10/11 系统配合WSL2 (Ubuntu 22.04 LTS)作为主要演示环境。这是目前 Zephyr 官方推荐且问题最少的开发方式。当然，你也可以使用纯 Linux 系统或 macOS，核心步骤是相通的。

必备条件清单：

操作系统：Windows 10/11 并已安装 WSL2。如果你尚未安装，请参考微软官方文档启用 WSL2 并安装一个 Ubuntu 发行版（建议 22.04 LTS）。
WSL 内的 Ubuntu：确保系统已更新。
```
sudo apt update && sudo apt upgrade -y
```

基础依赖：安装编译 Zephyr 所需的依赖包。

sudo apt install --no-install-recommends git cmake ninja-build gperf \ ccache dfu-util device-tree-compiler wget \ python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \ make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1

Python 环境：Zephyr 的工具west是基于 Python 的。建议使用pip3安装，并确保~/.local/bin在 PATH 环境变量中。
```
pip3 install --user -U pip echo 'export PATH=~/.local/bin:$PATH' >> ~/.bashrc source ~/.bashrc
```

准备好以上环境，我们就可以开始安装最关键的 Zephyr SDK 了。

3. 核心步骤：安装 Zephyr SDK 1.0.1

这是本文的重中之重。我们将采用手动下载安装包的方式进行，这种方式比在线安装脚本更可控，尤其适合网络环境不稳定或需要特定版本的情况。

3.1 下载 SDK 安装包

首先，在 WSL 的 Ubuntu 中，选择一个合适的目录，例如~/zephyrproject，然后下载 SDK。

# 创建项目目录并进入 mkdir -p ~/zephyrproject cd ~/zephyrproject # 下载 Zephyr SDK 1.0.1 的安装包 # 注意：版本号可能更新，请以实际需求为准。1.0.1是一个稳定的长期支持版本。 wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.1/zephyr-sdk-1.0.1_linux-x86_64.tar.xz # 下载对应的校验文件 wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.1/sha256.sum

3.2 验证与解压

下载完成后，务必验证文件的完整性，这是保证后续编译不出奇怪错误的重要一步。

# 校验下载文件的 SHA256 哈希值 sha256sum -c sha256.sum 2>/dev/null | grep OK

如果看到zephyr-sdk-1.0.1_linux-x86_64.tar.xz: OK的输出，说明文件完整无误。

接着，解压安装包到/opt目录（推荐）或你的用户目录。

# 解压到 /opt 目录，需要 sudo 权限 sudo tar xf zephyr-sdk-1.0.1_linux-x86_64.tar.xz -C /opt # 或者解压到用户目录 # tar xf zephyr-sdk-1.0.1_linux-x86_64.tar.xz -C ~

我们以安装到/opt为例。

3.3 运行安装脚本

解压后，进入 SDK 目录，运行安装脚本。这个脚本会设置工具链的权限并安装必要的 udev 规则（用于调试器访问设备权限）。

# 进入 SDK 目录 cd /opt/zephyr-sdk-1.0.1 # 运行安装脚本 # 对于所有用户，使用： sudo ./setup.sh # 或者仅为当前用户安装（不推荐，可能遇到权限问题）： # ./setup.sh -h

在安装过程中，脚本可能会询问是否安装用于 QEMU 模拟器的额外工具链，对于 STM32 开发，你可以选择n。但对于全面学习，安装所有工具链也无妨。

3.4 配置环境变量

安装脚本通常会自动尝试修改你的 shell 配置文件（如~/.bashrc或~/.zshrc），但为了确保万无一失，我们手动检查并添加。打开你的~/.bashrc文件：

nano ~/.bashrc

在文件末尾，添加以下两行，将 SDK 的交叉编译工具链路径加入到系统 PATH 中：

export ZEPHYR_SDK_INSTALL_DIR=/opt/zephyr-sdk-1.0.1 export PATH=$ZEPHYR_SDK_INSTALL_DIR/sysroots/x86_64-pokysdk-linux/usr/bin:$PATH

保存并退出编辑器（在 nano 中按Ctrl+X，然后按Y，最后回车）。让配置立即生效：

source ~/.bashrc

3.5 验证 SDK 安装

运行以下命令，检查工具链是否可用：

# 检查 ARM 交叉编译器 arm-zephyr-eabi-gcc --version # 检查 CMake 和 Ninja cmake --version ninja --version # 检查 west 是否已安装（如果之前没装过） west --version

如果arm-zephyr-eabi-gcc能正确输出版本信息（如gcc version 12.2.0），恭喜你，Zephyr SDK 已经成功安装！

4. 获取 Zephyr 源码并设置环境

有了 SDK，我们还需要 Zephyr 操作系统本身的源代码。

4.1 使用 West 工具获取源码

west是 Zephyr 的元工具，用于管理多个仓库（主仓库和众多的模块仓库）。我们用它来初始化工作区。

# 回到项目目录 cd ~/zephyrproject # 使用 west 初始化，并获取主仓库和所有必要的模块 # 这里我们获取 v3.6.0 版本（一个稳定的 LTS 版本），与 SDK 1.0.1 兼容性好 west init -m https://github.com/zephyrproject-rtos/zephyr --mr v3.6.0 # 拉取所有模块代码（这一步耗时较长，取决于网络） west update

4.2 导出 Zephyr 环境变量

Zephyr 构建系统需要知道 SDK 和源码的位置。通过一个脚本可以一次性设置好所有必要的环境变量。

# 导出 Zephyr 环境 source ~/zephyrproject/zephyr/zephyr-env.sh

为了方便，你也可以将这一行添加到你的~/.bashrc文件中，这样每次打开终端都会自动设置好 Zephyr 环境。

echo "source ~/zephyrproject/zephyr/zephyr-env.sh" >> ~/.bashrc source ~/.bashrc

5. 第一个案例：在 STM32F103C8T6 上点亮 LED

现在，激动人心的时刻到了。我们将编译一个最简单的blinky（闪烁 LED）例程，并将其烧录到你的 STM32F103C8T6 最小系统板（也就是常说的“蓝色药丸” Blue Pill）上。

硬件连接准备：

将 STM32F103C8T6 通过 USB 转 TTL 串口模块连接到电脑（用于查看日志）。连接方式：MCU 的PA9(TX) 接串口模块的 RX，PA10(RX) 接串口模块的 TX，GND 互连。
将 ST-Link V2 调试器连接到板子。连接方式：SWDIO->DIO,SWCLK->CLK,3.3V->3.3V,GND->GND。
找到板载 LED 对应的引脚。对于最常见的 Blue Pill，用户 LED 通常连接在PC13引脚。

5.1 配置项目

Zephyr 为许多开发板提供了现成的配置。STM32F103C8T6 最小系统板对应的板型名称通常是stm32f103c8t6或bluepill。我们以bluepill为例。

# 进入一个临时目录构建项目 mkdir -p ~/zephyrproject/blinky_test cd ~/zephyrproject/blinky_test # 使用 west 创建基于 blinky 示例的构建目录，并指定目标板为 bluepill west build -p always -b bluepill ~/zephyrproject/zephyr/samples/basic/blinky

-p always: 表示总是重新构建（如果目录已存在则先清理）。
-b bluepill: 指定目标开发板。
最后是示例程序的路径。

5.2 检查与自定义配置（可选）

在构建前，你可以使用图形化配置工具来查看或修改配置，例如确认 LED 引脚是否正确。

# 进入构建目录并启动 menuconfig cd build west build -t menuconfig

在menuconfig界面中，你可以通过箭头键导航。对于 LED，路径通常是：Device Drivers->LED drivers->[ ] LED driver for GPIO(确保启用)。然后检查GPIO配置。不过对于bluepill板型，这些通常已在设备树中定义好。你可以先尝试默认配置。

5.3 编译项目

如果你跳过了上一步的配置，或者配置完成后，直接编译即可：

# 在构建目录中，或回到项目目录使用 west 编译 west build

如果一切顺利，你将在最后看到类似以下的输出：

[XX/XX] Linking C executable zephyr/zephyr.elf Memory region Used Size Region Size %age Used FLASH: XXXXX B YYYY B ZZ% RAM: AAAAA B BBBB B CC% [XX/XX] Generating zephyr/zephyr.bin [XX/XX] Generating zephyr/zephyr.hex

这表示编译成功，并生成了zephyr.bin和zephyr.hex等烧录文件。

5.4 烧录与调试

我们将使用 OpenOCD（已包含在 Zephyr SDK 中）通过 ST-Link 进行烧录。

# 使用 west 和 openocd 烧录 west flash

west flash命令会自动调用正确的烧录 runner（这里是openocd）并找到生成的zephyr.elf文件进行烧录。看到** Flashing Success**之类的提示即表示烧录成功。

5.5 验证结果

烧录完成后，STM32F103C8T6 板子上的 LED（PC13）应该开始以大约 1Hz 的频率闪烁。如果没有闪烁，请检查：

硬件连接是否正确，特别是 ST-Link 的连接和供电。
板载 LED 的引脚是否是PC13（有些板子可能不同）。
串口日志：连接串口工具（如minicom,picocom或 Windows 下的 Putty、SecureCRT），波特率设置为 115200，可以看到 Zephyr 的启动日志，帮助诊断问题。
```
# 在 WSL 中安装并使用 picocom sudo apt install picocom picocom -b 115200 /dev/ttyUSB0 # 请将 /dev/ttyUSB0 替换为你的实际串口设备
```

6. 进阶案例：实现 UART 串口打印

仅仅点灯还不够，串口通信是嵌入式调试的“生命线”。让我们创建一个简单的程序，通过串口打印“Hello Zephyr from STM32F103C8T6!”。

6.1 创建自定义项目

我们不直接修改示例，而是创建一个新的项目目录。

mkdir -p ~/zephyrproject/uart_hello cd ~/zephyrproject/uart_hello

6.2 编写主程序代码

创建src目录和主文件main.c：

mkdir src nano src/main.c

将以下代码写入main.c：

#include <zephyr/kernel.h> #include <zephyr/drivers/uart.h> #include <zephyr/device.h> /* 获取 UART1 设备实例。在 STM32F103C8T6 上，UART1 通常对应 PA9(TX)/PA10(RX) */ #define UART1_NODE DT_NODELABEL(usart1) static const struct device *uart_dev = DEVICE_DT_GET(UART1_NODE); void main(void) { int ret; const char *tx_data = "Hello Zephyr from STM32F103C8T6!\r\n"; /* 检查 UART 设备是否就绪 */ if (!device_is_ready(uart_dev)) { printk("UART device not ready!\n"); return; } printk("UART1 is ready, start printing...\n"); while (1) { /* 通过 UART 发送字符串 */ for (int i = 0; tx_data[i] != '\0'; i++) { uart_poll_out(uart_dev, tx_data[i]); } /* 等待 1 秒 */ k_sleep(K_SECONDS(1)); } }

6.3 编写项目配置文件

在项目根目录创建CMakeLists.txt：

nano CMakeLists.txt

写入以下内容：

# 设置 Zephyr 所需的最小 CMake 版本 cmake_minimum_required(VERSION 3.20.0) # 查找 Zephyr 包。这会将 Zephyr 构建系统引入项目。 find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) # 将 src 目录添加到项目中 project(uart_hello) # 将源文件添加到目标 target_sources(app PRIVATE src/main.c)

创建板型覆盖文件（可选但推荐）。由于bluepill板型默认可能未使能 UART1，我们可以创建一个设备树覆盖文件来确保它被启用。

mkdir -p boards nano boards/bluepill.overlay

写入以下内容，明确启用 USART1：

/ { chosen { zephyr,console = &usart1; }; }; &usart1 { status = "okay"; current-speed = <115200>; pinctrl-0 = <&usart1_tx_pa9 &usart1_rx_pa10>; pinctrl-names = "default"; };

6.4 构建与烧录

现在，像之前一样构建和烧录项目，但指定我们自定义的项目目录。

# 在项目根目录执行 west build -p always -b bluepill . -- -DOVERLAY_CONFIG=boards/bluepill.overlay

.表示当前目录是项目目录。
--之后是传递给 CMake 的参数，这里指定了我们的设备树覆盖文件。

构建成功后，进行烧录：

west flash

6.5 验证串口输出

使用串口工具（如picocom -b 115200 /dev/ttyUSB0）连接开发板。你应该能看到每秒输出一次 “Hello Zephyr from STM32F103C8T6!” 字符串，同时开发板上的 LED 可能也在闪烁（因为默认的prj.conf可能继承了某些配置）。这证明你的 UART 驱动和应用程序都工作正常。

7. 常见问题与排查思路

在安装和开发过程中，你几乎一定会遇到一些问题。下表列出了最常见的问题及其解决方法：

问题现象	可能原因	排查方式	解决方案
`west`命令未找到	1.`pip3`安装的`west`不在 PATH 中。 2. 未执行`source ~/.bashrc`。	执行`which west`或`west --version`。	1. 确认`~/.local/bin`在 PATH 中，并`source ~/.bashrc`。 2. 重新安装：`pip3 install --user west`。
`arm-zephyr-eabi-gcc`未找到	1. SDK 环境变量未设置。 2. SDK 安装路径错误。	执行`echo $ZEPHYR_SDK_INSTALL_DIR`和`which arm-zephyr-eabi-gcc`。	1. 检查`~/.bashrc`中的`ZEPHYR_SDK_INSTALL_DIR`和`PATH`设置是否正确。 2. 重新运行 SDK 的`setup.sh`。
`west build`失败，提示找不到板型	1. 板型名称拼写错误。 2. Zephyr 源码中不支持该板型。	执行`west boards`查看所有支持的板型列表。	1. 使用 `west boards
编译错误，提示内存溢出	STM32F103C8T6 的 Flash/RAM 资源不足（64KB Flash, 20KB RAM）。	查看编译输出的内存占用报告。	1. 通过`menuconfig`裁剪不需要的功能模块（如文件系统、网络）。 2. 优化代码，减少全局变量和缓冲区大小。
`west flash`失败，无法连接 ST-Link	1. ST-Link 驱动未安装（Windows）。 2. 在 Linux/WSL 下缺少 udev 规则或权限。 3. 硬件连接问题。	1. 在设备管理器中检查 ST-Link。 2. 在 WSL 中执行`lsusb`查看是否能识别到 ST-Link 设备。	1. Windows 安装 ST-Link 官方驱动。 2. WSL/Linux：确保已运行 SDK 的`setup.sh`安装 udev 规则，或将用户加入`plugdev`组。 3. 检查接线，尤其是`SWDIO`和`SWCLK`。
串口无输出	1. 串口引脚接错（TX/RX 交叉）。 2. 波特率不匹配。 3. 设备树中 UART 未启用或引脚映射错误。	1. 确认硬件连接。 2. 检查代码和设备树中的波特率设置（应为 115200）。 3. 使用`west build -t menuconfig`检查 UART 驱动是否启用。	1. 交换 TX 和 RX 接线。 2. 确保代码、设备树和串口工具波特率一致。 3. 使用本文提供的设备树覆盖文件 (`bluepill.overlay`)。
下载速度慢 (`west update`)	网络连接 GitHub 不稳定。	观察下载进度。	1. 使用代理（需自行配置 git 和 wget 的代理）。 2. 使用国内镜像源（如 Gitee 镜像，但可能不是最新）。

8. 最佳实践与工程建议

当你成功运行了第一个程序后，为了进行更严肃的项目开发，请遵循以下建议：

版本控制：你的应用程序代码（src/目录、CMakeLists.txt、prj.conf、设备树覆盖文件等）应该用 Git 管理。但不要将build/目录和 Zephyr 源码本身（zephyr/目录）提交到你的仓库。使用.gitignore文件忽略它们。
配置管理：
- 使用prj.conf文件进行应用程序级别的 Kconfig 配置。
- 使用设备树覆盖文件（.overlay）进行板级硬件定制，而不是直接修改 Zephyr 内部的设备树文件。
- 对于不同的构建类型（如调试版、发布版），可以创建prj_release.conf等文件，并通过-DOVERLAY_CONFIG和-DCONF_FILECMake 参数指定。
调试：
- 日志：充分利用 Zephyr 的printk或更高级的日志系统进行调试。可以通过menuconfig调整日志级别。
- GDB 调试：Zephyr SDK 集成了 GDB。你可以使用west debug或west debugserver配合 ST-Link 进行源码级单步调试，这比单纯打印日志强大得多。
资源管理：对于 STM32F103C8T6 这类资源紧张的芯片，要时刻关注内存和 Flash 使用情况。定期使用west build -t rom_report和west build -t ram_report命令生成内存报告，指导你进行功能裁剪。
电源管理：如果开发电池供电设备，务必研究 Zephyr 的电源管理框架，合理使用低功耗模式。
社区与文档：遇到复杂问题，优先查阅 Zephyr 官方文档。在 Zephyr Discord 或 GitHub Issues 上提问时，提供尽可能多的信息：Zephyr 版本、SDK 版本、板型、你的prj.conf、错误日志等。

通过本文的步骤，你已经成功搭建了 Zephyr 开发环境，并在 STM32F103C8T6 上运行了两个基础示例。这个过程的真正价值在于，你掌握了一套标准化、可复现的嵌入式 RTOS 开发流程。接下来，你可以尝试集成传感器驱动、连接网络模块（如 W5500），甚至探索 Zephyr 对蓝牙或 LoRa 的支持，将这块经典的核心板潜力充分发挥出来。建议你将此环境保存为虚拟机或 Docker 镜像，作为未来所有 Zephyr 项目的可靠起点。