Controls RGB lighting, key remapping and macros on keyboards that support
VIA, the open configuration protocol of QMK firmware used by Akko,
Keychron, Glorious, KBDfans and many others. It needs only Python 3 and, for
the GUI, GTK 3 (python3-gi), both already on most Linux desktops.
viactl was called akkoctl until October 2026. The old name still works as a command, and old GitHub links redirect here.
| Keyboard | Status |
|---|---|
Akko 5075B Plus-S (342d:e4f6) |
✅ Tested by maintainer, including Akko's sidelights and custom keys |
| Other VIA keyboards with QMK RGB-matrix lighting | 🟡 Untested: same protocol, should work |
Tried another keyboard? Please report how it went, so it can be added to the table. Device support grows through test reports from people who own the hardware.
The keyboard must be connected by USB cable in wired mode. VIA control does not work over Bluetooth or 2.4G.
./install.shThis installs a udev rule so your user can access the keyboard without root
(it asks for your sudo password), adds a viactl command in
~/.local/bin, and adds "VIA Keyboard Control" to the app menu.
Unplug and replug the keyboard afterwards.
The udev rule covers Akko keyboards. For another brand, add a line with your
keyboard's USB vendor ID to 70-viactl.rules (see the comment in it) and run
./install.sh again.
viactl guiThe GUI has five tabs:
- Backlight / Sidelights: effect, brightness, speed, color and saturation for the per-key lighting and the side light strip. Changes apply live and are saved to the keyboard automatically.
- Keymap: click any key on any layer to remap it.
- Macros: edit macros M0–M15, then assign them to keys on the Keymap tab.
- Device: firmware info and factory reset.
viactl info # firmware + current lighting
viactl effects # list the 46 effects
viactl set --effect breathing --color '#00aaff'
viactl set -b 40% -s 80% # brightness / speed
viactl set --effect "solid reactive" -c red
viactl set --off
viactl set -c purple --temp # don't save to EEPROM
viactl effects --side # sidelight effects
viactl set --side --effect "rainbow swirl 3" # any `set` option works with --side
viactl set --side -c '#ff0000' -b 60%
viactl set --side --off
viactl status --side
viactl keymap --layer 0
viactl remap 0 3 0 KC_LCTL # layer 0, row 3, col 0 (Caps) -> Ctrl
viactl remap 1 0 1 KC_MPLY # Fn+F1 -> play/pause
viactl macro # list macros
viactl macro 0 'git status{KC_ENT}'
viactl macro 1 '{+KC_LCTL}{KC_C}{-KC_LCTL}{50ms}copied'
viactl remap 1 0 12 M0 # Fn+F12 types macro 0
viactl reset keymap --yes # or: macros | everythingKeycodes can be written as KC_A, A, ESC, MO(1), TG(2), LCTL(KC_C),
LT(1,KC_SPC), M0, KC_TRNS, KC_NO, BT_DEV1…DEV_USB, or raw hex
0x7E00. Hover a key in the GUI to see its row and column.
Add --demo to any command to try it against an emulated keyboard.
- "Permission denied": run
./install.shand replug the keyboard. Not an Akko? Add your vendor ID to70-viactl.rulesfirst (see Setup). - "No VIA keyboard found" / "did not answer": switch the keyboard to wired/USB mode (see the keyboard's manual) and use a data-capable USB cable.
- "does not support command …": the firmware doesn't implement that VIA feature. Lighting and keymap commands are separate, so the others still work.
Development: python3 -m unittest -v tests/test_viactl.py
- Finding the keyboard.
via.pyscans/sys/class/hidraw/*and reads each device's HID report descriptor, looking for VIA's raw-HID interface (usage page0xFF60, usage0x61). Akko boards (342d) are preferred, but any VIA keyboard is found the same way. - Talking to it. The VIA protocol is 32-byte request packets written to
/dev/hidrawN, each answered by a 32-byte reply. No libusb or hidapi is needed, onlyos.read/os.writeandselectfor timeouts. - Lighting uses VIA's custom-value commands (
0x07set,0x08get,0x09save to EEPROM). Per-key backlight is QMK's RGB-matrix channel (3); the side strip answers on the rgblight channel (2). Colors are QMK hue and saturation, converted from/to RGB. - Keymap is read in bulk with the dynamic-keymap buffer commands in
28-byte chunks.
keycodes.pyturns 16-bit QMK keycodes into names (KC_A,LT(1,KC_SPC), …) and back, taking the VIA protocol version into account.layout.pyholds the physical layout the GUI draws. - Macros (
macros.py) are encoded into VIA's shared macro buffer: NUL-separated strings with escape codes for tap, press, release and delay. - Front ends:
cli.py(argparse) andgui.py(GTK 3 via PyGObject). - Tests run against
fake.py, an in-memory keyboard that speaks the same packet protocol, which is also what--demouses.
Bug reports and pull requests are welcome.
- Report bugs and ask questions in issues.
- Run the tests before opening a pull request:
python3 -m unittest -v tests/test_viactl.py. They use an emulated device, so no hardware is needed, and they also run automatically on every pull request. - Use only the Python standard library (no third-party dependencies).
viactl/via.py,viactl/fake.pyare also bundled in clcr, the Computer Lighting Control Center. You don't need to change clcr yourself: after your pull request is merged here, clcr's automatic sync opens a pull request there with the change. If you change functions or classes in these files, say so in your pull request, since clcr's GUI uses them.- Want to add a different device or brand? See clcr's CONTRIBUTING.md.
Maintained by Juha Väisänen (@vaisajuh).
Part of a small set of Linux lighting tools, all pure Python with no third-party dependencies:
- clcr: Computer Lighting Control Center, one desktop app for lighting across brands and devices (bundles the drivers below)
- viactl (this repo): VIA/QMK keyboards (tested on Akko 5075B Plus-S): RGB backlight, sidelights, keymap and macros
- caselight: motherboard and case lighting (currently ASUS Aura)
- logiled: Logitech G502 HERO mouse: lighting, DPI, polling rate and onboard mode
MIT. See LICENSE.