在 asusctl 项目中，rog-anime库负责把图片、GIF 等素材转换成 AniMe Matrix 灯板可以识别的 USB HID 数据包。本文带你剖析这套 Rust 实现的编码流程：从 640 字节 HID 包结构、LED 亮度数据的分片策略，到对角线布局的字节排序，帮助你快速理解 ROG 灯板在 Linux 下的底层驱动原理。

1. 整体架构：从一张 PNG 到 USB 字节流

rog-anime是整个 asusctl 工作区里专门处理 AniMe Matrix 的 crate，模块划分在 rog-anime/src/lib.rs 中一目了然：

数据流向可以概括为三步：

1. 素材 → LED 缓冲：AnimeImage或AnimeDiagonal把图像采样成 8 位灰度值（每个 LED 只有亮度，没有颜色）；
2. LED 缓冲 → USB 包：通过TryFrom<AnimeDataBuffer>把一维亮度数组切分成 2~3 个 640 字节的 HID 包；
3. USB 包 → 设备：由asusd守护进程通过/dev/hidrawN直接写入硬件。

这种设计让rog-anime既能独立直写 USB，也能经由 D-Bus 交给守护进程，两种用法见 rog-anime/README.md。

2. 640 字节 HID 包：头部结构与关键常量

所有通信都建立在两个硬件常量上，定义在 rog-anime/src/usb.rs：

• VENDOR_ID = 0x0b05（华硕），PROD_ID = 0x193b（AniMe Matrix 设备）；
• 每个包固定PACKET_SIZE = 640字节，页面号DEV_PAGE = 0x5e。

显示画面时，数据包的头部固定为 7 个字节：

[0x5e, 0xc0, 0x02, START_LO, START_HI, LEN_LO, LEN_HI]

其中START和LEN是 little-endian 的u16，描述这个包写入的 LED 索引区间（线上从 1 开始编号）。第 7 字节之后到第 634 字节是 LED 亮度数据，其余全部补零。这些边界在 rog-anime/src/data.rs 中以BLOCK_START = 7、BLOCK_END = 634表示，每个包的可用载荷PANE_LEN = 627字节。

不同机型需要不同数量的"分片包"，每种机型的前 7 字节头部被预定义成常量：

usb_prefixes_for()函数（data.rs#L66-L81）按机型返回对应的头部序列：STRIX 系列（810 颗 LED）切成 490 + 320 两片，其余机型每片 627 字节。分片策略参考了 Windows 端 G Helper 的逆向结果，注释中保留了来源说明。

3. 初始化与刷新：握手的三个控制包

写画面之前，设备需要先完成初始化。流程在 usb.rs 的模块文档中写明，共三步：

1. 初始化：pkts_for_init()（usb.rs#L271-L285）返回两个 640 字节包——第一个包携带页面号0x5e和"ASUS Tech.Inc."字符串，第二个是0x5e, 0xc2命令。此步只需在系统刚开机时执行一次；
2. 写画面：连续写入第 2 节所述的 2~3 个数据包；
3. 刷新：pkt_flush()生成0x5e, 0xc0, 0x03命令，通知设备把刚写入的亮度数据真正显示出来。

值得注意的是这些函数都用const fn实现——包头字节在编译期就固定下来了，零运行时开销，这是 Rust 处理协议编解码的一个典型优势。

4. 亮度、开关与内置动画控制包

除了画面数据，usb.rs还封装了四类"配置型"控制包，全部遵循页面号 + 命令字 + 参数的结构：

• 亮度：pkt_set_brightness()写0x5e, 0xc0, 0x04, 级别，级别取值 0~3（Off/Low/Med/High），对应Brightness枚举；
• 显示开关：pkt_set_enable_display()使用命令0xc3，参数0x00表示开、0x80表示关；
• 省电动画：pkt_set_enable_powersave_anim()使用命令0xc4，控制内置开机/睡眠动画是否启用；
• 内置动画选择：pkt_set_builtin_animations()（usb.rs#L333-L348）把开机、唤醒、睡眠、关机四个阶段的动画选择位压缩进一个字节，用位移与位或完成编码。

这四类枚举（AnimBooting、AnimAwake、AnimSleeping、AnimShutdown）都实现了FromStr和From<i32>，可以无缝映射到 CLI 参数与 D-Bus 属性上。

5. 对角线布局：LED 字节顺序的编码

AniMe Matrix 的素材是"斜着"的——LED 按对角线方向排布，因此普通图片必须重排才能正确显示。diagonal.rs处理这件事：

• AnimeDiagonal::get_row()从斜矩阵中沿对角线抽取一行 LED 值；
• 每种机型有一个专门的打包函数，例如to_ga401_packets()、to_gu604_packets()通过copy_slice()按"行坐标 + 长度"的表把各行拼进缓冲区，to_strix_packets()则处理 G635L/G835L 的交错矩阵（前 28 行按 1→14 递增、之后固定 15 颗 LED）；
• 最终产出统一为AnimeDataBuffer——一个携带机型标识的一维亮度字节数组（data.rs#L192-L236）。

AnimeType与机型的对应关系通过 DMI 主板名判断（usb.rs#L245-L266）：GA401、GA402、GU604、G635L、G835L五类，由工作区内的 dmi-id/ crate 读取。每种机型还内置了对角线图片的宽高（如 GA401 为 74×36、GU604 为 70×43），素材必须按此尺寸导出，库不做缩放。

普通（非对角线）图片走 rog-anime/src/image.rs 的AnimeImage：它维护一组 LED 物理坐标，用glam矩阵做缩放、旋转、平移后逐点采样图像，按物理比例换算像素间距（源码注释给出了各机型的实测厘米数换算）。

6. 从编码到落盘：asusd 守护进程的完整写流程

rog-anime只负责"编码"，真正的"写 USB"由守护进程完成。在 asusd/src/aura_anime/mod.rs 中可以看到完整链路：

1. 启动时调用pkts_for_init()写入两个初始化包；
2. write_data_buffer()把AnimeDataBuffer转成AnimePacketType（Vec<[u8; 640]>），逐个写入，最后补发pkt_flush()；
3. 配置变更时依次写入显示开关、亮度、省电动画三个控制包。

USB 设备的发现与打开封装在 rog-platform/src/hid_raw.rs：HidRaw::new("193b")用 udev 枚举hidraw子系统，按idProduct属性匹配到设备节点并打开写句柄。动画循环则由run_animation()（data.rs#L288-L371）驱动，支持按时间/次数循环和淡入淡出，每帧通过回调交给上层写设备。

7. 验证与延伸阅读

编码正确性靠"黄金快照"测试保证：rog-anime/tests/ 下按机型各有一个测试文件，例如 g635l.rs 内嵌了完整期望字节数组，任何打包逻辑变动都会导致逐字节比对失败。项目还附带了一个基于虚拟 HID 设备的模拟器 simulators/src/simulator.rs，它复刻了0x5e报号的 640 字节 Feature Report 描述符，让你无需真机就能可视化验证编码结果。

如果你想在真机上实际操作灯板，可参考官方 CLI 文档 docs/usage/asusctl.md 中的anime子命令章节（如asusctl anime --brightness low），更多机型素材与对角线模板在 rog-anime/data/ 目录下，例如 rog-anime/data/diagonal-template.png。