Skip to content

control: drive the ATK ZERO, and let a mouse state its own lift-off range - #159

Open
itsnttt wants to merge 2 commits into
OpenMouse-Project:control-panelfrom
itsnttt:bitmouse-atk-zero
Open

control: drive the ATK ZERO, and let a mouse state its own lift-off range#159
itsnttt wants to merge 2 commits into
OpenMouse-Project:control-panelfrom
itsnttt:bitmouse-atk-zero

Conversation

@itsnttt

@itsnttt itsnttt commented Sep 5, 2026

Copy link
Copy Markdown

Companion to OpenMouse-Project/mouse-protocol#50, which adds the
BITMOUSE driver for the ATK ZERO. That PR needs to land first — the imports
here do not resolve without it.

Driving the new driver from the app turned up three things the app assumed, and
one of them is not ATK-specific at all.

A driver the app does not name is treated as Pulsar

pulsarClient() is a negative test — anything not in DEDICATED falls through
to the Pulsar explorer:

const pulsarClient = () =>
  active !== null && !isEggWeClient(active) && !DEDICATED.some((cls) => active instanceof cls)
    ? active as PulsarClient : null;

So connecting an ATK ZERO failed with client.describeCollections is not a function. The client joins DM_CLASSES, beside the older ATK, Lamzu and
WLMouse drivers whose surface it already shares.

Cards come from the family table, not from the status

ui.showAdvancedSection opens the section, but sleep and debounce stay
false until the family appears in BY_FAMILY, so both cards were missing even
though the driver was reporting values for them. "atk-bitmouse" gets the same
DIRECT_MODE entry as "atk".

Lift-off was three stops for every mouse

liftOffDistance offers only Low, Medium and High. A mouse that tunes lift-off
continuously — the ATK ZERO runs 0.7 mm to 1.7 mm in eleven steps, and the
vendor software shows a slider — had eight of its eleven settings thrown away.

Drivers can now report an optional liftOffScale, and the sensor card renders a
slider over the raw device codes, labelled with the millimetres the driver
supplies. The scale therefore stays in the driver and the control is not
ATK-specific; any brand whose firmware exposes a range can use it. The coarse
liftOffDistance is still reported alongside, and a driver that sets no scale
keeps the three stops exactly as before.

This part is independent of the ATK work and can be split into its own PR if
you would rather review it separately — happy to do that.

Two smaller controls

Sensor sampling mode was Teevolution-only; a generic row now shows whenever a
status carries sensorMode. Ultra Long Range gets a toggle against the new
longRangeMode field.

Supported devices

Adds the ATK ZERO as supported, pinning 0x1154 and 0x1155, with
PID_UNIVERSE importing BITMOUSE_PRODUCT_IDS from the protocol package so the
row cannot drift from the driver.

It also corrects the "VXE Zero Normal" note, which read "ATK driver (0x373b)
likely covers — needs hardware test". That inference was wrong: the ZERO family
does not expose the 0xff02 collection the existing ATK driver matches on. The
row stays likely — that model's own PID still needs confirming — but the note
now says why the existing driver does not reach it.

Artwork

Maps both ATK ZERO product ids to atk-zero.png. No image file is included, as
public/devices/README.md asks; the art itself goes through a Device artwork
request.

Verified

npm run check against the local protocol build: tsc --noEmit and
vite build clean, 112 tests.

On an ATK ZERO over its receiver, through this app: DPI, polling rate, lift-off,
angle snapping, debounce, sleep, motion sync, ripple control, sensor sampling
mode and Ultra Long Range all read and write. Lift-off and angle snapping were
checked by hand — lifting the mouse and dragging it — rather than by read-back
alone, because the protocol PR describes a defect where a write verified
correctly and still did nothing.

itsnttt and others added 2 commits September 5, 2026 07:04
The ZERO does not speak the 0xff02 EEPROM protocol the existing ATK
driver implements, so the "ATK driver (0x373b) likely covers" note on
the VXE Zero Normal row was wrong: that vendor id alone is not enough.
The family uses the BITMOUSE channel on usage page 0xff05, added in
OpenMouse-Project/mouse-protocol.

Pin the two PIDs verified on hardware and let the PID universe in the
test import them from the protocol package, so the row cannot drift.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ange

Wiring the BITMOUSE driver up exposed three things the app assumed.

A driver the app does not name is treated as Pulsar. `pulsarClient()` is a
negative test — anything not in DEDICATED falls through to the Pulsar
explorer — so connecting an ATK ZERO failed on `client.describeCollections
is not a function`. The client joins DM_CLASSES, beside the older ATK, Lamzu
and WLMouse drivers whose surface it shares.

Cards come from BY_FAMILY, not from the status. `ui.showAdvancedSection`
opens the section but `sleep` and `debounce` stay false until the family is
in the table, so both cards were missing even though the driver reported
values for them. "atk-bitmouse" gets the same DIRECT_MODE entry as "atk".

Lift-off was three stops for everyone. `liftOffDistance` has only Low,
Medium and High, so a mouse that tunes lift-off continuously — the ATK ZERO
runs 0.7 mm to 1.7 mm in eleven steps — had ten of its settings thrown away.
Drivers can now report a `liftOffScale`, and the card renders a slider over
the raw device codes labelled with the millimetres the driver supplies, so
the scale stays in the driver and any brand can use the control. The coarse
field is still reported alongside it, and a driver that sets no scale keeps
the three stops exactly as before.

Sensor sampling mode was likewise Teevolution-only; a generic row now shows
whenever a status carries `sensorMode`. Ultra Long Range gets a toggle
against the new `longRangeMode` field.

Also maps both ATK ZERO product ids to atk-zero.png. The art itself goes
through an artwork request, as public/devices/README.md asks.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant