Controle da barra de luz Robobloq QuikLight no Linux — interface gráfica, linha de comando e biblioteca Python.
A Robobloq distribui o SyncLight, aplicativo oficial dessas barras de luz, apenas para Windows e macOS. Não há versão para Linux, nem previsão de uma. Quem usa Linux fica com um dispositivo que acende no botão físico e nada mais: sem escolher cor, sem regular intensidade, sem efeitos.
Este projeto resolve isso falando o protocolo nativo da barra direto pelo HID do kernel. Não é uma camada de compatibilidade nem um emulador: é uma reimplementação do protocolo, verificada byte a byte contra o aplicativo oficial.
Sem Wine. Sem Electron. Sem dependências fora da biblioteca padrão do Python — a interface gráfica usa o PyQt6 que a sua distribuição já empacota.
1% de CPU e 14 MB de memória rodando animação a 30 quadros por segundo. O aplicativo oficial passa de 200 MB só para abrir.
| Dispositivo | Barra de luz Robobloq QuikLight, conexão por cabo USB |
| USB ID | 1a86:fe07 (fabricante ROBOBLOQ) |
| Testado com | Firmware 1.8.2, fita de 65 LEDs |
| Sistema | Qualquer Linux com hidraw — ou seja, qualquer um |
| Python | 3.10 ou mais novo |
Confirme que a sua é compatível:
lsusb | grep 1a86:fe07
# Bus 001 Device 008: ID 1a86:fe07 QinHeng Electronics USBHIDO que não é coberto: as variantes Bluetooth e o dongle sem fio usam um
protocolo diferente, com endereçamento por MAC (o aplicativo oficial os trata
em outro módulo). Teclados e mouses RGB da mesma marca usam um terceiro
protocolo, com cabeçalho SC e CRC16. Nenhum dos dois está implementado aqui,
mas ambos estão descritos em docs/PROTOCOL.md para quem
quiser continuar.
A barra se apresenta ao sistema como um dispositivo HID comum, com duas interfaces:
ROBOBLOQ USBHID (1a86:fe07)
├── Interface 0 — HID genérico, endpoints de 64 bytes ← canal de controle
└── Interface 1 — HID teclado ← botões de toque
Nenhum driver é necessário: o módulo usbhid do kernel já cria os nós
/dev/hidrawN. O que faltava era saber o que escrever neles.
Os comandos são quadros curtos com cabeçalho, um id sequencial e checksum:
┌─────┬─────┬─────────┬──────┬───────┬──────────┬──────────┐
│ 'R' │ 'B' │ tamanho │ id │ ação │ payload │ checksum │
└─────┴─────┴─────────┴──────┴───────┴──────────┴──────────┘
Cores são enviadas por trecho — [led_inicial, R, G, B, led_final] — e vários
trechos cabem no mesmo quadro. É isso que permite desenhar um degradê, ou
animar a fita inteira, com uma única escrita.
O protocolo completo, com a tabela de ações e as armadilhas encontradas, está
em docs/PROTOCOL.md.
git clone https://github.com/jrcn1991/quicklight-linux.git
cd quicklight-linux
# 1. permissão de acesso ao dispositivo (uma vez só, pede sudo)
sudo cp packaging/99-quicklight.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger --subsystem-match=hidraw
# 2. o pacote
pip install --user .
# 3. interface gráfica — prefira o pacote da sua distribuição
sudo apt install python3-pyqt6 # Debian/Ubuntu
# sudo dnf install python3-pyqt6 # Fedora
# sudo pacman -S python-pyqt6 # Arch
# 4. ícone e atalho no menu de aplicativos
./packaging/install-desktop.shA regra udev concede acesso apenas ao dispositivo 1a86:fe07, e apenas para o
usuário com a sessão ativa. Para desfazer, apague o arquivo.
quicklight-guiCor por matiz e saturação, paleta de atalhos, seletor completo, intensidade, os sete efeitos da firmware e oito animações geradas pelo computador.
quicklight info # id, firmware e número de LEDs
quicklight color azul # nome, #rrggbb ou rgb
quicklight color '#ff5500' --brightness 60
quicklight color verde --start 1 --end 20
quicklight gradient roxo ciano # degradê ao longo da fita
quicklight offSete efeitos dinâmicos, gravados na barra, que continuam rodando mesmo com o computador desligado:
quicklight effects # percorre todos, anunciando cada um
quicklight effect 2 3 # o que você gostou
quicklight effect none # volta para cor sólida
quicklight speed 60O tipo 3 reage a som pelo microfone da própria barra, sem nada rodando no computador:
quicklight effect 3 0
quicklight sensitivity 70Como a barra aceita pintura por trecho, a fita vira uma tela e o PC desenha nela. Oito animações incluídas:
quicklight anim arcoiris
quicklight anim cometa --color ciano
quicklight anim fogo --seconds 30
quicklight anim brilhos --fps 30 --speed 1.5arcoiris, cometa, scanner, onda, respiracao, ciclo, fogo,
brilhos. Rodam até Ctrl+C.
Duas otimizações mantêm o custo perto de zero: LEDs vizinhos de mesma cor viram um único trecho no pacote, e cada quadro envia apenas o que mudou desde o anterior — um quadro idêntico não gera tráfego nenhum.
from quicklight import QuickLight
with QuickLight() as bar:
print(bar.info()) # {'version': '1.8.2', 'lamps': 65, ...}
bar.show_color((255, 90, 0), 70) # cor a 70% de intensidade
bar.set_gradient((255, 0, 0), (0, 0, 255), steps=12)
# trechos independentes numa única escrita
bar.set_sections([(1, 255, 0, 0, 32), (33, 0, 0, 255, 65)])
# um quadro inteiro, um valor por LED
bar.paint([(i * 4 % 256, 0, 128) for i in range(65)])src/quicklight/
├── protocol.py monta os quadros — puro, sem E/S, é o que os testes cobrem
├── transport.py escrita e leitura em /dev/hidrawN, e o transporte falso
├── device.py API de alto nível
├── colors.py nomes, hexadecimal, degradê e escurecimento
├── effects.py animações, como funções puras do tempo
├── cli.py linha de comando
└── gui/app.py interface PyQt6
A separação em camadas existe por um motivo prático: o protocolo e os efeitos são testáveis com a barra desligada.
python -m unittest discover -s tests -t . -v68 testes, nenhum precisa de hardware. O mais importante compara cada
quadro montado com os bytes que o aplicativo oficial produz para os mesmos
comandos, guardados em tests/golden_packets.json. Se o formato dos pacotes
for alterado por engano, é ali que a conta não fecha.
Os efeitos, por serem funções puras, são verificados por propriedade: nenhum canal fora de 0–255, um valor por LED em todo quadro, animação que de fato muda com o tempo, e nenhum quadro que estoure o limite do pacote.
Sobre como os vetores foram obtidos, veja tools/README.md.
"barra QuikLight não encontrada" — confira com lsusb | grep 1a86:fe07. Se
o dispositivo aparece mas a mensagem persiste, a interface de controle não foi
localizada; abra uma issue com a saída de ls /sys/class/hidraw/.
"sem permissão para abrir /dev/hidrawN" — falta a regra udev do passo 1, ou ela não foi recarregada. Desconectar e reconectar a barra também aplica.
O slider de intensidade não muda nada — o comando de brilho da firmware age
sobre os efeitos, não sobre uma cor estática já pintada. Para escurecer cor
sólida use quicklight color <cor> --brightness 40, que multiplica os canais
antes de enviar. A interface gráfica já escolhe o caminho certo sozinha.
A barra ignorou um comando — a firmware ocasionalmente perde escritas; o próprio aplicativo oficial repete o comando de desligar quatro vezes. Repita.
quicklight funciona mas quicklight-gui reclama de PyQt6 — o pacote foi
instalado num interpretador diferente daquele em que o PyQt6 está. Veja qual
com head -1 $(which quicklight) e reinstale com o interpretador certo.
MIT — veja LICENSE.
Projeto independente, feito por engenharia reversa para uso próprio, sem qualquer relação com a Robobloq. Nenhum código do fabricante é redistribuído aqui. "QuikLight", "SyncLight" e "Robobloq" são marcas da Robobloq.