One enum with three readings, picked by what it is attached to: an axis, a usage, or a CatchFilter naming one of the byte-oriented catch classes.

The aliases are the same values under names that read at the call site: Direction.PRESS is Direction.POSITIVE. WITH and AGAINST are measured against the bearing rather than a fixed sign; .is_relative tells them apart.

Only an axis has a bearing, so WITH or AGAINST on a lock anywhere else raises RelativeDirectionError. A media usage has no edges: an edge named on one goes out as BOTH, which is what Locks reports it as.

How the box reads the direction it is injecting, which is what WITH and AGAINST resolve by. Set with dev.set_bearing(window_ms, mode).

What Locks reports back under VECTOR is there.

Built for you by LockTarget.x/y/wheel/usage (and the button/key/media shortcuts); you rarely name it directly.

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 runs on the box, matching the clip.start/stop/pause/resume/restart/toggle methods.

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

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

The address class a CatchFilter names. It is the same address vocabulary lock uses, with members 0 to 3 being the lock classes unchanged, extended with the byte-oriented traffic the box carries. id is class-specific.

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

The input classes are tapped before lock suppression and injection, so an input you have locked still reports here. EMIT is the opposite end, what the clone put on the wire afterwards.

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

It is what CatchFilter.traffic and traffic_class take, so an input class cannot reach a traffic constructor at all.

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(). The instance methods return a new filter rather than mutating in place.

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 and the wheel
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)

Matching is most-specific-first: an exact (class, id) is matched before a class blanket, that before everything(), and a named direction before BOTH. The winning entry supplies the capture.

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

The arguments are checked here, before they reach ctypes. with_direction, watch_axis, watch_class, traffic, and traffic_class want a member of their enum, and with_capture a byte; anything else is 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 ceiling request, not a guarantee. The box holds one entry per address and cuts once, so another subscriber naming that address more widely raises yours 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.

A stamp is only meaningful against another from the same domain. Both clocks are box-local, wrap every ~71.6 minutes, and restart at zero when that chip reboots, so a value below the previous one is a wrap, a reboot, or a domain change.

To put stamps on this machine's clock, feed them to a Timeline; to cross the two domains, apply the offset in ClockEstimate and respect 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 a InputEvent and a UsageSnapshot hand back. 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

A relative axis drive for dev.move_axis(motion, timing, pending). See Move.

LockTarget.x()            -> LockTarget
LockTarget.y()            -> LockTarget
LockTarget.wheel()        -> 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 own value.

The live subscription table read back from the box. Since catch_events() gets no reply, this is the only way to see which filters the box holds.

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

Two independent crystals make an offset stale at up to 20 µs per second, so extrapolate with rate_ppb rather than trusting it.

See Options.

See Options.

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

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

The stamp and its domain stay on the CatchEvent around it.

Only held usages that resolve against your filters appear, and no event is emitted when none do, so a subscription to one button stays sparse even 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 BUS: one packet, one control transaction, or one bus event, with whatever the entry's capture let through.

A CONTROL event is one completed transaction, not one stage: bytes is [setup 8][data…] and direction says which way the data stage went. Requests the box serves from its own descriptor cache still produce an event.

One decoded input: a press edge, a release edge, or a motion report. Yielded by dev.input_events(), which diffs the box's held-usage snapshots so you do not have to.

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

Only meaningful with the mock feature.

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 eight are argument refusals, raised before a frame reaches the box.