Aivle Robotics文档库
视觉结果UART协议
本章针对vision-demos默认输出的Gizmo VISION_RESULT v1。它是传感结果协议，不是NodeHexa动作协议。默认115200、8N1，GPIO1 TX、GPIO2 RX；当前主要主动发送，RX不提供通用参数下发接口。
帧头与CRC
固定35字节，所有多字节字段小端：
| 偏移 | 长度 | 内容 |
|---|---|---|
| 0 | 2 | A5 47 |
| 2 | 1 | 版本01 |
| 3 | 1 | 消息类型60（十六进制） |
| 4 | 1 | header flags，当前00 |
| 5 | 2 | sequence，uint16 |
| 7 | 2 | payload长度24，即18 00 |
| 9 | 24 | 结果载荷 |
| 33 | 2 | CRC16，小端 |
CRC多项式0x1021、初值0xFFFF、不反射、不最终异或，覆盖偏移2–32共31字节。不要把偏移0的帧头也纳入CRC。
24字节载荷
下面偏移相对payload开始位置，帧绝对偏移再加9：
| 偏移 | 类型 | 字段 | 当前含义 |
|---|---|---|---|
| 0 | uint8 | source_id | 来源编号，默认1，可配置 |
| 1 | uint8 | result_type | 见后表 |
| 2 | uint16 | result_sequence | 与头部sequence相同 |
| 4 | uint32 | timestamp_ms | 当前实现为识别结束后读取的启动毫秒 |
| 8 | uint8 | confidence | 0–100，语义按算法 |
| 9 | uint8 | flags | detected为05，未检测为06 |
| 10 | uint16 | age_ms | 当前填latency_ms，最大65535；不是完整采集到接收年龄 |
| 12 | int16 | x | 按任务解释 |
| 14 | int16 | y | 按任务解释 |
| 16 | int16 | w | 按任务解释 |
| 18 | int16 | h | 按任务解释 |
| 20 | int16 | id | 类别或内容散列 |
| 22 | int16 | aux | 附加结果 |
flags bit0为tracked，bit1为lost，bit2为相对坐标标记。统计任务沿用这个标记，但x/y实际是统计值，所以必须先按result_type/id解释字段。 接收端还应记录自己的接收时间并设置失效期限，不能仅靠age_ms判断结果是否新鲜。
result_type和id
| result_type | id | 任务 |
|---|---|---|
| 0 | — | None |
| 1 | 1红、2黄、3绿、4蓝、5紫 | 色块 |
| 2 | 当前默认0 | 巡线 |
| 3 | — | Tag预留，当前未实现AprilTag |
| 4 | 16位散列 | 二维码 |
| 5 | 1 / 2 / 3 | 运动 / 亮点 / 亮度统计 |
| 5 | 10 / 11 / 12 / 13 / 14 | 人脸 / 行人 / 猫 / 狗 / 手部 |
框类中心x/y在−1000..1000，尺寸w/h按图像比例映射到0..2000。中心标度约为pixel*2000/(extent-1)-1000，尺寸约为size*2000/extent。图像左上为负，右下为正。结果基于已校正方向的画面。
巡线：x为加权横向偏差，y固定500，w为底部带暗点覆盖率标度，h=aux为斜率缩放；不是框的高，也不是精确航向角。亮度统计：x均值、y方差；不是位置。二维码id不能用作无碰撞唯一键。
接收端建议流程
- 搜索A5 47，收集完整头部并检查版本/类型/长度。
- 收满载荷和CRC，校验后才更新结果；错误帧丢弃并重新同步。
- 依据source/type/id选择解释器，检查tracked/lost。
- 记录接收时刻；只保留最新有效结果，处理序号回绕与设备复位。
- 目标丢失、结果过期或链路异常时让上层策略进入停止/等待，不沿用旧目标位置。
不要直接memcpy到未定义布局的C结构体，编译器填充和大小端可能不同。按字段解码，或使用带明确小端格式的工具。
校验一帧
源码tools/decode_vision_result.py接受一整帧十六进制文本：
下面是人工构造并经解析器校验的协议示例（不是实机抓包）：source=1、色块、序号42、时间1000 ms、置信度87、已检测、x=−125、y=54、w=410、h=360、红色id=1、处理耗时12 ms。
python tools/decode_vision_result.py "A5 47 01 60 00 2A 00 18 00 01 01 2A 00 E8 03 00 00 57 05 0C 00 83 FF 36 00 9A 01 68 01 01 00 00 00 9C D9"
预期输出tracked=true、lost=false、id=1。工具会检查长度、帧头、版本和CRC，并输出JSON；不是实时串口监听程序。实际调试时把示例替换为抓到的完整35字节帧。默认USB日志不输出逐帧结果，启用Debug日志后可观察；二维码原文通过Info日志输出。