案例

AhaKey X1

Works with Nexting · 键盘案例

Nexting Devices SDK · AhaKey X1 集成指南

把 AhaKey 的按键和设备麦克风接到 Nexting

本文定义集成后的 AhaKey X1 如何作为第三方 Nexting 设备控制远端 Agent。目标链路把 AhaKey 麦克风音频经面向 CH582/CH58x 的固件端口和 BLE 送入 Nexting App，绝不借用手机麦克风冒充设备录音；量产主控的准确型号、生产 PCM 绑定与实物板测仍待确认。

查看当前公开 Devices SDK（0.4）当前 0.4 Wire 协议

先理解公开的 devices/ 目录

GitHub 仓库里的 devices/ 是硬件开发者与 Nexting App 之间的公开契约，不是 Nexting App 或云端的源码。设备按这套契约声明能力、发送物理输入和接收有限状态，官方 App 负责设备授权、语音识别、Agent 选择以及远程会话。

区域	当前公开 0.4	仍待完成
SPEC.md / schemas / protocol/vectors	10 个 profile，含 device-audio/1 的 Wire 规则、Schema 和测试向量	不再改 Wire；实物板证据仍待完成
sdk/c / reference/js	便携 C99 SDK、JavaScript 参考实现、设备音频编解码、分片和接收边界	产品 Host 仍是官方 Nexting App
firmware	Zephyr 参考开发板，以及 AhaKey 适配器、面向 CH58x 的端口、Device Info 模板与传输描述符	生产 PCM 绑定、目标构建和实物板测
tests / CI	协议、固件构建、导出、边界、音频模拟器及丢包、超时、流控和非法输入测试	iPhone/Android 对未知流的 fail-closed 一致性
docs	0.4 教程、接口说明、证据等级，以及 AhaKey 集成/实物验证指南	不宣称 Board verified

公开目录不包含 Nexting App 源码、Agent 路由、账号、云端地址、生产密钥或任何量产固件。AhaKey 适配只公开设备侧接口和可验证的协议边界。

实际数据路径

AhaKey → Nexting → Agenttext

实体语音键
  → AhaKey 麦克风
  → 面向 CH582/CH58x 的固件端口：PCM16 / 16 kHz / mono
  → IMA ADPCM + CRC32C + BLE 分片
  → Nexting App：重组、解码、语音识别
  → 录音开始时选定的 Agent
  → App / LED / OLED 状态反馈

AhaKey 是邻近的输入设备，Agent 可以运行在另一台电脑上。设备永远不拿到 Agent 凭证、内部会话 ID、账号信息或云端路由；这些都留在 Nexting App 和受信任的 Host 内。

硬件能力如何映射

X1 硬件	目标 Nexting 接口	行为
审批按键	approval/1	以 Allow 或 Deny 回答当前待决请求
通用按键	keys/1 槽位 0–3	发送 Host 定义的通用按键动作
物理拨杆	keys/1 槽位 7	离开静止位 press，回位 release
LED 灯带	status/1	显示工作、等待、完成或错误
OLED 160×80	text/1	显示有限的标题与正文
Battery Service 0x180F	Device Info	向 App 报告电量能力
设备麦克风 + 实体语音键	device-audio/1	PCM16 → IMA ADPCM → 加密 BLE → App

AhaKey 量产集成必须绑定实体语音键，可以复用一个可配置按键，也可以使用独立输入。公开协议不替厂商决定具体键位，Device Info 只声明实机确实存在且已验证的能力。

Nexting App 如何保持独立

App 核心不写 AhaKey 型号判断，也不解析 AhaKey 原厂命令。它只处理 Device Info、通用 profile 和四条逻辑通道。AhaKey 的 GATT UUID 与 A0–A3 opcode 只放在声明式 transport descriptor 和固件适配器中。下一款硬件可以换 UUID、芯片和按键，只要实现同一公共能力，App 的语音与 Agent 管线无需重写。

三种集成方式

方式	需要修改什么	按键/灯/屏幕	设备麦克风
Compatibility Tunnel 固件（推荐）	在 X1 固件中加入窄适配层，保留原厂 0x7340 服务	适配器 Core tested；目标构建和实物板测待完成	生产 PCM hook 与硬件验证待完成
原生 Nexting GATT	在 X1 固件中增加标准 Nexting 服务	协议路径已定义；目标构建和实物板测待完成	生产 PCM hook 与硬件验证待完成
stock 固件 + 桥接 dongle	键盘固件不变，外接 BLE dongle	仅完成设计；dongle 实现和板测待完成	除非 stock 固件开放真实 PCM，否则不可用

桥接 dongle 不能凭空获得键盘麦克风数据，也不能用手机麦克风替代。如果 stock 固件不开放 PCM，桥接模式就不得声明device-audio/1。

连接与录音生命周期

配对、绑定并加密
App 只在登录用户明确授权后连接第三方设备；撤销、退出账号或断连都会终止当前录音并清理临时状态。
读取 Device Info
设备声明身份、按钮、显示、电量和实际支持的 profile。未声明的能力不会被启用。
加载传输描述符
描述符把厂商 GATT 映射成 control_down、control_up、audio_up 和 flow_down；App 上层只看到逻辑通道。
准备录音会话
App 发 audio_config 表示已授权且缓冲区就绪。它只能准备，不能远程启动 AhaKey 麦克风。
实体键启动设备麦克风
按键在固件内创建 audio_begin，随后上传设备采到的帧。App 解码后进入现有 STT 和 Agent 发送路径。
停止、取消或失败即清理
按住达到 450 ms 后松键提交；不足 450 ms 松键会锁定录音，下一次实体按键才提交。取消、超时、断连、CRC 错误或流控停滞都会结束并擦除音频流；旧结果不能串入新的设备或 Agent 会话。

device-audio/1 的关键规则

项目	规则
采样	PCM16、16 kHz、单声道，每 20 ms 为 320 个样本
编码	IMA ADPCM；每帧带序号、样本位置和 CRC32C
传输	加密且已绑定的 BLE；ATT payload 至少 64 字节，推荐 MTU 247
流控	8 个初始 credit、最多缓存 10 帧、连续停滞 500 ms 即取消
分片	每个逻辑帧最多 4 个分片
序号	范围 0…5999；样本位置必须等于序号 × 320，最终样本总数必须精确匹配
丢包	重复帧忽略；缺 1 帧插入 20 ms 静音；连续缺 3 帧或累计缺 10 帧即终止
完整性失败	Experimental 0.4 要求 CRC 错误、未知流、分片不一致、ADPCM 元数据非法或样本位置不确定时终止并擦除音频流；移动端开发版本对未知流的 fail-closed 一致性仍待补齐
时长	单次最长 120 秒；重连不会恢复旧录音
隐私	只能由设备实体键开始；禁止常开采样和按键前预录
手机麦克风	device-audio/1 路径不申请、不启动，也不回退到手机麦克风

voice/1 仍然只表示 Host/手机麦克风的开始、停止与取消控制，本身不携带音频。device-audio/1 是另一条独立协商的 profile，携带物理设备自己采集的音频。两者不能混用。

面向 CH58x 的固件端口必须接什么

AhaKey 公开发布包和烧录资料指向 CH582 系列与 CH58x 工具链，但没有公开 BOM、原理图或芯片丝印证据确认量产主控的准确型号。Experimental 0.4 已经实现编码、分片、流控、状态机和 Compatibility Tunnel；量产端口必须接入麦克风、BLE 和显示回调，不需要把 Agent 或 Nexting App 逻辑塞进键盘。

0.4 公开发布包含的文件text

devices/sdk/c/include/nexting_device.h
devices/sdk/c/src/nexting_device.c
devices/sdk/c/include/nexting_device_audio.h
devices/sdk/c/src/nexting_device_audio.c
devices/firmware/ahakey-x1/CMakeLists.txt
devices/firmware/ahakey-x1/ahakey_proto.h
devices/firmware/ahakey-x1/ahakey_proto.c
devices/firmware/ahakey-x1/nexting_ahakey_adapter.h

量产固件回调边界c

notify_7344(...);          // BLE notify
vendor_7343_write(...);    // 原厂命令原样交回旧解析器
microphone_start(...);     // PCM16 / 16 kHz / mono / 320 samples
microphone_stop(...);      // 用户提交
microphone_cancel(...);    // 立即停止并擦除 DMA / ring buffer
render_audio_state(...);   // ready / receiving / transcribing / submitted / error

上游公开 firmware 仓库提供 CH582 HEX 和烧录说明，但没有可构建的 v1.1.0 量产源码、原理图或公开 PCM callback。因此这里不能虚构最终 ADC/I2S/PDM 函数名；拿到生产源码和实物后再完成最后的符号绑定。

按键如何接入

原厂 HID 键位仍可配置并保存到 Flash。下面是审批与通用按键的参考映射，不是强制产品布局；量产端口必须让语音键直接调用物理录音入口。

参考键位映射text

Key1 → F18   approval/1 Allow
Key2 → F19   approval/1 Deny
Key3 → F13   keys/1 槽位 0
Key4 → F14   keys/1 槽位 1
拨杆          keys/1 槽位 7（press / release）
语音键按下     nexting_ahakey_port_voice_pressed(...)
语音键松开     nexting_ahakey_port_voice_released(...)
语音键取消     nexting_ahakey_port_voice_cancel(...)

当前可用性与证据

device-audio/1 协议与固件核心Schema、测试向量、C99/JavaScript 编解码、模拟器、AhaKey 状态机和传输描述符已完成自动化测试。Core tested

Nexting App 通用设备音频路径iOS 与 Android 开发版本按能力协商设备音频并复用现有 STT/Agent 管线，App 核心不含 AhaKey 专属业务分支。未知流的 fail-closed 一致性仍待补齐，因此暂不能宣称完全符合协议。集成已存在；一致性待补齐

公开 GitHub 集成套件Experimental 0.4 是当前公开 SDK 身份。经审计的 devices/ 导出把 AhaKey 套件与 0.4 目录一并发布。公开 0.4

面向 CH58x 的麦克风端口与真机仍需生产固件 PCM hook、烧录、iPhone/Android 联调、BLE 抓包、距离和功耗测试。待实物板测

在实物清单完成前，准确结论是“协议与适配器 Core tested”，不是 “AhaKey 已完全兼容”或“Board verified”。公开 App 的第三方设备注册也必须按可用性页面单独确认。

拿到实物后逐项验证

确认主控并接 PCM
通过实物或厂商 BOM 确认量产主控，接入它的实际麦克风驱动，并逐项验证上表的采样、帧长和按键前采集规则。
接物理键和状态
按下/松开调用语音入口，并让 LED 或 OLED 明确显示 ready、receiving、transcribing、submitted 和 error。
发布真实 Device Info
写入每台设备稳定 UUID 和真实固件版本；只有麦克风测试通过后才声明 device-audio/1。
双端联调
分别在 iPhone 和 Android 上验证开始、短按锁定、松键提交、取消、断连和重连。
证明声音来源
禁用手机麦克风权限仍能完成录音，并用 BLE 抓包确认 audio_begin 与音频帧来自实体键和设备。
压测失败路径
停止 credit、制造丢包与 CRC 错误，逐项验证上表的流控、丢包、取消、队列与擦除限制。