A command-line tool to configure the AJAZZ AK820 Pro keyboard from macOS — set the screen clock, RGB lighting, and sleep timer, all without the Windows-only official software.
Connect by USB-C cable. Configuration only works over a wired USB connection. Bluetooth and the 2.4 GHz dongle do not expose the control channel this tool needs (the keyboard's own software says the same — config requires USB or 2.4 GHz, and on macOS specifically only the wired cable works). Your settings are written to the keyboard's onboard memory, so after configuring over USB you can unplug and keep using them over Bluetooth.
- macOS (Apple Silicon or Intel)
- Python 3.11+ (examples use
python3.13) - The keyboard connected with a USB-C data cable (a charge-only cable will not work)
# from the project folder
python3.13 -m venv .venv
source .venv/bin/activate
pip install -e .If installing fails while building hidapi, install the library first and retry:
brew install hidapi
pip install -e .Every command below assumes the virtualenv is active (source .venv/bin/activate).
ak820 identify # confirm the keyboard is connected
ak820 sync-clock # set the keyboard's clock to your Mac's current time
ak820 set-rgb --mode static --color 00AAFF # solid cyan lightingCheck that the tool can see the keyboard (read-only — changes nothing).
$ ak820 identify
Manufacturer: SONiX
Product: AK820
Serial:If you instead see No AK820 device found, see Troubleshooting.
# Set the keyboard clock to your Mac's current local time (most common use)
ak820 sync-clock
# Set a specific date/time (format: "YYYY-MM-DD HH:MM:SS", 24-hour)
ak820 sync-clock --time "2026-06-30 09:15:00"The keyboard's little screen must be on its clock face to see the result. The clock
keeps ticking on its own afterward; re-run sync-clock any time it drifts.
# Solid colors (use the "static" mode)
ak820 set-rgb --mode static --color FF0000 # solid red
ak820 set-rgb --mode static --color 00FF00 --brightness 3 # dimmer green
# Animated effects with a fixed color
ak820 set-rgb --mode breath --color 8000FF --speed 2 # purple breathing
# Rainbow / multi-color effects (ignore --color, use --rainbow)
ak820 set-rgb --mode spectrum --rainbow --brightness 5 --speed 3
ak820 set-rgb --mode rolling --rainbow --direction right
# Turn the lighting off
ak820 set-rgb --mode offOptions
| Option | Values | Default | Notes |
|---|---|---|---|
--mode |
see list below | static |
the lighting effect |
--color |
RRGGBB hex |
FFFFFF |
fixed color (ignored when --rainbow is set) |
--rainbow |
flag | off | cycle colors instead of a fixed color |
--brightness |
0–5 |
5 |
0 is off |
--speed |
0–5 |
3 |
animation speed (where applicable) |
--direction |
left right up down |
left |
for directional effects |
Modes: off, static, single-on, single-off, glittering, falling,
colourful, breath, spectrum, outward, scrolling, rolling, rotating,
explode, launch, ripples, flowing, pulsating, tilt, shuttle.
Tip:
staticshows your exact--colorsteady;spectrum/colourful/rollinglook best with--rainbow.
For quick, named lighting moods there's a small script — presets/ak820-preset:
presets/ak820-preset list # show all presets
presets/ak820-preset focus # dim steady blue (low distraction)
presets/ak820-preset party # bright, fast rainbow
presets/ak820-preset chill # slow rainbow drift
presets/ak820-preset demo # cycle through several (~15s)Available presets: focus, work, calm, chill, gaming, party, night, off, demo.
The script finds the ak820 CLI automatically (it uses the repo's .venv), so you don't even
need to activate the virtualenv. Make your own by editing presets/ak820-preset — each
preset is one line of set-rgb options; copy a line, rename it, and tweak the --mode /
--color / --brightness / --speed.
How long until the lighting sleeps when the keyboard is idle.
ak820 set-sleep 5 # sleep after 5 minutes
ak820 set-sleep 30 # sleep after 30 minutes
ak820 set-sleep 0 # never sleepAllowed values: 0 (never), 1, 5, 30 minutes.
If the screen clock freezes or the display gets stuck (most often after an interrupted command), this clears the keyboard's pending state and re-syncs the clock:
ak820 recover # clear stuck state + re-sync clock to now
ak820 recover --no-resync # just clear the stuck state, leave the clock as-isYou should not normally need this — but it's a one-liner alternative to unplugging the keyboard.
| Symptom | Cause & fix |
|---|---|
No AK820 device found |
The keyboard isn't reachable over USB. Connect it with a USB-C data cable (not the 2.4 GHz dongle, not Bluetooth, not a charge-only cable). Then re-run ak820 identify. |
| Commands run but nothing changes | You're likely connected via the dongle or Bluetooth — those don't expose the control channel. Switch to the USB-C cable. |
| Screen clock is frozen / stuck | Run ak820 recover. If it's still stuck, unplug the cable for ~5 seconds and replug (nothing is written to permanent memory, so it comes back clean). |
OSError: open failed |
Another program is holding the keyboard's interface. Quit other keyboard apps, or unplug/replug the cable, then retry. |
pip install fails building hidapi |
Run brew install hidapi, then pip install -e . again. |
command not found: ak820 |
Activate the virtualenv first: source .venv/bin/activate. |
| Python version error on install | Use Python 3.11+. Create the venv with python3.13 -m venv .venv. |
RGB --color seems ignored |
Some modes are multi-color; for a single steady color use --mode static. With --rainbow the color is intentionally ignored. |
Clock shows the wrong time after sync-clock |
Make the keyboard's screen show its clock face (not an image/GIF), then run ak820 sync-clock again. |
- LCD image / GIF upload is not supported on macOS. The screen's image data uses a bulk USB interface that macOS does not let user programs access (it works on Linux, and in the Windows software). Clock, lighting, and sleep are unaffected.
- Key remapping / macros are not implemented yet.
The keyboard is a SONiX-based device (USB VID 0x0C45). This tool talks to its vendor
HID control interface (0xFF13) over the wired USB connection using 64-byte HID
feature-report transactions (START → preamble → data → FINISH). Settings are saved to
the keyboard's onboard memory.
More docs:
docs/protocol.md— byte-level HID protocoldocs/DISCOVERY-LOG.md— how it was reverse-engineered (the path, blockers, and learnings)docs/REMAP-RESEARCH.md— the open key-remap problemdocs/USB-CAPTURE-GUIDE.md— capture →ak820 replayworkflow
Install with dev tools and run the test suite:
pip install -e ".[dev]"
pytestMost tests are pure and run anywhere. The keymap tests need the keyboard's layout file,
which is extracted from the proprietary Windows installer and not redistributed here — so
on a fresh clone they skip automatically. To run them, extract the installer locally to
extracted/app/ (see docs/protocol.md).
Protocol details were reverse-engineered with the help of these community projects:
- gohv/EPOMAKER-Ajazz-AK820-Pro
- TaxMachine/ajazz-keyboard-software-linux
- Aiacos/ajazz-control-center
- wsclx/ak820pro-modder
MIT © gusleig