在Linux系统下对华硕ROG Flow Z13的RGB键盘进行控制
- 分类
- 工具与下载
- 发布日期
- 2026年7月11日
- 作者
- Jacob Lloyd —— 项目完成后，在 AI 协助下撰写
- 阅读时长
- 约 9 分钟阅读
简单来说： 这是我编写的免费软件，用于在 Linux 系统下控制华硕笔记本电脑上的键盘背光。由于华硕并未提供官方控制程序，因此这个软件就派上用场了。用户可以通过命令行、桌面应用程序或网页来更改颜色；而且这些颜色设置即使在电脑进入休眠状态、重启或拔掉键盘后也依然有效。它填补了厂商留下的功能空白。
我的 ASUS ROG Flow Z13 有两个RGB控制区域——键盘本身以及平板边缘的灯条。不过在Linux系统下，对这两者的支持简直“全靠运气”。这里根本没有Armoury Crate这个软件。于是我决定自己动手：编写了一个命令行工具、一个基于 GTK4 的图形界面程序，还有一个能直接与硬件交互的浏览器面板；另外我还解决了一个常被忽略的问题：如何让设置的色彩在系统休眠、重启或拆下键盘后依然保留。
简而言之：
- 这是什么：专为Z13的键盘与灯条设计的Aura HID驱动程序；附带命令行工具、GTK4图形界面、浏览器面板、后台守护进程，以及一种每次按键都会随机变换颜色的趣味模式。
- 费用如何：完全免费。整个压缩包大小仅约40 KB——只用到Python标准库以及几乎无需任何依赖的 Node.js。
- 需要什么条件：一台运行Linux系统的ROG Flow Z13（2025款GZ302），再花五分钟运行安装程序即可。
- 最终效果：无论你合上盖子、重启系统，还是拆下键盘后再重新连接，设置的色彩都会原封不动地保留下来。
最终效果展示
以下是浏览器端控制面板的实际运行效果：
坦白说：图中两个控制区域均显示为白色（#ffffff）。这并非故障。这些截图取自一个状态文件为空的沙盒环境；而Aura协议本身又无法查询当前实际显示的颜色值。因此，该工具最后写入的内容便是唯一可信的信息——这也正是整个项目旨在解决的设计难题。详情见下文。
四种改变颜色的方法
后端相同，但提供了四种前端操作方式：
| 界面类型 | 命令/访问方式 | 适用场景 |
|---|---|---|
| 命令行界面 | rgb set all '#00ddcc' | 脚本编写、熟练操作、通过SSH远程控制 |
| GTK4图形界面 | 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)图形界面为每个区域提供了独立的调色对话框、亮度滑块以及九个预设颜色样本；还有一个同步开关，可让所有区域的颜色设置保持一致。网页面板的设计理念相同：包含调色器、十六进制颜色输入框、亮度滑块、开关按钮、预设颜色行，以及“全部开启/全部关闭”功能。
Aura HID协议
无论是键盘区域（USB 0b05:1a30）还是灯条区域（USB 0b05:18c6），它们都遵循Aura HID协议。该协议最初是由 g-helper 与 z13ctl 项目逆向工程得出的。目前尚无任何官方文档对此进行说明；人们是通过分析USB数据包才弄明白其运作方式的。本工具正是基于这些研究成果而开发的，而非重新进行逆向分析。
该协议的运作机制简单得近乎离谱：
- 输出报告为64字节长度，报告ID为
0x5D，数据以零填充。 - 设置模式数据包格式为：
5d b3 <zone> <mode> <r> <g> <b> <speed>。其中模式0x00代表静态颜色，这也是本工具唯一使用的模式。 - 随后需发送保存数据包（
5d b5）与应用数据包（5d b4）才能真正生效。 - 区域标识字节：
0x00代表键盘，0x01代表灯条。两个hidraw节点实际上都隶属于同一个通过USB复用的“N-KEY设备”；每个节点都会自动忽略发给另一个区域的数据包——因此只需发送相同的三个数据包即可同时控制两个区域。
这里所有设计决策的出发点就是：该协议为只写协议。 用户只能设置颜色，却无法读取当前颜色值。因此本工具会自行保存相关数据——所有设定的颜色与亮度信息都会存入 ~/.local/state/rgb-control/state.json 文件中；该文件而非硬件本身才是记录键盘外观状态的唯一依据。恢复服务、空闲守护进程以及重新连接时的处理机制：这一切的存在都是为了将该文件中的设置重新同步到容易遗忘设置的硬件上。
在检测过程中，程序会遍历 /sys/class/hidraw 目录，比对厂商与产品ID；确认报告ID 0x5D 确实存在于对应节点的报告描述符中后才会予以信任。此外还有备用后端机制：内核中的 asus-wmi 驱动会在 /sys/class/leds/asus-*:rgb:* 路径下提供多色LED控制接口，相关参数可通过 multi_intensity 与 brightness 文件进行配置。当Hidraw可用时由其执行写入操作；而由于Sysfs可读取数据，故硬件的初始状态信息便通过它来获取。
点击操作如何转化为颜色变化
从点击到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 服务、休眠钩子、tmpfiles 规则、指向 ~/.local/bin/rgb 的符号链接、桌面入口项，以及 rgb-idled 用户服务：
cd rgb-control
sudo ./install.sh安装路径采用模板形式（__RGB_DIR__、__RGB_STATE__），会在安装时自动填充，因此无论您将程序解压到何处都能正常运行。网页控制面板则是可选的额外步骤：
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 权限）。
注意事项/易错点
- 在 stricter 的发行版上的权限问题。 在 Fedora/Bazzite 上，
/dev/hidraw*默认就允许所有用户写入，因此一切都能正常工作。其他发行版则通常需要一条 udevuaccess规则（设置指南中有示例）。这是导致“程序看似没起作用”的最常见原因。如果你的华硕型号使用了不同的厂商/产品 ID，把此代码库交给 AI 助手来适配会比你自己去逆向分析 HID 数据要快得多。 - sysfs 中的 LED 节点归 root 所有。 自带的 udev 规则会将它们的所属组设为
chgrp，最终变为wheel。如果你不在该组中，请自行加入或修改规则。 - LED 节点名称带有机器特定的后缀。 比如
asus-0003:0B05:18C6.0008——末尾的数字会因机器而异。请执行ls /sys/class/leds查看，如果默认后端找不到对应节点，则需手动调整配置。 - 使用 rpm-ostree 的系统（如 Bazzite、Silverblue）中
/usr为只读。 安装程序特意将休眠钩子文件写入/etc。切勿试图将其改回原状态。 - rgb-idled 仅在 GNOME 环境下才会触发。 在 KDE 或纯 X11 环境下它虽能启动但不会执行任何操作。这属于预期行为，并非程序出错。
- 网页面板故意不设登录功能。 它仅绑定
127.0.0.1，因为程序会直接调用硬件控制接口且无需身份验证。服务器代码也明确说明：在未添加认证机制前切勿绑定0.0.0.0。虽然静态文件有路径遍历防护，但这并不等同于登录验证。 - 重新插拔时可能会出现短暂冲突。 一次物理上的重新连接可能触发多个 udev 事件；恢复流程会稍作延时以合并这些事件，因此灯光可能会稍微晚一点亮起。这是合并机制在起作用，并非延迟现象。
相关链接：我用来搭建家庭实验室的 ROG Flow Z13，如何让大型语言模型将此类项目适配到你自己的硬件上，以及后来取代 Z13 成为我的家庭实验室主机的 Chuwi Aubox AI365 迷你电脑。另外还有本网站提供的另一款免费 GTK4 桌面工具——OpenClaw 模型管理器。
下载
仅限个人使用免费。如果它替你省下了一下午的时间，欢迎点旁边的咖啡按钮支持一下。