环境安装

Ubuntu 和 Fedora 都可以用于本教程，按自己正在使用的系统选择安装命令即可。系统依赖包名不同，后续的工作区、应用源码、编译和烧录流程共用。

验证记录：本站固件编译实际在 Fedora 上完成；Ubuntu 24.04 LTS 的安装命令依据官方指南整理，尚未在全新 Ubuntu 主机上完整复验。这是验证范围的区别，不是系统优先级。

工具组成

写 C 文件只是第一步。编译配置需要 CMake，执行编译任务需要 Ninja，生成硬件定义需要设备树工具，下载依赖和烧录需要 Python 工具，生成 ESP32 指令需要交叉编译器。IDE 可以调用它们，但不会替你消除这些依赖。

工具	运行位置与职责
主机 gcc / g++	在电脑上构建工具或 Python 的原生扩展
CMake	根据应用、板卡与配置生成构建规则
Ninja	按规则调用编译器，执行增量构建
Python 虚拟环境	隔离 west 和 Python 依赖，不包含 Zephyr 内核
west	管理源码仓库，并调用构建、烧录等扩展命令
Zephyr SDK	包含交叉编译器和部分主机工具，输出给 MCU 运行的代码

因此，“已激活虚拟环境”不代表 SDK 已安装，也不代表正在使用正确的 Zephyr 源码。

系统依赖

以下用于新环境；已有环境先查看版本，不需要为了跟教程重装全部工具。

Ubuntu

以下命令适用于 Ubuntu 24.04 LTS x86-64：

sudo apt update
sudo apt install --no-install-recommends git cmake ninja-build gperf \
  ccache dfu-util device-tree-compiler wget python3-dev python3-venv python3-tk \
  xz-utils file make gcc g++ gcc-multilib g++-multilib libsdl2-dev libmagic1 \
  libusb-1.0-0-dev libudev-dev pkg-config

最后三个包用于 USB 相关 Python 扩展的构建，避免遇到 hidapi 找不到 libusb/udev 的错误。ARM64 主机不要照装两个 multilib 包；其 SDK 主机架构也必须匹配。

Ubuntu 24.04 的系统 Python 为 3.12，安装 python3-venv 后可继续创建虚拟环境。其他 Ubuntu 版本先核对工具版本。

Fedora

使用 dnf 安装主机工具与开发库：

sudo dnf install git gcc gcc-c++ make cmake ninja-build gperf ccache \
  dfu-util dtc wget which python3-pip python3-tkinter python3-devel \
  xz file SDL2-devel libusb1-devel systemd-devel pkgconf-pkg-config

libusb1-devel 对应 libusb 开发文件，systemd-devel 提供 libudev 开发文件，pkgconf-pkg-config 用于定位这些库。安装 Zephyr SDK 不能替代这里的主机 gcc。

Fedora 的系统 Python 版本随发行版变化。后续命令使用 Python 3.12；先执行 python3.12 --version。若未安装，可使用发行版提供的对应版本或 Python 版本管理工具 单独准备，不能只把虚拟环境目录取名 py312 就认为解释器变成了 3.12。使用源码构建的 Python 扩展时，开发头文件也必须匹配所选解释器。

历史上的 hidapi 缺库与编译器问题见 安装排错记录，无需先阅读该记录才能开始。

环境检查

本教程参考的 main 基线要求 CMake 至少 3.28、Python 至少 3.12、DTC 至少 1.4.6。后续工作区命令选择 Python 3.12；两个系统都要检查实际版本，不能只看到命令存在就继续。

cat /etc/os-release
uname -m
python3 --version
python3.12 --version
cmake --version
dtc --version
ninja --version
gcc --version
pkg-config --modversion libusb-1.0 libudev

目录布局

继续沿用本站已有命令中的路径，目录名称不限制操作系统：

~/Projects/
├── zephyr-docs/                 # 笔记与教学示例
└── zephyr-main-workspace/       # west 工作区
    ├── .venv-py312-main/        # Python 工具
    ├── .west/                  # 工作区配置
    ├── zephyr/                 # 内核、驱动、板卡定义
    ├── modules/                # LVGL、芯片 HAL 等
    └── applications/           # 可选：自己的应用
~/.local/opt/zephyr-sdk-1.0.1/    # 本教程已验证的 SDK

应用可以在工作区外，但构建时必须明确源码工作区和应用路径。不要将虚拟环境、模块仓库和 SDK 当成自己的应用代码一起提交。

USB 串口权限

连接开发板后先找端口：

ls -l /dev/serial/by-id/
id -un

若不存在 by-id，稍后安装 Python 依赖后用串口枚举工具检查。不要假设所有板都叫 ttyACM0。

两种系统都先用 ls -l /dev/ttyACM0 检查实际端口的属组。若属组是 dialout，且自己的账号不在其中，再执行：

sudo usermod -aG dialout "$USER"

退出桌面会话并重新登录，然后用 id -nG 检查。不要用 sudo west 绕过问题，否则还容易在工作区生成 root 所有的文件。

练习

为什么电脑上同时需要 gcc 和 SDK 中的编译器？为什么 Python 虚拟环境可以删除重建，但不应该包含应用源码？回答清楚后进入 west、源码与 SDK。

来源：Zephyr 入门指南。安装版本应与实际检出的 Zephyr 要求一起核对。