Ajazz Control

Configure the AJAZZ AK980 V2 from macOS — lighting, the TFT screen, key remapping, shortcuts, and live sports scores on the keyboard itself.

Download the app →

by d991d

---

AJAZZ ships configuration software for Windows only. This is the macOS equivalent, written from scratch by reverse-engineering the USB protocol.

No driver required

That is worth stating plainly, because it is the thing everyone gets wrong.

The AK980 V2 is built on a Sonix SN32F299 and enumerates under Microdia's USB vendor id (0x0C45:0x8009). Every configuration command — lighting, macros, key remaps, the clock, the screen — travels over a vendor-defined HID collection, and macOS lets any ordinary userspace process talk to one of those through IOHIDManager.

No kernel extension. No DriverKit system extension. No entitlement, no disabled SIP, no sudo. The Windows "driver" is a configuration app calling HidD_SetFeature and WriteFile; this is the same app in Swift.

What it does

Lighting	All 20 effects, colour, brightness, speed, direction, rainbow
Screen	Any image or GIF on the 240×135 panel
Live sport	Scores pushed to the panel automatically — F1, Premier League, Champions League, La Liga, Serie A, Bundesliga, Ligue 1, MLS, NFL, NHL, ATP, WTA
Clock	Set the keyboard's clock and date from the Mac
Keys	Per-key colours and remapping across the full 97-key layout
Shortcuts	Bind a key combination to an app, a file or link, the music, or an AppleScript
Settings	Win-key lock, Alt+F4 / Alt+Tab lock, Fn behaviour, sleep timeout, Num Lock indicator

Two of these do not exist in the Windows software either.

Live sport polls public scoreboard feeds and repaints the panel only when something actually changes — a goal, a lap, a different match — because every repaint writes to the keyboard's flash.

Shortcuts binds a system-wide key combination to opening an app, opening a file or web page, controlling the music, or running a short AppleScript. The music controls go to whichever of Spotify or Apple Music is actually playing, rather than guessing at one of them.

The two combine into something the keyboard cannot do alone: macOS ignores F13 to F20 completely, so remapping a key to one of those and binding it here gives you a genuine macro key that can clash with nothing.

It remembers your setup

Switching the keyboard between USB, Bluetooth and the 2.4 GHz dongle makes the firmware reload its own defaults — the AJAZZ startup animation returns and your picture is gone. Unplugging does the same. The keyboard keeps no record of what you configured.

So the Mac does. Your lighting, behaviour settings, clock and picture are stored on disk and sent again a couple of seconds after the keyboard reappears, which also means they survive quitting the app and rebooting.

Install

Download Ajazz-Control.zip from the latest release, unzip it, and drag Ajazz Control.app into /Applications.

The app is not notarised by Apple, so the first launch needs one extra step: right-click the app → Open → Open. After that it opens normally.

Connection

Use the USB-C cable. Over Bluetooth the keyboard exposes only its typing interface — the vendor collection that carries every configuration command is not there, so nothing can reach it.

The 2.4 GHz dongle is more interesting, and now investigated. It does expose two vendor collections (0xFF59 and 0xFF60), so the channel exists — but neither declares a Feature report, and every control command in the wired protocol is a feature report. Sending the same commands as output reports, with the keyboard awake and typing, gets accepted by macOS and ignored by the firmware; an eight-variant sweep of the clock packet fared no better. The wireless protocol is a different dialect, which agrees with the vendor binary carrying separate wireless builders. Full notes in docs/PROTOCOL.md; finishing it needs a USB capture over the dongle, and help is welcome.

Shortcuts are the exception: they are hot keys registered with macOS, so they work over any connection, including Bluetooth.

Build it yourself

Requires macOS 13 or later and the Xcode command line tools (xcode-select --install).

git clone https://github.com/d991d/ajazz-control.git
cd ajazz-control
./Tools/build-app.sh
open ~/Applications/"Ajazz Control.app"

The command-line tool

ajazzctl ships inside the app bundle and exposes everything the GUI does, plus the probes used to work the protocol out in the first place.

AJAZZ=/Applications/"Ajazz Control.app"/Contents/MacOS/ajazzctl

"$AJAZZ" probe                       # what the keyboard exposes
"$AJAZZ" time                        # sync the clock
"$AJAZZ" rgb --mode spectrum         # lighting
"$AJAZZ" screen picture.gif          # put an image on the panel
"$AJAZZ" sports --preview            # render a scoreboard card to a PNG

What was learned about the protocol

Documented in full in docs/PROTOCOL.md. The findings that no other public source has:

• Data packets carry no 0x04 magic. Only control frames do. Sending the magic on a data packet gets it rejected.
• The lighting mode table is off by one from the Windows UI. The UI lists "LED Off" last; on the wire it is 0x00.
• The frame trailer is AA 55, in that order.
• The 04 72 screen config needs 0x03 at payload[2], a format selector the vendor app always sets and never explains.
• Every pixel chunk must be acknowledged before the next is sent. Blind transfers garble the panel.
• On macOS the transport has to be split: output reports die on the 0xFF13 collection but work on 0xFF68. Control frames go to 0xFF13 as feature reports, 4 KiB pixel blocks to 0xFF68 as output reports. This split is what makes the screen work at all — every single-collection approach fails.
• Feature read-back byte 3 is a status oracle: 0x01 accepted, 0xFF rejected. Nearly the whole protocol was mapped by sending candidate packets and reading that byte.
• A frame delay is one byte in units of 2 ms, so the longest a frame can be held is 510 ms. A card meant to sit there for six seconds has to be sent twelve times over.
• macOS never sets the Num Lock LED bit, because macOS has no Num Lock — the keypad is always numeric. That is why the indicator on the panel stays dark on a Mac while the same keyboard toggles it happily on Windows. The app can send that report itself.

Layout

Sources/AjazzKit      IOKit transport and pure, testable packet builders
Sources/SportsKit     Scoreboard feeds and the 240x135 renderer
Sources/AjazzControl  The SwiftUI app, including the hot-key machinery
Sources/ajazzctl      Command-line tool and protocol probes
Tools/                Shell probes used during reverse engineering
docs/                 Protocol notes, capture method, download page

Author

Written by d991d — protocol reverse engineering, AjazzKit, SportsKit, the app and the command-line tool.

• GitHub: https://github.com/d991d
• This project: https://github.com/d991d/ajazz-control

Issues and pull requests are welcome, particularly hardware confirmations from other AK980 variants — the protocol notes mark which commands are verified and which are decoded but untested.

Licence

MIT — see LICENSE. Scoreboard data comes from ESPN's public endpoints and the jolpi.ca Ergast mirror; neither needs an API key, and neither is affiliated with this project.

Not affiliated with AJAZZ. Nothing here is officially supported. It talks to your keyboard's flash, which is a thing you should know before running it.