Omi 衍生 3D 打印版

案例：构建 Omi 衍生的 3D 打印版

这是 Nexting 基于 Omi 开源硬件路线改造的 3D 打印版。我们重新设计了外壳几何、按键手感和夹持结构，并为它编写 Nexting 固件。它不是 Omi 官方硬件，也不使用 Omi 固件。

Omi 改造版的组成

下载文件

下面的链接就是制作这台 Omi 改造版所需的文件，按文件名下载即可。

连接 Nexting App

“下载文件”是制作设备的材料入口；这一节说明设备做好以后如何接入 Nexting App。设备不直接连接 Claude Code、Codex、Grok、Cursor 或云端 Agent，Nexting App 才是管理 BLE、设备身份和 Agent 会话的可信 Host。

下面两张图直接由当前发货文件渲染：第一张是 base.stl 外壳，第二张是 cover.stl 与 button.stl 的组合。它们与上面的公开下载路径一一对应。

1. 1

   完成硬件和固件

   按上面的公开文件装好 Omi 改造版，刷入 pinclaw_v2.2.4.uf2；先在裸板上验证按键、录音和回放。
2. 2

   在 App 中登录并扫描

   打开 Nexting App，允许蓝牙权限，扫描附近设备。选择广播名称对应的 Omi 改造版。
3. 3

   核对并授权

   App 读取设备型号、固件版本和能力后，确认是 XIAO nRF52840 Sense，再完成配对。
4. 4

   从 App 进入 Agent

   配对后，PTT 录音通过 BLE 音频进入 App，再由 App 转发给云端 Agent；录音、回放和会话都在 App 中管理。

装配与首次开机

按“裸板 → 音频 → 外壳 → App”的顺序装配，完成每一步再进入下一步。

1. 1

   只接主控和 USB

   给 XIAO nRF52840 Sense 上电，确认能进入 UF2 卷、串口能枚举、板载 LED 有反应。先不接扬声器和电池。
2. 2

   接 PTT 与功放

   按原理图连接 D4 按钮、A1/A2/A3 I2S、D6 功放使能、3V3 和 GND。MAX98357A 使用 3V3 供电。
3. 3

   做裸板录音与回放

   不装外壳时验证按住 PTT 开始录音、释放停止、短按播放，以及 LED 的启动、连接和录音状态。
4. 4

   再装外壳和按钮

   打印件先空装检查孔位与行程，再固定电路板、扬声器和电池。确认按钮可以完整释放。
5. 5

   最后走 App 配对

   确认产品固件能广播、音频链路能建立，再通过 Nexting App 配对。

固件结构

固件采用 Zephyr。下面的源码表说明每个模块的作用，便于你修改和构建。

# 在 firmware/pinclaw_zephyr 所在的仓库根目录执行
export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
export GNUARMEMB_TOOLCHAIN_PATH="$HOME/Library/Arduino15/packages/Seeeduino/tools/arm-none-eabi-gcc/9-2019q4"
export ZEPHYR_BASE="$HOME/ncs/zephyr"

cd hardware-opensource/firmware/pinclaw_zephyr
west build -b xiao_ble/nrf52840/sense . \
  -DDTC_OVERLAY_FILE="$PWD/overlay/xiao_ble_sense_devkitv2-adafruit.overlay" \
  --pristine

# 产物：build/zephyr/zephyr.uf2

预构建 UF2 用于快速复现，源码构建用于开发。构建时使用与 XIAO nRF52840 Sense 匹配的 board 和 overlay。

接入 Nexting SDK

如果要把这台硬件接入 Nexting SDK，需要增加消息转换层和对应测试。可以先保留语音功能，再把 PTT 和状态灯接入公开 Profile。

故障排查

提交问题时请提供主控型号、固件文件名、overlay、电脑系统、USB 枚举结果、LED 现象和复现步骤。

两种使用方式

语音产品使用 BLE 音频链路；SDK 设备使用公开 Profile。要接入 SDK，需要在固件或 Host 适配层把按键、LED 和电池状态转换成公开消息，再通过可信 Host 连接 Agent。

烧录固件

1. 1

   先确认主控型号

   这份 UF2 适用于 Seeed XIAO nRF52840 Sense。请先核对开发板丝印和型号。
2. 2

   保存当前可恢复状态

   确认设备能开机、能录音、能回放，并保留当前固件文件。MultiPad 的 STM32 固件和其他 UF2 不适用于这块 XIAO。
3. 3

   双击 Reset 进入 UF2 卷

   XIAO 的 Reset 双击后，电脑应出现可移动磁盘；只在这个卷出现且型号正确时继续。
4. 4

   拖入 pinclaw_v2.2.4.uf2

   从 GitHub 的 firmware/pinclaw_zephyr 目录下载对应文件并拖入 UF2 卷。没有出现 UF2 卷时，请先排查 USB 和 Reset。
5. 5

   回到产品路径验证

   重连电池和 USB，确认按键、音频、LED 与 Nexting App 配对流程，再开始做 SDK Profile 适配。

把硬件映射到 SDK

建议先接入一个 PTT 事件和一个状态灯，完成按住、释放、断连、重连和过期清理，再扩展音频、配置、用量和自定义灯效。

完成检查

其他案例