AK820 Linux Driver

Userspace Linux controller for Ajazz / Evision AK820 keyboards (320f:505b). It talks to the keyboard over hidraw HID reports, so no kernel module is needed.

Current supported surface:

• firmware RGB modes: static, breath, spectrum, rain, stars, wave, and others;
• custom per-key RGB writes for all mapped keys;
• terminal studio UI with a centered keyboard layout and mouse/key selection;
• flicker-free live animations through the keyboard audio-stream protocol;
• game mode with Snake on the keyboard LEDs;
• hardware audio-reactive lighting stream, without rewriting the full custom RGB table every frame;
• Spotify lyrics overlay for music modes;
• background daemon with optional systemd autostart.

Quick Start

cd ~/Projects/ak820-linux-driver
./bin/ak820ctl devices
sudo ./bin/ak820ctl mode static --color '#00aaff' --brightness 5
sudo ./bin/ak820ctl studio
sudo ./bin/ak820ctl live-animation cosmic-rift
sudo ./bin/ak820ctl game snake

Start the current music driver mode directly:

sudo ./bin/ak820ctl music-reactive --engine hardware --style type1
sudo ./bin/ak820ctl music-reactive --engine hardware --style type2 --lyrics-overlay

Start it in the background, then close the TUI or terminal:

sudo ./bin/ak820ctl daemon start --style type1 --color-mode random
./bin/ak820ctl daemon status

Permissions

Without udev rules, many distros expose /dev/hidraw* as root:root 0600, so write commands need sudo. Install the included rule to use the tool as your regular user:

sudo install -m 0644 packaging/60-ak820.rules /etc/udev/rules.d/60-ak820.rules
sudo udevadm control --reload-rules
sudo udevadm trigger -s hidraw

Unplug and reconnect the keyboard after installing the rule if permissions do not update immediately.

Music-reactive mode reads the current PipeWire/PulseAudio monitor source with parec. Spotify lyrics overlay also needs Spotify to expose MPRIS metadata via playerctl; synced lyrics are fetched from LRCLIB.

Command Overview

./bin/ak820ctl devices
./bin/ak820ctl input-devices
./bin/ak820ctl dump-descriptor

sudo ./bin/ak820ctl mode breath --color 255,80,20 --brightness 3 --speed 2
sudo ./bin/ak820ctl off
sudo ./bin/ak820ctl sleep 30m

sudo ./bin/ak820ctl paint-index 12 '#ff0000' --base white
sudo ./bin/ak820ctl paint-key esc '#ff0000' --base white
./bin/ak820ctl keymap --all
sudo ./bin/ak820ctl scan-index --start 0 --end 20 --color '#00ff00'
sudo ./bin/ak820ctl scan-keys --delay 2
sudo ./bin/ak820ctl listen-keys --pressed --release
sudo ./bin/ak820ctl shortcut-help

sudo ./bin/ak820ctl studio
sudo ./bin/ak820ctl animate wave
sudo ./bin/ak820ctl live-animation cosmic-rift
sudo ./bin/ak820ctl game snake
sudo ./bin/ak820ctl music-reactive --engine hardware --style type1
./bin/ak820ctl daemon status
./bin/ak820ctl replay-pcap ~/capture.pcapng

Use --hidraw /dev/hidrawN when multiple compatible interfaces are present and you want to force a specific device. Use --transport feature or --transport output while probing protocol differences between AK820 variants.

replay-pcap can replay 64-byte report_id=04 packets captured from the official Windows tool through USBPcap. This was the starting point for matching the non-Pro 320f:505b AK820 protocol.

Studio TUI

Run:

sudo ./bin/ak820ctl studio

The studio opens an interactive terminal editor with a centered keyboard layout and a clickable color palette.

• click a key with the mouse or press its character to select it;
• press Enter or Space to paint it with the current brush;
• use arrow keys or Tab to move selection;
• press S to sync the current table to the keyboard;
• press H to enter a custom hex brush;
• press L for the live animation menu;
• press G for game mode;
• press W or O to fill white/off;
• press A for animation menu;
• press M for music/daemon menu;
• press Q to quit.

The music menu can select type1 or type2, toggle lyrics overlay, switch between random and fixed colors, set the fixed color, start/stop the daemon, and toggle autostart. If the daemon is running, changing music settings in the TUI updates its config live. Closing the TUI does not stop the daemon.

Live Animation

Run a no-refresh live animation directly:

sudo ./bin/ak820ctl live-animation cosmic-rift
sudo ./bin/ak820ctl live-animation aurora-storm --fps 45
sudo ./bin/ak820ctl live-animation neon-comets --brightness 0.85
sudo ./bin/ak820ctl live-animation bottom-fire

These modes use the same 0x12 audio-stream RGB path as the music visualizer, so they update live without the full custom-RGB refresh blink. In the studio TUI, press L to open the Live Animation section and choose an effect. bottom-fire keeps Space/Alt/Ctrl hot, raises random flame tongues upward, flashes the top row sometimes, and boosts the flame while you type.

Game Mode

Run Snake directly on the keyboard LEDs:

sudo ./bin/ak820ctl game snake
sudo ./bin/ak820ctl game snake --fps 9

Use the arrow keys to move. The snake wraps across the physical keyboard rows, red/orange is food, and the rest of the keyboard stays dark so the bright green snake is easy to see. Press Esc to stop. In the studio TUI, press G, choose Snake, then use the same arrow controls; r restarts the game.

Shortcut Help

Run:

sudo ./bin/ak820ctl shortcut-help

While the mode is running, hold a main shortcut key such as Ctrl, Alt, Shift, Win, Fn, or Caps. The keyboard keeps refreshing possible next keys in amber while the key is held, held keys in blue, and a fully matched shortcut in green. Unselected keys stay on a dim blue-black background so the whole layout remains visible; use --idle-color '#000000' if you want the old dark background. If you hold a second key, the list narrows to shortcuts that contain the exact held key set.

Press Esc by itself to stop the helper. Terminal Ctrl+C is ignored by default so you can inspect Ctrl+C as a real shortcut; use --allow-ctrl-c-stop to restore the usual terminal behavior.

Useful commands:

./bin/ak820ctl shortcut-help --list --app all
sudo ./bin/ak820ctl shortcut-help --app browser
sudo ./bin/ak820ctl shortcut-help --app terminal --candidate-color '#ff00ff'
sudo ./bin/ak820ctl shortcut-help --refresh-rate 30
sudo ./bin/ak820ctl shortcut-help --dry-run

Shortcut sources:

• built-in common, browser, terminal, editor, and system shortcuts;
• GNOME gsettings keybindings when available;
• optional custom JSON at ~/.config/ak820-driver/shortcuts.json.

Example custom profile:

{
  "shortcuts": [
    {"combo": "ctrl+alt+h", "title": "My helper", "context": "system"},
    {"combo": "ctrl+shift+k", "title": "My app action", "app": "browser"}
  ]
}

--app auto tries to detect the focused app with desktop tools such as xdotool. On Wayland this may be unavailable, so use --app browser, --app terminal, --app code, or --app all when you want a forced profile.

Music-Reactive Lighting

The useful music modes should run through the hardware audio stream:

sudo ./bin/ak820ctl music-reactive --engine hardware --style type1
sudo ./bin/ak820ctl music-reactive --engine hardware --style type2

--engine auto also chooses the hardware stream for type1, type1text, type2, type3, type4, and bars. The hardware stream sends compact audio RGB packets instead of re-applying the full custom RGB table every frame, so it avoids the visible refresh flicker from software per-key animation streaming.

Available driver-style modes:

• type1: Diagonal DJ Meter. A colorful diagonal meter grows from the lower left corner toward the upper right corner through the center.
• type2: Central Pulse Spectrum. A radial spectrum grows from the Y/U/H/J center area; different sectors react to different audio bands.
• type1text: legacy alias for type1 --lyrics-overlay.
• bars, smooth, type3, type4: experimental/compatibility styles.

Color modes:

sudo ./bin/ak820ctl music-reactive --style type1 --color-mode random
sudo ./bin/ak820ctl music-reactive --style type2 --color-mode fixed --color '#ff0066'

Lyrics overlay can be used on top of any type-style music mode:

sudo ./bin/ak820ctl music-reactive --style type1 --lyrics-overlay
sudo ./bin/ak820ctl music-reactive --style type2 --lyrics-overlay --color-mode random

The overlay reads the current Spotify track and position through playerctl, fetches lyrics from LRCLIB, and lights the active word's letters in red. Lookup first tries the exact Spotify metadata, then a normalized LRCLIB search; if only plain lyrics are available, the driver approximates timing across the track. If the status says playerctl cannot get Spotify data, Spotify/MPRIS data is not currently available to the process.

Useful tuning flags:

sudo ./bin/ak820ctl music-reactive --style type1 --gain 4 --fps 90
sudo ./bin/ak820ctl music-reactive --style type2 --source bluez_output.xx.monitor
sudo ./bin/ak820ctl music-reactive --style type1 --dry-run --duration 10

Background Daemon

The daemon keeps the selected music mode running after the TUI exits.

sudo ./bin/ak820ctl daemon start --style type1 --color-mode random
sudo ./bin/ak820ctl daemon start --style type2 --lyrics-overlay --color-mode fixed --color '#00aaff'
./bin/ak820ctl daemon status
sudo ./bin/ak820ctl daemon stop

Starting the daemon again while it is already running updates the saved config. The daemon reloads that config while running, so the TUI can change style, lyrics, and color mode without restarting the process. daemon stop also leaves the keyboard in a stable static mode so the previous audio stream does not keep looking alive after the process exits.

Default paths:

• config: ~/.config/ak820-driver/config.json
• runtime/logs: /tmp/ak820-<uid>/ak820-driver/
• log file: /tmp/ak820-<uid>/ak820-driver/daemon.log

Check status and logs:

./bin/ak820ctl daemon status
tail -f /tmp/ak820-$(id -u)/ak820-driver/daemon.log

Autostart

Install a systemd service so the daemon starts after reboot:

cd ~/Projects/ak820-linux-driver
sudo ./bin/ak820ctl daemon install-autostart --style type1 --color-mode random

Examples:

sudo ./bin/ak820ctl daemon install-autostart --style type2 --lyrics-overlay --color-mode random
sudo ./bin/ak820ctl daemon install-autostart --style type2 --color-mode fixed --color '#00aaff'

The service is installed at /etc/systemd/system/ak820-driver.service and is enabled immediately. The service runs as root for HID access, but stores config under the original user's home and exports AK820_USER_UID/GID so audio and Spotify helpers can target the user session.

Inspect or remove autostart:

./bin/ak820ctl daemon status
sudo systemctl status ak820-driver
sudo journalctl -u ak820-driver -b
sudo ./bin/ak820ctl daemon uninstall-autostart

If audio is not ready during early boot, the daemon logs a waiting message and retries.

Animations

animate supports two different paths.

Hardware effects are firmware-driven and do not flicker:

sudo ./bin/ak820ctl animate wave
sudo ./bin/ak820ctl animate stars
sudo ./bin/ak820ctl animate rain
sudo ./bin/ak820ctl animate aurora
sudo ./bin/ak820ctl animate cyberpunk
sudo ./bin/ak820ctl animate matrix

Software per-key effects generate full custom RGB frames:

sudo ./bin/ak820ctl animate letters --engine software --fps 2 --duration 20
sudo ./bin/ak820ctl animate qwerty --engine software --fps 2 --duration 20
sudo ./bin/ak820ctl animate wave --engine software --stream full

Software effects can still flicker on this keyboard because they rewrite custom RGB data repeatedly. Prefer hardware effects or music-reactive --engine hardware for live no-refresh animation.

Per-Key RGB And Key Map

The custom RGB table has 128 RGB slots at keyboard memory offset 0x0400. paint-index writes a generated full table, while paint-key uses the mapped key names below.

Useful mapping commands:

./bin/ak820ctl keymap
./bin/ak820ctl keymap --all
sudo ./bin/ak820ctl scan-index --start 0 --end 127 --base white --color '#ff0000'
sudo ./bin/ak820ctl scan-keys --base white --delay 2

Current mapped keys:

Esc 0 | F1 8 | F2 16 | F3 24 | F4 32 | F5 40 | F6 48 | F7 56 | F8 64 | F9 72 | F10 80 | F11 88 | F12 96
` 1 | 1 9 | 2 17 | 3 25 | 4 33 | 5 41 | 6 49 | 7 57 | 8 65 | 9 73 | 0 81 | - 89 | = 97 | Backspace 105 | Del 114
Tab 2 | Q 10 | W 18 | E 26 | R 34 | T 42 | Y 50 | U 58 | I 66 | O 74 | P 82 | [ 90 | ] 98 | \ 106 | Home 121 | PgUp 122
Caps 3 | A 11 | S 19 | D 27 | F 35 | G 43 | H 51 | J 59 | K 67 | L 75 | ; 83 | ' 91 | Enter 107 | End 123 | PgDn 115
LShift 4 | Z 20 | X 28 | C 36 | V 44 | B 52 | N 60 | M 68 | , 76 | . 84 | / 92 | RShift 108 | Up 116
LCtrl 5 | Win 13 | LAlt 21 | Space 45 | RAlt 77 | Fn 85 | RCtrl 93 | Left 109 | Down 117 | Right 125

listen-keys reads Linux evdev input events from every AK820 non-mouse event interface without grabbing the device, so normal typing continues. Use --release to also show key releases, --hold for autorepeat events, and --event /dev/input/eventN to force one interface while debugging.

Protocol Status

The RGB packet layout is based on reverse-engineered AK820 / EVision HID traffic. The confirmed device reports as Evision AK820 with VID/PID 320f:505b.

Implemented:

• standard EVision lighting mode packets;
• custom RGB table writes;
• OpenRGB-style custom writes for some stream strategies;
• hardware audio-stream packets for music-reactive modes;
• Linux evdev key listening across AK820 keyboard interfaces.

Not implemented yet:

• macro programming;
• LCD/image upload;
• vendor Windows GUI profile import/export.