「一语控物」的设备端和 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 === 11004
帧大小 ≤ 8 KiB1002
动作在 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 整理
写完才发现,这篇里每个设计都指向同一件事:把不确定性往确定的方向压—— 角度用相对增量压掉累积误差,越界用钳制压掉异常分支, 安全用设备侧看门狗压掉断连风险,演进用能力协商压掉版本碎片化。