Skip to content
cobanovPublic

About

Configure ATK / VXE mice on macOS from the terminal, without ATK Hub

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

14 Commits

Folders and files

Repository files navigation

atkctl

Configure ATK and VXE mice on macOS from the terminal, without ATK Hub. It reads firmware versions, battery and settings, changes polling rate, DPI, sleep time and the sensor options, pairs the mouse with its receiver, and finds the macOS problems that make the receiver look dead.

$ atkctl
NK mouse NANO dongle      firmware 1.0.19   connected
mouse (via receiver)      firmware 1.0.14   battery 100%   receiver, 1K

  polling         1000 Hz
  dpi             1600   (stage 3 of 4)
  lift-off        1.2 mm
  sleep           2 min
  debounce        4 ms
  motion-sync     on
  ripple          off
  angle-snapping  off

Quick start

git clone https://github.com/cobanov/atkctl && cd atkctl
swift build -c release
cp .build/release/atkctl ~/.local/bin/
atkctl doctor

For the menu bar app, scripts/build-app.sh --install builds ATKBar.app into /Applications and opens it.

Needs macOS 13 or later and the Swift toolchain that comes with Xcode or the Command Line Tools. The mouse works through its receiver or its cable; with both plugged in, atkctl talks over the cable.

Menu bar app

ATKBar panel ATKBar classic panel

ATKBar keeps the mouse's battery in the menu bar and sends a notification when it drops to 15%. Click it for the settings: DPI stage, polling rate, lift-off, sleep time, debounce, motion sync, ripple control and angle snapping. It reads the mouse again every minute, each time the panel opens, when the receiver is plugged in or out, and after the Mac wakes. While the mouse sleeps the panel keeps its last values.

With no mouse plugged in, Try Demo (or Demo Mode in the settings menu) shows an in-memory mouse whose settings change in the panel only.

The panel comes in two designs: the dark one (left), built around the mouse itself, and the classic macOS one (right). The dark one shows ATK's product photo of the connected model, in the colour picked in its gear menu. ATKBar downloads the photo from ATK's CDN, as ATK Hub does, and keeps it in ~/Library/Caches; offline, it draws the mouse instead. Through a receiver the model is found by asking for the mouse's ID (0x89, then 0x4A). Switch from the gear menu in the dark panel, or with the sparkles button in the classic one. The dark panel hangs from the menu bar by its own arrow; StatusPanel.swift holds that part and depends on nothing else in the app.

On first launch macOS asks to allow ATKBar under Input Monitoring; it needs that to talk to the receiver. The app is signed ad hoc, so a rebuild asks again. Set SIGN_IDENTITY to a signing identity when building to keep the permission.

Commands

Command Does
atkctl / atkctl status [--json] Firmware of mouse and receiver, battery, connection, current settings
atkctl dpi DPI stages, the active one starred
atkctl set <setting> <value> Changes a setting, then reads it back from the mouse
atkctl pair [--yes] Pairs the mouse with the plugged-in receiver (forgets the old pairing)
atkctl doctor [--fix-karabiner] Finds what stops the mouse or ATK Hub from working
atkctl list Connected ATK / VXE devices
atkctl raw <command> [payload…] Sends one request and prints the reply in hex, for working out other models
Setting Values
sleep 30s 1m 2m 3m 5m 20m 25m 30m
polling 125 250 500 1000 2000 4000 8000 (what the mouse and receiver support)
debounce 0 1 2 4 8 15 20 (ms)
motion-sync, ripple, angle-snapping on / off
lift-off 0.7 to 1.7 (mm, in 0.1 steps)
dpi <stage> <value>, for example atkctl set dpi 2 1600 (both axes, multiples of 50)
dpi-stage <stage>, makes that stage the active one

Every setting is one ATK Hub can also change, and can be changed back from ATK Hub. Firmware updates are left to ATK Hub on purpose: they go through the bootloader, and a failed one can brick the mouse.

Waiting for an inactive mouse

With the mouse or receiver plugged in, use atkctl --wait (or atkctl status --wait) to wait until the mouse responds, then print its current status and exit. atkctl dpi --wait and atkctl set dpi-stage 2 --wait also wait before running. The CLI checks again every 250 ms after an unavailable response; a timed-out request can take longer. Move or click the mouse to resume, or press Ctrl+C to cancel. The waiting message goes to stderr, so atkctl --wait --json keeps stdout as JSON. Permission and other non-transient errors still fail immediately. Without --wait, commands retain their existing behavior.

When the receiver looks dead

atkctl doctor checks for these:

  • Karabiner-Elements grabs the receiver. The receiver reports itself as a keyboard as well as a mouse, so Karabiner takes it over and nothing else can talk to it. ATK Hub then fails with Device initialization failed and pairing never starts. atkctl doctor --fix-karabiner adds an ignore rule for it (and backs up karabiner.json); unplug and replug the receiver afterwards.
  • Secure Input is on. While the screen is locked, or a password field has focus, macOS refuses to send reports to devices that act as keyboards, the receiver included. Unlock and run the command again.
  • Input Monitoring is not allowed. macOS asks before a program may open input devices. If atkctl reports that access was denied, allow your terminal app under System Settings › Privacy & Security › Input Monitoring.
  • The receiver has no mouse. The receiver answers, but no mouse is paired or connected: run atkctl pair.
  • Firmware mismatch. Mouse and receiver need the same major firmware version to pair.

Supported devices

The BitMouse device list is the one ATK Hub drives with this protocol: about seventy ATK and VXE mice and receivers, NearLink (NK) and 2.4 GHz alike. It has been tested with an ATK A9 Plus NK (0x1263) and its NK mouse NANO dongle (0x1216); atkctl list marks the others [untested]. Reports from other models are welcome.

The ATK A9 Ultra (0x1119, Compx model ID 2,87) and its Wireless mouse 8k dongle (0x111a) use a separate Compx transport. Version, battery, configuration and DPI reads have been verified on this pair. DPI stage selection uses a zero-based hardware index (the CLI remains one-based). Other settings writes are implemented from ATK Hub's format but have not been hardware-verified. Pairing for this pair must be done in ATK Hub; other Compx mouse models are not supported.

How it works

ATK Hub is a web app that talks to the mouse over WebHID. atkctl speaks the same protocol through IOKit: 63-byte requests on HID output report 8 of the vendor usage page 0xFF05, answered on input report 8. The receiver forwards anything addressed to the mouse. The format and the commands are written up in docs/PROTOCOL.md.

The library part, ATKKit, can be used on its own:

import ATKKit

let session = Session()
print(try session.firmwareVersion(), try session.battery().percent)
print(try session.dpiTable().active?.x ?? 0)
try session.setSleep(seconds: 120)

Build from source

swift build          # debug builds of atkctl and ATKBar in .build/debug
swift run ATKBar     # the menu bar app without an app bundle
swift run ATKBar --render-preview panel.png   # draws the dark panel with recorded values
swift test           # protocol tests, using replies recorded from a real mouse

License

MIT. Not affiliated with ATK or VXE; the names are used only to say which devices this works with.

About

Configure ATK / VXE mice on macOS from the terminal, without ATK Hub

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages

⌂ 换网址