Structs

VersionFirmware identity and box id

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

use medius::Version;

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

HealthBox readiness flags

Box readiness from query_health(), one bool per bit of a u16 flags word. from_flags(u16) and to_flags() convert it: bits 0-7 hold the first eight fields, and the high byte holds the advanced control layer's three.

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 && !h.rewrite_on);
assert_eq!(h.to_flags(), 0b0000_0011); // round-trips to the same word

DeviceInfoClone's USB identity, kind, product

USB identity from device_info(). With nothing cloned, every field is zero or empty, and is_cloned() reads false. A clone with no HID interface (a vendor-class pad, n_hid 0 in Caps) still has its identity filled in. 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
assert!(d.is_cloned());
assert!(!DeviceInfo::default().is_cloned()); // nothing cloned

CapsWhole clone, mouse and keyboard

Everything one caps() query returns. has_mouse() / has_keyboard() report which are bound. is_composite() is true when the clone has >1 HID interface.

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

MouseCapsWhat the cloned mouse can do

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_pan: false, has_report_id: false, n_hid: 1 };
assert!(!c.is_composite()); // single HID interface

RateNative report rate the box tracks

Live rate from query_rate(). native_hz() converts the period to hertz. It returns None while native_period_us is 0. On a change-driven input, poll_period_us is the only rate.

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));

StatsDelivery and telemetry counters

Delivery counters from query_stats(), decoded from the 31-byte RESP(STATS).

Nonzero tx_drops or tx_wedges means native input was lost on the way to the PC. Nonzero link_rx_drops or host_rx_drops means it was lost between the box's two chips. relay_drops is relayed traffic and commands that went no further, not lost native input. The narrowed fields saturate instead of wrapping. link_rx_drops, host_rx_drops and relay_drops are full width, and session wraps.

LocksActive input scales

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

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

let locks = device.query_locks()?;
if locks.is_locked(Axis::X, Direction::Positive) {
    // native +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));

LockEntryOne entry in a Locks list

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

One weighed direction in a Locks list. Entries mirror the LOCK frame field for field, so an entry is the frame that reproduces it.

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

BearingWhat With and Against are measured against

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

The configured bearing from query_bearing(). The native bearing describes what it does.

is_live() reports whether a bearing is held.

CatchFilterWhat to catch, and how much

struct CatchFilter { /* private */ }

One entry in the table passed to catch_events or input_events, built with a constructor.

Matching order: an exact (class, id) before a class blanket, a class blanket before the wildcard, and a named direction before Both. The matching 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 isn't part of a filter's address. Two filters naming one entry at different lengths are one box entry, at the wider length. same_address compares addresses only; == compares everything.

The table holds 32 entries. A larger subscription, an empty one, or a capture on an input class is refused before anything is sent (Error).

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);

MotionEventOne native relative-axis event

The payload of a CatchEvent::Motion, read off an EventStream. It holds the native delta at the merge point, before lock suppression or injection, so a locked or injected axis still reports it.

use medius::{CatchEvent, CatchFilter};

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

UsageSnapshotOne native held-usage snapshot

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");
    }
}

InputEventDecoded input edge and its timestamp

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);
    }
}

TrafficEventBytes off one pipe, with what was cut

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

One event frame carries ≤180 bytes, so Capture::Whole still truncates a longer packet. truncated() reports it.

A Control or ClipTransfer event is one completed transaction: bytes is the 8-byte SETUP packet then the data stage, and direction says which way that data went. A Control event is the transaction the game PC received, on every control endpoint. A request served from the box's value cache still raises one.

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);
    }
}

ButtonButton a command acts on

struct Button(pub u8)

The button an INJECT or LOCK command acts on, as an open numeric id. The five standard buttons are named constants, and the mouse may declare further ids (caps n_buttons). A Button converts Into<Usage> as class button, so inject takes one directly.

Injecting a button the real device declares but never wires is descriptor-faithful: the box drives the full declared count, and one past it is a no-op.

UsageMomentary input: (class, id)

struct Usage { class: Class, id: u16 }

What inject drives and LockTarget locks. A Button, Key, and MediaKey each impl Into<Usage>, so any verb takes one directly. Usage::new(class, id) builds one by hand.

use medius::{Button, Class, Key, Usage};

let from_button: Usage = Button::LEFT.into();      // Class::Button, id 0
let from_key: Usage = Key::A.into();               // Class::Key, id 0x04
let by_hand = Usage::new(Class::Media, 0x00E9);    // volume up
device.press(from_button)?;                         // press takes any impl Into<Usage>

KeyHID keyboard keycode

A newtype over a HID keyboard/keypad usage. It converts Into<Usage>, so inject and press take one directly. 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());

MediaKey16-bit Consumer usage

A newtype over a 16-bit Consumer usage. It converts Into<Usage>, so inject and press take one directly.

use medius::MediaKey;

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

KbdCapsWhat the cloned keyboard can do

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

CatchStateLive subscription table, read back

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

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

An entry absent from entries was refused. If table_full is set, 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);

CatchEntryOne accepted subscription, and what it lost

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 shows that events are being lost. This one shows which entry lost them. Vendor bulk drops first, because its queue drains last.

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);
}

ClockEstimateHow the two chips' timers relate

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 ≤20 µs/s.

error_bound_us() is half delay_us. 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());
    }
}

TimelineBox stamps on this machine's clock

struct Timeline { /* private */ }

A catch stamp counts microseconds on a chip that booted before this process did. It wraps, restarts at zero on reboot, and has no relation to any clock here. Feed every event in as it arrives, in order. reset a domain whose chip restarted (a device-chip restart raises restarts).

&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. The error is one-sided: an event can arrive late but never early. The mapping 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);
}

StampedOne event placed on this machine's clock

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

TransformOne field operation and its two fields

struct Transform { op: TransformOp, source: LockTarget, dest: LockTarget }

One entry in the table passed to transform. The named constructors cover common cases. new is the general form.

The written value is clamped to the destination field's declared range. To weigh a field, or reverse it, use scale, which runs first.

use medius::{Axis, Button, Key, Transform, TransformOp};

let swap = Transform::swap(Axis::X, Axis::Y);
assert_eq!(swap.op, TransformOp::Swap);

let wheel_drives_y = Transform::remap(Axis::Wheel, Axis::Y); // the wheel drives Y
let side_key = Transform::remap(Button::new(4), Key::A);     // the fifth button types 'A'

TransformKey(source, dest) pair an entry is filed under

struct TransformKey { source: LockTarget, dest: LockTarget }

What Transform::key returns, and what untransform drops by. Two transforms sharing a key are one entry: setting the second overwrites the first's op in place, keeping its position in the table.

TransformsTransform table, read back

struct Transforms { table_full: bool, entries: Vec<Transform> }

What query_transforms returns: the held entries, as the commands that rebuild them. Every entry read back is a live one, and the table is re-asserted wholesale on reconnect.

use medius::Transforms;

let table = device.query_transforms()?;
println!("{}/{} transforms", table.entries.len(), Transforms::CAPACITY);
for t in &table.entries {
    println!("  {:?} {:?} -> {:?}", t.op, t.source, t.dest);
}

ImperfectStatusImperfect-clone state

The imperfect-clone state from query_imperfect().

EmitPaceStatusEmit-rate pacing and clone rate

The emit-rate pacing state from query_emit_pace().

RenderStatusMotion texture, and whether a profile armed

The render state from query_render().

SpreadStatusSpread percent and interval in effect

The spread state from query_spread().

LogLineOne line from the LOG stream

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

PortInfoDiscovered serial port

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.

BoxInfoOne discovered box

One entry from Device::list(), and the value find_where's predicate receives.

CountersSnapshotLink statistics snapshot

Five running link totals from counters().

LogStreamReceiver for the box LOG stream

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

ClipSettingsPersistent clip config, read back

A clip's configuration from ClipHandle::query_config(): the readback of the handle setters (set_autolock, set_loop, set_retain, set_ride, finalize, bind, bind_packet).

let cfg = handle.query_config()?;
if cfg.loop_ && cfg.finalized {
    println!("sealed looping clip, {} triggers", cfg.triggers.len());
}
for e in &cfg.packet_triggers {
    println!("{:?} id {} -> {:?}, {} hits", e.trigger.class, e.trigger.id, e.trigger.action, e.hits);
}

ClipTriggerOne input binding that drives a clip

One native-input binding for a clip, handed to ClipHandle::bind. The box keeps ≤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

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)?;

ClipPacketTriggerOne packet binding that drives a clip

fn new(class: TrafficClass, id: u16, direction: Direction, action: ClipAction) -> ClipPacketTrigger

fn matching(self, match_bytes: impl Into<Vec<u8>>, mask: impl Into<Vec<u8>>) -> ClipPacketTrigger

fn consume(self) -> ClipPacketTrigger

fn once_per_run(self, selector_len: u8) -> ClipPacketTrigger

One packet binding for a clip, handed to ClipHandle::bind_packet. The box keeps ≤8 (CLIP_PKT_TRIG_MAX), keyed by (class, id, direction, match_bytes, mask). They share 112 match bytes (CLIP_PKT_MATCH_POOL).

use medius::{ClipAction, ClipPacketTrigger, Direction, TrafficClass};

// Report ID 7 on interface 2 carries a button in bit 5 of its second byte. Start once per hold.
let held = ClipPacketTrigger::new(TrafficClass::HidIn, 2, Direction::IN, ClipAction::Start)
    .matching([0x07, 0x20], [0xFF, 0x20])
    .once_per_run(1);
handle.bind_packet(&held)?;

ClipPacketTriggerEntryOne packet trigger the box holds, read back

struct ClipPacketTriggerEntry { trigger: ClipPacketTrigger, hits: u16 }

One row of ClipSettings::packet_triggers.

ClipStatusClip ring and playback state

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

ChipFirmwareWhat one chip is running

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

FirmwareInfoBoth chips, and what is staged

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

UpdateProgressOne acknowledged window

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

SetupEight-byte USB setup packet

struct Setup { request_type: u8, request: u8, value: u16, index: u16, length: u16 }

What a transfer carries. It is the USB §9.3 setup packet: bmRequestType, bRequest, wValue, wIndex, wLength, little-endian on the wire.

  byte   0            1          2   3     4   5     6   7
        +------------+----------+---------+---------+---------+
        |request_type| request  |  value  |  index  | length  |
        | bmRequest  | bRequest | wValue  | wIndex  | wLength |
        +------------+----------+---------+---------+---------+
                                 <-- LE -> <-- LE -> <-- LE ->

Setup::new builds one from its five fields, and is_in reads the direction bit. to_bytes gives the eight wire bytes (<BBHHH>, little-endian).

use medius::Setup;

// GET_DESCRIPTOR(Device): standard device-to-host request for the 18-byte device descriptor.
let setup = Setup::new(0x80, 0x06, 0x0100, 0x0000, 18);
assert!(setup.is_in());
assert_eq!(setup.to_bytes(), [0x80, 0x06, 0x00, 0x01, 0x00, 0x00, 0x12, 0x00]);

TransferOutcomeNative reply: status and any IN data

struct TransferOutcome { status: TransferStatus, data: Vec<u8> }

What transfer returns. A non-Ok status carries no data.

RewriteRuleRule set_rewrite installs

fn new(class: RewriteClass, id: u16, direction: Direction, action: RewriteAction) -> RewriteRule

fn matching(self, match_bytes: impl Into<Vec<u8>>, mask: impl Into<Vec<u8>>) -> RewriteRule

fn at_offset(self, offset: u16) -> RewriteRule

fn with_payload(self, payload: impl Into<Vec<u8>>) -> RewriteRule

One entry in the table passed to set_rewrite, built by chaining onto new.

RewriteTableRewrite table, read back

struct RewriteTable { table_full: bool, generation: u8, entries: Vec<RewriteEntry> }

What query_rewrite returns: a summary row per rule, without its match, mask, or payload bytes. query_rewrite_entry reads one in full.

query_health reports a non-empty table in its rewrite_on flag.

RewriteEntryOne row in a RewriteTable

struct RewriteEntry { class: RewriteClass, id: u16, direction: Direction, action: RewriteAction, match_len: u8, offset: u16, payload_len: u16, hits: u16 }

One rule's summary in a RewriteTable: its address and action, the lengths of what it carries, and its hit count. The bytes come from query_rewrite_entry.

PatchDescriptor overwrite set_patch stores

fn new(section: PatchSection, offset: u16, bytes: impl Into<Vec<u8>>) -> Patch

fn in_config(cfg: u8, offset: u16, bytes: impl Into<Vec<u8>>) -> Patch

fn in_interface(cfg: u8, interface: u8, offset: u16, bytes: impl Into<Vec<u8>>) -> Patch

fn in_string(index: u8, bytes: impl Into<Vec<u8>>) -> Patch

One entry in the set passed to set_patch, with a constructor per section.

PatchSetStored patch set and its apply state

struct PatchSet { applied: bool, pending: bool, refused: bool, table_full: bool, entries: Vec<PatchEntry> }

What query_patches returns, as four apply-state flags over a list of PatchEntry. The list is the stored set. query_health reports a patched clone in its patch_on flag.

  set_patch --> stored set          (NVS, per VID:PID; pending while it differs from the served set)
                    |
                    |  apply_patch, the opt-in turning on, the real device attaching
                    v
                presented --- checks pass ---> applied   (the clone serves the patched set)
                    |
                    +-------- a check fails ---> refused   (served unpatched; the log names the check)

PatchEntryOne row in a PatchSet

struct PatchEntry { section: PatchSection, cfg: u8, index: u8, offset: u16, len: u16 }

One patch's key and length in a PatchSet, without its bytes. query_patch_entry reads one in full.