AJAZZ Keyboard for Omarchy (AK820 V2 fork)

A native Omarchy Quattro top-bar controller for the AJAZZ AK820 family — extended with full AK820 V2 support, a music visualizer, wallpaper sync, effect auto-shuffle, and dedicated TFT screens. No Windows driver needed.

Forked from ESHAYAT102/ajazz-keyboard-omarchy-plugin, which targets the AK820 MAX. All V2 features below are new in this fork. Upstream is kept as a git remote (upstream) for reference.

Features

• AK820 V2 wired support (0C45:8019): HID vendor page FF68 with AA/55 framed 64-byte output reports. The original MAX path (0C45:8009, FF13:0001 feature reports) is untouched.
• Music visualizer: per-key RGB driven by system audio (PipeWire monitor via ffmpeg) with 4 patterns — radial, pulse, equalizer bars, wave — rainbow or solid wave colors, background on/off, adjustable sensitivity, and live config reload (no stream restart).
• Wallpaper sync: extracts the most vibrant color from the current Omarchy background and follows wallpaper changes in the background, with a live preview and a selectable lighting effect to play the color with.
• Auto-shuffle: rotates lighting effects on a timer (1 / 5 / 15 / 30 min presets), independently per mode. Music stays exclusive; a manual effect pick always wins and stops the shuffler.
• Dedicated TFT screens (V2 knob positions): live weather (OpenWeatherMap) and CPU/GPU stats pushed over command 52.
• TFT slot tools: weather/stats/test screens plus GIF backup/restore.

Requirements

• Omarchy Quattro on Linux
• Python 3, Pillow (python-pillow), ffmpeg (audio capture for the visualizer)
• udev and Linux hidraw support
• Keyboard connected in wired USB mode:
  • AK820 V2 → USB identity 0C45:8019, HID collection FF68
  • AK820 MAX → USB identity 0C45:8009, HID collection FF13:0001

Bluetooth device 0C45:FEFE exposes only standard keyboard, mouse, media, and lock-LED reports, so it cannot carry these RGB commands. The unverified 05AC:024F 2.4 GHz receiver is intentionally read-only as well.

Install

Install the plugin through Omarchy's transactional Git installer:

omarchy plugin add https://github.com/AndoNull/ajazz-keyboard-omarchy-plugin.git --enable

The RGB interface is root-owned by default. Install the included udev rule to grant the active desktop session access only to USB interface 3:

PLUGIN_DIR="$HOME/.config/omarchy/plugins/esh.ajazz-keyboard"
sudo install -Dm644 "$PLUGIN_DIR/udev/70-ajazz-ak820.rules" \
  /etc/udev/rules.d/70-ajazz-ak820.rules
sudo udevadm control --reload-rules

Reconnect the keyboard in wired mode after installing the rule. The panel detects the supported interface automatically.

Usage

• Left-click the keyboard icon to open or close the panel.
• Press Escape to close the panel.
• LIGHTING card: effect dropdown, color picker, brightness, speed, direction, rainbow mode, plus the normal-mode auto-shuffle toggle.
• Music card: toggle the visualizer, pick a pattern, background, wave colors, and sensitivity. The header shows MUSIC · <PATTERN>.
• Wallpaper sync card: toggle follow mode, see the detected color and source wallpaper, choose the effect, plus its own auto-shuffle toggle. The header shows WALLPAPER · <EFFECT> · <#HEX>.
• Scroll over the bar icon to adjust brightness.
• Right-click the bar icon to toggle lighting power.

The plugin can also be driven through the shell IPC handlers:

omarchy-shell shell summon esh.ajazz-keyboard '{}'
omarchy-shell shell hide esh.ajazz-keyboard

Backend diagnostics

The bundled helper can inspect the connection without writing to hardware:

PLUGIN_DIR="$HOME/.config/omarchy/plugins/esh.ajazz-keyboard"
"$PLUGIN_DIR/bin/ajazz-keyboard" status
"$PLUGIN_DIR/bin/ajazz-keyboard" diagnose
"$PLUGIN_DIR/bin/ajazz-keyboard" apply --effect static --color '#ff3158' --dry-run

status reports music / ambient / cycle blocks with live configs and running flags. Feature commands (all V2):

"$PLUGIN_DIR/bin/ajazz-keyboard" music start --pattern bars --sensitivity 1.4
"$PLUGIN_DIR/bin/ajazz-keyboard" music test
"$PLUGIN_DIR/bin/ajazz-keyboard" music stop
"$PLUGIN_DIR/bin/ajazz-keyboard" ambient once --effect flowing
"$PLUGIN_DIR/bin/ajazz-keyboard" ambient watch
"$PLUGIN_DIR/bin/ajazz-keyboard" cycle watch --mode ambient --interval 300
"$PLUGIN_DIR/bin/ajazz-keyboard" screen weather
"$PLUGIN_DIR/bin/ajazz-keyboard" tft backup

The helper refuses writes unless both the wired VID/PID and vendor collection match. It never opens the standard keyboard input interfaces. Long-running loops (music/ambient/cycle watchers) use pidfiles, handle SIGTERM cleanly, and restore the saved lighting on exit where applicable.

Remove

Remove the plugin through Omarchy:

omarchy plugin remove esh.ajazz-keyboard

The privileged udev rule and optional saved lighting state are separate from the Git checkout. Remove them explicitly if they are no longer wanted:

sudo rm -f /etc/udev/rules.d/70-ajazz-ak820.rules
sudo udevadm control --reload-rules
rm -rf "${XDG_STATE_HOME:-$HOME/.local/state}/omarchy/plugins/esh.ajazz-keyboard"

Reconnect the keyboard once after removing the rule.

Development

Validate the repository root and QML entry points before publishing:

omarchy plugin validate .
/usr/lib/qt6/bin/qmllint -I "$OMARCHY_PATH/shell" \
  BarWidget.qml Panel.qml Service.qml ColorPicker.qml
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -v

The protocol tests cover report size, command order, control markers, RGB and parameter offsets, state persistence, the captured AA 55 trailer, music frame layout (byte-identical golden frames), wallpaper color extraction, and shuffle-pool invariants.

Protocol

The MAX path follows the vendor driver's 35 ms pacing and captured feature-report transaction:

1. 04 18 start, then feature readback
2. 04 13 mode preamble with byte 8 set to 01, then readback
3. 64-byte effect payload
4. 04 02 save, then readback
5. 04 F0 finish, then readback

At the Linux hidraw boundary every feature transfer is prefixed with report ID zero, producing a 65-byte ioctl buffer for the unnumbered 64-byte report.

The V2 path instead uses 64-byte output reports on the FF68 collection with AA <cmd> … framing and 55 <cmd> … acknowledgements. Notable commands (reverse-engineered from the vendor web driver and a Music.exe USB capture):

• 35 LED effect (16-byte payload, brightness/speed are 1–6 on device)
• 50 per-key RGB ([keyId, r, g, b] quads, 80 keys over 6 frames) — music
• 52 screen info (24-byte CPU/GPU/weather payload) — dedicated screens
• 80 TFT user animation (128×128 RGB565 upload)

Implementation details live next to the code that uses them.

Differences vs upstream

Area	Upstream	This fork
AK820 V2 wired	Not supported	Full support (FF68, AA/55)
Music visualizer	No	Yes (4 patterns, live reload)
Wallpaper sync	No	Yes (vibrant color, follow mode)
Auto-shuffle	No	Yes (per-mode, presets)
TFT / dedicated screens	No	Yes (cmd 52/80)
AK820 MAX wired	Yes	Unchanged

License

MIT. See LICENSE.