ak820-linux 0.3.3

New

• New logo: the AK820 Pro's own corner, with the screen next to the up arrow. Used for the window, the app menu entry and the AppImage.
• Stable download link: every release now also has ak820-x86_64.AppImage, so this always gets the latest version:

  curl -LO https://github.com/hcristosm/ak820-linux/releases/latest/download/ak820-x86_64.AppImage

Changed

• README reorganized around the AppImage quick start, with a "Tested on" table and a troubleshooting section. The USB protocol notes moved to docs/PROTOCOL.md.

No changes to the keyboard features since 0.3.2.

AppImage

chmod +x ak820-x86_64.AppImage
./ak820-x86_64.AppImage

Install / upgrade from source

curl -L https://github.com/hcristosm/ak820-linux/archive/refs/tags/v0.3.3.tar.gz | tar xz
cd ak820-linux-0.3.3 && ./install.sh

ak820-linux 0.3.2

New

• AppImage for any distro with glibc 2.35 or newer (Ubuntu 22.04, Debian 12, Fedora 36, Linux Mint 21 or later). Python, Qt and everything else are inside, nothing to install. Run it without arguments for the GUI, or with the usual ak820 commands (./ak820-0.3.2-x86_64.AppImage mode static -c 00ff88).
• ak820 setup installs the udev rule (asks for your password). The GUI offers to do the same the first time it can't open the keyboard, so the AppImage needs no installer.

Changed

• install.sh installs the udev rule through ak820 setup, and warns when libxcb-cursor is missing or ~/.local/bin is not on PATH.
• README: install steps for Ubuntu 24.04 / Linux Mint 22, which have no PySide6 package (PySide6 from pip, plus libxcb-cursor0).

AppImage

chmod +x ak820-0.3.2-x86_64.AppImage
./ak820-0.3.2-x86_64.AppImage

Install / upgrade from source

curl -L https://github.com/hcristosm/ak820-linux/archive/refs/tags/v0.3.2.tar.gz | tar xz
cd ak820-linux-0.3.2 && ./install.sh

ak820-linux 0.3.1

Fix

• ak820 music with no --colors option crashed with ValueError in 0.3.0. The default (classic colors) works now, and a malformed --colors value gets a clear error message. The GUI was not affected.

Everything else is as in 0.3.0 (music mode with meter, center, spectrum and pulse styles).

Install / upgrade

curl -L https://github.com/hcristosm/ak820-linux/archive/refs/tags/v0.3.1.tar.gz | tar xz
cd ak820-linux-0.3.1 && ./install.sh

ak820-linux 0.3.0

⚠️ Use 0.3.1 instead. In 0.3.0, ak820 music without --colors crashes. The GUI is not affected.

What's new: music mode

The keys react to whatever your PC is playing. It works the way the vendor's Windows app does: the PC captures the system audio and streams live per-key frames to the keyboard (op 0x20, about 17 frames per second). Nothing is written to the keyboard's flash, and your saved effect comes back by itself when you stop.

• Styles: Meter (fills left→right), Center (fills outwards from the middle), Spectrum (16-band equalizer, bass on the left, rows fill from the bottom), Pulse (the whole keyboard flashes on each beat and changes color).
• Colors: Classic (green→yellow→red), Rainbow, or two colors of your choice.
• GUI: a new ♫ Music page with Start/Stop, style, colors and sensitivity. Changes apply while it runs, and they're saved with your settings and profiles.
• CLI: ak820 music [--style meter|center|spectrum|pulse] [--colors classic|rainbow|RRGGBB-RRGGBB] [-g SENSITIVITY], stop with Ctrl-C.
• The protocol table in the README now documents op 0x20.

Dependencies

• Music mode needs parec (package pulseaudio-utils). It works with PipeWire too.
• The Spectrum style also needs numpy (python3-numpy). Everything else works without it.

sudo dnf install pulseaudio-utils python3-numpy     # Fedora
sudo apt install pulseaudio-utils python3-numpy     # Debian / Ubuntu

The music mode is only on main (Qt GUI and CLI). The tk-gui branch doesn't have it.

Install / upgrade

curl -L https://github.com/hcristosm/ak820-linux/archive/refs/tags/v0.3.0.tar.gz | tar xz
cd ak820-linux-0.3.0 && ./install.sh

Running install.sh over an older version upgrades it in place.

ak820-linux 0.2.0

What's new

• New GUI, built with Qt 6 (PySide6). Dark theme with a cyan accent, sidebar navigation, and the 20 effects as a clickable gallery instead of a dropdown. Per-key keyboard with rounded, colored keys. Disabled controls now look disabled.
• Settings and profiles from 0.1.x load unchanged (~/.config/ak820/config.json).
• A bad value in the saved settings no longer stops the GUI from opening: it is skipped and reported in the status bar.

⚠️ New dependency: PySide6

The GUI now needs PySide6 instead of Tkinter:

sudo dnf install python3-pyside6 python3-pillow                 # Fedora
sudo apt install python3-pyside6.qtwidgets python3-pil          # Debian 13+ / Ubuntu 24.10+
pip install --user PySide6 pillow                               # anything else

Prefer the lighter Tkinter GUI (now with a dark theme)? It lives on the tk-gui branch.

Install / upgrade

curl -L https://github.com/hcristosm/ak820-linux/archive/refs/tags/v0.2.0.tar.gz | tar xz
cd ak820-linux-0.2.0 && ./install.sh

Running install.sh over 0.1.x upgrades it in place; it tells you which package to install if PySide6 is missing. The command line tool (ak820) is unchanged.

ak820-linux 0.1.1

What's new

• GUI in English. All labels and messages were translated (they were in Portuguese in 0.1.0).
• Remembers your settings. The GUI restores effect, colors, per-key colors and the chosen screen image when you reopen it. Saved in ~/.config/ak820/config.json.
• Named profiles. Type a name and click Save. Load fills in the tabs and applies the profile's lighting to the keyboard. The screen image is remembered but not re-sent, because uploads take a few seconds. Delete asks for confirmation.
• A corrupted config file is kept as config.json.bad instead of being overwritten.

Install / upgrade

curl -L https://github.com/hcristosm/ak820-linux/archive/refs/tags/v0.1.1.tar.gz | tar xz
cd ak820-linux-0.1.1 && ./install.sh

Running install.sh over 0.1.0 upgrades it in place. Dependencies and known limits are the same as in 0.1.0.

ak820-linux 0.1.0

First release: control the AJAZZ AK820 Pro's RGB lighting and 128×128 screen on Linux, no Windows software needed.

Features

• 20 built-in lighting effects with color, rainbow, brightness (0-5), speed (0-5) and direction
• Per-key static colors
• Upload an image or animated GIF (up to 140 frames) to the screen
• Sync the screen clock to your PC
• Command line tool (ak820) and a small Tk GUI (ak820-gui, plus an app-menu entry)
• install.sh installs for your user plus a udev rule for hidraw access; --uninstall removes it all

Verified on hardware

AK820 Pro over wired USB (0c45:8009): static color, per-key colors, rolling and scrolling with both directions, screen GIF (orientation and colors), clock.

Known limits

• Only static, rolling and scrolling were tested on the keyboard. The other effects use the same packet format.
• The 0c45:800a variant is untested. The 2.4 GHz dongle and Bluetooth are not supported.
• Key remapping, macros and the music-reactive mode are not implemented.
• The GUI labels are in Portuguese.

Install

sudo dnf install python3-tkinter python3-pillow     # or: sudo apt install python3-tk python3-pil python3-pil.imagetk
curl -L https://github.com/hcristosm/ak820-linux/archive/refs/tags/v0.1.0.tar.gz | tar xz
cd ak820-linux-0.1.0 && ./install.sh