工程组织

应用可以在任意目录，但团队需要一个明确入口：取得你的仓库后，应能知道使用哪个 Zephyr 提交、怎样取得依赖、哪些命令生成固件。

先读 west 使用指南区分 Git 仓库、west 工作区与入口 manifest。仓库里存在 west.yml，不代表当前工作区已在读取它。

本机固件仓库

2026-09-24 已建立独立代码仓库 ~/Projects/esp32-zephyr，包含 apps/learning、apps/backlight、apps/dashboard。以后自己的固件改动在这个仓库维护；本站 examples/ 保留为教程配套快照，不再把两份目录都当成最新代码。

在已经准备好的电脑上直接使用现有 SDK 与工作区：

source ~/Projects/zephyr-main-workspace/.venv-py312-main/bin/activate
export ZEPHYR_SDK_INSTALL_DIR=~/.local/opt/zephyr-sdk-1.0.1
cd ~/Projects/esp32-zephyr
python scripts/build.py --list
python scripts/build.py learning

将 learning 换为 learning-backlight、backlight 或 dashboard 可构建其他实验。config/targets.json 保存应用/板卡组合；新板先加 profile 和对应应用配置，再逐项实测。当前只适配微雪 Touch 1.28，不能把不同 ESP32 型号视为可直接互换。

构建输出在 ~/Projects/zephyr-main-workspace/build/esp32-zephyr/<目标>/<应用>/，与文档旧示例的构建目录分开。脚本只编译，成功后会打印对应的烧录与串口命令。

仓库根 boards/ 留给自制 PCB 的完整板级定义，apps/*/boards/ 放已有板卡的应用 overlay。具体命令和验证状态以固件仓库 README、docs/validation.md 为准。

仓库布局

embedded-workspace/                  # 不是整体提交的仓库
├── .west/
├── .venv/
├── zephyr/
├── modules/
├── bootloader/
├── build/
└── firmware/                        # 你自己的 Git 仓库
    ├── west.yml
    ├── README.md
    ├── .gitignore
    ├── apps/
    │   ├── dashboard/
    │   │   ├── CMakeLists.txt
    │   │   ├── Kconfig
    │   │   ├── prj.conf
    │   │   ├── src/
    │   │   └── boards/              # 应用针对各板的 overlay/.conf
    │   └── sensor-node/
    ├── boards/
    │   └── mycompany/my_s3/         # 自己 PCB 的板卡定义，需要时才创建
    ├── lib/                         # 多应用共享代码，需要时再抽取
    └── docs/

应用按功能命名，板卡适配单独存放。同一个 dashboard 可以适配不同屏幕；同一块板也能运行不同应用。不要为每个项目复制整个 Zephyr 源码树再改上游文件。

依赖版本

将下面的 manifest 放在 firmware/west.yml：

manifest:
  remotes:
    - name: zephyrproject
      url-base: https://github.com/zephyrproject-rtos
  projects:
    - name: zephyr
      remote: zephyrproject
      revision: 52b48529aecc3ad0ef9b159996bdb5d2b3e5b794
      import: true
  self:
    path: firmware

import: true 让 west 继续读取这个 Zephyr 版本的依赖清单，所以应用仓库不用手工重写 LVGL、HAL 等所有修订。SDK 与 Python 依赖仍需要另外安装。

在一个新的 embedded-workspace 中，先把自己的仓库克隆到 firmware，再创建并激活该工作区的 Python 虚拟环境、安装 west，然后：

cd ~/Projects/embedded-workspace
west init -l firmware
west update
west packages pip --install
west zephyr-export

这是自己的 manifest 仓库初始化方式，不要在已经初始化的 main 工作区里直接重复执行。上面使用 firmware 作为通用目录示例；本机已建立仓库使用 esp32-zephyr 作为目录名，其 west.yml 的 self.path 与之对应。新机器按该仓库 README 操作。

多板卡配置

先使用上游已有板卡定义，把板级差异放在应用的 boards 目录。例如：

apps/dashboard/boards/
├── waveshare.overlay
├── waveshare.conf
├── another_board.overlay
└── another_board.conf

构建时明确指定：

cd ~/Projects/embedded-workspace/zephyr
west build -p always -b esp32s3_touch_lcd_1_28/esp32s3/procpu \
  ../firmware/apps/dashboard -d ../build/dashboard-waveshare \
  -- -DDTC_OVERLAY_FILE=boards/waveshare.overlay \
  -DEXTRA_CONF_FILE=boards/waveshare.conf

这是目录设计示例，需先创建对应应用文件。另一个目标用另一个 build 目录，避免复用缓存时误烧录上一块板的固件。

版本管理

内容	是否提交	原因
C 源码、CMakeLists	是	应用实现与构建入口
prj.conf、额外 .conf、overlay	是	可复现的软件/硬件配置
自己的 Kconfig	有自定义参数时提交	定义参数，不复制上游配置树
自己 PCB 的板卡定义	是	硬件连接不能靠口头记录
west.yml	是	固定依赖入口
SDK、.venv、build、下载的上游模块	否	工具或可再生成内容
最终 .config、zephyr.dts	通常不作为源配置提交	可在故障报告中留快照，不能替代源文件

顶层应用仓库无需强行拥有一个总 Kconfig。每个独立应用可以有自己的 Kconfig；只有共享配置/驱动增长后，再考虑 Zephyr module 的 CMake/Kconfig 集成。

练习：从 learning-app 复制到一个自己的应用仓库，保持上游工作区不变，用绝对路径完成构建；解释为什么没有复制 zephyr/ 也能成功。

来源：应用开发、west manifest。

本机固件仓库​

仓库布局​

依赖版本​

多板卡配置​

版本管理​

本机固件仓库

仓库布局

依赖版本

多板卡配置

版本管理