02 · west、源码与 SDK
目标：建立固定 Zephyr v4.2.0 的固件开发工作区。以下命令只在新工作区首次执行；已经存在 .west 时，不要再次初始化。
创建独立 Python 环境
mkdir -p ~/Projects/zephyr-workspace
# 首次创建时先确认解释器版本；已有 .venv 则直接激活，不要覆盖。
python3 --version
python3 -m venv ~/Projects/zephyr-workspace/.venv
source ~/Projects/zephyr-workspace/.venv/bin/activate
python -m pip install west
每次开启新终端先执行 source。不要使用 sudo pip。
如果已安装 Python 3.12，首次创建时可将 python3 -m venv 换成 python3.12 -m venv。这不是让已有工作区重复创建虚拟环境。
python -c "import sys; print(sys.executable); print(sys.version); assert sys.prefix != sys.base_prefix, '未进入虚拟环境'"
python -m pip --version
确认解释器和 pip 都来自选定的工作区虚拟环境。
固定源码版本
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/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。这是 Python 依赖安装验证，不代表固件编译或实板验证已完成。
本机后续可以直接使用：
source ~/Projects/zephyr-workspace/.venv-py312/bin/activate
cd ~/Projects/zephyr-workspace/zephyr
python --version
west --version
选择这个环境后，其余教程中激活 .venv/bin/activate 的位置相应改为 .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/bin/activate
cd ~/Projects/zephyr-workspace/zephyr
-
west update完整成功，无缺失模块。 - 系统开发包检查和
west packages pip --install均成功。 - 已记录源码标签、west 和 SDK 版本。
- 已完成 SDK 安装和 blobs 下载。
下一步：确认板卡。
官方来源
基于 Zephyr v4.2.0 官方资料整理的中文学习笔记，非逐字翻译；命令及说明作了学习场景适配。