Types & errors

Its meaning depends on what it is attached to: an axis, a usage, or a CatchFilter naming a byte-oriented catch class.

Aliases are the same values under call-site names: Direction.PRESS is Direction.POSITIVE. WITH and AGAINST are measured against the bearing, not a fixed sign; .is_relative tells them apart.

Only an axis has a bearing, so WITH or AGAINST on a lock of anything else raises RelativeDirectionError. A media usage has no edges: an edge named on one is sent as BOTH, and reads back that way in Locks.

How the box reads the direction it is injecting, which WITH and AGAINST are measured against. Set with dev.set_bearing(window_ms, mode).

Under VECTOR, Locks reports that one scale.

Built by LockTarget.x/y/wheel/pan/usage (and the button/key/media shortcuts).

These are ABI-local ordinals (matching the crate's Blanket order), not the clip auto-lock scope bits.

A frozen dataclass carrying mode and hz. Build it with EmitPace.learned(), EmitPace.interval(), or EmitPace.fixed(hz) (the rate snaps to 1000/n and caps at 1 kHz).

Which edge of a ClipTrigger runs its action.

The action a bound trigger of either kind runs on the box, matching the clip.start/stop/pause/resume/restart/toggle methods.

A dataclass binding a native usage's edge to a clip action, passed to clip.bind(). The box runs the action with no host round-trip.

Construct it directly, e.g. ClipTrigger(Usage.button(Button.SIDE1), Edge.PRESS, ClipAction.TOGGLE, consume=True).

A dataclass binding a matched packet to a clip action, keyed by (traffic_class, id, direction, match_bytes, mask). Passed to clip.bind_packet() and read back by clip.query_config(). See Clip.

from medius import ClipAction, ClipPacketTrigger, ClipPacketTriggerError, Direction, TrafficClass

clip = dev.clip()

# Report ID 7 on interface 2 carries a button in bit 5 of its second byte. Start once per hold.
held = ClipPacketTrigger(TrafficClass.HID_IN, 2, Direction.IN, ClipAction.START,
                         match_bytes=b"\x07\x20", mask=b"\xFF\x20",
                         once_per_run=True, selector_len=1)
clip.bind_packet(held)

try:
    clip.bind_packet(ClipPacketTrigger(TrafficClass.CONTROL, 0, Direction.OUT,
                                       ClipAction.STOP, consume=True))
except ClipPacketTriggerError as e:
    print(e)                      # consume on CONTROL; nothing was sent

for t in clip.query_config().packet_triggers:
    print(t.traffic_class, t.id, t.action, t.hits)

clip.unbind_packet(held)          # by key
clip.clear_triggers()             # both kinds

The address class a CatchFilter names. Members 0 to 3 are the lock classes, unchanged; the rest are the byte-oriented traffic the box carries. id is class-specific.

The every-class wildcard is CatchFilter.everything(), whose catch_class reads None. cls.is_input() is true for 0 to 3, cls.is_traffic() for the rest.

Where each class is tapped, and why a locked input still reports, is on Catch.

The byte-oriented half of the address space, values 4 to 11 under the same names as CatchClass.

CatchFilter.traffic and traffic_class take a TrafficClass, so an input class can't be passed to a traffic constructor.

One relative axis, for CatchFilter.watch_axis(axis). The values are the wire axis ids a catch or lock entry carries.

One subscription entry: a class, an id inside it, a direction, and how many bytes to keep per event. Pass one or an iterable to dev.catch_events() or dev.input_events(). Instance methods return a new filter.

CatchFilter.watch(usage)               -> CatchFilter         # a Usage, or a Button/Key/MediaKey
CatchFilter.watch_axis(axis)           -> CatchFilter         # one Axis
CatchFilter.watch_class(input_class)   -> CatchFilter         # every usage in one Class
CatchFilter.watch_axes()               -> CatchFilter         # X, Y, the wheel and AC Pan
CatchFilter.all_input()                -> List[CatchFilter]   # all four input classes
CatchFilter.traffic(traffic_class, id) -> CatchFilter         # one endpoint, interface, or EP number
CatchFilter.traffic_class(tc)          -> CatchFilter         # every id in one TrafficClass
CatchFilter.everything()               -> CatchFilter         # every class, every id, one entry

  .with_direction(direction)           -> CatchFilter   # a Direction, default BOTH
  .with_capture(n)                     -> CatchFilter   # bytes kept per event, default 0 = all
  .on_press() / .on_release()          -> CatchFilter   # one edge of an input filter
  .inbound() / .outbound()             -> CatchFilter   # one flow of a traffic filter
  .same_address(other)                 -> bool          # same table entry, whatever the capture

CatchFilter.traffic(TrafficClass.VENDOR_INTERRUPT, 0x83).with_capture(16)

The top-ranked entry supplies the capture; the ranking is on The table.

same_address is true across two filters that differ only in capture, and false once one is narrowed to a direction.

Arguments are checked before ctypes: with_direction, watch_axis, watch_class, traffic, and traffic_class take a member of their enum, with_capture a byte; anything else raises a ValueError naming the argument.

Capture.WHOLE      # 0, keep the whole packet
Capture.first(n)   # keep the first n bytes; first(0) is WHOLE

What with_capture takes. Traffic classes only: an input class carries no packet, so naming one with a capture raises CaptureNotApplicableError.

A capture is a ceiling you request, not a guarantee. The box holds one entry per address and cuts once, so another subscriber asking for more of that address raises your capture too.

Which of the box's two chips stamped an event's ts_us. The two ESP32-S3s boot independently, so nothing relates their timers.

Compare stamps only within one domain. Both clocks are box-local, wrap every ~71.6 minutes, and restart at zero when their chip reboots. A value below the previous one is a wrap, a reboot, or a domain change.

A Timeline puts stamps on this machine's clock; to cross domains, apply the ClockEstimate offset within its error bound.

What a CatchClass.BUS event describes. These also drive Health bits and Stats counters; catching them adds a timestamped ordering.

BusEvent is the decoded dataclass TrafficEvent.bus_event() returns: a kind plus configuration, interface and alt, each 0 for the kinds carrying none.

Usage.button(button) -> Usage      # build
Usage.key(key)       -> Usage
Usage.media(media)   -> Usage

usage.kind           -> Class      # read one back
usage.id             -> int

An injection target for dev.inject(input, action), and what an InputEvent and a UsageSnapshot return. It compares by value, hashes, and reprs as Usage(kind=BUTTON, id=0).

# Naming a button off the stream: id is the Button value, kind says which class it is.
if ev.usage is not None and ev.usage.kind is Class.BUTTON:
    print(Button(ev.usage.id).name)

# Or compare whole usages.
if ev.usage == Usage.button(Button.SIDE1):
    print("side button")

Motion.cursor(dx, dy) -> Motion
Motion.wheel(delta)   -> Motion
Motion.pan(delta)     -> Motion

A relative axis drive for dev.move_axis(motion, timing, pending); pan is AC Pan (horizontal scroll), a full peer of the wheel. See Move.

LockTarget.x()            -> LockTarget
LockTarget.y()            -> LockTarget
LockTarget.wheel()        -> LockTarget
LockTarget.pan()          -> LockTarget
LockTarget.usage(usage)   -> LockTarget
LockTarget.button(button) -> LockTarget
LockTarget.key(key)       -> LockTarget
LockTarget.media(media)   -> LockTarget

An axis or usage to lock for dev.lock(target, direction); the button/key/media shortcuts wrap usage(). See Lock.

What Direction.WITH and Direction.AGAINST are measured against; see the native bearing.

Module constant BEARING_WINDOW_DEFAULT_MS (20) is the factory window; a box that has been set boots at its stored value.

The live subscription table: the only view of which filters the box holds, since catch_events() gets no reply.

One row of the box's table: the CatchFilter you sent, with its drop count.

The two chips' crystals drift the offset by up to 20 µs/s; extrapolate with rate_ppb.

See Options.

See Options.

See Options.

See Options.

Pass path to Device.open(path). Canonical: PortInfo.

Pass id or serial to Device.open_by_id(id). Canonical: BoxInfo.

import medius

for b in medius.list_boxes():
    if b.device is None:
        print(f"{b.id} speaks protocol {b.version.proto_ver}: update its firmware")
    else:
        print(b.id, b.device.kind.name, b.device.product)

The enclosing CatchEvent carries the stamp and domain.

Only held usages matching your filters appear, and no event is sent when none match. A one-button subscription stays sparse while the mouse reports at 1 kHz.

An empty snapshot still names its class: cls and direction come from the frame header, not the entries.

The payload for every byte-oriented CatchClass from HID_IN to CLIP_TRANSFER: one packet, one control transaction, or one bus event, with whatever the entry's capture let through.

A CONTROL or CLIP_TRANSFER event is one completed transaction. bytes is [setup 8][data...] (IN data only on CLIP_TRANSFER); direction says which way the data stage went.

A CONTROL event is the transaction as the game PC received it, on any control endpoint. Requests the box serves from its value cache still produce one.

One decoded input: a press edge, a release edge, or a motion report. Yielded by dev.input_events(), diffed from the box's held-usage snapshots.

One event placed on this machine's clock by a Timeline.

Only meaningful with the mock feature.

RewriteRule is what dev.set_rewrite takes and query_rewrite_entry returns, keyed by (rewrite_class, id, direction, match_bytes, mask). query_rewrite returns a RewriteTable (table_full, generation, entries) of RewriteEntry summaries. table_full says the box refused the last new rule or overwrite for lack of room (32 rules, or the 2048-byte payload pool full). The next change to the table, or a clear, resets it.

Patch is what dev.set_patch takes, keyed by (section, cfg, index, offset); empty bytes removes it. query_patches returns a PatchSet (applied, pending, refused, table_full, entries) of PatchEntry summaries; the four flags read as on PatchSet.

Transform.swap(a, b)              -> Transform
Transform.remap(source, dest)     -> Transform
Transform(op, source, dest)

Transforms carries table_full (bool) and entries (a list of Transform, in the order the box applies them).

from medius import Device, MediusError, NotFoundError

try:
    dev = Device.find()
except NotFoundError:
    ...                      # no box plugged in
except MediusError as e:     # any other failure
    print(e.status, e.message)

The last 24 are argument refusals, raised before a frame reaches the box.

All three are None when the library raised it without a detail from the box.