wangcong/story
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bf1233d5df51308edeacfe95082c7c10ccdfd797
story/docs/embedded-device-handoff-20260914.md
T

738 lines
54 KiB
Markdown
Raw Normal View History

feat: expand companion platform, device controls, and memoir workflows
2026-10-08 10:06:44 +08:00
# VoiceLink 设备接入交接文档
> 历史技术明细：本文描述旧的“设备自行注册火山”流程。当前代码已改为平台代注册，新的接口与迁移说明见同目录《平台注册火山与设备取参.md》和《设备接口文档-MQTT与OTA版.md》。本文件保留作旧协议参考，不用于指导新固件注册。
版本：1.1 / 2026-09-14。交付对象：嵌入式开发人员。本版更新蓝牙名称及小程序筛选规则，未改设备身份或密钥。
依据：线上后端 `0.90.0-rc.wechat1`、EchoEar 固件 `1.5.0-elder-agent.2`、VoiceLink 小程序 `wx4553119e05f11660` 的实际实现。
本文是当前方案：**明文 BLE 配网绑定 + 设备向平台申请开聊参数 + 设备直连火山 RTC + 火山回调文字 + 设备上报结束**。每位老人一个智能体，平台负责创建、保存、配置；设备不创建老人或智能体。
不要混用旧文档中的 `/device/v2/*`、`/device/v3/agent-sessions`、`/api/v1/device/calls/*`、旧网页 setup/handoff 接口。当前蓝牙无 `salt/verifier/session_password/client_nonce/server_nonce/proof` 握手。平台 HTTPS 的工厂密钥签名仍在实际代码中，本文如实列出，不是新增功能。
## 1. 已创建的交接设备与初始化
| 项目 | 本次设备值 | 中文解释与用途 |
|---|---|---|
| 工厂设备编号 `factory_id` / 接口 `device_id` | `KP01-020000260914` | BLE 自报和所有设备请求中的身份；不要使用平台 UUID 替代 |
| 生产编号后缀 `factory_mac` | `020000260914` | 本次人为保留的联调编号，不是读取到的实物 MAC；不要修改网卡真实 MAC 来迁就它 |
| 平台设备 UUID | `f9839cde-3078-4edc-a40a-c2dbe284fad6` | 平台列表、详情、解绑使用；设备协议不使用它作为 X-Device-ID |
| 型号 `model` | `ECHOEAR-S3` | BLE get_info 输出；注册 hardware_model 必须一致 |
| 硬件版本 | `V1.2` | register 的 hardware_revision 必须与此一致 |
| 后端地址 `origin` | `https://121.41.46.238` | 无末尾斜线；设备 HTTP 请求拼接下表路径 |
| 蓝牙广播名 | `voicelink-ECHOEAR-S3-00260914` | voicelink- + 型号 + - + 工厂编号末 8 位；小程序仅按服务 UUID 搜索，不按名称拒绝设备 |
| 平台密钥版本 `key_version` | `1` | 请求头、校时请求携带 |
| 平台设备密钥 | 同目录 `device-init.private.json` | 本设备专属随机 32 字节；不在通用文档明文展示 |
| BLE 协议版本 | `2` | get_info 的 protocol_version，必须是数字 2 |
| 平台接入契约标识 | `ONBOARDING-1.1` | 当前响应中的实际值；不是 BLE 版本，也不是聊天接口路径 |
| 当前状态 | `CLAIMABLE`、`released=true`、未绑定 | 平台已登记放行，尚未绑定任何老人、未做火山动态注册 |
| 登记批次 | `EMBEDDED-HANDOFF-20260914-TEST` | 后台查找这台联调设备 |
本次只给一台联调板使用这份身份，**不能把同一份密钥和编号烧进多台设备**。正式生产应读取各板真实 MAC，按对应编号逐台登记并分配独立密钥；本次测试身份可直接写入应用身份区联调，固件并不要求它等于网卡当前地址。若硬件并非 EchoEar，需要移植屏幕确认、音频驱动、存储、RTC SDK，不应照抄 EchoEar 分区偏移去烧录。
### 1.1 烧录/配置字段表
| 字段 | 类型/存储 | 中文解释与用途 | 如何取得 |
|---|---|---|---|
| `factory_id` | UTF-8 字符串 | 平台设备身份，17 字符，不含 NUL 终止符长度 | 上表及私有 JSON |
| `model` | 字符串，1–32 字节 | 型号 | `ECHOEAR-S3` |
| `origin` | 字符串 | 平台 HTTPS 根地址 | 上表 |
| `device_key` | **32 字节二进制** | 平台 HMAC 密钥 | 将私有 JSON 的 `device_key_hex` 每两位解码为 1 字节；或解码 `device_key_b64`，二者是同一密钥，不是两把 |
| `key_version` | uint32 | 平台密钥版本 | `1` |
| `hardware_revision` | 编译常量或持久化字符串 | 每次注册上报实际登记版本 | `V1.2` |
| TLS 信任根 | 系统/SDK CA 证书集合 | 校验平台及火山 HTTPS 证书；设备先校时再 TLS | 支持根证书更新，勿关闭证书验证；可使用 ESP-IDF crt bundle |
现有 ESP-IDF 代码从 `ble_factory` NVS 分区、`identity` 命名空间读取前 5 项：`factory_id/model/origin` 是 NVS string，`device_key` 是 blob，`key_version` 是 u32。其它 MCU 使用等价持久化区即可。BLE 服务 UUID 是编译常量，无需逐台烧录。旧 salt/verifier 不需要生成、读取或发送。
**初始化时不要烧录** Wi-Fi、手机号、账号密码、老人 ID、bind_token、bot_id、S2SConfig、MemoryConfig、微信 AppSecret、火山管理 AK/SK。Wi-Fi 和临时绑定令牌来自小程序；火山产品配置来自平台；注册得到的火山设备密钥和 RTCAppID 运行时保存。平台注册密钥与火山设备密钥不是同一个东西。
新板用户配置区初始为空：没有 Wi-Fi、没有待绑定任务、没有火山 device_secret/RTCAppID、没有未结束会话；首次启动生成新的 boot_id。不需要预生成 session_id、attempt_id、client_nonce；它们按流程产生。不要把参考板的运行期 NVS 整块克隆过来。
## 2. 完整实现顺序
| 顺序 | 谁做 | 动作/结果 |
|---|---|---|
| 1 | 设备 | 读取初始化身份，进入可连接 BLE 配网广播 |
| 2 | 小程序 | 用户登录，搜索、连接、订阅 TX，get_info 识别工厂编号和型号 |
| 3 | 小程序→平台 | 查是否已绑定；未绑定选择老人并拿 bind_token，已绑定使用空字符串 |
| 4 | 小程序→设备 | configure 发送 Wi-Fi 和 bind_token；设备先回复 received |
| 5 | 设备 | 等待 60 秒内轻点屏幕确认；确认后持久化任务，连接 Wi-Fi |
| 6 | 设备→平台 | 校时；有令牌则 ble-bind，空令牌则 ble-state 检查仍已绑定 |
| 7 | 设备 | 云端成功才保存 Wi-Fi，BLE get_status 返回 success；可约 15 秒后重启 |
| 8 | 设备→平台 | 每次新启动：新 boot_id → time-challenges → register → voice-runtime |
| 9 | 设备→平台/火山 | 首次没有火山设备凭据：activation-attempts → SDK 动态注册 → 保存凭据 → activation-results |
| 10 | 设备→平台 | 初始化 RTC SDK，保存配置后 activation-acks；已有凭据时跳过重复注册，但每次启动仍获取配置并确认 |
| 11 | 设备→平台 | 每次聊天新 session_id，chat/start 检查绑定并获得老人的 bot_id、params |
| 12 | 设备↔火山 | 用 SDK 获取房间、加入 RTC、采集和播放音频；聊天中每 10 秒重复 chat/start 续期 |
| 13 | 火山→平台 | 字幕回调自动保存聊天文字；设备不用上传聊天文字 |
| 14 | 设备→平台 | 先停音频和 SDK，再 chat/end；失败保留结束任务补报 |
平台创建老人时创建专属智能体、配置豆包 S2S 并关联火山硬件产品。嵌入式只选择平台本次返回的 bot_id，不能把某一老人 bot_id 固化成所有设备共用值。
## 3. 接口地址总表
以下 H = `https://121.41.46.238`。设备接口均由设备主动发起，平台通过响应返回数据，不需要在设备上开 HTTP 服务。
| 编号 | 调用方向 | 方法和完整地址/通道 | 接口描述 |
|---|---|---|---|
| B1 | 小程序→设备 | BLE RX / `get_info` | 获取设备身份、型号、协议版本 |
| B2 | 小程序→设备 | BLE RX / `configure` | 发送 Wi-Fi 和绑定令牌 |
| B3 | 小程序→设备 | BLE RX / `get_status` | 查询配网绑定结果 |
| M1 | 小程序→平台 | POST `https://121.41.46.238/api/v1/mini/ble-device-state` | 权限校验、查询绑定状态 |
| M2 | 小程序→平台 | POST `https://121.41.46.238/api/v1/mini/ble-bind-tokens` | 给未绑定设备申请短期绑定令牌 |
| M3 | 小程序→平台 | POST `https://121.41.46.238/api/v1/mini/ble-bind-status` | 查询令牌对应的绑定结果 |
| M4 | 小程序→平台 | GET `https://121.41.46.238/api/v1/devices` | 当前账号设备列表 |
| M5 | 小程序→平台 | GET `https://121.41.46.238/api/v1/devices/{id}/binding-impact?action=unbind` | 查询解绑影响，id 为平台 UUID |
| M6 | 小程序→平台 | POST `https://121.41.46.238/api/v1/devices/{id}/binding-change` | 用户确认解绑 |
| D1 | 设备→平台 | POST `http://121.41.46.238/api/v1/device/time-challenges` | 启动校时，唯一 HTTP 特例 |
| D2 | 设备→平台 | POST `https://121.41.46.238/api/v1/device/ble-bind` | 兑现绑定令牌 |
| D3 | 设备→平台 | POST `https://121.41.46.238/api/v1/device/ble-state` | 只读查询是否绑定 |
| D4 | 设备→平台 | POST `https://121.41.46.238/api/v1/device/register` | 当前启动注册，不是创建库存设备 |
| D5 | 设备→平台 | POST `https://121.41.46.238/api/v1/device/voice-runtime` | 获取当前绑定的语音注册配置 |
| D6 | 设备→平台 | POST `https://121.41.46.238/api/v1/device/activation-attempts` | 获取一次 SDK 注册执行许可 |
| D7 | 设备→平台 | POST `https://121.41.46.238/api/v1/device/activation-results` | 上报 SDK 注册真实结果 |
| D8 | 设备→平台 | POST `https://121.41.46.238/api/v1/device/activation-acks` | 确认配置已保存、SDK 已初始化 |
| D9 | 设备→平台 | POST `https://121.41.46.238/api/v1/device/chat/start` | 开聊检查/聊天续期 |
| D10 | 设备→平台 | POST `https://121.41.46.238/api/v1/device/chat/end` | 上报一次聊天结束 |
| V1 | 设备 SDK→火山 | POST `https://iot-cn-shanghai.iot.volces.com/2021-12-14/DynamicRegister?Action=DynamicRegister&Version=2021-12-14` | 获取火山设备密钥和 RTCAppID |
| V2 | 设备 SDK→火山 | POST `https://iot-cn-shanghai.iot.volces.com/2021-12-14/GetRTCConfig?Action=GetRTCConfig&Version=2021-12-14` | 获取本次 RTC 房间参数 |
| C1 | 火山→平台 | POST `https://121.41.46.238/callbacks/v1/volcengine/chat?session_id={session_id}` | 聊天文字回调；设备不调用 |
V1/V2 为当前工程内火山 SDK 的调用地址，优先复用 SDK，不把 RTC 当成普通 WebSocket。平台当前 IP 地址可用于设备 HTTPS；小程序正式发布的 request 合法域名配置是另一项工作。
## 4. 小程序与设备：BLE GATT
### 4.1 发现、连接和传输
| 项目 | 值 | 用途 |
|---|---|---|
| 服务 UUID | `8e7a2000-6f4b-4a2d-9c31-7d824f5e6100` | 放入广播/扫描响应的 128-bit Service UUID，小程序按它搜索 |
| RX UUID | `8e7a2001-6f4b-4a2d-9c31-7d824f5e6100` | 属性 Write，手机→设备，带应答写入 |
| TX UUID | `8e7a2002-6f4b-4a2d-9c31-7d824f5e6100` | 属性 Indicate，设备→手机，提供 CCCD 0x2902，等待 indication 确认后发下一片 |
| 广播名称 | `voicelink-ECHOEAR-S3-00260914` | 格式 voicelink-型号-xxxxxxxx，末尾为工厂编号后 8 位大写十六进制 |
| 协议 | 明文 UTF-8 JSON | 不要求 BLE 配对，不做业务加密握手 |
| 消息边界 | 2 字节小端长度 + JSON 字节 | 长度不含自身 2 字节，也不含 C 字符串结尾 NUL |
| 分片 | 每片最多 20 字节 | 同一逻辑消息仅头部出现一次长度，后续直接续传 |
| 消息长度 | 1–2048 字节 JSON | 帧最多 2050 字节；不支持同时并发多条命令 |
| 超时 | 整条消息 45 秒，无分片进展 10 秒 | 不完整帧超时断开并清缓冲，不能把部分 JSON 当作完整请求 |
小程序顺序：openBluetoothAdapter → startBluetoothDevicesDiscovery（services=[服务 UUID]）→ createBLEConnection → getBLEDeviceServices → getBLEDeviceCharacteristics → notifyBLECharacteristicValueChange（type=indication）→ 写 RX。订阅后约等 150 ms 再写入。必须在 TX 已订阅后发送应答。扫描约 20 秒停止，可重搜。
服务 UUID 是发现条件，名称仅用于显示，不是身份认证；旧 EchoEar 名称、自定义名称如 abcd-232223 也不会因名称被过滤，无名称时显示“未命名设备”。若扫描回调明确给出服务 UUID 列表，则也检查其中包含配网 UUID；未提供列表时依赖系统扫描过滤，连接后再次发现服务/特征并执行 B1。手机蓝牙 API 的 `deviceId` 是操作系统临时标识，只用于连接；业务 `device_id` 从 B1 读取。UUID 字符串比较可忽略大小写。广播 UUID 的字节序以蓝牙栈 API 为准，不能把文本 UUID 直接当原始 16 字节发送。
当前使用传统 31 字节扫描响应，名称 AD 的长度和类型占 2 字节，可用名称最多 29 字节。命名分配：`voicelink-` 10 字节 + 型号最多 10 个 UTF-8 字节 + `-` 1 字节 + 后缀 8 字节。超长型号只在广播名中按完整 UTF-8 字符边界缩短，B1 的 model 不缩短。GAP Device Name 和扫描响应使用同一个名称。原 EchoEar 实物编号 KP01-B43A451634A8 对应 `voicelink-ECHOEAR-S3-451634A8`；本次联调编号对应表中 `00260914`，这不改变编号本身。
帧示例（可直接比对十六进制）：
```text
JSON: {"cmd":"get_info"}
UTF-8 长度: 18 = 0x0012
完整帧 hex: 12007b22636d64223a226765745f696e666f227d
```
不使用换行分帧，不对每个 BLE 分片单独加头，不在 JSON 中加入包序号。按长度累加，完整后只处理一个对象。设备仅响应命令，**不主动推送状态**，否则当前小程序会认为收到非预期数据并断开。get_status 使用轮询。
### 4.2 B1 获取设备信息
| 方向 | 字段 | 类型/要求 | 中文解释与用途 | 示例 |
|---|---|---|---|---|
| 输入 | cmd | string，必填 | 命令 | `get_info` |
| 输出 | device_id | string | 工厂编号，后续向平台查询归属 | `KP01-020000260914` |
| 输出 | model | string | 设备型号，用于显示与注册一致性 | `ECHOEAR-S3` |
| 输出 | protocol_version | number | 明文 BLE 版本，小程序仅接受 2 | `2` |
```json
{"cmd":"get_info"}
```
```json
{"device_id":"KP01-020000260914","model":"ECHOEAR-S3","protocol_version":2}
```
### 4.3 B2 配网和绑定
| 方向 | 字段 | 类型/要求 | 中文解释与用途 | 示例 |
|---|---|---|---|---|
| 输入 | cmd | string，必填 | 配网命令 | `configure` |
| 输入 | wifi_ssid | string，必填，1–32 UTF-8 字节 | 2.4 GHz Wi-Fi 名称 | `HomeWiFi` |
| 输入 | wifi_password | string，必填，8–63 可打印 ASCII 字符 | Wi-Fi 密码；当前不支持开放网络 | `Example123` |
| 输入 | bind_token | string，必填 | 未绑定时 43 字符 base64url 令牌；已绑定仅配网时必须是空字符串 | `服务器返回值` 或 `""` |
| 输出 | status | string | received 只表示已接收，尚未联网/绑定成功 | `received` |
| 输出 | message | string，仅失败时 | 给用户的失败说明 | `Wi-Fi 参数不正确` |
```json
{"cmd":"configure","wifi_ssid":"HomeWiFi","wifi_password":"Example123","bind_token":"<M2返回的43字符原值>"}
```
```json
{"status":"received"}
```
已绑定只换 Wi-Fi 的完整示例：
```json
{"cmd":"configure","wifi_ssid":"NewHomeWiFi","wifi_password":"Example456","bind_token":""}
```
空令牌不等于解绑，也不等于缺字段或 null。设备不需要获得微信 OpenID、手机号、家庭账号密码或账号 access_token。Wi-Fi 密码只在手机与设备之间传输，不上传平台。
设备收到后提示用户轻点屏幕，60 秒内确认才开始联网。嵌入式可以实现等价的明确确认按键，但不能直接把 received 当成确认成功。确认后把本次 Wi-Fi、令牌和新 UUID v4 确认事件 ID 原子保存，D2 的 X-Request-ID 使用此事件 ID；重试保持它和正文不变。空令牌调用 D3，返回 bound=false 时不保存新 Wi-Fi，提示重新绑定。
### 4.4 B3 查询配网状态
| 方向 | 字段 | 类型/要求 | 中文解释与用途 | 示例 |
|---|---|---|---|---|
| 输入 | cmd | string，必填 | 查询命令 | `get_status` |
| 输出 | status | string | 当前状态，见下表 | `success` |
| 输出 | message | string，可选 | 失败/恢复提示 | `设备已解绑，请重新搜索并绑定账号` |
```json
{"cmd":"get_status"}
```
```json
{"status":"failed","message":"设备已解绑，请重新搜索并绑定账号"}
```
| status | 中文解释与设备动作 |
|---|---|
| idle | 等待 configure |
| received | 已收参数，等待设备屏幕确认 |
| wifi_connecting | 正在连接新 Wi-Fi |
| binding | 正在 D2 绑定或 D3 查询已有绑定 |
| success | 云端成功且 Wi-Fi 已持久化；可以结束配网 |
| failed | 明确失败，message 解释原因 |
小程序约每 2.5 秒轮询结果。同一任务进行中收到完全相同的 configure 返回已有状态；不同参数不替换进行中的任务。云端超时不代表绑定未执行，保留任务重试。明确 4xx（408/429 除外）停止并提示。BLE 断开不能作为成功依据。当前固件支持首次自动配网、双击触摸屏重新进入、5 分钟广播窗口；不要长按电源键作为入口，它会关机。
## 5. 小程序辅助接口（嵌入式不调用）
公共请求头：`Content-Type: application/json`，`X-Request-ID: UUID v4`，`Authorization: Mini <登录返回的access_token>`，`X-Login-Portal: customer`。access_token 已包含 customer. 前缀，不重复添加。用户登录及 getPhoneNumber 均由小程序负责。
以下示例省略公共成功信封，仅展示 data。设备状态查询和绑定令牌都应以平台为准，不能靠设备本地保存的“已绑定”标志替代。
| 接口 | 方向/字段 | 中文解释与用途 | 示例 |
|---|---|---|---|
| M1 | 输入 device_id | 工厂编号，查询当前账号是否有权操作 | `KP01-020000260914` |
| M1 | 输出 device_id / id / model / bound | 工厂编号 / 平台公开 UUID / 型号 / 是否已绑定 | `{"device_id":"KP01-020000260914","id":"f9839cde-3078-4edc-a40a-c2dbe284fad6","model":"ECHOEAR-S3","bound":false}` |
| M2 | 输入 device_id / elder_id | 工厂编号 / 选定老人公开 UUID，均由小程序明确传入 | `{"device_id":"KP01-020000260914","elder_id":"<老人UUID>"}` |
| M2 | 输出 bind_token | 32 随机字节的 base64url 无填充编码，43 字符，5 分钟有效；原样 BLE 转发，不自行计算 | `{"bind_token":"<43字符值>"}` |
| M3 | 输入 bind_token | 本次申请的非空令牌，查绑定结果 | `{"bind_token":"<43字符值>"}` |
| M3 | 输出 status / message | pending 等待、success 成功、failed 失败及说明 | `{"status":"pending"}` |
| M4 | 输入 | 无正文 | GET 请求 |
| M4 | 输出 items[] | 设备集合，含 id、binding_id、model、subject_id、subject_name、household_id、status、firmware_version | `{"items":[]}` |
| M5 | 输入 URL id / action | 平台设备 UUID / 固定 unbind | `.../devices/f9839cde-3078-4edc-a40a-c2dbe284fad6/binding-impact?action=unbind` |
| M5 | 输出 binding_id / allowed / blockers | 当前绑定版本、是否可解绑、不能解绑的原因；另有任务数量及源家庭/老人信息 | `{"binding_id":"<绑定UUID>","allowed":true,"blockers":[]}` |
| M6 | 输入 action / expected_binding_id / acknowledged / reason | 固定 unbind / M5 取得的绑定 UUID / 用户已确认 true / 解绑原因 | `{"action":"unbind","expected_binding_id":"<绑定UUID>","acknowledged":true,"reason":"小程序设备管理解除绑定"}` |
| M6 | 输出 device_id / action / previous_binding_id / changed_at | 变更设备 UUID、操作类型、旧绑定、变更时间 | `{"device_id":"<平台UUID>","action":"unbind","previous_binding_id":"<旧绑定UUID>","changed_at":"<UTC时间>"}` |
小程序在点击发送前再次调用 M1。未绑定才调用 M2，已绑定直接发空令牌。M1 返回 403 时停止，不向设备发送 Wi-Fi。M2 的 409 ALREADY_BOUND 要刷新状态，不得覆盖绑定。解绑由 M5/M6 完成，历史记录不删除，设备 Wi-Fi 不被远程擦除；设备下次 D9 会收到绑定错误。当前平台有进行中的通话等阻塞项时会拒绝解绑，不能循环强行提交。
## 6. 设备 HTTPS 公共格式与计算
### 6.1 请求头（D2–D10）
| 输入字段 | 类型 | 中文解释与用途 | 示例/计算 |
|---|---|---|---|
| Content-Type | header string | JSON 正文 | `application/json` |
| X-Device-ID | header string | 工厂编号，不是蓝牙地址或平台 UUID | `KP01-020000260914` |
| X-Key-Version | header 十进制字符串 | 平台密钥版本，无前导零 | `1` |
| X-Timestamp-Ms | header 十进制字符串 | 校时后的 Unix UTC 毫秒时间，需在服务器 ±120 秒内 | `1789372800000` |
| X-Nonce | header string | 每次 HTTP 尝试新生成 16 随机字节，base64url 无填充 → 22 字符 | 不复用；不是 boot_id |
| X-Request-ID | header string | 小写 UUID v4；业务重试策略见 6.4 | `12345678-1234-4234-8234-123456789abc` |
| Authorization | header string | 按下一节 HMAC-SHA256 计算 | `Device-HMAC-SHA256 <64位小写hex>` |
这些接口没有 URL 查询参数，不能自行添加 `?device_id=...`。不用旧的 X-Device-Timestamp、X-Device-Signature 等签名头。正文必须是 UTF-8 JSON 对象，不允许重复字段、未知字段、错误类型；普通设备接口请求正文上限 8192 字节，chat/start/end 上限 2048 字节。必须处理非 2xx 和业务 code。
### 6.2 签名算法：直接照此实现
```text
K = hex_decode(device-init.private.json 中 device_key_hex) // 32 字节，不是64字符文本
raw = UTF8(实际要发送的 JSON 字符串)
body_sha = lowercase_hex(SHA256(raw))
canonical = "DEVREQ1\n"
+ "POST\n"
+ path + "\n" // 如 /api/v1/device/ble-state；无域名、无查询串
+ factory_id + "\n"
+ decimal(key_version) + "\n"
+ decimal(timestamp_ms) + "\n"
+ nonce_base64url + "\n"
+ request_id + "\n"
+ body_sha // 最后没有换行
signature = lowercase_hex(HMAC_SHA256(K, UTF8(canonical)))
Authorization = "Device-HMAC-SHA256 " + signature
```
分隔符是真实 LF 字节 `0x0A`，不是反斜杠和 n 两个字符，不是 Windows CRLF。先序列化一次，签名和发送使用同一份 raw；空格、换行、字段顺序都会改变摘要。D3 的正文是 `{}`，不是空字符串。
base64url 无填充：普通 Base64 的 `+` 换成 `-`、`/` 换成 `_`，去掉末尾 `=`。解码时反向替换并补足到 4 的倍数。UUID v4：16 随机字节，byte[6]=(byte[6]&0x0f)|0x40，byte[8]=(byte[8]&0x3f)|0x80，再输出小写 `8-4-4-4-12` 十六进制字符串。
离线验算（以下是公开假密钥，不是新设备真实密钥）：
```text
K hex = 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
path = /api/v1/device/ble-state
factory_id = KP01-020000260914
key_version = 1
timestamp_ms = 1789372800000
nonce = AAECAwQFBgcICQoLDA0ODw
request_id = 12345678-1234-4234-8234-123456789abc
raw = {}
body_sha = 44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a
signature = 6589d587fad96f306ed1ef839d66a9a4f8408e133a1cb65796168106e89ca66d
```
附带 `embedded-signing-reference.cjs` 可用 Node.js 执行并输出完整 canonical、请求头及 BLE 帧。固定测试时间、nonce 和示例假密钥仅用于离线算法测试，不能用于线上请求。
### 6.3 公共输出信封
```json
{"ok":true,"code":"OK","request_id":"<UUID>","server_time_ms":1789372800000,"data":{}}
```
| 输出字段 | 中文解释与用途 |
|---|---|
| ok | 业务是否成功；不能仅看 TCP/HTTP 发送成功 |
| code | 业务码，成功 OK；错误按码分支 |
| request_id | 本次请求追踪 ID |
| server_time_ms | 服务器 UTC 毫秒时间；用于聊天有效期计算 |
| data | 下面各接口的业务输出 |
| message | 错误说明，可能存在于失败响应 |
| recovery_action | 部分错误附带恢复提示；优先按 HTTP/code 实现 |
错误示例：HTTP 409，`{"ok":false,"code":"DEVICE_UNBOUND","message":"绑定错误：设备没有绑定人员","request_id":"<UUID>"}`。D1 校时成功响应例外，不带这层信封。M4–M6 的旧业务接口采用 `{request_id,data}` 成功包装，小程序自行处理，嵌入式不用兼容它。
### 6.4 重试和持久化
| 对象 | 生成/重试规则 |
|---|---|
| boot_id | 每次 MCU 真正启动生成一次，当前启动各请求保持；不是每次 HTTP 新建 |
| session_id | 每次新聊天生成一次；start 重试、10 秒续期、end 始终相同；结束后不能复用 |
| X-Request-ID | D2 确认事件、D4 注册、D6 申请、D7 结果、D8 确认的一次业务操作重试保持，正文逐字节不变；新操作新建；同 ID 不同正文返回冲突 |
| D9/D10 | 核心业务幂等按 device + session_id；每次 start/续期可新 request_id；end 建议持久化一个固定 request_id 及正文直到成功 |
| timestamp / X-Nonce | **任何 HTTP 重试都重新生成**，即使 request_id 保持；重新计算签名 |
| bind_token | 仅本次绑定使用，成功清理；过期不自行生成，回小程序重新申请 |
| 火山 SDK 注册结果 | 成功先保存 device_secret、RTCAppID、attempt_id 和待上报结果，再确认平台；断电后补报，不重复消耗注册流程 |
| 待结束聊天 | 保存 session_id、reason、sdk_stopped、end request_id；成功才删除。重启残留会话 reason=reboot，不能伪造已观察到 SDK 正常停止 |
网络/5xx/408/429 使用有上限的延迟重试；有有效租期时只用剩余时间，不能自行延长音频权限。401 先校时核验设备身份；403/409 按业务码恢复，不无限重试。任务 HTTP 不要放在蓝牙回调或 UI 回调里阻塞执行，使用独立任务，避免看门狗重启。
## 7. 设备与平台接口明细
下文输入均为 JSON body，输出为 data 内字段（D1 例外）。每个接口完整地址见第 3 节。
### D1 校时：`POST /api/v1/device/time-challenges`
唯一可用 HTTP 的设备接口，不需要 6.1 签名头，也不传 Wi-Fi/绑定令牌；响应自带工厂密钥 HMAC。设备时钟尚未设置时先做它。
| 方向 | 字段 | 类型/要求 | 中文解释与用途 | 示例 |
|---|---|---|---|---|
| 输入 | device_id | string，必填 | 工厂编号 | `KP01-020000260914` |
| 输入 | key_version | integer，必填 | 工厂密钥版本 | `1` |
| 输入 | boot_id | UUID v4，必填 | 当前启动编号 | `<本次启动UUID>` |
| 输入 | client_nonce | string，必填 | 新 16 字节随机数 base64url，无填充 22 字符，关联请求与响应 | `<22字符值>` |
| 输出 | payload_b64 | string | base64url 编码的 JSON，不是密文 | `<编码值>` |
| 输出 | mac_hex | string | 64 小写 hex，校验返回内容 | `HMAC(K,"TIME1\n"+payload_b64)` |
| 解码输出 | device_id / boot_id / client_nonce | string | 必须与本次请求逐项相同，拒绝错设备/旧响应 | 原值 |
| 解码输出 | challenge_id | UUID v4 | 启动注册所用挑战 ID | `<服务器UUID>` |
| 解码输出 | server_time_ms | int64 | 用于设置设备 UTC 时钟 | `<当前毫秒>` |
| 解码输出 | expires_at_ms | int64 | 挑战过期时间，当前为签发后 120 秒 | `<当前毫秒+120000>` |
```json
{"device_id":"KP01-020000260914","key_version":1,"boot_id":"12345678-1234-4234-8234-123456789abc","client_nonce":"AAECAwQFBgcICQoLDA0ODw"}
```
```json
{"payload_b64":"<base64url JSON>","mac_hex":"<64位小写hex>"}
```
计算 `expected=hex_lower(HMAC_SHA256(K,UTF8("TIME1\n"+payload_b64)))`，与 mac_hex 比较成功，再解码 JSON，核对回传字段。使用单调计时判断整个请求往返小于 15 秒，不能用未校准的墙上时钟判断。正确后设置 UTC，保存 challenge_id 并在 120 秒内 register。这里 client_nonce 是校时用，不是已取消的 BLE 握手。
### D2 兑现绑定：`POST /api/v1/device/ble-bind`
| 方向 | 字段 | 类型/要求 | 中文解释与用途 | 示例 |
|---|---|---|---|---|
| 输入 | bind_token | string，必填，43 字符 | 小程序 BLE 传来的非空令牌，原样传递 | `{"bind_token":"<43字符原值>"}` |
| 输出 | status | string | 绑定是否完成；成功固定 success | `{"status":"success"}` |
设备完成物理确认、联网、校时后调用。X-Request-ID 使用已保存的本次确认事件 UUID。无需发送 Wi-Fi、老人 ID 或账号资料，令牌已包含服务器端关联。平台验证令牌所属设备/家庭/老人、有效期及绑定代次；重试不会重复绑定。不接受空令牌。
### D3 查询绑定：`POST /api/v1/device/ble-state`
| 方向 | 字段 | 类型/要求 | 中文解释与用途 | 示例 |
|---|---|---|---|---|
| 输入 | 无业务字段 | 空对象，必填 | 查询签名头对应的设备，不传其他字段 | `{}` |
| 输出 | bound | boolean | 当前是否仍绑定；false 要回到首次绑定流程 | `{"bound":false}` |
收到空 bind_token 时调用。bound=true 才保存本次新 Wi-Fi，bound=false 不改变归属、不保存新配置。这里为 true 仅表示已绑定，不代表 SDK 已注册或智能体已就绪。
### D4 每次启动注册：`POST /api/v1/device/register`
| 方向 | 字段 | 类型/要求 | 中文解释与用途 | 示例 |
|---|---|---|---|---|
| 输入 | challenge_id | UUID v4，必填 | D1 返回值，未过期、未消费 | `<D1值>` |
| 输入 | boot_id | UUID v4，必填 | 与 D1 同一启动编号 | `<本次启动UUID>` |
| 输入 | hardware_model | string，必填 | 必须与生产登记型号相同 | `ECHOEAR-S3` |
| 输入 | hardware_revision | string，必填 | 必须与生产登记硬件版本相同 | `V1.2` |
| 输入 | firmware_version | string，必填，1–32 字节 | 自己的真实固件版本 | `1.5.0-elder-agent.2` |
| 输入 | sdk_version | string，必填，1–64 字节 | 使用的真实语音 SDK 版本 | `2.0.0` |
| 输出 | contract_version | string | 当前平台接入契约标识 | `ONBOARDING-1.1` |
| 输出 | state | object | 当前绑定/激活状态，见下表 | `<状态对象>` |
```json
{"challenge_id":"<D1挑战UUID>","boot_id":"<启动UUID>","hardware_model":"ECHOEAR-S3","hardware_revision":"V1.2","firmware_version":"1.5.0-elder-agent.2","sdk_version":"2.0.0"}
```
```json
{"contract_version":"ONBOARDING-1.1","state":{"device_id":"KP01-020000260914","device_revision":3,"binding_generation":0,"binding_state":"UNBOUND","activation_state":"NOT_STARTED","state_hash":"<64位摘要>"}}
```
示例 revision 仅示意，以真实返回为准。新 boot_id 会关闭旧启动的设置状态，正在执行但未确认的 SDK 注册可能转为待对账；不要每次请求都更换 boot_id。
#### 公共 state 输出
| 输出字段 | 中文解释与用途 |
|---|---|
| device_id | 工厂编号 |
| device_revision | 平台设备状态版本，状态变化会增加；不是固件版本 |
| binding_generation | 绑定代次，绑定/解绑会变化；设备只能保存响应原值，不自行 +1 |
| binding_state | UNBOUND 未绑定、CLAIM_PENDING 旧流程待确认、BOUND 已绑定 |
| activation_state | NOT_STARTED/RESERVED/CONTACT_POSSIBLE/REGISTERED_OBSERVED/READY/RECONCILE_REQUIRED/BLOCKED 等激活任务状态；不是库存的 CLAIMABLE 生命周期 |
| state_hash | SHA256 状态摘要；当前最小流程无需单独 state-acks，可保存和核对 |
如需验算 state_hash，使用：
```text
hex_lower(SHA256(UTF8("STATE1\n" + device_id + "\n" + decimal(device_revision)
+ "\n" + decimal(binding_generation) + "\n" + binding_state + "\n" + activation_state)))
```
### D5 获取语音运行配置：`POST /api/v1/device/voice-runtime`
| 方向 | 字段 | 类型/要求 | 中文解释与用途 | 示例 |
|---|---|---|---|---|
| 输入 | boot_id | UUID v4，必填 | 已完成 D4 的当前启动编号 | `{"boot_id":"<启动UUID>"}` |
| 输出 | state | object | 当前绑定代次、激活状态 | 见 D4 |
| 输出 | command | object 或 null | 当前需应用的激活配置；null 不可继续当作有效配置 | 见下例 |
| 输出 | command.command_id | UUID | 激活任务 ID | `<activation_id>` |
| 输出 | command.type | string | 配置命令 | `APPLY_ACTIVATION` |
| 输出 | command.expires_at_ms | int64 | 配置有效期 | `<毫秒>` |
| 输出 | command.payload.config_b64 | string | base64url JSON 配置 | `<编码值>` |
| 输出 | command.payload.config_mac | string | 配置 HMAC，校验公式如下 | `<64位hex>` |
| 输出 | call_contract | string | 现有兼容字段，可能仍为 CALL-MEMORY-1.1；本实现明确使用 D9/D10，不按此字段切回旧 calls 路径 | `CALL-MEMORY-1.1` |
```json
{"state":{"binding_generation":1,"binding_state":"BOUND","activation_state":"RESERVED"},"command":{"command_id":"<激活UUID>","type":"APPLY_ACTIVATION","expires_at_ms":1789459200000,"payload":{"config_b64":"<编码配置>","config_mac":"<64位hex>"}},"call_contract":"CALL-MEMORY-1.1"}
```
state 在这里省略了 D4 已列出的通用字段。先比较：
```text
expected_config_mac = hex_lower(HMAC_SHA256(K, UTF8("CFG1\n" + config_b64)))
config = JSON_parse(base64url_decode(config_b64))
```
此处是 **Base64 编码 + 签名，不是应用层加密**；实际通过 HTTPS 传输。解码后的字段：
| 输出字段 | 中文解释与用途 | 示例/处理 |
|---|---|---|
| contract_version | 当前注册配置契约 | ONBOARDING-1.1 |
| device_id | 应与烧录工厂编号一致 | 不一致拒绝 |
| activation_id | 本次绑定的激活任务 ID，后续 D6–D8 使用 | 原样保存 |
| config_version | 当前配置版本，D6/D8 使用 | 原样保存，不自行递增 |
| binding_generation | 必须与 state.binding_generation 一致 | 不一致重新拉取 |
| expires_at_ms | 24 小时配置有效期，以实际返回为准 | 过期重新拉取 |
| iot.instance_id | 火山实例 ID | SDK 初始化/注册使用 |
| iot.product_key | 火山产品 Key | SDK 初始化/注册使用 |
| iot.product_secret | 当前实现确实下发的火山产品注册密钥 | 仅动态注册时使用，不是平台设备密钥；不打印、不发给小程序 |
| iot.device_name | 平台分配的火山设备名称 | 原样使用，不能自行替换为 MAC |
| bot_id | 产品默认激活配置中的 bot | **聊天必须用 D9 返回的老人专属 bot_id，不要用这个默认值覆盖它** |
未绑定返回 409 DEVICE_UNBOUND。已经有火山 device_secret 时复用本地凭据，检查实例/产品/名称是否匹配；不因为重启或换绑老人就重新动态注册。若注册状态不确定（RECONCILE_REQUIRED），停止重复注册，交给平台核对。
### D6 SDK 注册执行许可：`POST /api/v1/device/activation-attempts`
| 方向 | 字段 | 类型/要求 | 中文解释与用途 | 示例 |
|---|---|---|---|---|
| 输入 | activation_id | UUID v4，必填 | D5 激活任务 | `<D5值>` |
| 输入 | config_version | integer，必填，≥1 | D5 配置版本 | `1` |
| 输入 | attempt_id | UUID v4，必填 | 设备为一次 SDK 注册生成并保存的编号 | `<新UUID>` |
| 输出 | allowed | boolean | 是否允许这次外部 SDK 操作 | `true` |
| 输出 | attempt_id | UUID | 对应本次操作 | 原值 |
| 输出 | permit_expires_at_ms | int64 | 必须在许可有效期内发起注册，当前 30 秒 | `<毫秒>` |
| 输出 | state | object | 平台激活状态 | CONTACT_POSSIBLE |
```json
{"activation_id":"<D5激活UUID>","config_version":1,"attempt_id":"<新UUID>"}
```
```json
{"allowed":true,"attempt_id":"<同一UUID>","permit_expires_at_ms":1789372830000,"state":{"activation_state":"CONTACT_POSSIBLE"}}
```
这一步只在确实需要首次动态注册时执行，不是每次聊天都调用。拿到许可并保存“可能已经发起注册”记录后才调用 V1。不要在许可不确定/超时后换个 attempt_id 再次注册；先恢复原结果，防止重复注册。当前直聊首次通话可完成激活，不用另外实现旧 CONVERSATION_TEST 会话。
### D7 SDK 注册结果：`POST /api/v1/device/activation-results`
| 方向 | 字段 | 类型/要求 | 中文解释与用途 | 示例 |
|---|---|---|---|---|
| 输入 | activation_id | UUID v4，必填 | 当前激活任务 | `<D5值>` |
| 输入 | attempt_id | UUID v4，必填 | D6 使用的原编号 | `<D6值>` |
| 输入 | stage | string，必填 | 当前最小流程固定 SDK_REGISTER | `SDK_REGISTER` |
| 输入 | sdk_result | integer，必填 | SDK 返回码，成功必须 0 | `0` |
| 输入 | outcome | string，必填 | SUCCESS_OBSERVED 确认成功、DEFINITE_FAILURE 确认失败、UNKNOWN 无法确认 | `SUCCESS_OBSERVED` |
| 输出 | activation_id | UUID | 对应激活任务 | 原值 |
| 输出 | state | object | 成功通常 REGISTERED_OBSERVED | 见 D4 |
| 输出 | reconcile_required | boolean | true 表示需平台核对，不能再盲目注册 | `false` |
```json
{"activation_id":"<D5值>","attempt_id":"<D6值>","stage":"SDK_REGISTER","sdk_result":0,"outcome":"SUCCESS_OBSERVED"}
```
```json
{"activation_id":"<D5值>","state":{"activation_state":"REGISTERED_OBSERVED"},"reconcile_required":false}
```
只有真的拿到并保存火山 device_secret 和 RTCAppID 才报成功。超时、断电无法确认归 UNKNOWN，不等于 DEFINITE_FAILURE。该接口不上传火山密钥。结果重试保持同一正文和结果 request_id；同一 attempt 已保存不同结果时不能覆盖。
### D8 SDK 初始化确认：`POST /api/v1/device/activation-acks`
| 方向 | 字段 | 类型/要求 | 中文解释与用途 | 示例 |
|---|---|---|---|---|
| 输入 | activation_id | UUID v4，必填 | D5 任务 ID | `<原值>` |
| 输入 | config_version | integer，必填，≥1 | 已保存的当前配置版本 | `1` |
| 输入 | local_generation | integer，必填，≥0 | 本地保存配置的代次；同一启动不得倒退。现有固件直接用 config_version | `1` |
| 输出 | accepted | boolean | 平台已接受保存/初始化回执 | `true` |
| 输出 | state | object | 当前状态 | REGISTERED_OBSERVED 或 READY |
```json
{"activation_id":"<D5值>","config_version":1,"local_generation":1}
```
```json
{"accepted":true,"state":{"activation_state":"REGISTERED_OBSERVED"}}
```
在 D7 成功之后、RTC SDK 初始化成功之后调用。没有成功回执不能开始聊天。普通每次开机已存在火山凭据时仍需要 D4→D5→SDK 初始化→D8。
### D9 开始聊天/续期：`POST /api/v1/device/chat/start`
| 方向 | 字段 | 类型/要求 | 中文解释与用途 | 示例 |
|---|---|---|---|---|
| 输入 | device_id | string，本实现必传 | 与 X-Device-ID 一致；服务端兼容旧固件可省略，但新实现不要省 | `KP01-020000260914` |
| 输入 | session_id | UUID，必填，建议 UUID v4 | 一次聊天的唯一编号；重试和续期保持 | `<新聊天UUID>` |
| 输入 | boot_id | UUID，必填 | 已完成 D4 的当前启动编号 | `<启动UUID>` |
| 输出 | session_id | UUID | 必须对应本次聊天 | 原值 |
| 输出 | bot_id | string | 当前绑定老人的专属智能体 | `bot...` |
| 输出 | params | object | 整体交给 SDK；不要只挑一两个字段 | 下表 |
| 输出 | lease_expires_at_ms | int64 | 当前音频运行租期截止，最多 45 秒 | `<毫秒>` |
| 输出 | expires_at_ms | int64 | 本通话总截止，最多 1 小时，也可能受配额缩短 | `<毫秒>` |
```json
{"device_id":"KP01-020000260914","session_id":"<本次聊天UUID>","boot_id":"<启动UUID>"}
```
```json
{"ok":true,"code":"OK","request_id":"<请求UUID>","server_time_ms":1789372800000,"data":{"session_id":"<本次聊天UUID>","bot_id":"<老人bot_id>","params":{"PlatformTaskID":"<本次聊天UUID>","AgentConfig":{"WelcomeMessage":"你好，今天想聊些什么？","EnableConversationStateCallback":false,"ServerMessageURLForRTS":"https://121.41.46.238/callbacks/v1/volcengine/chat?session_id=<本次聊天UUID>","ServerMessageSignatureForRTS":"<平台生成的本次回调签名>"}},"lease_expires_at_ms":1789372845000,"expires_at_ms":1789376400000}}
```
| params 输出字段 | 中文解释与用途 | 设备动作 |
|---|---|---|
| PlatformTaskID | 本次平台会话关联号 | SDK 取它作为火山 task_id；不能另外随机生成 |
| AgentConfig.WelcomeMessage | 欢迎语 | 原样传给 SDK |
| AgentConfig.EnableConversationStateCallback | 是否开通供应商会话状态回调，当前 false | 原样传递；聊天结束由设备上报 |
| AgentConfig.ServerMessageURLForRTS | 本次字幕回调 URL，含 session_id | 原样传火山；不是 Function calling URL |
| AgentConfig.ServerMessageSignatureForRTS | 平台生成的回调签名值 | 原样传火山；设备不需要计算，不需要平台回调主密钥 |
该字段由平台计算为 `base64url_no_padding(HMAC_SHA256(callbackSecret, UTF8("volc-subtitle-v1\ndirect:" + session_id)))`。callbackSecret 只留服务器；这条公式供接口理解，嵌入式不需要获得该密钥，也不能改用工厂设备密钥计算。设备仅复制 D9 实际返回值。
平台每次新聊天查 `设备→绑定老人→老人智能体`，未绑定 HTTP 409 DEVICE_UNBOUND；未注册 SDK/未 D8 确认 DEVICE_NOT_READY；智能体未创建成功 VOICE_AGENT_NOT_READY。同老人/设备有另一通活动聊天返回 CHAT_ALREADY_ACTIVE。S2SConfig、模型、记忆由平台配置到该老人智能体，本接口不再把它们交给设备配置。
**聊天中每 10 秒重复调用 D9**，同 session_id/boot_id，返回新的 lease_expires_at_ms；这不是重新创建聊天。第一次把 params 交给 SDK，续期不重进房。超过租期或明确绑定/授权错误，关闭本地采集、播放及 SDK，然后 D10。
设备使用单调计时避免校时跳变：
```text
request_started = monotonic_ms()
收到响应后 elapsed = monotonic_ms() - request_started
remaining = data.lease_expires_at_ms - envelope.server_time_ms - elapsed
要求 0 < remaining <= 45000
local_deadline = monotonic_ms() + remaining
```
剩余时间非正则拒绝这次授权。expires_at_ms <= server_time_ms 也拒绝。网络失败仅沿用上一次仍有效的 local_deadline，不能按“现在+45秒”自续。总期限到达需结束，不复用旧 session_id。
### D10 聊天结束：`POST /api/v1/device/chat/end`
| 方向 | 字段 | 类型/要求 | 中文解释与用途 | 示例 |
|---|---|---|---|---|
| 输入 | device_id | string，本实现必传 | 与请求头工厂编号一致 | `KP01-020000260914` |
| 输入 | session_id | UUID，必填 | D9 使用的同一个聊天编号 | `<原值>` |
| 输入 | reason | string，必填 | 结束原因：hangup、start_failed、disconnected、reboot、timeout | `hangup` |
| 输入 | sdk_stopped | boolean，本实现明确传 | 已观察到本地 SDK 停止成功才 true；不是“我准备停止” | `true` |
| 输出 | session_id | UUID | 对应会话 | 原值 |
| 输出 | ended | boolean | 平台已接收结束；不证明远端所有媒体均已被平台观测停止 | `true` |
```json
{"device_id":"KP01-020000260914","session_id":"<本次聊天UUID>","reason":"hangup","sdk_stopped":true}
```
```json
{"session_id":"<本次聊天UUID>","ended":true}
```
先停本地音频，再停止 SDK，最后上报。网络失败保存补报；重启时未完成会话使用 reason=reboot，sdk_stopped=false（未亲眼观察到旧 SDK 正常停止）。即使已解绑，仍可用有效工厂身份给旧 session_id 补报结束。已结束的 session_id 再 start 返回 CHAT_ENDED；start 超时也要尝试 end，避免服务器已创建而设备不知道。
## 8. 设备直连火山 SDK 的必要参数
本节按项目内已验证的火山硬件 SDK 实现说明，不是让嵌入式自行实现整套 RTC。初次注册有外部 License/配额影响；本交接设备尚未执行此步骤。
### 8.1 V1 DynamicRegister：首次获取火山设备凭据
SDK 函数 `volc_device_register(&iot_info, &device_secret)` 使用 D5 的 instance_id/product_key/product_secret/device_name。收到 D6 许可后才执行。
| 方向 | 字段 | 中文解释与用途 | 示例/来源 |
|---|---|---|---|
| 输入 | InstanceID | 火山实例 ID，注意大小写 | D5 iot.instance_id |
| 输入 | product_key | 产品标识 | D5 iot.product_key |
| 输入 | device_name | 火山设备名 | D5 iot.device_name |
| 输入 | random_num | 本次签名随机字段；当前 SDK 取 int32(timestamp_ms)，可能为负数 | 原始十进制值参与签名 |
| 输入 | timestamp | UTC 毫秒数字，不是秒 | 已校时设备时钟 |
| 输入 | auth_type | 注册使用产品密钥，固定数字 1 | `1` |
| 输入 | signature | 火山格式 HMAC 签名，见 8.3 | 普通 Base64，非 hex |
| 输出 | Result.payload | 加密的火山设备密钥 | SDK 解密后得到 device_secret |
| 输出 | Result.RTCAppID | RTC 应用 ID | 持久化，初始化 RTC 引擎 |
| 输出 | ResponseMetadata.Error | 火山错误信息（失败时） | SDK 检查，不把错误包当成功 |
```json
{"InstanceID":"<实例>","product_key":"<产品>","device_name":"<火山设备名>","random_num":123456,"timestamp":1789372800000,"auth_type":1,"signature":"<普通Base64签名>"}
```
```json
{"Result":{"payload":"<加密Base64内容>","RTCAppID":"<RTC应用ID>"}}
```
SDK 注册解码：`ciphertext=普通Base64_decode(Result.payload)`，AES-128-CBC 密钥为 **product_secret 字符串前16字节**，IV 也是前16字节，解密后校验并去除 PKCS#7 填充，得到火山 device_secret 字符串。不是用平台的 32 字节 K，也不是将 product_secret 按 hex 解码。项目现有 `volc_aes_decode(product_secret,payload,true)` 已实现，优先复用。
### 8.2 V2 GetRTCConfig：每次开聊获取房间
| 方向 | 字段 | 中文解释与用途 | 示例/来源 |
|---|---|---|---|
| 输入 | InstanceID / product_key / device_name | 此设备火山身份 | 首次注册配置的原值 |
| 输入 | random_num / timestamp / signature | 用火山 device_secret 签名，auth_type 按 0 参与计算；当前此请求 body 不额外加 auth_type | 见 8.3 |
| 输入 | bot_id | 此次老人的智能体 | **D9 bot_id** |
| 输入 | audio_codec | RTC 编码枚举，必须与 SDK 引擎和实际上传编码一致 | 当前 RTCLite `AUDIO_CODEC_TYPE_OPUS=1`，本项目传数字 `1` |
| 输入 | task_id | 此次通话关联号 | D9 params.PlatformTaskID |
| 输入 | agent_config | 本次欢迎语和字幕回调配置 | D9 params.AgentConfig，转换为 body 小写字段 agent_config |
| 输入 | config | 可选的覆盖配置 | 当前老人智能体方案 **省略整个 config 字段**，不要传空 S2SConfig 覆盖后台配置 |
| 输出 | Result.RoomID | RTC 房间 ID | SDK 加入该房间 |
| 输出 | Result.UserID | 本设备在房间内的用户 ID | 原样传 SDK |
| 输出 | Result.Token | RTC 临时凭据 | 原样传 SDK，不当永久设备密钥 |
| 输出 | Result.TaskID | 火山任务 ID | SDK 保存管理本次会话 |
```json
{"InstanceID":"<实例>","product_key":"<产品>","device_name":"<火山设备名>","random_num":123456,"timestamp":1789372800000,"signature":"<签名>","bot_id":"<D9老人bot_id>","audio_codec":1,"task_id":"<D9 PlatformTaskID>","agent_config":{"WelcomeMessage":"你好，今天想聊些什么？","EnableConversationStateCallback":false,"ServerMessageURLForRTS":"<D9回调URL>","ServerMessageSignatureForRTS":"<D9签名原值>"}}
```
上例 audio_codec=1 对应当前工程 RTCLite 的 OPUS 枚举；换 SDK 时需重新核对该层枚举，不能只改编码标志而不改实际音频编码。输出示例：`{"Result":{"RoomID":"<房间>","UserID":"<本机用户>","Token":"<房间token>","TaskID":"<任务>"}}`。
最容易遗漏：`params.AgentConfig` 转为 `agent_config`，`params.PlatformTaskID` 转为 `task_id`。如果换用未包含这些修改的原始 SDK，可能能通话但回调对不上。参考包提供本项目实际修改过的 SDK 对接源文件，不是可以脱离完整 SDK 独立编译的库。
### 8.3 火山签名计算（与平台 DEVREQ1 不同）
```text
canonical = "auth_type=" + decimal(auth_type)
+ "&device_name=" + device_name
+ "&random_num=" + decimal(random_num)
+ "&product_key=" + product_key
+ "&timestamp=" + decimal(timestamp_ms)
signature = STANDARD_BASE64(HMAC_SHA256(UTF8(secret_string), UTF8(canonical)))
```
顺序必须与上面一致（random_num 在 product_key 前），没有末尾换行。注册 auth_type=1、secret_string=product_secret；RTC 配置 auth_type=0、secret_string=火山 device_secret。Base64 保留 `+ / =`，不要使用平台请求的 lowercase hex 或 base64url。实例 ID 在 JSON 中发送，不在此 RTC 签名原文中；不要混用旧 WS 的追加 instance_id 算法。
### 8.4 音频与 SDK 停止
当前实机链路使用 high_quality/RTC；应用侧麦克风/扬声器为 **16 kHz、单声道、16-bit signed little-endian PCM**。20 ms PCM 一帧为 `16000×0.020×1×2 = 640` 字节；当前 RTC 上行在封装内编码 Opus（24 kbps），下行 Opus 解码后播放。不能把 PCM 字节标成 Opus 发送，也不能把 Opus 压缩数据直接送 DAC。
优先用完整工程中的音频/RTC 封装。通话停止时关闭采集和播放，调用 SDK stop/leave room；用真实返回结果设置 sdk_stopped，不能仅设置一个本地布尔值假装 SDK 已停止。
## 9. C1 火山聊天记录回调
这是 **火山→服务器**，不需要嵌入式上传文字、生成字幕签名或连接记忆数据库。设备责任只有把 D9 的回调字段交给火山 SDK。
| 方向 | 字段 | 中文解释与用途 | 示例 |
|---|---|---|---|
| 输入 URL | session_id | 平台本次聊天编号 | D9 session_id |
| 输入 body | message | 火山字幕包的普通 Base64 | `<Base64>` |
| 输入 body | signature | 原样回传本次 ServerMessageSignatureForRTS | `<平台给出的值>` |
| 解码字段 | type | 字幕消息类型 | subtitle |
| 解码字段 | data[].userId | 发言方，input=用户，output 或 RTC bot 用户=助手 | input |
| 解码字段 | data[].roundId / sequence | 轮次/片段序号，用于去重 | 1 / 1 |
| 解码字段 | data[].text | 发言文本 | 今天心情不错 |
| 解码字段 | data[].definite | 是否确定稿，平台只保存确定稿 | true |
| 解码字段 | data[].paragraph | 供应商段落标记 | true |
| 输出 | HTTP 200 + text/plain `ok` | 已处理回调 | `ok` |
```json
{"message":"<以下subtitle JSON的普通Base64>","signature":"<本次ServerMessageSignatureForRTS>"}
```
```json
{"type":"subtitle","data":[{"userId":"input","roundId":1,"sequence":1,"text":"今天心情不错","definite":true,"paragraph":true}]}
```
平台也支持供应商带 subv 帧头的字幕包，嵌入式不需要解析或重编码。文字写入本次会话的 call_utterance，重复回调去重，迟到回调仍归旧会话。**文字保存要求平台已获得该老人 transcript_storage 授权**；仅绑定的默认配置不自动开通记录存储。没有此授权时回调可能返回 403，设备不能据此改走私自上传。首次完整激活还依赖正常挂断和实际助手字幕证据，联调前由平台确认授权与老人智能体就绪。
## 10. 异常处理与验收清单
| 错误/场景 | 嵌入式处理 |
|---|---|
| DEVICE_AUTHENTICATION_FAILED / 401 | 核对工厂编号、32字节密钥解码、签名 LF、正文和校时；不可降级旧签名协议 |
| DEVICE_UNBOUND / 409 | 停止/禁止聊天，提示设备未绑定人员，进入配网绑定入口 |
| DEVICE_BINDING_CHANGED / BINDING_GENERATION_CONFLICT | 停止使用旧参数，同步当前启动/绑定，必要时重新走 D4/D5/D8 |
| DEVICE_NOT_READY | 恢复 D5–D8，不能绕过注册/保存确认 |
| VOICE_AGENT_NOT_READY | 平台修复老人智能体，设备不自行改用公共默认 bot |
| CHAT_ALREADY_ACTIVE | 清理/结束本设备旧会话，不并发制造新 session_id |
| CHAT_ENDED / 总期限或租期到期 | 停音频、停 SDK、D10；再次聊天用新 session_id |
| VOICE_CHAT_CONSENT_REQUIRED / MEMORY_CONSENT_REVOKED | 停止使用旧授权，交给平台/用户处理 |
| RECONCILE_REQUIRED / ATTEMPT_RECONCILIATION_REQUIRED | 保留注册凭据和结果，平台核对，不循环动态注册 |
| 429 / 配额不足 | 提示并退避，不能高速循环重试 |
| BLE received 后无 success | 查询 B3/M3；不能因为 BLE 断开就认定成功 |
| 解绑后再换 Wi-Fi | 空 bind_token + D3 得到 false，转首次绑定流程 |
| 断电重启 | boot_id 更新；恢复未完成绑定、注册结果及结束上报；工厂密钥不擦除 |
验收项目：
1. 小程序能发现 voicelink-ECHOEAR-S3-00260914，B1 型号和编号一致，协议为数字 2；UUID 正确的旧名称、自定义名称也能显示。
2. 离线 BLE 帧、DEVREQ1 测试向量完全一致，包括中文 SSID 的 UTF-8 字节长度。
3. 未绑定时配网令牌非空，设备确认后绑定成功；已绑定只配网发送空令牌，归属不改变。
4. D1 验签和 D4 注册通过；错误密钥/型号/硬件版本被拒绝。
5. 首次火山注册后凭据掉电保留，连续重启不重复注册；未确认结果恢复正确。
6. 连续两次聊天各用不同 session_id；同次每 10 秒续期；音频双向正常。
7. 文字由火山回调入平台，人物/设备/会话对应正确；设备无文字上传队列。
8. 正常挂断、断网、重启都能补报 D10；结束后不继续采集或播放。
9. 小程序解绑后，再 start 返回 DEVICE_UNBOUND，不再用旧 bot_id 直接开聊。
### 本次交付已验证与未验证
已创建并放行库存设备；使用私有初始化密钥在真实线上验证 TIME1 校时 HMAC、D4 注册 HTTP 200、D3 bound=false、D9 返回 HTTP 409 / DEVICE_UNBOUND。测试注册固件标记为 handoff-probe-1，真实硬件下一次 D4 会报告自己的固件版本。未绑定任何老人，未发起火山动态注册，未修改原有 EchoEar。
尚未把新身份烧录到实际硬件；该新设备的 BLE、Wi-Fi、音频及完整火山聊天需要嵌入式实现后按上述清单验收。不要把接口连通测试等同于新硬件整机验收。
## 11. 交付文件和代码依据
| 文件 | 用途 |
|---|---|
| 本文 `.md` / 同内容 `.html` | 可转发给工程师的接口、字段、算法、示例说明 |
| `device-init.private.json` | 只给本设备的烧录信息，含真实设备密钥；受控交接，不提交公共仓库 |
| `embedded-signing-reference.cjs` | 无第三方依赖的 JS 签名和 BLE 帧参考，Node.js 18+ |
| `test-vectors.json` | 离线公开假密钥测试向量，与真实设备密钥无关 |
| `reference/` | 当前固件核心通信源文件快照，辅助 C 实现；不包含完整 BSP/SDK/构建依赖 |
运行参考：`node embedded-signing-reference.cjs` 仅输出离线向量。`node embedded-signing-reference.cjs --probe device-init.private.json` 会对**这台未绑定联调设备**执行线上校时/注册/未绑定验证，不绑定、不注册火山；实物已绑定后不要再执行该 probe，避免创建新 boot_id 干扰实物。
代码依据：平台 `internal/onboarding/{auth,crypto,setup,ble,voice_runtime,device_activation,service}.go`、`internal/callmemory/direct.go`；固件 `main/{ble_cloud,ble_setup,call_client}.c`；小程序 `src/ble/client.js`；火山适配 `volc_device_manager.c`、`volc_auth.c`、`volc_rtc.c`。当前服务端事实优先于历史兼容文档，后续接口变更应同步更新本文版本。
Reference in New Issue Copy Permalink