ASUS ROG Flow Z13 RGB 键盘控制,不需要 Armoury Crate

我的 ASUS ROG Flow Z13 有两个 RGB 分区——键盘,还有平板边缘的一条灯条——而 Linux 对这两者的原生支持,基本就是"祝你好运"。这个世界里根本没有 Armoury Crate。所以我自己写了一套:一个 CLI、一个 GTK4 应用,还有一个直接跟硬件对话的浏览器面板,外加没人愿意费心做的那部分——让颜色能扛过休眠、重启,以及把键盘从平板上拔下来。

最终得到什么

下面是浏览器面板干活的样子:

老实说一句:上面两个分区显示的都是白色(#ffffff)。这不是 bug。我是从一个状态文件为空的沙盒实例里截的图,而 Aura 协议根本没法被问"你现在是什么颜色"。工具最后一次写入的颜色,就是唯一存在的真相——而这恰恰就是这整个项目要解决的设计难题。详见下文。

换颜色的四个入口

后端是同一个,前门有四扇:

接口	命令 / 访问方式	最适合
CLI	rgb set all '#00ddcc'	脚本、肌肉记忆、SSH 远程
GTK4 GUI	rgb-gui	带滑块的正经取色器,不用碰终端
网页面板	http://127.0.0.1:3003	同一张桌子上的手机,不用装任何应用
派对模式	rgb-reactive.py	每次按键换个随机新颜色,纯粹好玩

# the CLI in one breath
rgb list                       # what zones exist, current known state
rgb set all '#00ddcc'          # set every zone to teal
rgb brightness keyboard 2      # 0-3
rgb on / rgb off               # per-zone or all
rgb restore                    # reapply the last saved color (what the restore service runs)

GUI 把同样的操作包进了每个分区各自的取色对话框、亮度滑块、九个预设色块,以及一个能把一次改动同步应用到所有分区的开关。网页面板是同样的思路搬到一个标签页里:取色器、hex 输入框、亮度滑块、关闭开关、预设色一排,还有 All On / All Off。

Aura HID 协议

键盘(USB 0b05:1a30)和灯条(USB 0b05:18c6)这两个分区,说的都是 g-helper 和 z13ctl 项目最先逆向出来的 Aura HID 协议。官方没有任何文档,都是有心人盯着 USB 抓包一点点摸出来的,这个工具是站在他们的成果上接着做,而不是从头再来一遍。

底层机制简单得几乎有点不讲道理:

• 64 字节的输出报文,report ID 是 0x5D,零填充。
• SetMode 包:5d b3 <zone> <mode> <r> <g> <b> <speed>——模式 0x00 是静态颜色,这个工具只用这一种。
• 接着用一个 Save 包(5d b5)和一个 Apply 包(5d b4)来提交。
• 分区字节:0x00 是键盘,0x01 是灯条。两个 hidraw 节点都藏在一个 USB 多路复用的"N-KEY Device"背后,各自会安静地忽略发给另一个分区的包——所以同样的三包写入序列,发到哪个节点上都管用。

支配这里每一个设计决定的事实是:这个协议只能写,不能读。你可以设置一个颜色,但永远没法把它读回来。所以工具自己留了一份记忆——每一次应用过的颜色和亮度,都落在 ~/.local/state/rgb-control/state.json 里,而记录"这个键盘本该是什么颜色"的,是这份文件,不是硬件本身。恢复服务、空闲守护进程、重新插拔的处理逻辑,存在的目的都是把这份文件重新推给一台老是失忆的硬件。

设备探测会遍历 /sys/class/hidraw,匹配 vendor/product ID,然后确认该节点的 report descriptor 里确实存在 report ID 0x5D,才会信任它。还有一个后备后端:内核的 asus-wmi 驱动在 /sys/class/leds/asus-*:rgb:* 暴露了一个多彩 LED 类,带 multi_intensity 和 brightness 文件。写入这活儿,能用 hidraw 就用 hidraw;初始状态则由 sysfs 提供,因为跟 HID 不一样,它是能被读出来的。

一次点击是怎么变成一个颜色的

从点击到 LED 的完整路径:

扛过休眠与重新插拔

我在 Linux 上找到的每一个 RGB 工具都能设置一个颜色。但没有一个能在下一次休眠、重启,或者——因为 Z13 的键盘是可拆卸的——下一次重新插拔之后还记得它。这几种情况每次都会把硬件重置成一片漆黑,而只写不读的协议意味着它根本不知道自己刚才显示的是什么。要解决这个问题,答案只能放在硬件之外:

这大约 6 秒的重试预算是有讲究的:刚插上的键盘需要一点时间才会出现在总线上,udev 在枚举过程中会连续触发一串事件。恢复单元会先睡 1 秒,等这波事件消停下来,然后重试发现,而不是第一次没找到就放弃。

还有一个空闲守护进程 rgb-idled,只在 GNOME/Wayland 下生效,因为它监听的是两个特定的 D-Bus 信号:org.gnome.ScreenSaver ActiveChanged(锁屏 → 调暗到亮度 1)和 org.gnome.Mutter.IdleMonitor WatchFired(GNOME 用来熄灭屏幕的同一个空闲时钟 → 熄灯)。解锁之后它会从 state.json 恢复。我个人特别喜欢的一个细节:调暗和熄灭走的都是 persist=False 路径,所以这些临时状态永远不会覆盖你保存好的颜色。醒来之后看到的是你自己选的那个颜色,而不是守护进程最后做的那件事。

安装设置

不装东西,先快速测一下:

cd rgb-control
./rgb-cli list
./rgb-cli set all '#00ddcc'

完整安装会配好 udev 规则、rgb-restore.service、sleep 钩子、一条 tmpfiles 规则、一个 ~/.local/bin/rgb 符号链接、一个桌面入口,以及 rgb-idled 用户服务:

cd rgb-control
sudo ./install.sh

安装脚本里的路径都是模板化的(__RGB_DIR__、__RGB_STATE__),会在安装时填好,所以不管你把 zip 解压到哪里都能用。网页面板是单独的、可选的一步:

cd rgb-web
node server.js
# → http://127.0.0.1:3003
# PORT= and RGB_CLI= env vars override the defaults

它还支持 systemd 的套接字激活——第一个请求打过来之前不占任何资源,空闲 10 分钟后自动退出。而派对模式——每次按键都换一个随机新颜色——只差一条命令:./rgb-toggle.sh start(会向你要 sudo 权限)。

踩过的坑

• 严格一点的发行版上的权限问题。在 Fedora/Bazzite 上,/dev/hidraw* 开箱即可被任何人写入,所以直接就能用。其他发行版通常需要一条 udev 的 uaccess 规则(设置指南里有示例)。这是"毫无反应"这类问题的头号原因。
• sysfs 的 LED 节点是 root 拥有的。附带的 udev 规则会把它们 chgrp 成 wheel 组。不在这个组里?把自己加进去,或者改一下规则。
• LED 节点名带有一个跟机器相关的后缀。类似 asus-0003:0B05:18C6.0008 这样,末尾那个数字在不同机器上可能不一样。如果后备后端什么都没找到,检查一下 ls /sys/class/leds,再相应调整配置。
• rpm-ostree 机器(Bazzite、Silverblue)的 /usr 是只读的。安装脚本特意把 sleep 钩子放在 /etc 下。别"好心"把它改回去。
• rgb-idled 只在 GNOME 上会真正起作用。在 KDE 或裸 X11 上,它能正常启动,但永远不会做任何事。这是预期行为,不是坏了。
• 网页面板没有登录,这是故意的。它只绑定 127.0.0.1,因为它会在没有任何鉴权的情况下直接 shell 调用硬件控制。服务器代码里写得很明白:没加认证之前,别绑定 0.0.0.0。静态文件有路径穿越防护,但防护不等于登录。
• 重新插拔会跟自己抢一下跑。一次物理上的重新插拔,可能会触发好几个 udev 事件;恢复流程会短暂睡一下把它们合并处理,所以灯光可能会晚半拍才亮回来。那是合并窗口在起作用,不是卡顿。

下载

• 下载 rgb-keyboard 源码(zip) 39 KB

仅限个人使用免费。如果它替你省下了一下午的时间，欢迎点旁边的咖啡按钮支持一下。