企业官网建设流程全解析

Nexting是一款让物理设备远程遥控 Claude Code、Codex 等 AI Agent 的开源项目。它的设备端固件（Nexting 参考固件）有一个很有意思的设计：同一套 Zephyr 源码，不改一行main.c，就能编译出 Nordic nRF52840 和乐鑫 ESP32-C3/S3 共四块开发板的固件。本篇教程带你从零了解这套"一份代码、四板通跑"的移植架构，并给出完整的构建与验证步骤。🔌

为什么一套代码能跑四块板？

移植 BLE 设备固件最大的坑，往往是"每换一块板就改一堆代码"。Nexting 参考固件用三层结构把这个问题解决了：

换句话说，芯片和引脚的差异被收敛到了薄薄的.overlay设备树文件里，协议行为由共享的 C99 核心保证四块板表现完全一致，不存在"两套解析器各自演化"的问题。🧩

四块支持的开发板与 Zephyr 目标

官方 Experimental 0.2 将 Nordic 与 ESP32 视为对等的产品家族，四块板全部处于 Build verified（构建已验证）状态：

各板"允许 / 拒绝 / 待处理"引脚的参考接线如下（按键均用内部上拉、低电平有效）：

一键构建：west build 四板命令

在配置好的 Zephyr 或 nRF Connect SDK 工作空间中，只需切换-b参数即可切换目标板：

west build -p always -b nrf52840dk/nrf52840 /path/to/nexting-devices/firmware/zephyr west build -p always -b xiao_ble/nrf52840/sense /path/to/nexting-devices/firmware/zephyr west build -p always -b xiao_esp32c3/esp32c3 /path/to/nexting-devices/firmware/zephyr west build -p always -b xiao_esp32s3/esp32s3/procpu /path/to/nexting-devices/firmware/zephyr

⚠️ 两个常见坑：

• ESP32 目标需要上游 Zephyr 工作区中的hal_espressif及其配套无线电固件（radio blobs）和兼容的 Zephyr SDK——仅列出 ESP 板定义的 nRF Connect SDK 清单是不够的；
• 只构建你手上有的板。官方 CI 锁定版本为Zephyr 4.3.0 / Zephyr SDK 0.17.4 / west 1.5.0，建议对齐。

如果还没有 Zephyr 环境，仓库提供了引导脚本（自动创建隔离 Python 环境、初始化固定版本的 Zephyr 工作区并构建）：

git clone --branch devices-v0.2.0-experimental.2 --depth 1 \ https://gitcode.com/gh_mirrors/ne/nexting cd nexting/devices ./scripts/bootstrap-zephyr.sh --board xiao-nrf52840-sense --install-sdk --build

脚本位于 devices/scripts/bootstrap-zephyr.sh，重复执行安全，可用--dry-run预览所有解析出的版本与路径。

板级差异如何收敛：overlay 与自动选择机制

这套"一份代码"的魔法来自两个文件配合：

1. devices/firmware/zephyr/CMakeLists.txt根据编译时的BOARD变量自动挑对应的 overlay：

if(BOARD MATCHES "^xiao_ble") set(DTC_OVERLAY_FILE ${CMAKE_CURRENT_SOURCE_DIR}/boards/xiao_ble.overlay) elseif(BOARD MATCHES "^xiao_esp32c3") set(DTC_OVERLAY_FILE ${CMAKE_CURRENT_SOURCE_DIR}/boards/xiao_esp32c3.overlay)

2. overlay 文件为每块板声明统一的引脚别名。以 xiao_esp32c3.overlay 为例，它把 D0/D1 声明为 Allow/Deny 按键，D2 声明为 Pending LED（高电平有效）：

nexting-allow = &nexting_allow; nexting-deny = &nexting_deny; nexting-led = &nexting_led;

而 main.c 读取这些别名时还做了兜底：优先找nexting-allow，找不到就用 nRF52840 DK 的sw0/sw1/led0别名——这就是 DK 连 overlay 文件都没有也能直接编译的原因。

💡想加自己板子？新建一个 overlay，把 Allow/Deny/Pending 三个别名指到你自己的引脚，再在 CMakeLists.txt 加一条BOARD MATCHES分支即可，main.c一行都不用动。

BLE 安全配置（强制绑定、Secure Connections、NVS 存储等）统一写在 devices/firmware/zephyr/prj.conf，同样与板无关。

烧录与第一次验证

XIAO 系列（UF2 拖拽烧录，无需烧录器）：

1. USB-C 连接板子，快速双击 Reset 键，出现名为XIAO BLE的 U 盘；
2. 把构建产物zephyr.uf2拖进去，卷自动弹出即完成烧录；
3. 此时 Pending LED 应保持熄灭——只有 Host 下发审批请求时才会点亮。

nRF52840 DK则直接用west flash通过板载调试器烧录。

上电后的标准手势验证：

• 短按任意一个按键：回答当前的 Allow/Deny 请求；
• 同时按住两个键 3 秒：清除板上全部 BLE 绑定（Pending LED 亮 1 秒作为确认，随后恢复广播）；
• 注意手机端也需"忽略此设备"，因为绑定关系两边各存一份。

详细接线与流程见 devices/docs/reference-approval-controller.md 和 devices/docs/first-approval.md；遇到配对失败、Device Info 读不到等问题，查 devices/docs/troubleshooting.md。

构建验证不等于板级验证：证据等级

Nexting Devices 对"支持"的定义非常克制，四个等级逐级递进：

要拿到Board verified，需逐项完成 devices/docs/board-verification.md 的实板清单——包括"按键抖动不能改变首次选择""断连后不得从 flash 恢复审批""TTL 边界后按键不得生效"等 30 余项行为用例，并记录板子版本、工具链、固件 commit、手机 App 版本和串口日志。

把这套模式移植到你的新芯片

如果你的平台不是上述四块板，devices/docs/porting-guide.md 把移植工作拆成五块，核心原则是协议核心原样复用，平台适配器保持薄：

平台侧只需满足最小硬件契约：BLE 外设/GATT、加密绑定与本地吊销、≥512 字节接收缓冲、两个无歧义本地动作、Pending 输出、单调毫秒时钟、掉电即失的审批状态。完整路线见 devices/docs/implementation-tracks.md。

小结

Nexting 参考固件展示了一个可复制的移植范式：共享协议核心 + 薄平台适配器 + 板级 overlay 收敛差异。一份main.c与一套 C99 核心，靠west build -b切换目标就点亮了 nRF52840 与 ESP32 的两大家族四块开发板——对正在做多平台 BLE 设备固件的你来说，这套分层思路值得直接借鉴。🚀

延伸阅读：

• 固件说明与接线表：devices/firmware/zephyr/README.md
• 协议规范：devices/SPEC.md
• C99 设备 SDK：devices/sdk/c/README.md
• 硬件支持状态：devices/docs/hardware-support.md