Skip to content

refactor: read the battery in one call behind a HID interface seam - #11

Merged
softmaxe merged 4 commits into
mainfrom
refactor/hidpp-one-read
Oct 20, 2026
Merged

softmaxe merged 4 commits into
mainfrom
refactor/hidpp-one-read

Conversation

@softmaxe

Copy link
Copy Markdown
Owner

Summary

hidpp now exposes one call that returns one outcome, and HID interface opening sits behind a seam both production and tests cross.

 main::run
-  open_first_working_transport(api) -> Discovery<HidppTransport>
-  found_transport(discovery)           # Offline / NotFound messages
-  read_battery(&transport) -> Option<BatteryStatus>
-  ok_or_else(..)                       # "Wake the mouse up" message
+  read_battery(api) -> Reading         # Status | NoStatus | Offline | NotFound
+  battery_status(reading)              # one match, same messages
read_battery(api)                       # hidapi adapter
  read_battery_from(openers, now)       # the seam; tests pass scripted HID interfaces
    for device index, for HID interface (index-major, 6 s budget)
      Slot::open                        # lazy, first open error kept
      Device { io, index }.find_battery_feature
      Device.read_feature               # first battery feature found ends discovery

Along the way:

  • ReportMatch is gone; match_report returns Option<Reply> directly.
  • A Device { io, index } handle replaces threading the HID interface and device index through every request function.
  • HidppTransport, Discovery::map, and the mem::replace/unreachable! handoff are deleted.
  • CONTEXT.md defines HID interface.

Evidence

  • Before: 26 tests pass, but no test reaches open_first_working_transport or the ProbeSlot glue (the cargo-mutants survivors noted in refactor: trim redundant tests and indirection in the HID++ module #9). Tests rebuild that composition with probe_and_read and discover_single.
    After: 26 tests pass (cargo fmt --check, cargo clippy --all-targets -- -D warnings clean). Every scripted test calls read_battery_from, the same entry point production uses. Hand mutations confirm the glue is covered now:
drop HID interface open errors       -> an_interface_that_fails_to_open_is_skipped FAILS
swallow read errors (unwrap_or None) -> 5 battery_recovery tests FAIL

Not run against a real GPW2.

Merge Danger

Door: two-way

Internal refactor of a private module; revert is a single squash commit.

Blast Radius: messages

The only user-visible change: HID errors during discovery now print Could not read battery level: … instead of Could not probe Logitech HID++ interface: …. The README troubleshooting table never listed the old prefix. Probe order, timeouts, the discovery budget, and the stop-at-first-battery-feature rule are unchanged, so read latency and failure latency are unchanged.

ReportMatch only renamed its variants into Reply inside read_response, so
the offline rule was spelled in two adjacent enums. match_report now
returns the Reply itself, or None for an unrelated report, and the
response carries its Report.
Every function on the request path took the HID interface and the device
index as separate arguments, so a mixed-up index compiled silently. A
Device handle now pairs them once, and the request, feature lookup, and
battery read become its methods; read_response folds into request, its
only caller.
The hidpp interface made callers discover a transport, then read it, and
classify two failure channels (Discovery and a None status). It now
exposes one read_battery(api) that returns a single Reading: a status,
no status, offline, or nothing found. HidppTransport, Discovery::map,
and the mem::replace/unreachable! handoff are gone.

Opening HID interfaces moves behind the seam: read_battery_from takes
openers, with hidapi in production and scripted interfaces in tests.
Every scripted test now drives that entry point, so the lazy open,
open-error, and probe-order glue that had no test is covered, and the
probe_and_read/discover_single recompositions are deleted.

HID errors from discovery and from the read now share the "Could not
read battery level" prefix; "Could not probe Logitech HID++ interface"
is gone.
The code now names the seam it probes after HID interfaces, and the bare
word "interface" collides with a module's interface.
@softmaxe
softmaxe merged commit ee48209 into main Oct 20, 2026
4 checks passed
@softmaxe
softmaxe deleted the refactor/hidpp-one-read branch October 20, 2026 18:49
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