Linux上でのASUS ROG Flow Z13用RGBキーボード制御
- カテゴリ
- ツールとダウンロード
- 公開日
- 2026年7月11日
- 著者
- Jacob Lloyd — プロジェクト完了後、AIの支援を受けて執筆
- 読了時間
- 約12分で読めます
かんたんに言うと: Linux環境下でASUS製ノートパソコンの光るキーボードライトを制御するために私が書いたフリーソフトです。公式アプリが存在しない環境です。コマンドラインやデスクトップアプリ、ウェブページから色を変更でき、その色はスリープ、再起動、キーボードの取り外し後も実際に保持されます。これはメーカーが残した空白を埋めるものです。
私のASUS ROG Flow Z13には、キーボードとタブレットの周囲にあるライトバーという2つのRGBゾーンがあります。しかし標準のLinuxではどちらも「運次第」な状態です。Armoury Crateはここには存在しません。そこで私は自作することにしました。CLI、GTK4アプリ、ハードウェアと直接通信するブラウザパネルです。さらに誰も気にかけない部分、つまりスリープ、再起動、キーボードのドッキング解除後でも色設定が維持されるようにする機能も実装しました。
要約
- 概要： Z13のキーボードとライトバー用のAura HIDドライバーで、CLI、GTK4 GUI、ブラウザパネル、アイドルデーモン、そしてキーを押すたびに新しい色になるパーティモードを備えています。
- 費用： 無料です。配布ファイル全体のサイズは約40 KBで、Python標準ライブラリと依存関係ゼロのNodeのみを使用しています。
- 必要なもの： Linuxが動作するROG Flow Z13（2025年モデルのGZ302）と、インストーラーを実行するための5分程度の時間です。
- 結果として得られるもの： 蓋を閉じた後や再起動時、あるいはキーボードをタブレットから取り外して再びドッキングした後でも色が維持されます。
最終的に得られるもの
以下が、ブラウザ上で正常に機能しているパネルの様子です：
正直に申し上げますと、上記の画像では両ゾーンとも白色（#ffffff）となっています。これはバグではありません。空の状態ファイルを持つ隔離環境からこの画像を撮影したのですが、Auraプロトコルでは現在表示されている色を問い合わせることができないのです。つまり、ツールが最後に書き込んだ内容こそが唯一の真実となるのです。まさにこの点こそが、本プロジェクト全体が解決しようとしている設計上の課題なのです。詳細は以下に記載します。
色を変更するための4つの方法
バックエンドは同じで、フロント側には4つの操作方法があります：
| インターフェース | コマンド／アクセス方法 | 最適な用途 |
|---|---|---|
| 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版では、各ゾーンごとにカラーダイアログや明るさ調整用のスライダー、9種類のプリセットカラーが用意されており、すべてのゾーンに一括で変更を適用するための同期スイッチもあります。ウェブパネルも同様で、カラーピッカーや16進数入力欄、明るさ調整スライダー、オフ切り替え機能、プリセット行、そして「全てオン／全てオフ」のボタンが備わっています。
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が固定色モードであり、本ツールではこれのみを利用します。 - その後、保存用パケット（
5d b5）および適用用パケット（5d b4）を送信して設定を確定させます。 - ゾーン指定用バイト：
0x00がキーボード、0x01がライトバーです。両方のhidrawノードは1つのUSBマルチプレクス型「N-KEYデバイス」の下に存在し、それぞれ相手側ゾーン向けのパケットを無視するようになっています。そのため、同じ3つのパケットを送信するだけでどちらのノードにも設定が反映されます。
ここでの設計の根幹となる事実は「このプロトコルは書き込み専用である」という点です。色を設定することはできても、読み出すことは不可能です。そのため本ツールは独自のメモリ領域を保持しており、適用されたすべての色や明るさの情報が ~/.local/state/rgb-control/state.json に記録されます。つまりハードウェアではなくこのファイルこそが、キーボードがどのような見た目であるべきかを示す唯一の情報源となります。復元サービスやアイドル状態時のデーモン、再接続時の処理などもすべて、忘れ去られがちなハードウェアにこの情報を再送信するために存在します。
検出処理では /sys/class/hidraw を走査し、ベンダーIDおよび製品IDが一致するか確認した上で、レポートID 0x5D がそのノードのレポート記述子内に実際に存在するかも検証してから信頼します。またバックアップ用のバックエンドとして、カーネルの asus-wmi ドライバーが /sys/class/leds/asus-*:rgb:* にマルチカラーLEDクラスを提供しており、multi_intensity や brightness といったファイルも用意されています。HIDが利用可能な場合はそちらで書き込み処理を行い、sysfsは初期状態の読み出し用として機能します。なぜならHIDとは異なりsysfsではデータを読み取ることができるからです。
クリックが色に変わるまでの流れ
クリックから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__）となっており、インストール時に実際の値に置き換えられるため、どこに解凍しても問題なく動作します。ウェブパネルの設定は別途、任意で行うことができます：
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ルールが必要です（設定方法はガイドを参照）。これが「何も動作しない」状態の最も一般的な原因です。もしお使いのASUS製品が異なるベンダーIDや製品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、LLMを活用して自分の環境用にプロジェクトを調整する方法、私のホームラボ用としてZ13の代わりに導入した Chuwi Aubox AI365、そして本サイトから提供されている別の無料GTK4デスクトップツールである OpenClaw Model Manager もご覧ください。
ダウンロード
個人利用は無料です。役に立ったら、コーヒーをおごってもらえると嬉しいです。