Enums

DeviceKindClone's primary kind

enum DeviceKind { Unknown, Keyboard, Mouse }

The kind field of a DeviceInfo, read from the native HID report descriptors and Boot declarations. A device with both kinds reads keyboard if it has a full key bitmap (unless it declares Boot for both) or declares Boot for its keyboard only. Otherwise it reads mouse. It also drives find_mouse_box and find_keyboard_box. Display prints the lowercase name.

ActionPress / release tri-state

enum Action { SoftRelease, Press, ForceRelease }

The override action for an inject call, on any Usage class (button, key, or media). The discriminant is the wire byte. Convert with as_u8() and from_u8(u8) -> Option<Action>.

The two releases differ only under a hold on the real device:

ClassClass of a momentary usage

enum Class { Button, Key, Media }

The class byte of a Usage, shared by INJECT, LOCK, and CATCH. Convert with as_u8() and from_u8(u8) -> Option<Class>.

CatchClassWhat a catch subscription addresses

enum CatchClass { Button, Key, Media, Axis, HidIn, HidOut, VendorInterrupt, VendorBulk, Control, Emit, Bus, ClipTransfer }

The address space a CatchFilter picks from, and the class of a TrafficEvent. Convert with as_u8() and from_u8(u8) -> Option<CatchClass>. Split it with is_input() and is_traffic().

The first four are LOCK's classes at the same byte values. The other eight address USB traffic. TrafficClass is that half alone.

A blanket is one table entry, not one per id. CatchFilter::watch_class(c) and traffic_class(c) are the per-class blankets, and CatchFilter::everything() is the wildcard over all twelve. The wire sentinels never appear in Rust.

The input classes are captured at the emission merge point, before lock suppression and injection, so a locked input still reports. Emit is the far end of the same path: what the clone emitted.

real device --> [ merge point ] --> locks --> injection --> [ clone emits ] --> game PC
                       |                                           |
          Button / Key / Media / Axis                            Emit

The traffic classes tap each pipe on the chip that owns it. Each event's ClockDomain records which.

use medius::{Button, Capture, CatchFilter, Direction, TrafficClass};

// The same target, once as a lock and once as a catch.
device.lock(Button::SIDE1, Direction::Both)?;                    // suppressed in the emitted report
let stream = device.catch_events([
    CatchFilter::watch(Button::SIDE1).on_press(),                // the tap is before suppression
])?;

// A byte-oriented class instead: one vendor interrupt endpoint, IN only, 16 bytes a packet.
let trace = device.catch_events([
    CatchFilter::traffic(TrafficClass::VendorInterrupt, 0x83)
        .inbound()
        .with_capture(Capture::First(16)),
])?;

TrafficClassByte-oriented half of the address space

enum TrafficClass { HidIn, HidOut, VendorInterrupt, VendorBulk, Control, Emit, Bus, ClipTransfer }

The eight packet-carrying classes, at their CatchClass byte values. It's a separate enum, so CatchFilter::traffic can't take an input class. TrafficClass::ALL lists them, and From and TryFrom convert both ways.

CaptureHow much of each packet to keep

enum Capture { Whole, First(u8) }

Traffic classes only: a capture on an input class, which carries no packet, is refused.

It's a ceiling. The box holds one entry per address and cuts once, so another subscriber naming the same address with a wider capture raises yours too. First(0) is Whole. bytes() returns Option<u8>, and widest() resolves two captures.

InputOne decoded input edge

enum Input { Press(Usage), Release(Usage), Motion { dx: i16, dy: i16, dz: i16, pan: i16 } }

What input_events yields, wrapped in an InputEvent with its timestamp. usage(), is_press(), is_release(), direction() and axes() read it without a match.

MotionRelative axis for move_axis

enum Motion { Cursor { dx: i16, dy: i16 }, Wheel(i16), Pan(i16) }

What move_axis drives. Every delta spans the full i16 range. A lock names a single Axis instead.

MoveTimingWhen a delta reaches the game PC

enum MoveTiming { Ride, Now }

The move_axis timing argument, against movement riding. Defaults to Ride.

PendingMotionWhat a move does to held motion

enum PendingMotion { Keep, Flush, Discard }

The move_axis pending argument, for motion already held for a ride. Defaults to Keep.

AxisSingle relative axis

enum Axis { X, Y, Wheel, Pan }

A lock_axis or LockTarget::Axis names one, with a Direction for the sign. Convert with as_u16() and from_u16().

RebootTargetWhich chip to restart, and how

enum RebootTarget { DeviceDownload, HostDownload, DeviceRun, HostRun }

Which chip a REBOOT restarts, and into what mode. Convert with as_u8() and from_u8(u8) -> Option<RebootTarget>.

EmitPaceWhat paces injected motion

enum EmitPace { Learned, Interval, Fixed(u16) }

What sets the emit-rate ceiling for injected motion, passed to set_emit_pace and returned in EmitPaceStatus. It raises the ceiling only: the box still emits only while motion is pending.

RenderModeTexture the box renders motion with

enum RenderMode { Off, Stock, Despiked, Unsmoothed }

Passed to set_render and returned in RenderStatus. The box boots at Despiked, which is also this enum's Default. The model is ABCurves (MIT).

LedTargetWhich chip's status LED to drive

enum LedTarget { Device, Host, Both }

Which chip's LED a LED command drives. The discriminant is the wire target byte. Convert with as_u8() and from_u8(u8) -> Option<LedTarget>.

LedModeWhat to drive the LED to

enum LedMode { Auto, Off, Solid, Blink }

What a LED command drives the LED to. Auto restores the box's status display. The discriminant is the wire mode byte. Convert with as_u8() and from_u8(u8) -> Option<LedMode>.

LockTargetOne addressable input field: an axis or a usage

enum LockTarget { Axis(Axis), Usage(Usage) }

What a lock weighs and a Transform reads and writes. The box addresses a field the same way everywhere. An Axis and any impl Into<Usage> convert Into<LockTarget>, so either passes straight in. A button locks exactly like a key.

LockScopeWhat a reported lock covers

enum LockScope { Target(LockTarget), Blanket(Class) }

What a LockEntry in a query_locks reply covers.

DirectionWhich way, which edge, or which transfer direction

enum Direction { Both, Positive, Negative, With, Against }

The one byte LOCK, CLIP and CATCH all carry. The variants are named for the axis reading. The class picks which of the three readings applies, and no class carries two. Convert with as_u8() and from_u8(u8) -> Option<Direction>.

A media usage has no edges. An edge on one is sent as Both, and reads back as Both in query_locks.

With and Against are measured against the bearing, not a fixed sign, so the sign they cover follows the injection. is_relative() tells them apart. On any class but an axis, a lock or catch call refuses them with Error::RelativeDirection.

The other two readings have separate names: Direction::PRESS and RELEASE for a usage, Direction::IN and OUT for traffic. admits() tests one against another, and of_delta() reads the sign of a delta.

BearingModeHow the box reads the injected direction

enum BearingMode { PerAxis, Vector }

Set by set_bearing. It resolves Direction::With and Against. Convert with as_u8() and from_u8(u8) -> Option<BearingMode>.

In Vector, the relative pair addresses X and Y as one vector. The box applies the lower of X's and Y's scale to both axes, so address them together with scale_all. Locks documents the readback.

The projection is the first of two stages. Each axis's Positive / Negative scale then applies to what the projection left on that axis, so it can weigh motion the projection moved there.

BlanketWhole-group lock selector

enum Blanket { Aim, Wheel, Buttons, Keys, Media }

A whole input group. scale_all / lock_all weigh one in a single call, and a clip's ClipSettings auto-lock is a list of them.

LogLevelSeverity tag on a log line

enum LogLevel { Error, Warn, Info, Debug, Verbose }

The severity tag on a LogLine. from_u8(u8) is infallible: an unknown byte falls back to Info.

CatchEventOne caught event off the stream

enum CatchEvent { Motion(MotionEvent), Usages(UsageSnapshot), Traffic(TrafficEvent) }

What an EventStream yields, one variant per event frame the box sends.

All three carry ts_us and a ClockDomain. Until the ClockEstimate is applied, a stamp compares only with another from the same domain.

One rolling seq counter covers all three frame types. It counts what the box sent, not what it captured, so loss shows in CatchState, not as a seq gap.

use medius::{CatchEvent, CatchFilter};

let stream = device.catch_events([CatchFilter::everything()])?;
match stream.recv()? {
    CatchEvent::Motion(m)  => println!("{} {} {}", m.dx, m.dy, m.dz),
    CatchEvent::Usages(s)  => println!("{} held", s.usages.len()),
    CatchEvent::Traffic(t) => println!("{:?} 0x{:04X}: {} bytes", t.class, t.id, t.true_len),
}

ClockDomainWhich chip stamped the event

enum ClockDomain { HostChip, DeviceChip }

The clock field beside every event's ts_us. The box runs two unsynchronised microsecond timers. The chip that captured the event stamps it. Convert with as_u8() and from_u8(u8) -> Option<ClockDomain>.

Both timers are box-local, unrelated to any clock on this machine. They wrap every ~71.6 minutes (a u32 of microseconds) and restart at zero when their chip reboots.

A stamp lower than the one before it means a wrap, a reboot, or a domain change. Only the domain change shows in the value itself. To put both domains on one timeline, apply the ClockEstimate from query_catch.

ControlStatusHandshake the game PC received

enum ControlStatus { Ok, Stalled, Naked, Other(u8) }

Read it with TrafficEvent::control_status(), which returns None for any class other than Control. It is flags bits 0-1. Bit 7 is rule_acted().

BusEventWhat happened on the USB bus

enum BusEvent { Reset, Suspend, Resume, Configured(u8), Deconfigured,
                SetInterface { interface: u8, alt: u8 },
                DeviceAttached, DeviceDetached, CloneUp, CloneDown }

The kind of a CatchClass::Bus event. Read it with TrafficEvent::bus_event(), which returns Option<BusEvent>: None for a kind byte this build does not name. The two kinds with operands parse them into named fields.

DeviceAttached and DeviceDetached are the real device on USB3. The other eight are on the clone's USB1 bus, which the control PC isn't on.

use medius::{BusEvent, CatchEvent, CatchFilter, TrafficClass};

let stream = device.catch_events([CatchFilter::traffic_class(TrafficClass::Bus)])?;
if let CatchEvent::Traffic(t) = stream.recv()? {
    match t.bus_event() {
        Some(BusEvent::Configured(n))              => println!("configuration {n}"),
        Some(BusEvent::SetInterface { interface, alt }) => println!("iface {interface} alt {alt}"),
        Some(kind)                                 => println!("{kind:?}"),
        None                                       => {}
    }
}

TransformOpWhat a transform does to its fields

enum TransformOp { Remap, Swap }

How a Transform's source and destination relate. as_u8() and from_u8() convert the wire byte. admits(source, dest) checks a pair, as the crate does before sending.

admits refuses a pair whose source and destination are the same field. To weigh a field, or reverse it, use scale.

ClipStateClip lifecycle state

enum ClipState { Idle, Playing, Paused, Faulted }

The box's clip state on ClipStatus::state, from ClipHandle::query_status().

EdgeWhich edge fires a clip trigger

enum Edge { Both, Press, Release }

Which edge of a bound usage fires a ClipTrigger. Shares wire values with Direction.

ClipActionWhat a fired clip trigger does

enum ClipAction { Start, Stop, Pause, Resume, Restart, Toggle }

What a bound ClipTrigger or ClipPacketTrigger does to the clip when it fires. The discriminant doubles as the CLIP_CTRL op byte for the same action.

UpdateTargetWhich chip an update op addresses

enum UpdateTarget { Device, Host }

ImageStateWhere a booted image is in its probation

enum ImageState { New, PendingVerify, Valid, Invalid, Aborted, Unknown }

The bootloader's record for a slot. See rollback.

TransferStatusHow a control transfer ended

enum TransferStatus { Ok, Refused, Stall, Nak, NoDevice, Other(u8) }

The status byte of a TransferOutcome, and of a ClipTransfer event through TrafficEvent::transfer_status(). The codes sit at the top of the byte range so they never collide with a length. An unknown byte is carried through as Other.

use medius::TransferStatus;

match reply.status {
    TransferStatus::Ok => println!("{} bytes", reply.data().len()),
    TransferStatus::Stall => println!("device rejected the request"),
    TransferStatus::NoDevice => println!("nothing attached on the host chip"),
    TransferStatus::Refused => println!("box refused it: opt-in off, malformed, too large, or queue full"),
    other => println!("other status: {other:?}"),
}

RewriteClassWhich traffic a rewrite rule addresses

enum RewriteClass { HidIn, HidOut, VendorInterrupt, VendorBulk, Control, Emit, Any }

The class picks the traffic a RewriteRule addresses, and the id picks the address within it. Together they are the writable half of catch's address space.

The parsed-input and bus classes are not rewritable. as_u8() and from_u8() convert the wire byte.

RewriteActionWhat the top-ranked rewrite rule does

enum RewriteAction { Pass, Drop, Patch, Replace, Answer, Stall, Nak, ReplyPatch, ReplyReplace }

The top-ranked rule's action sets what happens to a matched packet. The class column says which RewriteClass accepts the action. A report-only action on a control class, or the reverse, returns Error::RewriteActionClass.

PatchSectionWhich descriptor a patch overwrites

enum PatchSection { Device, Config, Report, String, Bos }

The section names the descriptor a Patch overwrites, and that patch's cfg and index address within it.