02 · west、源码与 SDK
目标：建立跟随官方 Zephyr main 的固件开发工作区。以下 main 命令只在新工作区首次执行；已经存在 .west 时，不要再次初始化。
项目已升级到官方 main。当前可直接使用的最新工作区是 ~/Projects/zephyr-main-workspace，Python 环境为 .venv-py312-main，SDK 为 1.0.1。下方原 zephyr-workspace / v4.2.0 内容作为已验证的旧版归档保留；新实验请使用下面的 main 工作区命令。
source ~/Projects/zephyr-main-workspace/.venv-py312-main/bin/activate
export ZEPHYR_SDK_INSTALL_DIR=~/.local/opt/zephyr-sdk-1.0.1
cd ~/Projects/zephyr-main-workspace/zephyr
git log -1 --oneline
main 工作区当前提交为 52b48529aec，Zephyr 开发版本显示为 4.4.99。它使用 SDK 1.0.1 和 esptool 5.4.0；不要把 main 的构建命令与旧 v4.2.0 虚拟环境混用。
关机后继续：只需重新激活
本机的 Python 依赖、SDK 和源码已保存在磁盘上；关机不会删除。main 工作区每次新开终端执行：
source ~/Projects/zephyr-workspace/.venv-py312/bin/activate
cd ~/Projects/zephyr-workspace/zephyr
python --version
west --version
本机 main 环境为 Python 3.12.14、west 1.5.0、Zephyr 4.4.99、SDK 1.0.1、esptool 5.4.0。2026-09-18 已用该环境成功编译微雪板卡 Hello World 和背光应用。继续板卡验证，不用再次 west init、west update、安装 Python 包或下载 SDK。
首次创建独立 Python 环境
本节仅用于在新机器或新工作区重建。已有 .venv-py312 时跳过，不能覆盖现有环境。
先准备 Python 3.12。本机由 uv 管理的解释器保存在 .tools/python/cpython-3.12.14-linux-x86_64-gnu/bin/python3.12；在其他机器可安装发行版的 Python 3.12，或参考 uv 官方安装说明。下面命令假设 python3.12 已在 PATH 中：
mkdir -p ~/Projects/zephyr-workspace
python3.12 -m venv ~/Projects/zephyr-workspace/.venv-py312
source ~/Projects/zephyr-workspace/.venv-py312/bin/activate
python -m pip install west
python -c "import sys; print(sys.executable); print(sys.version); assert sys.prefix != sys.base_prefix"
旧 .venv 只作排错记录保留；本教程后续统一使用 .venv-py312。不要使用 sudo pip。
旧版 v4.2.0 工作区初始化（归档）
以下命令仅用于重建旧版 v4.2.0 工作区。当前学习请使用上方已创建的 zephyr-main-workspace。
west init -m https://github.com/zephyrproject-rtos/zephyr \
--mr v4.2.0 ~/Projects/zephyr-workspace
cd ~/Projects/zephyr-workspace
west update
west zephyr-export
west init 建立工作区；west update 拉取清单中指定的模块；west zephyr-export 注册 CMake 包。下面单独安装 Python 依赖，失败时不需要重新执行以上步骤。
安装 Python 依赖：先检查 Fedora 开发包
本机先遇到 libusb 开发文件缺失，补齐后又因没有 gcc 导致 hidapi wheel 编译失败。因此不能只补 USB 库；安装完整主机依赖后再执行 pip。参考环境准备。
补齐本次错误涉及的包：
sudo dnf install gcc gcc-c++ make python3-devel libusb1-devel systemd-devel pkgconf-pkg-config
rpm -q gcc gcc-c++ make python3-devel libusb1-devel systemd-devel pkgconf-pkg-config
gcc --version
pkg-config --modversion libusb-1.0 libudev
以上检查全部成功后再继续。已经安装的包无需重复下载；其他版本 Python 的头文件按解释器来源确认。sudo 密码只在自己的终端输入。
然后激活虚拟环境，安装当前源码要求的 Python 包：
source ~/Projects/zephyr-workspace/.venv-py312/bin/activate
cd ~/Projects/zephyr-workspace
west packages pip --install
该命令符合 Zephyr v4.2.0 官方流程。它会调用虚拟环境中的 pip，安装 Zephyr 和声明了 Python 依赖的模块所列出的 requirements；不会自动安装 Fedora 系统开发包。
确认安装命令以成功状态结束，再检查：
python -m pip check
python -c "import hid; print('hidapi import OK')"
pip check 只检查已安装包之间的依赖一致性，单独显示成功不代表整份 requirements 已安装完成。
如果此前已经在最后一步失败
从上面的系统依赖检查继续，然后仅重试 west packages pip --install。不要删除工作区、不要再次 west init，也不用重新下载源码。
pkg-config package 'libusb-1.0 >= 1.0.9' not found：缺少或无法定位 libusb 开发文件。error: [Errno 2] No such file or directory: 'gcc'：缺少主机 C 编译器，按本页前置条件补齐。- 最后伴随
TypeError: expected string object, got 'PosixPath'：当前 west 在报告前一个 pip 失败时产生的次生错误，先看前面的原始错误。 - 补齐依赖后仍失败：记录新的首个错误；本轮没有验证全部依赖在 Python 3.14 下均能成功安装，不应把本次缺库问题直接归因于 Python 版本。
详细说明见 hidapi 安装排错。
本机已验证的 Python 3.12 环境
本次排查另建了 ~/Projects/zephyr-workspace/.venv-py312，保留原 .venv，没有修改系统 Python。新环境使用 Python 3.12.14、west 1.5.0。
验证结果：完整 west packages pip --install 退出码为 0；python -m pip check 无依赖冲突；import hid 成功，hidapi 版本为 0.14.0.post4。此外，2026-09-18 已完成本页目标板的 Hello World 编译、烧录与实板运行验证。
本机后续可以直接使用：
source ~/Projects/zephyr-workspace/.venv-py312/bin/activate
cd ~/Projects/zephyr-workspace/zephyr
python --version
west --version
全文操作已统一使用 .venv-py312/bin/activate。不要在同一次实验中混用两个环境。Python 和 uv 工具归档在工作区 .tools/，安装日志与依赖快照在 .diagnostics/python-dependencies/。
安装 SDK 与 ESP32 blobs（首次安装或更新后）
cd ~/Projects/zephyr-workspace/zephyr
west sdk install --help
SDK 安装参数以 v4.2.0 工作区中的帮助为准。使用下方命令把 SDK 放进专用目录；下载体积可能较大。
mkdir -p ~/.local/opt
west sdk install --install-base ~/.local/opt
west blobs fetch hal_espressif
Espressif 的 Wi-Fi / Bluetooth 使用二进制 blobs。板卡指南建议在 west update 后获取它们。SDK 和 blobs 都有各自的许可；本仓库不打包这些二进制。
记录当前状态
west --version
git describe --tags --always
west list
west manifest --freeze --active-only -o ../west-manifest-frozen.yml
最后一个文件放在固件工作区中，用于记录当前启用模块的修订。
--active-only 很重要：v4.2.0 的清单包含未启用的 optional 模块，例如 canopennode。普通 west update 可以跳过这些模块，但不带此参数的 --freeze 会尝试冻结它们，因未克隆而失败。这不代表当前启用模块下载不完整。
使用 -o 让 west 在清单生成成功后写入文件，避免 shell 的 > 在命令失败前就截空原文件。本机已验证该命令成功生成包含 57 个项目的快照；其他工作区的数量可能不同。如果报错涉及启用的模块，则仍需先完成相应模块的 west update。
git describe 应表明检出的是 v4.2.0。如果 SDK 定位失败，检查实际安装路径及 ZEPHYR_SDK_INSTALL_DIR，并核对是否已运行 SDK 的 setup 注册步骤。
日常重新进入
source ~/Projects/zephyr-workspace/.venv-py312/bin/activate
cd ~/Projects/zephyr-workspace/zephyr
-
west update完整成功，无缺失模块。 - 系统开发包检查和
west packages pip --install均成功。 - 已记录源码标签、west 和 SDK 版本。
- 已完成 SDK 安装和 blobs 下载。
下一步：确认板卡。
官方来源
基于 Zephyr v4.2.0 官方资料整理的中文学习笔记，非逐字翻译；命令及说明作了学习场景适配。