xvf_host 命令是怎么解析的： 从命令行参数到 I²C 字节流
为什么 xvf_host LED_COLOR 0xff8800 能直接控制设备，而自己写 I²C 裸机驱动却读回乱码？答案在于三件事：命令名的查表机制、参数的类型化打包、以及读写靠的是同一个字节的不同 bit。
一句话结论：命令名并不写死在程序里——它由固件编译期生成的 command_map 动态库解析成「ResID + CmdID + 参数类型表」；参数按类型定长、依序、小端打包进 payload；读命令则把 CmdID 最高位置 1，响应首字节回状态码。命令号与固件版本强绑定，这是所有「命令失效」问题的根源。
一、先看一条命令由哪几段组成
官方的语法格式是 xvf_host [command | option]…，即选项与命令可以交错出现。一条典型命令拆开来看：
$ xvf_host --use i2c LED_COLOR 0xff8800
# └─ 选项 ─┘ └ 命令名 ┘ └ 参数1 ┘
三个部分承担的职责完全不同：选项决定通信怎么走（传输层、日志、脚本），命令名决定要操作哪个服务者的哪个能力，参数才是真正要写进设备的数值。常用的选项有四个：
--use i2c | spi | usb：选择传输层，默认 USB。选错的表现是「找不到设备」而不是「命令错」。--list-commands：列出当前 command_map 支持的全部命令名——这是判断版本是否匹配最快的方法。--dump-params：把所有可读参数一次性导出，做现场排查或产线校验时非常有用。--execute-command-list 文件.txt：批量执行一组命令，用于开机自检或出厂配置。
二、解析链路：七个步骤
［图 1 从命令行到设备执行的七步链路：选项解析 → 查表 → 参数解析 → 组帧 → 收发 → 状态判定］
其中第 ② 步最容易忽略，也最关键：程序并不会把 LED_COLOR 当字符串发给设备。设备只认数字，所以主机侧必须先查表，把命令名翻译成 ResID、CmdID 和参数类型，然后按类型去解析后面跟的几个参数。
三、command_map：命令名与数字的翻译表
这个库（Linux 下是 libcommand_map.so，Windows 下是 command_map.dll）不是独立发布的，而是跟着固件源码一起编译出来的。每个条目大致包含四类信息：
命令名：人可读的标识符，如 LED_COLOR、PP_AGCGAIN、VERSION；
ResID + CmdID：真实发到总线上的两个字节，CmdID 由编译期自动生成；
参数类型序列：有几个参数、分别是什么类型（决定后面怎么解析与打包）；
读写属性：只读（ro）、只写（wo）还是可读写（rw）。
因为 CmdID 是自动生成的，换一版固件、命令号就可能整体后移。用旧版 command_map 去控制新固件，表现往往不是「报错」，而是「命令发了但没反应」或「读到别的参数值」——这类幽灵问题九成源于版本不匹配。判断方法很简单：跑一次 --list-commands，与固件发布包里的命令附录对照，名字缺失或多余就是不匹配。
四、参数怎么变成字节
解析完类型后，主机按「定长 + 依序 + 小端」把参数铺进 payload，没有分隔符、没有字段名，全靠类型表约定。所以同一条命令的参数顺序一旦搞反，设备收到的就是一个数值合法、语义错误的命令——这种错误最难查。
| 类型 | 命令行写法 | 实际字节 | 典型命令 |
|---|---|---|---|
| uint8_t | 255 或 0xff | 1 字节 | LED_EFFECT、LED_BRIGHTNESS |
| uint32_t | 0xff8800 | 4 字节，小端（00 88 FF 00） | LED_COLOR、LED_DOA_COLOR |
| float | 3.0 | 4 字节 IEEE754 | PP_AGCGAIN 一类增益参数 |
| 多参数 | 0x001100 0x00ff00 | 4 + 4 字节，顺序不可换 | LED_DOA_COLOR（底色 + 指向色） |
［图 2 三种帧型：写事务、读请求（CmdID 置 0x80）、读响应（首字节为状态码）］
还有一个硬限制：单次事务不能超过 60 字节。这意味着批量写 LED 序列、上传长字符串时必须切片，切片的边界要落在命令允许的粒度上，不能把一条命令的 payload 掰成两半发。
五、读命令：同一条命令，靠一个 bit 翻转方向
读写共用一个 CmdID，区别只在最高位：CmdID | 0x80 表示「我要读」。读请求只有三个字节（ResID、CmdID|0x80、期望长度），设备回的第一字节不是数据而是状态码：
0x00：成功，后面紧跟数据；
0x40：设备忙，需要稍后重试——这是最容易被忽略的一种「正常响应」；
其它值：命令非法、参数越界或该配置下不支持。
［图 3 读事务时序：状态码 0x40 表示忙，需退避重试而不是直接判失败］
所以自己写裸机 I²C 驱动时，正确做法是：读 Len+1 个字节，首字节取状态，判断 0x00 后再取数据；遇 0x40 循环重试并设超时。直接把返回值当数据用，就会出现「版本号是乱码」「DOA 角度漂移」这类玄学现象。
六、几个高频命令的参数速查
| 命令 | 属性 | 参数含义 |
|---|---|---|
| VERSION | 只读 | 无参数，返回 3 字节主/次/修订号，输出形如「3 2 1」 |
| LED_EFFECT | 读写 | uint8：0 关 / 1 呼吸 / 2 彩虹 / 3 单色 / 4 DoA 指示 |
| LED_COLOR | 读写 | uint32：0xRRGGBB，用于呼吸与单色模式 |
| GPO_WRITE_VALUE | 只写 | 两个 uint8：引脚号 + 电平，引脚号对应硬件定义 |
| SAVE_CONFIGURATION | 只写 | 任意值即触发，把当前可写参数存进 Flash；重启后仍生效 |
七、排错清单
| 现象 | 最可能的原因 | 处理 |
|---|---|---|
| 命令名不被识别 | command_map 与固件版本不一致 | 用固件发布包里的 map 重新编译或替换 |
| 命令执行了但参数没变 | 命令号错位，写到了别的参数上 | 核对版本；用 --dump-params 对比前后值 |
| I²C 扫到 0x2C 但读回乱码 | 漏读状态字节，或上拉接到别的电压域 | 读 Len+1 字节并跳过首字节；检查上拉电源 |
| 偶发失败、重跑就好 | 未处理 0x40 忙状态 | 加退避重试与超时 |
| 这台机器能用、那台不行 | 权限不足或同时接了多台 XVF 设备 | 提权运行；一台主机只接一台设备 |
八、结论
一条 host 命令的解析可以概括为三步翻译：人话 → 数字（查 command_map）→ 字节（按类型打包）；读操作再把数字的最高位翻一翻，用状态码确认对方是否真的执行了。
真正需要记住的不是命令表长什么样，而是两个约束：command_map 必须与固件同版本，状态码 0x40 必须重试。把这两点固化进工具链和驱动里，绝大多数「控制不生效」的问题都不会发生。
一句话记法：命令名是给人看的，设备只认 ResID/CmdID；参数是约定好的排队，不许多也不许插队。