# ESP32 项圈固件接口与开发指南

本文面向项圈 ESP32 固件和可信设备网关开发，完整说明新项圈开通、设备侧 RPC、
遥测发布、寻宠控制、业务数据流和本地验收流程。字段范围、签名验证和错误定义以
[Zenoh RPC API](./zenoh-rpc-api.md) 为服务端契约；Redis、Router 和服务启动见
[测试指南](./testing.md)。

本仓库没有 ESP32 固件或设备 X.509 证书签发流程。`collar-simulator` 是协议模拟器，
可验证签名、序号、发布授权和寻宠 queryable；它不驱动物理传感器、LED 或蜂鸣器。

## 1. 设备职责与完整业务流程

接入步骤为：**生成设备身份 → 管理端开通 → APP 绑定 → ESP32 授权并上报 → APP
收到数据/发起控制**。

| 组件 | 职责 |
| --- | --- |
| 管理/制造开通工具 | 以全局开通口令调用 `collars/provisionCollar`，登记项圈 ID、配对码哈希和遥测公钥 |
| ESP32 | 调用 GPS/IMU 发布授权 RPC；发布系统信息、GPS 和 IMU；声明用户设置及 `findPet` queryable |
| 管理服务 | 验证开通及用户绑定，向在线 APP 会话分发已授权数据，下发寻宠 query |
| 遥测服务 | 验证 GPS/IMU/系统信息签名和序号，保存最新系统信息，转发 GPS 并处理电子围栏 |
| `behavior-processor` | 订阅内部 IMU 数据，识别行为并发布行为结果；ESP32 不上传行为标签 |

`COLLAR_PROVISIONING_TOKEN` 是管理服务端的共享开通口令。测试脚本中的
`PROVISIONING_TOKEN` 只是客户端变量名，两者都不应写入 ESP32 固件。项圈遥测使用
每台设备自己的 Ed25519 私钥和 `telemetry_key_id`；配对码供 APP 首次绑定。

## 2. Zenoh 调用约定

管理 RPC 使用 Zenoh Query/Reply，不是 HTTP。客户端对精确 key 执行 `get`，请求和
响应均为 UTF-8 JSON。管理 RPC key 形式：

```text
petpal/{tenant}/api/v1/{domain}/{operation}
```

遥测使用 Pub/Sub；控制命令使用设备专属 queryable。`tenant` 必须与服务和 Router 配置
一致。测试环境可按[测试指南](./testing.md)使用回环 TCP；公网或生产环境不得照搬明文
TCP 配置。

设备/网关调用 RPC 时使用 v2 envelope：

```json
{
  "v": 2,
  "reqId": "esp32-1731398400000",
  "deviceId": "collar-esp32-001",
  "ts": 1731398400000,
  "payload": {}
}
```

- `v` 固定为 `2`；`reqId` 使用非空 ASCII 前缀、连字符和 13 位 Unix 毫秒时间戳。
- RPC `ts` 为 Unix 毫秒，与服务端时间相差不得超过 120 秒。
- `deviceId` 为 1–128 个 ASCII 字母、数字或 `-_.:`。发布授权 RPC 要求它等于项圈 ID。
- `payload` 是 JSON object，字段名为 snake_case。RPC 响应共用 `{v,reqId,code,msg,data,ts}`；
  `code=0` 成功，其他值是业务错误码，不是 HTTP 状态码。
- 不要使用通配 selector 或 `All` query target 调用写操作。建议客户端 query 超时设为 10 秒。

## 3. 新项圈凭据注入与开通

### 3.1 每台项圈的凭据

项目业务规则要求 `collar_id` 跨所有 tenant 全局唯一且不可变。制造/资产系统必须为每台
物理项圈分配 UUID 或厂商序列号，并确保 ID 不会在其他 tenant 或未来设备上再次分配；
建议使用标准 UUID，或规范化且永久保留的厂商序列号。当前 ID 字符集为 1–128 个 ASCII
字母、数字及 `-_.:`，大小写按字面区分。APP 等客户端应同时保存 tenant 和 `collar_id`。

服务端 Redis 记录和 Zenoh topic 虽然按 tenant 隔离，但开通 API 不提供全局唯一性校验；
跨 tenant 重用 ID 会形成独立记录，仍违反业务规则。同一 tenant 内重复使用
`collar_id` 会指向同一项圈记录和 topic；再次开通会覆盖原遥测公钥和配对码，同时保留
原用户绑定，使新物理设备可能继承错误的项圈身份和用户关系。不能依靠服务端检测冲突，
开通前必须通过制造/资产发号系统确认 ID 已唯一分配。

每台设备还需稳定的 `telemetry_key_id`、配对码和独立 Ed25519 签名密钥。设备私钥应在
芯片内生成或通过可信制造流程注入，并存于受保护的 NVS/安全硬件；绝不发送给服务端。
配对码只能经受控渠道交给用户。生产环境应避免将明文配对码写入普通日志。
建议制造端为每台项圈用安全随机数生成独立的高强度配对码，并通过包装内的保密码卡交付。
制卡、扫码和发放目前尚未实现；制造开通、用户首次绑定及安全限制的建议流程见
[配对码发放与首次绑定流程](./app-development.md#配对码发放与首次绑定流程)。

本地模拟测试可生成密钥：

```sh
SIM_DIR="$(mktemp -d)"
chmod 700 "$SIM_DIR"
cargo run --locked --bin collar-simulator -- --generate-key "$SIM_DIR/collar.key"
```

模拟器会写入私钥文件并打印对应 64 位十六进制 Ed25519 公钥；该私钥文件只用于模拟器。
真实 ESP32 应使用设备自己的密钥，不能复用测试私钥。

### 3.2 `collars/provisionCollar`

管理服务须通过 CLI、环境变量或 YAML 配置 `COLLAR_PROVISIONING_TOKEN`。服务端未配置时
开通返回 `503`；调用方的 `payload.provisioning_token` 必须与当前服务配置完全相同，
不匹配返回 `403`。服务使用常量时间比较，不会把全局口令写入 Redis。

精确 Query key：

```text
petpal/{tenant}/api/v1/collars/provisionCollar
```

请求 `payload`：

```json
{
  "provisioning_token": "<管理服务配置的共享开通口令>",
  "collar_id": "collar-esp32-001",
  "pairing_code": "<该项圈独立的配对码>",
  "telemetry_key_id": "collar-key-001",
  "telemetry_public_key": "<64位十六进制Ed25519公钥>"
}
```

此 RPC 不需要用户 access token，但 envelope 仍需合法 `deviceId`、有效 `reqId` 和时间。
成功 `data`：

```json
{
  "collarId": "collar-esp32-001",
  "telemetryKeyId": "collar-key-001",
  "provisioned": true
}
```

服务保存配对码的 Argon2 哈希、遥测 key ID 和公钥。配对码为 1–256 字节；公钥须是
32 字节 Ed25519 公钥的 64 位 hex。非法字段/公钥返回 `400`。服务端只校验 ID 格式，
不检查全局是否已分配。`provisionCollar` 对 tenant 内同一 `collar_id` 会写入同一 Redis
记录，覆盖配对码和遥测身份但保留已有用户绑定；对其他 tenant 的同 ID 则另建记录。
因此，开通前必须从全局资产系统确认 ID 唯一且未分配给其他物理项圈，不能把重复开通当作
创建新设备或未协调的密钥轮换。

本地可在已加载 `scripts/test-apis.sh` 的 Bash 会话中运行：

```sh
api_call collars provisionCollar 0 "$DEVICE_ID" "" \
  provisioning_token "$PROVISIONING_TOKEN" \
  collar_id "$COLLAR_ID" pairing_code "$PAIRING_CODE" \
  telemetry_key_id "$KEY_ID" telemetry_public_key "$PUBKEY"
```

ESP32 不应调用或保存这个管理端共享口令。项圈在 `collars/bind` 中也不会发送遥测私钥；
绑定由 APP 登录后使用配对码完成。

## 4. 设备发布授权 RPC

发布前，可信项圈客户端或网关分别执行以下 Query。仓库模拟器会在启动时自动调用两个
接口。

| 操作 | 精确 key | 请求 `payload` |
| --- | --- | --- |
| `collars/authorizeGpsPublisher` | `petpal/{tenant}/api/v1/collars/authorizeGpsPublisher` | `{"collar_id":"collar-esp32-001"}` |
| `collars/authorizeImuPublisher` | `petpal/{tenant}/api/v1/collars/authorizeImuPublisher` | `{"collar_id":"collar-esp32-001"}` |

请求 envelope 的 `deviceId` 必须等于 `collar_id`，不需要用户 token。成功 `data`：

```json
{
  "collarId": "collar-esp32-001",
  "authorized": true
}
```

服务确认项圈已开通、有遥测 key 且至少绑定一个用户。未知项圈返回 `404`；ID 不匹配、
没有用户绑定或缺少遥测身份返回 `403`。这只是发布前检查，不会为之后的每个样本签发
授权凭证，也不替代 Router ACL 和遥测签名验证。生产环境必须由 Router ACL 限定可调用
这两个不带用户 token 的 RPC 的客户端。
这些授权 RPC 不读取或返回用户设置。默认 IMU 批量上传间隔和 GPS 上报间隔均为 1 秒；
用户设置通过 APP 登录响应下发给 APP，并由用户显式操作时发送给设备。

## 5. GPS、IMU、系统信息上行协议

上行 topic 由项圈独占：

```text
petpal/{tenant}/api/v1/collars/reportSystemInfo/{collarId}
petpal/{tenant}/api/v1/collars/reportGps/{collarId}
petpal/{tenant}/api/v1/collars/reportImu/{collarId}
```

每个 topic 发布 v2 signed envelope；`collarId` 从 topic key 确定，不写入原始上行
payload。`seq` 为正整数，对项圈、`keyId` 和数据流严格递增；须持久化，重启不能回退。
采样时间为顶层 `ts`，单位 Unix 毫秒。发布没有逐样本 RPC 应答；本地 put 成功只表示
Zenoh 接受发布。

### 5.1 系统信息

```json
{
  "v": 2,
  "reqId": "sys-1731398400000",
  "ts": 1731398400000,
  "payload": {
    "seq": 1,
    "startupTime": 1731398300000,
    "uptimeSeconds": 100,
    "flashBytes": 4194304,
    "manufacturer": "Example vendor",
    "batteryPercent": 87,
    "firmwareVersion": "1.2.3"
  },
  "auth": { "keyId": "collar-key-001", "signature": "<128位hex签名>" }
}
```

`startupTime` 是不晚于样本 `ts` 的正 Unix 毫秒；`uptimeSeconds` 为非负整数；
`flashBytes` 为正整数；`manufacturer` 为非空、最长 128 字节字符串；`batteryPercent`
为 0–100 的整数百分比；`firmwareVersion` 为非空、最长 64 字节的固件版本字符串。
系统信息只要求项圈已开通并通过签名校验，不要求先绑定用户。服务持久化最新有效样本，APP 可用
`collars/getSystemInfo` 读取。

### 5.2 GPS

```json
{
  "v": 2,
  "reqId": "gps-1731398400000",
  "ts": 1731398400000,
  "payload": {
    "seq": 42,
    "latitude": 39.9,
    "longitude": 116.4,
    "altitude": 42.0,
    "speed": 2.5,
    "heading": 180.0,
    "accuracy": 4.0
  },
  "auth": { "keyId": "collar-key-001", "signature": "<128位hex签名>" }
}
```

纬度 `-90..90`，经度 `-180..180`；海拔和精度单位米，速度单位 m/s，速度与精度不能
为负，航向取 `[0,360)` 度。GPS 通过签名及序号检查后会送往符合在线租约、绑定/分享和
流权限条件的 APP。设置电子围栏后，服务实时判断位置并发布越界告警。

### 5.3 IMU

```json
{
  "v": 2,
  "reqId": "imu-1731398400000",
  "ts": 1731398400000,
  "payload": {
    "seq": 901,
    "frame": "body",
    "accelMps2": { "x": 0.1, "y": 0.0, "z": 9.8 },
    "gyroRadS": { "x": 0.01, "y": 0.02, "z": 0.0 },
    "orientation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 }
  },
  "auth": { "keyId": "collar-key-001", "signature": "<128位hex签名>" }
}
```

`frame` 为 `body` 或 `world`；加速度单位 m/s²，角速度单位 rad/s；可选 orientation
为归一化 quaternion。原始 IMU 不转发给 APP。
模拟器仍按 `--imu-interval-ms` 生成逐帧数据，但默认每 1 秒将多帧放入一个签名信封发送；
APP 可将间隔分别调整为 1–60 秒。服务端验签后按原采样时间和序号逐帧交给行为处理器。
实际 ESP32 可使用上述单帧信封，也可使用[遥测协议中的批量 payload](./zenoh-rpc-api.md#collarsreportgps-主题)
以减少信封开销。

### 5.4 Ed25519 签名与验收约束

签名输入为以下 UTF-8 字节串，`canonicalPayloadJson` 必须逐字节匹配服务端的 JSON
序列化结果：

```text
petpal-telemetry-v1\n{tenant}\n{topicKey}\n{v}\n{reqId}\n{ts}\n{keyId}\n{canonicalPayloadJson}
```

签名是 64 字节 Ed25519 signature 的 128 位十六进制编码。顶层 `auth.keyId` 必须等于
开通时的 `telemetry_key_id`。键顺序、数字格式或空白不一致会导致验签失败。签名必须针对
最终发布的 payload JSON 字节内容生成；浮点数不能在签名之后再舍入或转换格式。服务端
使用精确浮点往返解析，但不会替设备修正不一致的签名输入。每条样本的合法性、最大大小、
序列号和签名错误规则详见[遥测协议](./zenoh-rpc-api.md#collarsreportgps-主题)。

## 6. IMU 行为识别业务

设备只发布 IMU，不把“walking”等设备自行生成的行为字符串当作识别结果发送。
遥测服务验证签名和序号后，将 IMU 转发到：

```text
petpal/{tenant}/internal/collars/{collarId}/imu
```

`behavior-processor` 消费内部样本，以每项圈 100 帧窗口、每次移动 50 帧做启发式识别，
再向上行结果 topic 发布：

```text
petpal/{tenant}/api/v1/collars/reportBehavior/{collarId}
```

行为 processor 会依据加速度和角速度特征生成 `feeding`（进食）、`jumping`（跳跃）、
`playing`（逗猫）、`scratching`（磨爪）、`rolling`（打滚）、`running`（奔跑）、
`licking_fur`（舔毛）、`lying_down`（趴着）、`sleeping`（睡觉）、`standing`（站着）、
`walking`（走路）、`sitting`（坐着）或 `unknown`（未知）。该原型不是经过训练验证的
机器学习模型，所有结果为 `simulated: true`。

APP 订阅自己的行为会话 topic；设备无需发布 `reportBehavior`，也不订阅内部 topic。
处理器停止时，IMU 不缓存补算，行为结果会中断。

## 7. APP 设备控制

### 7.1 用户级设备设置

设备须声明自己的 queryable：

```text
petpal/{tenant}/internal/collars/{collarId}/commands/setCollarSettings
```

设置保存在 `(userId, collarId)` 维度。登录响应会向 APP 一次性返回该用户已绑定项圈的设置，
但登录本身不改变设备。APP 用户显式更改蜂鸣器、LED、IMU 批量上传周期或 GPS 上报周期时，
服务先保存用户设置，再查询在线设备；设备离线或无有效确认时 API 返回 `status="pending"`，
APP 应在设备在线时显式重试。设置默认蜂鸣器/LED 关闭、IMU/GPS 周期均为 1 秒；周期范围
为 1–60 秒。不同用户的设置独立，项圈实际状态取最后一次成功应用的完整配置。

服务命令示例：

```json
{
  "v": 1,
  "command": "setCollarSettings",
  "commandId": "<命令ID>",
  "collarId": "collar-esp32-001",
  "deviceSettingsVersion": 2,
  "buzzerOn": true,
  "ledOn": false,
  "imuBatchIntervalSeconds": 1,
  "gpsIntervalSeconds": 5
}
```

设备应校验 `collarId`、命令版本和间隔范围，只接受不低于本地 `deviceSettingsVersion` 的
命令；成功应用后立即设置输出和上报周期。IMU 当前缓存帧可先按旧间隔封包，再开始新周期。
应答需包含相同的 `commandId`、`collarId`、`deviceSettingsVersion`、蜂鸣器/LED 状态、两个
周期及 `status="applied"`。仅服务能查询该 queryable，APP 不得直接访问内部 key。设备离线时
没有自动重放机制；用户须显式重新应用其保存的设置。

### 7.2 一键寻宠设备接口

设备须声明自己的 queryable：

```text
petpal/{tenant}/internal/collars/{collarId}/commands/findPet
```

APP 调用 `collars/findPet` 后，管理服务向此 key 查询。设备命令：

```json
{
  "v": 1,
  "command": "findPet",
  "commandId": "<命令ID>",
  "collarId": "collar-esp32-001",
  "durationSeconds": 30,
  "restoreBuzzerOn": false,
  "restoreLedOn": false
}
```

设备确认示例：

```json
{
  "v": 1,
  "commandId": "<同一命令ID>",
  "collarId": "collar-esp32-001",
  "status": "started",
  "durationSeconds": 30,
  "startedAt": 1731398400000
}
```

设备必须先实际启动 LED 闪烁和蜂鸣器，再返回 `started`。硬件不能启动时回复
`status="rejected"`；不得伪报成功。时长限制 5–120 秒，APP 未传时默认为 30 秒。
寻宠期间临时覆盖蜂鸣器和 LED，结束后恢复 `restoreBuzzerOn` / `restoreLedOn` 指定的
状态；这两个值来自发起操作用户对该项圈的设置。
服务等待有效确认 5 秒；APP 得到启动后响应才能显示命令成功。该内部 key 必须由
Router ACL 限制为服务查询、对应项圈声明 queryable；APP 不得直接查询。

## 8. 本地设备联调和验收

### 8.1 启动前提

先按[测试指南](./testing.md)启动专用 Redis、Zenoh Router 和统一 `pet_collar_service`。
另启 `behavior-processor` 才能验证行为链路。所有服务必须使用相同测试 tenant 和
Router endpoint；不要在生产或共享 Redis/Router 上执行。仓库模拟器只接受 `tcp/`
endpoint，仅用于回环隔离测试。

### 8.2 开通并绑定模拟项圈

在 Bash 会话加载 API 测试脚本、登录测试用户并生成私钥：

```sh
export ZENOH_ENDPOINT='tcp/127.0.0.1:17447'
export TENANT='demo'
export Z_GET="$HOME/src/zenoh-1.10.2/target/release/examples/z_get"
source ./scripts/test-apis.sh
PHONE='<已注册的测试手机号>'
PASSWORD='<测试账号密码>'
api_login_password

SIM_DIR="$(mktemp -d)"
chmod 700 "$SIM_DIR"
cargo run --locked --bin collar-simulator -- --generate-key "$SIM_DIR/collar.key"
COLLAR_ID="esp32-test-$(python3 -c 'import uuid; print(uuid.uuid4())')"
PAIRING_CODE="test-pair-$(date +%s)-123456"
KEY_ID="key-${COLLAR_ID}"
PUBKEY='<上一步输出的公钥>'
```

复制服务端 `COLLAR_PROVISIONING_TOKEN` 为测试终端的 `PROVISIONING_TOKEN` 后开通并绑定：

```sh
PROVISIONING_TOKEN='<与服务端相同的隔离测试口令>'
api_call collars provisionCollar 0 "$DEVICE_ID" "" \
  provisioning_token "$PROVISIONING_TOKEN" collar_id "$COLLAR_ID" \
  pairing_code "$PAIRING_CODE" telemetry_key_id "$KEY_ID" \
  telemetry_public_key "$PUBKEY"
api_call collars bind 0 "$DEVICE_ID" "$ACCESS_TOKEN" \
  collar_id "$COLLAR_ID" pairing_code "$PAIRING_CODE"
```

### 8.3 运行模拟器并逐项检查

在新终端重新设置 `ZENOH_ENDPOINT`、`TENANT`，并填入前一步生成的 `SIM_DIR`、
`COLLAR_ID`、`KEY_ID`：

```sh
export ZENOH_ENDPOINT='tcp/127.0.0.1:17447'
export TENANT='demo'
SIM_DIR='<私有模拟器目录>'
COLLAR_ID='<本次项圈 ID>'
KEY_ID='<本次遥测 key ID>'
cargo run --locked --bin collar-simulator -- \
  --endpoint "$ZENOH_ENDPOINT" --tenant "$TENANT" \
  --collar-id "$COLLAR_ID" --key-id "$KEY_ID" \
  --key-file "$SIM_DIR/collar.key" --sequence-file "$SIM_DIR/collar.seq" \
  --interval-ms 1000 --imu-interval-ms 20 \
  --manufacturer 'Test manufacturer' --flash-bytes 4194304
```

模拟器会自动调用 GPS/IMU 授权 RPC，声明寻宠 queryable，并发布系统信息、固定坐标
`(39.9,116.4)` 的 GPS 及随机行为 IMU。成功运行应看到授权通过和 topic 发布日志。
再在 APP 测试终端执行：

```sh
api_call collars getSystemInfo 0 "$DEVICE_ID" "$ACCESS_TOKEN" collar_id "$COLLAR_ID"
api_call collars authorizeGpsPublisher 0 "$COLLAR_ID" "" collar_id "$COLLAR_ID"
api_call collars authorizeImuPublisher 0 "$COLLAR_ID" "" collar_id "$COLLAR_ID"
```

逐项验收：

| 项目 | 成功检查 | 失败/边界检查 |
| --- | --- | --- |
| 开通 RPC | `provisioned=true`，登记的 key ID 与公钥匹配 | 错口令 `403`、缺服务端口令 `503`、非法字段/公钥 `400` |
| 发布授权 RPC | 两项均 `authorized=true` | 未知项圈 `404`；无绑定或 `deviceId` 不匹配 `403` |
| 系统信息 | `getSystemInfo` 返回最新 `reportedAt` 和 payload | 上报前 `404`；坏签名/旧序号不覆盖已存值 |
| GPS topic | 有效 GPS 分发到在线且获授权 APP；围栏更新后可触发告警 | 坏签名、错误 key ID、非法位置或旧序号不作为有效位置 |
| IMU topic | 有效样本进入 processor 并形成行为结果 | 坏签名/旧序号不产生新行为 |
| 行为输出 | processor 发布英文标签，APP 获授 IMU stream 后收到结果 | processor 停止或 APP 离线/无权限时不收到 |
| `findPet` queryable | APP `findPet` 得到匹配的 `commandId` 和 `started` ACK | 设备拒绝/无效 ACK 为 `502`，设备离线或超时为 `504` |

模拟器 GPS 固定在 `(39.9,116.4)`。围栏要测越界时，APP 可把默认圆心更新到 `(0,0)`；
下一条有效 GPS 应触发一次 `outside_geofence`。越界期间不重复告警，回到边界内后重新
布防。发布日志只表示本地提交，不代表服务端已验收或 APP 已收到。

序号文件必须对每个项圈私有且只允许一个模拟器持有。同一密钥重启时复用原序号文件；
丢失或回滚会触发重放保护。重复开通同一生产项圈会改变其配对码和遥测公钥，不应用于
普通联调。

## 9. ESP32 上线检查

- 每台设备使用唯一项圈 ID、遥测 key ID、配对码和 Ed25519 私钥；全局开通口令不进入固件。
- 持久化每个遥测流的序号；RTC/网络授时提供可信毫秒时间，签名采用与服务端一致的 JSON 字节。
- 先用模拟器通过签名、序号、topic ACL 和寻宠 ACK 验收，再联调真实传感器及 LED/蜂鸣器。
- 管理服务当前没有 ESP32 X.509 证书签发流程；生产 mTLS 需另建设备证书发放、轮换流程，
  或让受控网关代理设备访问并配置精确 Router ACL。

## 10. 设备接口输入/输出字段中文说明

本节逐项解释本指南涉及的设备 RPC、遥测 topic 和设备控制命令字段。RPC 使用第 2 节的
信封；topic 使用 signed envelope，发布后没有逐样本业务响应。以下时间戳均为 Unix 毫秒，
另有说明时除外。
`scripts/test-apis.sh` 只测试管理 RPC，不会发布设备遥测或验证设备控制确认；开通 RPC
字段可与下方对照，完整设备上报和命令字段以本节为准。

### 10.1 设备 RPC 信封

| 字段 | 方向 | 中文解释 |
| --- | --- | --- |
| `v` | 请求/响应 | 协议信封版本，固定为 `2` |
| `reqId` | 请求/响应 | 请求关联 ID；响应必须回显请求 ID |
| `deviceId` | 请求 | 调用设备或项圈 ID；发布授权接口要求等于 `collar_id` |
| `ts` | 请求 | 请求生成时间；RPC 请求与服务端时钟相差不得超过 120 秒 |
| `payload` | 请求/响应 | 操作的业务参数或结果对象 |
| `code` | 响应 | 业务结果码，`0` 表示成功 |
| `msg` | 响应 | 服务端结果说明 |
| `data` | 响应 | 成功结果；失败时通常为 `null` |

设备发布授权 RPC 不需要用户 `token`。管理端 `provisionCollar` 虽在设备指南说明，但
应由受信任的制造/管理工具调用，ESP32 不得持有全局开通口令。

### 10.2 项圈开通 RPC

`collars/provisionCollar` 请求 `payload` 字段：

| 字段 | 中文解释 |
| --- | --- |
| `provisioning_token` | 管理服务配置的共享开通口令；仅管理工具使用，不写入固件 |
| `collar_id` | 全局唯一且不可变的项圈 ID |
| `pairing_code` | 交给用户用于 APP 绑定的该项圈独立配对码 |
| `telemetry_key_id` | 该项圈遥测签名公钥的标识 |
| `telemetry_public_key` | 32 字节 Ed25519 公钥的 64 位十六进制编码；不包含私钥 |

成功响应 `data` 字段：`collarId` 为项圈 ID，`telemetryKeyId` 为登记的遥测公钥标识，
`provisioned` 表示开通是否成功。

### 10.3 遥测发布授权 RPC

`authorizeGpsPublisher` 和 `authorizeImuPublisher` 使用相同字段：

| 字段 | 方向 | 中文解释 |
| --- | --- | --- |
| `payload.collar_id` | 请求 | 要发布遥测的项圈 ID |
| `deviceId` | 请求信封 | 必须与 `collar_id` 相同 |
| `data.collarId` | 响应 | 获准发布的项圈 ID |
| `data.authorized` | 响应 | 是否通过发布前授权检查；`true` 不替代逐条签名验证或 Router ACL |

### 10.4 遥测 signed envelope 与系统信息

遥测 envelope 的 `v` 是协议版本 `2`，`reqId` 是样本关联 ID，`ts` 是采样 Unix 毫秒时间，
`payload` 是数据内容。`auth.keyId` 是开通时登记的遥测公钥 ID；`auth.signature` 是使用
对应 Ed25519 私钥生成的 64 字节签名，以 128 位十六进制字符串表示。项圈 ID 来自 topic
末段，不需要重复放入 `payload`。遥测发布没有 RPC `data` 响应。

`reportSystemInfo` 的 `payload` 字段：

| 字段 | 中文解释 |
| --- | --- |
| `seq` | 系统信息流的正整数序号；同一项圈不得回退或重复 |
| `startupTime` | 本次启动时间，正 Unix 毫秒，不能晚于 envelope 的 `ts` |
| `uptimeSeconds` | 自本次启动以来运行的秒数，非负整数 |
| `flashBytes` | Flash 容量，正整数，单位字节 |
| `manufacturer` | 制造商名称，非空字符串，最长 128 字节 |
| `batteryPercent` | 电池剩余电量百分比，整数范围 0–100 |
| `firmwareVersion` | 固件版本字符串，非空，最长 64 字节 |

### 10.5 GPS 与 IMU 遥测字段

`reportGps` 的 `payload`：

| 字段 | 中文解释 |
| --- | --- |
| `seq` | GPS 流正整数序号，持续递增 |
| `latitude` / `longitude` | 纬度（-90 至 90 度）/ 经度（-180 至 180 度） |
| `altitude` | 海拔，单位米 |
| `speed` | 可选速度，单位米/秒，不得为负 |
| `heading` | 可选航向角，单位度，范围 `[0, 360)` |
| `accuracy` | 可选定位精度，单位米，不得为负 |

`reportImu` 单帧 `payload`：

| 字段 | 中文解释 |
| --- | --- |
| `seq` | IMU 流正整数序号，持续递增 |
| `frame` | 坐标参考系，`body` 表示设备机身坐标，`world` 表示世界坐标 |
| `accelMps2` | 加速度向量，单位 m/s²；子字段 `x`、`y`、`z` 分别为三轴分量 |
| `gyroRadS` | 角速度向量，单位 rad/s；子字段 `x`、`y`、`z` 分别为三轴分量 |
| `orientation` | 可选归一化四元数；子字段 `x`、`y`、`z`、`w` 为四元数分量 |

批量 IMU `payload.samples` 是按时间递增的帧数组；每个元素的 `ts` 是该帧采样 Unix 毫秒
时间，`imu` 是上述单帧结构。外层信封签名覆盖整个批次。

行为结果由 `behavior-processor` 生成，不由 ESP32 上报；结果 payload 的 `collarId` 为项圈
ID，`seq` 为行为结果序号，`behavior` 为识别标签，`simulated` 表示结果是否为模拟值。

### 10.6 `setCollarSettings` 设备命令与确认

请求字段：

| 字段 | 中文解释 |
| --- | --- |
| `v` | 控制命令协议版本，固定为 `1` |
| `command` | 命令名称，固定为 `setCollarSettings` |
| `commandId` | 唯一命令 ID；设备应在确认中原样返回 |
| `collarId` | 命令目标项圈 ID |
| `deviceSettingsVersion` | 设备设置单调递增版本；设备拒绝比本地版本旧的命令 |
| `buzzerOn` / `ledOn` | 蜂鸣器 / LED 输出开关 |
| `imuBatchIntervalSeconds` | IMU 批量上报周期，单位秒，范围 1–60 |
| `gpsIntervalSeconds` | GPS 上报周期，单位秒，范围 1–60 |

确认响应应回显 `commandId`、`collarId`、`deviceSettingsVersion` 和完整设置；`status` 为
`applied` 表示已应用，`stale` 表示版本旧而未应用，`rejected` 表示设备不能应用。
确认响应字段：

| 字段 | 中文解释 |
| --- | --- |
| `v` | 命令协议版本，固定为 `1` |
| `commandId` | 对应请求的命令 ID |
| `collarId` | 应用设置的项圈 ID |
| `status` | 应用结果：`applied`、`stale` 或 `rejected` |
| `deviceSettingsVersion` | 设备确认的当前设置版本 |
| `buzzerOn` / `ledOn` | 确认后的蜂鸣器 / LED 状态 |
| `imuBatchIntervalSeconds` / `gpsIntervalSeconds` | 确认后的 IMU / GPS 上报周期，单位秒 |
| `simulated` | 可选的模拟器标记；真实固件不要求返回 |

### 10.7 `findPet` 设备命令与确认

请求字段：`v` 为命令协议版本 `1`；`command` 固定为 `findPet`；`commandId` 为命令关联 ID；
`collarId` 为目标项圈 ID；`durationSeconds` 为寻宠持续秒数（5–120）；`restoreBuzzerOn` 和
`restoreLedOn` 分别指定寻宠结束后恢复的蜂鸣器、LED 状态。

确认响应字段：`v` 为版本 `1`；`commandId` 和 `collarId` 必须与请求一致；`status` 为
`started` 或 `rejected`；`durationSeconds` 为确认的持续时间；`startedAt` 为设备确认实际
启动时间；模拟器可额外返回 `simulated=true`，真实固件不要求该字段。设备只能在实际启动
蜂鸣器/LED 后返回 `started`，并须在寻宠结束时恢复请求指定的输出状态。
