ASUS ROG Flow Z13のRGBキーボード制御、Armoury Crateは要りません

かんたんに言うと: 公式アプリが存在しないLinux上で、ASUSノートPCの光るキーボードを操作するために自作した無料ソフトです。コマンド、デスクトップアプリ、ブラウザ画面のどれからでも色を変えられ、スリープや再起動、キーボードの取り外し後も設定した色がちゃんと残ります。メーカーが放置した穴を埋める一本です。

自分の環境で実装したい? おすすめの方法: 下のファイルを手元にコピーして、LLM(Claude、ChatGPT、ローカルモデルなど)に渡し、あなたの環境に合わせて実装してもらってください。 LLMアシスタントが初めての方は、セットアップガイド(Claude Code、Cowork、Terminex、DeepSeek)をどうぞ。

自分で用意するもの

ASUS ROG Flow Z13(GZ302)— または、HIDまわりを自分のASUS機に移植する意欲
udevルールを追加できるLinux環境
任意:ブラウザのコントロールパネルを使うならNode.js

LLMに任せられること

下のzipをダウンロード・展開し、CLI・GTKアプリ・ウェブパネルをインストールしてもらう
udevルールと、サスペンド・再起動・キーボード再装着後に色を復元するサービス群を設定してもらう
各操作面をテストしてもらう — ハードウェアが違う場合はHIDデバイスのマッチングを移植してもらう

コピペで使えるプロンプト:

まず https://www.laserlloyd.com/ja/projects/rgb-keyboard-web-control/ を取得して読んでください。このプロジェクトの詳細な手順・設定・注意点がすべて載っています。 rgb-keyboardツールを私のLinuxマシンにセットアップし、CLIとウェブパネルの両方からキーボードの色を制御でき、サスペンドと再起動を越えて色が維持される状態にしてください。udevルールをインストールし、デバイスIDが違う場合はマッチングを調整すること。検証として、色を設定し、サスペンド・復帰後も維持されることを確認してください。最後に、変更点と普段の色の変え方をまとめてください。

うちのASUS ROG Flow Z13にはRGBゾーンが2つあります。キーボードと、タブレット縁のライトバー。そしてLinuxでの標準サポートは、どちらも「健闘を祈る」レベルです。Armoury Crateはこの世界には存在しません。だから自分で書きました。ハードウェアに直接話しかけるCLI、GTK4アプリ、ブラウザパネル、それから誰もやりたがらない部分:サスペンドしても、再起動しても、キーボードを引っこ抜いて挿し直しても、色が生き残るようにする処理です。

tl;dr

これは何:Z13のキーボード+ライトバー用のAura HIDドライバに、CLI、GTK4 GUI、ブラウザパネル、アイドルデーモン、そしてキーを叩くたびに色が変わるパーティーモードを付けたもの。
費用:無料。zip全体で約40KB。Python標準ライブラリと、依存ゼロのNodeだけです。
必要なもの:Linuxの動くROG Flow Z13(2025年のGZ302)と、インストーラに使う5分。
手に入るもの:フタを閉じても、再起動しても、キーボードをタブレットから剥がして戻しても、そこにまだ残っている色。

手に入るもの

ブラウザパネルが仕事をしている図:

ブラウザ上のrgb-web制御パネル:キーボードとライトバーの2枚のゾーンカードが両方ONで明るさ3/3、プリセットカラーの列、All On / All Offボタン — 両ゾーン接続済み、上段にプリセット、会議前に全部消すボタンは1つ。

同じrgb-webパネルをスマホ幅で表示したところ。カードが1列に積まれている — 同じページを幅390pxで。モバイル用に特別なことは何もしていません。狭い画面と喧嘩しないページというだけです。

正直に言うと、上の画像は両ゾーンとも白(#ffffff)です。バグではありません。状態ファイルが空のサンドボックス環境でキャプチャした上に、Auraプロトコルには「今なに色?」と聞く手段がないんです。ツールが最後に書いた色だけが、存在する唯一の真実。そして、それこそがこのプロジェクト全体の設計課題です。詳しくは後述。

色を変える4つの入口

バックエンドは同じ、玄関が4つ:

インターフェース	コマンド / アクセス	向いている用途
CLI	`rgb set all '#00ddcc'`	スクリプト、指が覚えた操作、SSH越し
GTK4 GUI	`rgb-gui`	スライダー付きの本物のカラーピッカー、ターミナル不要
Webパネル	`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は同じ操作を、ゾーンごとのカラーダイアログ、明るさスライダー、9つのプリセットスウォッチ、1回の変更を全ゾーンに適用する同期スイッチで包んだもの。Webパネルは同じ発想をタブの中でやります:カラーピッカー、hex入力欄、明るさスライダー、オフのトグル、プリセット列、All On / All Off。

Aura HIDプロトコル

キーボード(USB 0b05:1a30)もライトバー(USB 0b05:18c6)も、g-helperとz13ctlのプロジェクトが先にリバースエンジニアリングしたAura HIDプロトコルを話します。公式ドキュメントは存在せず、有志がUSBキャプチャを睨んで解明したもの。このツールはその成果を作り直さず、ありがたく上に乗っています。

仕組みは拍子抜けするほど単純です:

64バイトの出力レポート、レポートID 0x5D、残りはゼロ埋め。
SetModeパケット:5d b3 <zone> <mode> <r> <g> <b> <speed>。モード 0x00 が静的カラーで、このツールが使うのはそれだけです。
続けてSaveパケット(5d b5)とApplyパケット(5d b4)でコミット。
ゾーンバイト:0x00 がキーボード、0x01 がライトバー。両方のhidrawノードはUSB多重化された1つの「N-KEY Device」の背後にいて、相手ゾーン宛のパケットは黙って無視します。だから同じ3パケット書き込みがどちらのノードでも通ります。

ここの設計判断すべてを支配する事実:このプロトコルは書き込み専用です。色を設定することはできても、読み返すことは絶対にできません。だからツールが自前で記憶します。適用した色と明るさはすべて ~/.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は初期状態の取得担当です。HIDと違って、読めるので。

クリックが色になるまで

クリックからLEDまでの全経路:

サスペンドと再ドッキングを生き延びる

Linuxで見つけたRGBツールは、どれも色を設定することはできました。次のサスペンド、再起動、あるいは(Z13のキーボードは着脱式なので)次の再ドッキングを越えて覚えているものは皆無。そのどれもがハードウェアを真っ暗にリセットし、書き込み専用プロトコルのせいで、ハードウェアは自分がなに色だったかも知りません。直すなら、ハードウェアの外に住まわせるしかない:

約6秒のリトライ枠には理由があります。ドッキング直後のキーボードはバスに現れるまで一拍かかり、列挙中のudevはイベントを連射してくるんです。復元ユニットは1秒スリープして連射が落ち着くのを待ってから、最初の空振りで諦めずに探索をリトライします。

アイドルデーモン rgb-idled もあります。GNOME/Wayland限定なのは、特定の2つの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__)、インストール時に埋められます。どこに展開しても動くということです。Webパネルは別立てのオプション:

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

systemdのソケットアクティベーションにも対応しています。最初のリクエストが来るまでリソース消費ゼロ、アイドル10分で自動終了。そしてパーティーモード(キーを叩くたびに新しいランダム色)はコマンド1つです:./rgb-toggle.sh start(sudoを聞かれます)。

ハマりどころ

厳しめのディストロではパーミッション。Fedora/Bazziteでは /dev/hidraw* が最初から誰でも書き込めるので、そのまま動きます。他のディストロではだいたいudevの uaccess ルールが必要です(セットアップガイドに例あり)。「うんともすんとも言わない」原因の第1位。
sysfsのLEDノードはroot所有です。同梱のudevルールが wheel グループに chgrp します。そのグループに入っていない人は、入るかルールを書き換えてください。
LEDノード名にはマシン固有のサフィックスが付きます。asus-0003:0B05:18C6.0008 のような名前で、末尾の番号はマシンごとに違うことがあります。フォールバックバックエンドが何も見つけないときは ls /sys/class/leds を確認して、設定を合わせてください。
rpm-ostree系のマシン(Bazzite、Silverblue)は /usr が読み取り専用です。インストーラはわざとスリープフックを /etc に置いています。親切心で「直して」戻さないように。
rgb-idledが仕事をするのはGNOMEだけ。KDEや素のX11でも普通に起動して、そして永遠に何もしません。仕様であって故障ではないです。
Webパネルにログインはありません。わざとです。認証なしでハードウェア制御をシェル実行する以上、バインドは 127.0.0.1 のみ。サーバーのコードにもはっきり書いてあります:認証を足す前に 0.0.0.0 にバインドするな、と。静的ファイルにはパストラバーサル対策のガードがありますが、ガードはログインの代わりにはなりません。
再ドッキングは自分自身と少し競合します。物理的な再ドック1回でudevイベントが複数発火することがあり、復元パスは短くスリープしてそれをまとめます。だからライトが一拍遅れて点くことがある。あれは遅延ではなく、まとめ待ちが仕事をしている姿です。

ダウンロード

rgb-keyboardのソースをダウンロード(zip) 39 KB

個人利用は無料です。役に立ったら、コーヒーをおごってもらえると嬉しいです。