Controle de Teclado RGB para o ASUS ROG Flow Z13, Sem Precisar do Armoury Crate

Meu ASUS ROG Flow Z13 tem duas zonas RGB — o teclado e uma barra de luz ao redor da borda do tablet — e o suporte nativo do Linux para qualquer uma delas é "boa sorte". O Armoury Crate simplesmente não existe aqui. Então eu mesmo escrevi: uma CLI, um app GTK4 e um painel de navegador que falam direto com o hardware, mais a parte que ninguém se dá ao trabalho de fazer: fazer a cor sobreviver à suspensão, ao reinício e ao desconectar do teclado.

O que você ganha

Aqui está o painel de navegador fazendo seu trabalho:

Nota honesta: as duas zonas aparecem em branco (#ffffff) ali em cima. Não é um bug. Capturei essas telas de uma instância isolada com um arquivo de estado vazio, e o protocolo Aura não pode ser perguntado qual cor está mostrando no momento. O que quer que a ferramenta tenha escrito por último é a única verdade que existe — que é exatamente o problema de design em torno do qual este projeto inteiro foi construído. Mais sobre isso adiante.

Quatro jeitos de mudar a cor

Mesmo backend, quatro portas de entrada:

Interface	Comando / acesso	Melhor para
CLI	rgb set all '#00ddcc'	scripts, memória muscular, SSH
GUI GTK4	rgb-gui	um seletor de cor de verdade com sliders, sem terminal
Painel web	http://127.0.0.1:3003	o celular na mesma mesa, sem app para instalar
Modo festa	rgb-reactive.py	uma nova cor aleatória a cada tecla pressionada, por diversão

# 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)

A GUI embrulha as mesmas operações num diálogo de cor por zona, sliders de brilho, nove amostras predefinidas e um interruptor de sincronização que aplica uma mudança a todas as zonas. O painel web é a mesma ideia numa aba: seletor de cor, campo hex, slider de brilho, alternador de desligar, fileira de predefinições, All On / All Off.

O protocolo HID Aura

As duas zonas — teclado (USB 0b05:1a30) e barra de luz (USB 0b05:18c6) — falam o protocolo HID Aura que os projetos g-helper e z13ctl fizeram engenharia reversa primeiro. Nada oficial documenta isso; as pessoas descobriram olhando para capturas de USB, e esta ferramenta se apoia no trabalho delas em vez de refazê-lo.

A mecânica é quase insultantemente simples:

• Relatórios de saída de 64 bytes, report ID 0x5D, preenchidos com zeros.
• Pacote SetMode: 5d b3 <zone> <mode> <r> <g> <b> <speed> — o modo 0x00 é cor estática, que é tudo que esta ferramenta usa.
• Depois um pacote Save (5d b5) e um pacote Apply (5d b4) para confirmar.
• Byte de zona: 0x00 teclado, 0x01 barra de luz. Os dois nós hidraw ficam atrás de um único "N-KEY Device" multiplexado por USB, e cada um ignora silenciosamente pacotes endereçados à outra zona — então a mesma escrita de três pacotes funciona em qualquer um dos nós.

O fato que comanda cada decisão de design aqui: o protocolo é só de escrita. Você pode definir uma cor; nunca pode ler uma de volta. Então a ferramenta mantém sua própria memória — toda cor e brilho aplicados vão para ~/.local/state/rgb-control/state.json, e esse arquivo, não o hardware, é o único registro de qual cor o teclado deveria estar mostrando. O serviço de restauração, o daemon de ociosidade, o tratamento de redocking: tudo isso existe para empurrar esse arquivo de volta a um hardware que vive esquecendo.

A descoberta percorre /sys/class/hidraw, casa vendor/product ID, depois confere que o report ID 0x5D realmente existe no descritor de relatório do nó antes de confiar nele. Também há um backend de fallback: o driver asus-wmi do kernel expõe uma classe de LED multicor em /sys/class/leds/asus-*:rgb:*, com arquivos multi_intensity e brightness. O hidraw faz a escrita quando está disponível; o sysfs fornece o estado inicial, já que, ao contrário do HID, pode ser lido.

Como um clique vira uma cor

O caminho completo do clique ao LED:

Sobrevivendo à suspensão e ao redocking

Toda ferramenta RGB que encontrei no Linux conseguia definir uma cor. Nenhuma lembrava dela depois da próxima suspensão, do próximo reinício ou — como o teclado do Z13 é destacável — do próximo redocking. Cada um desses eventos reseta o hardware para o escuro, e um protocolo só de escrita significa que ele não faz ideia do que estava mostrando. O conserto precisa morar fora do hardware:

A janela de nova tentativa de ~6 segundos importa: um teclado recém-encaixado leva um instante para aparecer no barramento, e o udev dispara uma rajada de eventos enquanto enumera. A unidade de restauração dorme 1 segundo para deixar a rajada se acalmar, e então tenta a descoberta de novo em vez de desistir na primeira falha.

Também há um daemon de ociosidade, o rgb-idled, exclusivo para GNOME/Wayland porque ele escuta dois sinais D-Bus específicos: org.gnome.ScreenSaver ActiveChanged (bloqueia a tela → escurece para o brilho 1) e org.gnome.Mutter.IdleMonitor WatchFired (o mesmo relógio de ociosidade que o GNOME usa para apagar a tela → luzes desligadas). Ao desbloquear, ele restaura a partir do state.json. O detalhe que eu realmente gosto: escurecer e desligar passam por um caminho persist=False, então esses estados transitórios nunca sobrescrevem sua cor salva. Ao acordar, é a cor que você escolheu, não o que o daemon fez por último.

Instalação

Teste rápido, sem instalar:

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

A instalação completa configura a regra udev, o rgb-restore.service, o hook de sleep, uma regra tmpfiles, um link simbólico ~/.local/bin/rgb, uma entrada de desktop, e o serviço de usuário rgb-idled:

cd rgb-control
sudo ./install.sh

Os caminhos do instalador são baseados em templates (__RGB_DIR__, __RGB_STATE__) e preenchidos no momento da instalação, então funciona de onde quer que você tenha descompactado. O painel web é um passo separado e opcional:

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

Também tem suporte a ativação por socket do systemd — zero consumo de recursos até a primeira requisição chegar, e encerra depois de 10 minutos ociosos. E o modo festa, uma nova cor aleatória a cada tecla pressionada, está a um comando de distância: ./rgb-toggle.sh start (ele vai pedir sudo).

Pegadinhas

• Permissões em distros mais restritas. No Fedora/Bazzite, /dev/hidraw* já vem gravável por qualquer um, então isso simplesmente funciona. Outras distros geralmente precisam de uma regra udev uaccess (exemplo no guia de instalação). Essa é a causa número um de "não faz nada".
• Os nós de LED do sysfs pertencem ao root. A regra udev incluída faz chgrp deles para wheel. Não está nesse grupo? Adicione-se ou edite a regra.
• Os nomes dos nós de LED carregam um sufixo específico da máquina. Algo como asus-0003:0B05:18C6.0008 — esse número final pode variar de máquina para máquina. Confira ls /sys/class/leds e ajuste a configuração se o backend de fallback não encontrar nada.
• Máquinas rpm-ostree (Bazzite, Silverblue) têm um /usr somente leitura. O instalador propositalmente aponta o hook de sleep para /etc. Não "conserte" isso de volta.
• O rgb-idled só dispara no GNOME. No KDE ou no X11 puro, ele inicia normalmente e nunca faz nada. Esperado, não quebrado.
• O painel web não tem login, de propósito. Ele só se vincula a 127.0.0.1, porque dispara controle de hardware sem nenhuma autenticação na frente. O próprio código do servidor deixa isso claro: não vincule a 0.0.0.0 sem antes adicionar autenticação. Há uma proteção contra path traversal nos arquivos estáticos, mas uma proteção não substitui um login.
• O redocking compete um pouco consigo mesmo. Um redocking físico pode disparar vários eventos udev; o caminho de restauração dorme brevemente para colapsá-los, então as luzes podem piscar de volta com um instante de atraso. É a janela de colapso funcionando, não lentidão.

Downloads

• Baixar o código-fonte do rgb-keyboard (zip) 39 KB

Gratuito para uso pessoal. Se isso te economizar uma tarde, o botão do café está logo ali.