ak820ctl

linux driver for the ajazz ak820 max plus (the tri-mode rgb one). it does lighting, per-key colors, key remaps, macros, sleep/response settings and battery status, over the usb cable or the 2.4g dongle.

install

pipx install ak820ctl

then let your user talk to the keyboard without sudo:

sudo curl -o /etc/udev/rules.d/70-ajazz-ak820.rules \
  https://raw.githubusercontent.com/shrey715/ak820ctl/main/udev/70-ajazz-ak820.rules
sudo udevadm control --reload && sudo udevadm trigger

unplug and replug the dongle or cable after that.

usage

run ak820ctl with no arguments to get the tui. it has tabs for lighting, per-key rgb, remaps, macros and settings. you click keys on the keyboard map to select them, pick a color, and hit upload. battery refreshes every 5 seconds.

everything is also available as plain commands if you want to script it:

ak820ctl status                  # battery + link state
ak820ctl modes                   # list lighting effects
ak820ctl light 7 -b 5            # static light, full brightness
ak820ctl light 8 -s 3            # breathing at speed 3
ak820ctl custom -a 101010 esc=red w=cyan a=cyan s=cyan d=cyan
ak820ctl sleep 30                # 5 | 15 | 30 | never
ak820ctl response 1              # key response gear, 1 is fastest
ak820ctl fn-switch fn            # normal | fn
ak820ctl remap capslock esc
ak820ctl remap --fn f1 playpause
ak820ctl remap --list-targets
ak820ctl macro f12 +lctrl c -lctrl   # ctrl+c on f12
ak820ctl reset-keys
ak820ctl menu                    # old-school prompt menu

macro events: +key presses, -key releases, a bare key taps it, and @ms sets the delay after an event (like a@200). flags like --fn or -r 3 go before the key name.

-n / --dry-run prints the packets and sends nothing, and -v shows every packet that goes out. both work with the tui too (ak820ctl -n).

what works and what doesn't

decoded from the driver: lighting effects with brightness/speed/direction, per-key colors (custom mode), sleep timer, key response time, the fn switch, remapping to keys or media functions, keyboard macros, and the battery/link query.

still open (see the issues tab): what the effect color index numbers mean, live streaming frames, one unidentified command (0x0A), firmware updates and mouse-button assignments.

if you own one of these, running ak820ctl -v status and posting what comes back helps a lot.

how it works

every command is a 64-byte hid output report that starts with aa 55 cc 33, sent to the vendor hid interface (usage page 0xff02). PROTOCOL.md has the full command table and the driver function each finding came from.

dev

git clone https://github.com/shrey715/ak820ctl && cd ak820ctl
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

license

mit. "ajazz" and "ak820" are their owner's trademarks and only used here to say what hardware this is for.