Omi 固件 Docker 构建指南：一条命令在任意平台编译 XIAO BLE Sense 固件并生成 OTA 包

Omi 固件 Docker 构建指南：一条命令在任意平台编译 XIAO BLE Sense 固件并生成 OTA 包

【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend

本文基于 docker-build.md 的完整内容，结合 build-docker.sh 与 build-firmware-in-docker.sh 两个脚本的真实实现，讲解如何用 Docker 在 Linux/macOS/Windows 上以完全一致的环境编译 Omi DevKit 固件（基于 Zephyr RTOS / nRF Connect SDK v2.7.0，目标板xiao_ble/nrf52840/sense），并产出zephyr.hex、zephyr.bin、zephyr.uf2与 OTA 升级包zephyr.zip。读完本文，你可以直接复制命令完成首次构建、增量构建、清理重建，并理解每个构建参数在源码层面的实际作用，最后把固件烧录到开发板。

为什么用 Docker 构建

Omi 固件构建依赖一整套 Zephyr / nRF Connect SDK 工具链：west 元工具、SDK 仓库、Nordic 工具链、约 5GB 的 SDK 数据与hal_nordic二进制 blob。在裸机上手动搭这套环境，不同系统（尤其 macOS 与 Windows 的路径差异）很容易出偏差。

Docker 方案把整个工具链封装进 Zephyr 官方 CI 镜像ghcr.io/zephyrproject-rtos/ci，带来三个好处：

1. 跨平台一致：Linux、macOS（含 Apple Silicon）、Windows 上执行同一镜像，产物一致；
2. 消除环境搭建：不需要本机预装 Zephyr、west 或工具链，首次构建时容器内自动完成；
3. 与官方构建完全对齐：脚本使用的构建参数与 nRF Connect for VS Code 产生的配置完全相同，保证 Docker 产物与 IDE 构建产物等价，可直接用于正式 OTA 流程。

前置条件只有两项：

• 系统已安装 Docker（Docker Desktop 或 Docker Engine）；
• 仓库已克隆到本地，并从仓库根目录执行脚本。

快速开始

从仓库根目录执行：

chmod +x omi/firmware/scripts/build-docker.sh ./omi/firmware/scripts/build-docker.sh

脚本会依次完成五件事：

1. 启动带有 Zephyr RTOS 构建环境的 Docker 容器（镜像ghcr.io/zephyrproject-rtos/ci）；
2. 在容器内安装必要工具与依赖（pip install --user adafruit-nrfutil）；
3. 为xiao_ble/nrf52840/sense板型编译固件；
4. 在firmware/build/docker_build/zephyr.zip生成 OTA 升级包（注意：仓库中的目录实际为 omi/firmware/build/docker_build，即omi/firmware相对仓库根的路径）；
5. 打印全部构建产物的绝对路径与文件列表。

对照 build-docker.sh 的源码，宿主脚本的实际行为比文档描述的更细：

• 开头set -euo pipefail，任一命令失败立即终止；
• 先检查docker是否在 PATH 中，否则直接报错退出；
• 通过REPO_ROOT=$(cd "$(dirname "$0")/../.." && pwd)自动推算仓库根目录，再把整个仓库挂载为容器内/omi，因此脚本位置移动后依然能正确定位仓库；
• 容器启动参数为-e CMAKE_PREFIX_PATH=/opt/toolchains -e PATH="/root/.local/bin:$PATH"，这两个环境变量分别让 CMake 找到镜像内的工具链、让 pip 安装到 user 目录的adafruit-nrfutil可被找到；
• 构建结束后，脚本检查firmware/build/docker_build目录是否存在且非空：存在则打印产物路径，否则报错退出（退出码 1），给你一个明确的成败信号。

两个构建脚本的职责划分

仓库包含两个脚本，分工明确：

1. build-docker.sh（宿主侧）：解析命令行参数（支持--clean）、检测 Docker 是否存在、检测 Apple Silicon 架构、启动容器并在容器内安装adafruit-nrfutil，然后调用容器侧脚本；
2. build-firmware-in-docker.sh（容器内）：执行真正的 west 初始化、模块更新、编译与 OTA 打包。

容器内脚本 build-firmware-in-docker.sh 的完整流程是：

cd /omi/firmware/ # 1. west 初始化（若 v2.7.0/.west 不存在则执行） west init -m https://github.com/nrfconnect/sdk-nrf --mr v2.7.0 v2.7.0 cd v2.7.0 # 2. 更新 west 模块（浅克隆 + 后台下载），失败时继续用现有模块 west update -o=--depth=1 -n || echo "West update failed, continuing with existing modules." west blobs fetch hal_nordic || echo "Blob fetch failed, continuing with existing blobs." # 3. 导出构建环境 west zephyr-export # 4. 编译（参数与 IDE 完全一致） west build -b xiao_ble/nrf52840/sense --pristine always ../devkit -- \ -DNCS_TOOLCHAIN_VERSION="NONE" \ -DCONF_FILE="prj_xiao_ble_sense_devkitv2-adafruit.conf" \ -DDTC_OVERLAY_FILE="/omi/firmware/devkit/overlay/xiao_ble_sense_devkitv2-adafruit.overlay" \ -DCMAKE_EXPORT_COMPILE_COMMANDS="YES" \ -DCMAKE_BUILD_TYPE="Debug" \ -DPLATFORM=nrf52840 \ -DCACHED_CONF_FILE="/omi/firmware/devkit/prj_xiao_ble_sense_devkitv2-adafruit.conf" # 5. 收集产物并生成 OTA 包 mkdir -p /omi/firmware/build/docker_build cp -r build/zephyr/zephyr.{hex,bin,uf2} /omi/firmware/build/docker_build/ || echo "Warning: Some build artifacts not found" cd /omi/firmware/build/docker_build/ adafruit-nrfutil dfu genpkg --dev-type 0x0052 --dev-revision 0xCE68 --application zephyr.hex zephyr.zip

几点值得注意的实现细节：

• 增量复用：脚本以v2.7.0/.west目录是否存在判断是否已初始化，west update与west blobs fetch失败时会打印警告并继续（|| echo ...），这是"默认复用已有 west 安装、避免每次重新下载约 5GB 数据"的增量构建机制在源码层面的具体体现；
• 构建源目录是devkit/：从 build-firmware-in-docker.sh 第 30 行可见，west build的应用源目录是../devkit（对应 omi/firmware/devkit/CMakeLists.txt），即 DevKit V2 工程，而非omi/目录下的量产固件工程。原文档 Manual Build 章节中../app的写法与当前脚本实际的../devkit不一致，以脚本为准；
• OTA 包参数：--dev-type 0x0052与--dev-revision 0xCE68是 adafruit-nrfutil 的 DFU 设备类型/版本标识，烧录时用于校验目标设备匹配。

构建参数详解：与 nRF Connect IDE 完全一致

Docker 构建使用的参数与 nRF Connect for VS Code 完全相同，逐项说明：

以 prj_xiao_ble_sense_devkitv2-adafruit.conf 为例，这份配置文件启用的核心能力包括：GPIO/PDM（麦克风）/Flash/ADC 硬件驱动、看门狗（CONFIG_WATCHDOG=y）、蓝牙外设模式（CONFIG_BT_PERIPHERAL=y，设备名Omi DevKit 2）、电池/设备信息服务（CONFIG_BT_BAS=y、CONFIG_BT_DIS=y，固件版本字符串2.0.10），以及为 BLE 音频流优化的大包传输参数（CONFIG_BT_L2CAP_TX_MTU=498、CONFIG_BT_CTLR_DATA_LENGTH_MAX=251、CONFIG_BT_CTLR_PHY_2M=y）。这些配置决定了固件开机即处于"可被手机 App 通过 BLE 连接并流式传输 Opus 音频"的状态。

devkit/CMakeLists.txt 还显示了固件的实际构成：应用源码包含main.c、mic.c（麦克风采集）、codec.c（音频编码）、transport.c（蓝牙传输）、sdcard.c/storage.c（离线存储）、speaker.c、battery.c、button.c、led.c、usb.c等模块；当CONFIG_OMI_CODEC_OPUS=y时，会额外编译约 130 个 Opus 1.2.1 编解码器源文件，并开启FIXED_POINT、DISABLE_FLOAT_API与 ARM Cortex-M4 内联汇编优化（OPUS_ARM_INLINE_EDSP等），这是固件"音频采集—Opus 压缩—BLE 流式传输"链路在构建层面的直接体现。

可用的板型配置

omi/firmware/devkit 下提供三份设备差异化配置，配合 overlay/ 中同名 overlay 使用，覆盖不同硬件版本：

overlay 的作用是在编译期为固件提供该版本的引脚与外设映射，每个硬件版本都需要对应的一次独立构建。Docker 脚本默认锁定 V2 + Adafruit 配置；如要改板型，需要修改 build-firmware-in-docker.sh 中的CONF_FILE与DTC_OVERLAY_FILE两处取值（仓库只读环境下，可在自己的 fork 中调整）。

构建产物

构建成功后，firmware/build/docker_build（仓库内路径 omi/firmware/build/docker_build）下会得到四个文件：

• zephyr.hex—— 原始固件 hex 文件，也是 OTA 打包的输入；
• zephyr.bin—— 二进制固件文件；
• zephyr.uf2—— 可直接拖入开发板 UF2 引导区烧录的文件；
• zephyr.zip—— 由adafruit-nrfutil dfu genpkg生成的 OTA 升级包。

--clean选项的行为：build-docker.sh 收到--clean后会删除三处目录再开始构建——firmware/v2.7.0（west 工作区/SDK）、firmware/build/docker_build（产物目录）以及firmware/app/build内可能残留的旧构建缓存。遇到"改了代码却不生效"或环境损坏时，优先用：

./omi/firmware/scripts/build-docker.sh --clean

手动执行 Docker 构建（进阶）

如果你不想依赖脚本、想逐步排查问题，可以按 docker-build.md 给出的手动流程执行。与脚本的等价手动命令为：

# 从仓库根目录执行 docker run --rm -it -v "$(pwd):/omi" -e CMAKE_PREFIX_PATH=/opt/toolchains -e PATH="/root/.local/bin:$PATH" ghcr.io/zephyrproject-rtos/ci bash # 进入容器后： pip install --user adafruit-nrfutil cd /omi/firmware/ west init -m https://github.com/nrfconnect/sdk-nrf --mr v2.7.0 v2.7.0 cd v2.7.0 west update -o=--depth=1 -n west blobs fetch hal_nordic west zephyr-export west build -b xiao_ble/nrf52840/sense --pristine always ../app -- \ -DNCS_TOOLCHAIN_VERSION="NONE" \ -DCONF_FILE="prj_xiao_ble_sense_devkitv2-adafruit.conf" \ -DDTC_OVERLAY_FILE="/omi/firmware/devkit/overlay/xiao_ble_sense_devkitv2-adafruit.overlay" \ -DCMAKE_EXPORT_COMPILE_COMMANDS="YES" \ -DCMAKE_BUILD_TYPE="Debug" \ -DPLATFORM=nrf52840 \ -DCACHED_CONF_FILE="/omi/firmware/devkit/prj_xiao_ble_sense_devkitv2-adafruit.conf"

（原文档此处写../app，当前脚本实际使用../devkit，见上文说明。）手动构建的价值在于：每一步（west init/west update/blobs fetch/build）都可以单独观察输出与耗时，定位网络、工具链或 CMake 配置问题。

兼容性说明

Apple Silicon（M1/M2/M3）：build-docker.sh 通过uname -m检测arm64，会打印Detected ARM64 platform (M1/M2/M3 Mac)提示并选用兼容镜像。Zephyr CI 镜像提供 arm64 标签，无需任何额外配置。

Windows：路径映射语法不同，$(pwd)需替换为%cd%：

docker run --rm -it -v %cd%:/omi -e CMAKE_PREFIX_PATH=/opt/toolchains ghcr.io/zephyrproject-rtos/ci bash

烧录固件

构建完成后，将zephyr.uf2拷贝到开发板：

1. 双击复位键（double-press reset），让 XIAO 板进入 UF2 bootloader 模式；
2. 板子会以 U 盘形式出现（设备名为XIAO-SENSE）；
3. 把zephyr.uf2复制到该盘根目录；
4. 烧录完成后板子自动复位运行新固件。

各平台拷贝命令（D:为 Windows 下 XIAO-SENSE 的盘符）：

# macOS cp firmware/build/docker_build/zephyr.uf2 /Volumes/XIAO-SENSE/ # Linux cp firmware/build/docker_build/zephyr.uf2 /path/to/XIAO-SENSE/ # Windows (cmd) copy firmware\firmware\build\docker_build\zephyr.uf2 D:\

若走 OTA 通道，则使用生成的zephyr.zip通过设备端 DFU 流程升级，无需进入 bootloader。

调试构建补充

如果构建出的固件需要串口日志排障，omi/firmware/readme.md 给出了 DevKit2 的调试配置：编辑 prj_xiao_ble_sense_devkitv2-adafruit.conf，启用CONFIG_CONSOLE=y、CONFIG_PRINTK=y、CONFIG_LOG=y、CONFIG_LOG_PRINTK=y、CONFIG_UART_CONSOLE=y，并关闭CONFIG_OMI_ENABLE_OFFLINE_STORAGE=n（离线存储实验性，需先禁用才能稳定看日志；如需两者共存，可设CONFIG_LOG_PROCESS_THREAD_PRIORITY=5与CONFIG_LOG_PROCESS_THREAD_CUSTOM_PRIORITY=y，可能影响 BLE 传输与 SD 卡写入性能），然后仍可用本 Docker 流程重新构建烧录，用 nRF Serial Terminal 查看输出。

小结与延伸阅读

• Docker 构建的等价性承诺：容器内参数与 nRF Connect for VS Code 完全一致（xiao_ble/nrf52840/sense+ V2-Adafruit conf/overlay + Debug + nrf52840），产物可直接用于 UF2 烧录与 OTA 升级；
• 增量构建默认复用v2.7.0west 工作区（约 5GB），环境问题用--clean重建；
• 关键文件：omi/firmware/scripts/docker-build.md（本指南依据）、omi/firmware/scripts/build-docker.sh、omi/firmware/scripts/build-firmware-in-docker.sh、omi/firmware/devkit/CMakeLists.txt；
• 仓库中另有 BUILD_AND_OTA_FLASH.md，面向更新的 nRF5340 硬件与 nRF Connect SDK 2.9.0 环境的手动构建/OTA 流程，可作为量产固件方向的对照阅读；BUILD_AND_OTA_FLASH.md 与本文的 Docker 流程针对不同硬件版本，二者不要混用参数。

【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend