「一语控物」的设备端和 App 端之间,跑着一门自己定义的协议:DAP v1 (Device Agent Protocol)。定它的时候给自己划了一条线:只有六个动词。 这篇记录这门协议的几个关键取舍——为什么是六个动词、为什么角度是相对增量、 为什么小车没有行驶时长参数,以及同一套校验规则为什么要在两端各写一份。
01为什么不是 MQTT,不是通用 RPC
市面上现成的方案很多:MQTT、Home Assistant 的生态、或者干脆定义一套通用 RPC。 都没选,原因是场景太窄:小程序 → 单台局域网设备 → 少数几个动作。 通用协议的灵活性在这个场景里全部是负担——broker 要部署、主题语义要约定、 QoS 要理解。而自定协议可以做到:6 个动作覆盖全部演示场景、 设备注册时自报能力(无硬编码型号)、参数范围写在能力描述里两端同规则校验。
传输绑定选了最朴素的一种:NDJSON over TCP—— 每条 JSON 后跟一个换行符,UTF-8 编码,单帧上限 8 KiB。 它天然处理 TCP 的粘包/拆包(按行切就是了),人肉 telnet 也能调试, 几乎不需要文档以外的解释。
{"v":1, "id":"cmd_20260912_000123", "type":"motion.rotate",
"params":{"axis":"yaw","deg":-45,"speed":30}, "expire_at":1760300000}
{"v":1, "id":"cmd_20260912_000123", "type":"ack", "code":0, "msg":"ok",
"state":{"yaw":-45,"pitch":0,"bat_v":3.92}}
02角度是相对增量,不是绝对角
这是整门协议里最值得抄走的一个设计。motion.rotate 的
deg 是相对增量:设备收到后执行
目标角 = clamp(当前角 + deg, -180, 180)。
为什么不做绝对角?三个理由叠加:
- 多轮对话自然表达:「再往左一点」就是
deg = -15, 不需要客户端先查设备当前角再算差值; - 失败不累积误差:如果上一条指令执行失败或有机械偏差, 用绝对角累积出的目标角就是错的;相对增量每次都从真实当前角出发;
- 越界钳制而非拒绝:当前 170° 再 +45°,钳到 180°,
回执仍是
code=0,state.yaw=180告诉客户端实际停在哪。 把「到限位」当正常结果而不是错误,UI 和用户都不需要特殊处理。
回执的 state 里返回执行后的绝对角——
客户端拿它更新 UI,它同时是下一轮相对计算的基准。
03没有时长参数的小车
后加的 motion.drive(驾驶小车)暴露了另一个设计决策:
它只有方向和速度,没有「行驶 N 毫秒」的参数。
这个动作表达的是「以某速度向某方向行驶」这个持续状态,
而不是一段定时动作——真机电机的控制和 ROS 的 cmd_vel 都是这个模型,
加了时长反而表达不了「边前进边微调方向」。但持续状态意味着开环风险:
断连了、小程序崩了,小车岂不是一直开?
答案是设备侧看门狗,写进协议规范作为强制规则:
带行驶能力的设备,自最后一次收到任何指令起 5 秒内没有新指令,
必须自动停车并在状态里上报归零。它不产生错误码——看门狗触发是正常停车。
小程序侧则在断连前补发 stop。安全兜底放在离执行器最近的那一端,
因为那是唯一保证还活着的端。
04同一套校验,两端各写一份
协议规范 §8 列了一张校验规则表:版本、帧大小、动作存在、必填参数、参数类型、 数值范围、枚举、时效、绑定、限流——按序执行,首个失败即返回。 关键决定是:这份规则在小程序端(TypeScript)和 ESP32 端(Arduino C++) 各实现一份,语义必须完全一致。
| 规则 | 违反时 code |
|---|---|
| 版本 v === 1 | 1004 |
| 帧大小 ≤ 8 KiB | 1002 |
| 动作在 capabilities 内 | 1001 |
| 必填参数存在 / 类型正确 / 范围合法 | 2002 / 2003 / 2001 |
| 指令未过期(expire_at) | 3003 |
| 设备 READY / 限流 ≤ 60 条/分钟 | 3001 / 3004 |
错误码本身分了段:1xxx 协议层、2xxx 参数层、
3xxx 安全与状态层、4xxx 设备运行时、5xxx 内部错误。
分段的意义在调试现场:看到 2xxx 就知道是解析层生成参数出了问题,
看到 4xxx 就知道该去看设备状态。
「双闸」是这个体系的安全结构:解析层在生成指令前先按能力表约束一次, 设备端收到后再按同一套规则校验一次。客户端被破解、解析层有 bug, 都到不了执行器——参数范围最终由设备自己说了算。
05演进策略:先定什么时候升版本
v1 冻结时同时冻结了演进规则,三条:
- 新增可选字段:不升版本,接收方忽略未知字段;
- 新增动作:不升版本,靠
capabilities协商—— 老端不认识就不下发,万一收到回1001; - 变更字段语义、删字段、改必填性:升版本
v=2,保留 v1 兼容分支至少一个版本周期。
第一条路径很快被实战验证了一次:2026-10-15 新增 motion.drive,
是第一个走「新增动作不升版本」的动作。老固件的云台不上报这个能力就收不到
相关指令——能力协商让协议可以在不破坏任何存量设备的前提下长出新动词。
这大概就是「自描述」两个字真正兑现的时刻。
- 关于本文
- 整理自 DAP v1 协议规范(docs/02,v1.0 冻结于 2026-09-12)及 motion.drive 增量的实施记录。协议一致性由 tests/fixtures/commands.json 的测试向量保证。
- 2026.10.23 整理
- 写完才发现,这篇里每个设计都指向同一件事:把不确定性往确定的方向压—— 角度用相对增量压掉累积误差,越界用钳制压掉异常分支, 安全用设备侧看门狗压掉断连风险,演进用能力协商压掉版本碎片化。
留言
正在载入留言…