Plain value types you get back from queries and discovery. Their fields are public.

Firmware identity from query_version(). Display prints fw M.m.p and omits proto_ver; read it from the field.

use medius::Version;

let v = Version { proto_ver: 5, fw_major: 3, fw_minor: 2, fw_patch: 0, mac: [0x12, 0x34, 0x56, 0x78, 0x9a, 0xbc], name: "Loki".into() };
assert_eq!(v.to_string(), "fw 3.2.0"); // Display omits proto_ver
assert_eq!(v.mac_hex(), "123456789abc");
println!("{v} (protocol {}, box {}, name {})", v.proto_ver, v.mac_hex(), v.name);

Box readiness from query_health(), one bool per bit. from_flags(u8) and to_flags() convert the byte.

use medius::Health;

let h = Health::from_flags(0b0000_0011); // link_up | mouse_attached
assert!(h.link_up && h.mouse_attached);
assert!(!h.clone_configured);
assert_eq!(h.to_flags(), 0b0000_0011); // round-trips to the same byte

USB identity from device_info(). Every field is zero/empty when nothing is cloned. Display prints VVVV:PPPP product.

use medius::{DeviceInfo, DeviceKind};

let d = DeviceInfo {
    vid: 0x046D, pid: 0xC08B, bcd_device: 0, bcd_usb: 0x0201,
    has_serial: true, has_bos: true, kind: DeviceKind::Mouse, product: "G502".into(),
};
assert_eq!(d.to_string(), "046D:C08B G502"); // Display is VVVV:PPPP product

Everything one caps() query returns. has_mouse() / has_keyboard() tell you which are bound; is_composite() is true when the device has more than one HID interface.

let caps = device.caps()?;
if caps.has_keyboard() && caps.keyboard.has_consumer {
    // media injection is real on this board
}
println!("{} mouse buttons", caps.mouse.n_buttons);

Semantic capabilities from caps(). Every field is zero when no relative-axis mouse interface is bound. is_composite() is true when n_hid > 1.

use medius::MouseCaps;

let c = MouseCaps { n_buttons: 5, has_x: true, has_y: true, has_wheel: true, has_report_id: false, n_hid: 1 };
assert!(!c.is_composite()); // single HID interface

Live rate from query_rate(). native_hz() converts the period to a frequency, returning None while native_period_us is still 0. On a change-driven input, poll_period_us is the only rate there is.

use medius::Rate;

let r = Rate { native_period_us: 1000, poll_period_us: 1000, confident: true, change_driven: false };
assert_eq!(r.native_hz(), Some(1000.0));

Delivery counters from query_stats(). A nonzero tx_drops or tx_wedges means delivery degraded under load. The narrowed fields saturate instead of wrapping.

The active set from query_locks(), a list of LockEntry across every class, one per direction that is not passing untouched. See the native LOCKS reply for the wire format.

use medius::{Axis, Button, Direction};

let locks = device.query_locks()?;
if locks.is_locked(Axis::X, Direction::Positive) {
    // physical +X is zeroed
}
if locks.is_locked(Button::Left, Direction::Negative) {
    // a left-click is latched down: the release edge is blocked
}
// how much of a delta opposing the injection survives
println!("{}%", locks.scale_of(Axis::X, Direction::Against));

struct LockEntry { scope: LockScope, direction: Direction, scale: u8 }

One weighed direction in a Locks list. Entries mirror the LOCK frame field for field, so what comes back is what you would send to reproduce it.

is_block() is scale == 0: blocked outright rather than weighed.

struct Bearing { window: Option<Duration>, mode: BearingMode }

The configured bearing from query_bearing(). See the native bearing for what it does.

is_live() is whether a bearing is held at all.

struct CatchFilter { /* private */ }

One entry in the table you hand to catch_events or input_events. Built with a constructor rather than by hand.

An exact (class, id) is matched before a class blanket, that before the wildcard, and a named direction before Both. That entry supplies the capture:

catch_events([
    CatchFilter::everything().with_capture(Capture::First(16)),   // everything, 16 bytes
    CatchFilter::traffic(TrafficClass::VendorInterrupt, 0x83),    // except 0x83, in full
])

  packet on 0x83  ->  traffic(VendorInterrupt, 0x83)  resolves  ->  whole packet
  packet on 0x84  ->  everything()                    resolves  ->  First(16)

Capture is not part of a filter's address, so two filters naming one entry at different lengths are one box entry at the wider of the two. same_address is that comparison; == compares everything.

The table holds 32 entries, and a subscription that would exceed it is refused before anything is sent. See Error. So is an empty subscription, and a capture on an input class.

use medius::{CatchFilter, Class, TrafficClass};

// Press edges of every key, plus one control endpoint, plus bus context.
let stream = device.catch_events([
    CatchFilter::watch_class(Class::Key).on_press(),
    CatchFilter::traffic(TrafficClass::Control, 0),
    CatchFilter::traffic_class(TrafficClass::Bus),
])?;

// Dropping the stream clears the whole table.
drop(stream);

The payload of a CatchEvent::Motion, read off an EventStream. The real hand motion at the merge point, before lock suppression or injection, so a locked or injected axis still reports the true delta.

use medius::{CatchEvent, CatchFilter};

let stream = device.catch_events([CatchFilter::watch_axes()])?;
if let CatchEvent::Motion(m) = stream.recv()? {
    println!("at {} us ({:?}): moved {} {}, wheel {}", m.ts_us, m.clock, m.dx, m.dy, m.dz);
}

The payload of a CatchEvent::Usages: every held Usage of one class (buttons, keys, or media, all one shape), captured before injection. Diff successive snapshots for press/release edges, or test one with is_held; a dropped frame self-corrects on the next.

use medius::{Button, CatchEvent, CatchFilter, Class};

let stream = device.catch_events([CatchFilter::watch_class(Class::Button)])?;
if let CatchEvent::Usages(s) = stream.recv()? {
    if s.is_held(Button::Left) {
        println!("left button held");
    }
}

struct InputEvent { ts_us: u32, clock: ClockDomain, input: Input }

What input_events yields. The Input is the edge, decoded from the held-usage snapshots the box sends.

use medius::{CatchFilter, Input};

for ev in device.input_events(CatchFilter::all_input())? {
    if let Input::Press(u) = ev.input {
        println!("{u:?} down at {}", ev.ts_us);
    }
}

The payload of a CatchEvent::Traffic: one packet, one completed control transaction, or one bus event.

One event frame carries at most 180 bytes, so Capture::Whole still truncates a longer packet, and still says so.

bytes is the 8-byte SETUP packet then the data stage, and direction says which way that data went. Requests answered from the box's descriptor cache still raise events.

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

let stream = device.catch_events([CatchFilter::traffic(TrafficClass::VendorInterrupt, 0x83)
    .with_capture(Capture::First(16))])?;
if let CatchEvent::Traffic(t) = stream.recv()? {
    println!("ep 0x{:02X} {:?}: {:02X?}", t.id, t.direction, t.bytes);
    if t.truncated() {
        println!("  cut: {} of {} bytes", t.bytes.len(), t.true_len);
    }
}

A newtype over a HID keyboard/keypad usage. It converts Into<Usage>, so you pass one straight to inject or press. Modifiers are the usages 0xE0-0xE7.

use medius::Key;

let a = Key::A;            // 0x04
let custom = Key::new(0x04);
assert_eq!(a.usage(), custom.usage());

A newtype over a 16-bit Consumer usage. It converts Into<Usage>, so you pass one straight to inject or press.

use medius::MediaKey;

let vol_up = MediaKey::VOLUME_UP;   // 0x00E9
let custom = MediaKey::new(0xE9);
assert_eq!(vol_up.usage(), custom.usage());

Semantic capabilities from caps(). Every field is zero when no keyboard is bound. has_consumer gates media injection.

struct CatchState { table_full: bool, dropped: u32, clock: ClockEstimate, entries: Vec<CatchEntry> }

What query_catch() returns. Subscribing has no reply of its own, so this is the only view of what the box accepted.

An entry absent from entries was refused; table_full says the reason was capacity rather than a malformed filter.

let c = device.query_catch()?;
if c.entries.is_empty() {
    println!("catching nothing");
}
if c.table_full {
    eprintln!("some filters were refused: the 32-entry table is full");
}
for e in &c.entries {
    println!("{:?} {:?} {:?} {:?} dropped={}",
             e.filter.class(), e.filter.id(), e.filter.direction(), e.filter.capture(), e.dropped);
}
println!("{} dropped box-wide", c.dropped);

struct CatchEntry { filter: CatchFilter, dropped: u16 }

One row of the box's subscription table in a CatchState: the CatchFilter the box accepted, echoed back. A blanket comes back as one entry, not one row per id.

The box-wide count on CatchState says you are losing events; this one says which. Vendor bulk drops first, by design.

let c = device.query_catch()?;
for e in c.entries.iter().filter(|e| e.dropped > 0) {
    eprintln!("{:?} {:?} lost {} events", e.filter.class(), e.filter.id(), e.dropped);
}

struct ClockEstimate { offset_us: i32, rate_ppb: Option<i32>, delay_us: u16, age: Option<Duration> }

The clock field of a CatchState, and the only thing that puts stamps from both clock domains on one timeline.

The box measures the difference with a four-timestamp exchange across the inter-chip link, stamping each frame as it reaches the wire rather than when it is queued. The two crystals drift by up to 20 µs per second.

error_bound_us() halves delay_us for you; drift_us_over(age) extrapolates rate_ppb, returning 0 for a None rate.

let clock = device.query_catch()?.clock;
match clock.age {
    None => println!("no cross-chip estimate yet: compare stamps within one domain only"),
    Some(age) => {
        let offset_now = clock.offset_us as i64 + clock.drift_us_over(age);
        println!("offset {offset_now} us, +/- {} us", clock.error_bound_us());
    }
}

struct Timeline { /* private */ }

A catch stamp is microseconds on a chip that booted before this process did: it wraps every ~71.6 minutes, restarts at zero on reboot, and has no relation to any clock here. Feed every event in as it arrives, in order.

&event is anything implementing Timestamped: an InputEvent, a CatchEvent, or one of the three frame structs. The decoded and raw paths share one timeline.

Each domain is tracked separately, so both chips' stamps land on one comparable timeline.

The mapping keeps a per-domain minimum of (elapsed here minus elapsed on the box), not an average. It improves as it runs and never steps backwards.

use medius::{CatchFilter, Timeline};

let mut input = device.input_events(CatchFilter::all_input())?;
let mut time = Timeline::new();
for ev in input.by_ref().take(20) {
    println!("{:?} at {:?}", ev.input, time.observe(&ev).host);
}

struct Stamped { host: Instant, box_us: u64, excess: Duration }

The imperfect-clone state from query_imperfect().

The emit-rate pacing state from query_emit_pace().

One line from the box's LOG stream, read off a LogStream.

A serial port that looks like a Medius box, from find_medius(). serial is the CH343 adapter's serial string, part of the box identity.

Four running link totals from counters().

Receives the box's LOG frames as LogLine values off a local channel, from device.logs(). No receive method touches the wire, so cloning shares the queue. The methods and an example are on Logs & counters.

A clip's configuration from ClipHandle::query_config(). You set these with the handle setters (set_autolock, set_loop, set_retain, set_ride, finalize, bind); this is the readback.

let cfg = handle.query_config()?;
if cfg.loop_ && cfg.finalized {
    println!("sealed looping clip, {} triggers", cfg.triggers.len());
}

One physical-input binding for a clip, handed to ClipHandle::bind. The box keeps up to 8, keyed by usage and edge.

Build one with the constructor, where consume defaults to false:

fn new(on: impl Into<Usage>, edge: Edge, action: ClipAction) -> ClipTrigger

No round-trip

use medius::{Button, ClipAction, ClipTrigger, Edge};

// Toggle the clip on a Side1 press, and suppress that press.
let trig = ClipTrigger::new(Button::Side1, Edge::Press, ClipAction::Toggle).consume();
handle.bind(trig)?;

The clip ring depth and playback counters from ClipHandle::query_status(). Pace top-ups off free; a ClipState::Faulted state means re-sync (stop, then rebuild).

One chip's half of firmware_info(). Display renders it as major.minor.patch.

Returned by firmware_info(). any_pending() is true while either chip is still on probation, which is when an update is refused.

Handed to the closure passed to stage_firmware(), once per acknowledged window rather than once per chunk.