Types & errors

Sizing constantsFixed-cap arrays sized to the wire limits

Event, lock and log PODs embed arrays sized to the protocol limits, with a count of live slots. char arrays are NUL-terminated.

MEDIUS_MAX_CATCH_ENTRIES is the box's subscription table size, so a MediusCatchState always carries the whole live table.

MEDIUS_MAX_TRAFFIC_BYTES is the largest payload one traffic event carries, so the inline array never truncates. A short len means your capture cut the packet.

Enumsuint8_t-backed selectors (MediusStatus is int32_t)

Each value is a wire byte; meanings are on Enums. The *Kind enums and MediusClass tag which arm is set in a built value (MediusUsage, MediusMotion, MediusCatchEvent).

MediusDeviceKindCloned device's primary kind

enum MediusDeviceKind : uint8_t

The kind field of a MediusDeviceInfo, from the cloned device's HID report descriptors and Boot declarations. A device carrying both kinds reads keyboard if it has a full key bitmap (unless it declares Boot for both), or if it declares a Boot keyboard and no Boot mouse. Otherwise it reads mouse. medius_device_find_mouse_box / _find_keyboard_box select on this field. See DeviceKind.

MediusButtonMouse button id

enum MediusButton : uint8_t   /* values match the firmware button id */

The button an inject call drives. Ids on Usage IDs.

MediusAxisRelative axis id

enum MediusAxis : uint8_t   /* values match the wire axis id */

The axis a medius_catch_filter_watch_axis subscribes to: the same ids a catch or lock entry carries on the wire.

MediusActionPress / release tri-state

enum MediusAction : uint8_t

The override action of inject calls on a button, key, or media usage. See the injection model.

MediusClassWhich arm of a MediusUsage is set

enum MediusClass : uint8_t

The kind tag of a MediusUsage you build with medius_usage_button/_key/_media.

MediusMotionKindWhich arm of a MediusMotion is set

enum MediusMotionKind : uint8_t

Tags the MediusMotion you build with medius_motion_cursor/_wheel/_pan. See Move.

MediusLockTargetKindWhich input a MediusLockTarget addresses

enum MediusLockTargetKind : uint8_t

The kind of a MediusLockTarget. See Lock.

MediusDirectionAxis sign, usage edge, or transfer direction

enum MediusDirection : uint8_t

Its meaning depends on what it is attached to. The transfer direction applies to a MediusCatchFilter naming a byte-oriented catch class. See LOCK and Catch.

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

Direction parameters and struct fields are declared uint8_t, so a value no enumerator names can be passed. The library handles it at the boundary; it never reaches the wire.

MediusEdgeWhich edge of a trigger usage fires a clip binding

enum MediusEdge : uint8_t

The edge of a MediusClipTrigger's on usage that runs its action. Same wire values as MediusDirection. See Clip.

MediusClipActionEngine action a clip trigger drives

enum MediusClipAction : uint8_t

What a bound MediusClipTrigger or MediusClipPacketTrigger does to the clip when it fires. The verbs match the medius_clip_start/_stop/... calls. See Clip.

MediusBlanketWhole-group lock selector

enum MediusBlanket : uint8_t

A whole input group: what medius_device_lock_all/_unlock_all block in one call, and the scope medius_clip_set_autolock locks while a clip plays. See Lock.

The values are ABI-local ordinals (matching the crate's Blanket order), not the CLIP_LOCK_* wire bits.

MediusLedTargetWhich chip's status LED to drive

enum MediusLedTarget : uint8_t

See LED.

MediusLedModeWhat to drive the LED to

enum MediusLedMode : uint8_t

See LED. Solid / Blink use the command's level.

MediusRebootTargetWhich chip to restart, and how

enum MediusRebootTarget : uint8_t

See Admin.

MediusEmitModeWhat paces injected motion

enum MediusEmitMode : uint8_t

See Options.

MediusRenderModeTexture the box renders motion with

enum MediusRenderMode : uint8_t

Passed to medius_device_set_render and returned in MediusRenderStatus. See Options.

MediusCatchEventKindWhich arm of a MediusCatchEvent is set

enum MediusCatchEventKind : uint8_t

Which member of the MediusCatchEvent union to read. The last column lists the MediusCatchClass values that raise each kind. See Catch.

MediusClockDomainWhich chip's clock stamped an event

enum MediusClockDomain : uint8_t

The clock field of a MediusCatchEvent, beside ts_us. Where an event is tapped fixes its domain.

The box is two ESP32-S3s (a device chip and a host chip) that boot independently. A stamp only compares with stamps from the same domain.

Each clock is a box-local uint32_t of microseconds. It wraps every ~71.6 minutes and returns to zero when its chip reboots. A stamp below the previous one is a wrap, a reboot, or a domain change.

A MediusTimeline puts both on this machine's clock. The clock estimate in MediusCatchState relates the two box domains directly.

MediusInputKindWhich arm of a MediusInputEvent is set

enum MediusInputKind : uint8_t

Tags a MediusInputEvent off the decoded-input stream. The box sends held-usage snapshots; the stream diffs them into these edges.

MediusLogLevelSeverity tag on a log line

enum MediusLogLevel : uint8_t

The severity of a MediusLogLine. See Logs & counters.

MediusCatchClassWhat a catch filter addresses

typedef uint8_t MediusCatchClass;   /* one MEDIUS_CATCH_CLASS_* value */

The class half of a MediusCatchFilter, and the class_ field of both MediusTrafficEvent and MediusCatchEntry.

Classes 0 to 3 are the same vocabulary Lock uses; the rest address USB interfaces, endpoints and the bus, and arrive as byte-oriented traffic. See Catch.

Test one with medius_catch_class_is_input (the four parsed classes, which arrive decoded and carry no packet) or medius_catch_class_is_traffic (the eight byte-oriented ones).

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

MediusCatchFilterOne subscription entry: class, id, direction, capture

struct MediusCatchFilter {
    MediusCatchClass class_;      /* MEDIUS_CATCH_CLASS_*                   */
    uint16_t         id;          /* class-specific, or MEDIUS_CATCH_ID_ANY */
    uint8_t          direction;   /* MEDIUS_DIRECTION_*: edge, sign, or flow */
    uint8_t          capture;     /* 0 = whole packet; traffic classes only */
};

The array passed to medius_device_catch_events or medius_device_input_events. Build each with a medius_catch_filter_* helper and narrow it with a modifier.

Each element becomes one entry in the box's table; read the accepted set back with medius_device_query_catch. The field is class_ because class is a C++ keyword.

capture is per entry, not box-wide: keep a 64-byte vendor interrupt report whole, and only 16 bytes of a bulk pipe traced for framing.

The top-ranked matching entry's capture applies, so "everything at 16 bytes, except endpoint 0x83 in full" is two entries. Ranking: The table.

  a report arrives on VENDOR_INTERRUPT endpoint 0x83
          │
          ├─ exact   { class_ = VENDOR_INTERRUPT, id = 0x0083 }  ──▶ resolves first
          ├─ blanket { class_ = VENDOR_INTERRUPT, id = ID_ANY }  ──▶ used if no exact entry
          └─ any     { class_ = ANY,              id = ID_ANY }  ──▶ used if neither matched
                     ties inside one tier go to the earlier entry in your array

/* every class and id, first 16 bytes only */
MediusCatchFilter blanket =
    medius_catch_filter_with_capture(medius_catch_filter_everything(), 16);

/* except this endpoint's IN traffic, kept whole */
MediusCatchFilter whole = medius_catch_filter_inbound(
    medius_catch_filter_traffic(MEDIUS_CATCH_CLASS_VENDOR_INTERRUPT, 0x83));

MediusCatchFilter filters[2] = { blanket, whole };
MediusEventStream *events = NULL;
medius_device_catch_events(dev, filters, 2, &events);

A malformed entry fails the whole call with a distinct MediusStatus. medius_catch_filter_same_address tests whether two filters name the same table entry, whatever their captures.

MediusKeyHID keyboard/keypad usage

typedef uint8_t MediusKey;   /* modifiers are 0xE0 to 0xE7 */

A raw HID keyboard usage for the key calls: any usage byte, or a MEDIUS_KEY_* macro. Full set: Usage IDs.

MediusMediaKey16-bit HID Consumer usage

typedef uint16_t MediusMediaKey;

A raw Consumer usage for the media calls: any 16-bit usage, or a MEDIUS_MEDIA_* macro. Full set: Usage IDs.

MediusFrameTypeWire frame TYPE byte (mock only)

enum MediusFrameType : uint8_t   /* always defined; read only by the mock recorder */

The TYPE byte of a wire frame, used with the mock recorder (medius_mock_saw / medius_mock_recorded_frame). See the mock feature.

Argument structsTagged values you build, then pass in

Three PODs built with a helper and passed to a call; the medius_*_* constructors set the kind tag and the matching field.

MediusUsageMomentary usage for inject

What medius_device_inject drives. Build with medius_usage_button(...), _key(...), or _media(...); id holds the button id or usage per kind. See Inject.

MediusMoveTimingWhen a move is emitted

enum MediusMoveTiming : uint8_t

The timing argument of medius_device_move_axis: follow movement riding or bypass it. See Move.

MediusPendingMotionWhat a move does to held motion

enum MediusPendingMotion : uint8_t

The pending argument of medius_device_move_axis. See Move.

MediusMotionRelative axis for move_axis

What medius_device_move_axis drives. Build with medius_motion_cursor(dx, dy), medius_motion_wheel(delta), or medius_motion_pan(delta). See Move.

MediusLockTargetWhat a lock acts on

Passed to medius_device_lock / _unlock. Build it with medius_lock_target_axis or medius_lock_target_usage; usage is read only when kind is USAGE. See Lock.

Query valuesPODs written through a query's out-param

Each medius_device_query_* / _caps / _counters call fills one of these by value. Canonical field docs are on Structs; query semantics on Requests.

MediusVersionDecoded firmware version and box name

From medius_device_query_version. Set the box's name with medius_device_set_name.

MediusHealthBox readiness flags (each 0 or 1)

From medius_device_query_health.

MediusDeviceInfoCloned device's USB identity, kind, and product

From medius_device_device_info. All-zero/empty when nothing is cloned, which medius_device_info_is_cloned tests. A clone with no HID interface (n_hid 0) still has its identity filled in. product is NUL-terminated ASCII, with ? for each non-ASCII character.

MediusCapsWhole cloned device's capabilities

From medius_device_caps: a mouse half and a keyboard half plus the per-class change-driven flags. Test it with medius_caps_has_mouse, medius_caps_has_keyboard, medius_caps_is_composite.

MediusMouseCapsWhat the cloned mouse can do

The mouse half of MediusCaps; all-zero when no mouse interface is bound.

MediusKbdCapsWhat the cloned keyboard can do

The keyboard half of MediusCaps; all-zero when no keyboard is bound. n_keys == 0xFF signals an NKRO bitmap.

MediusRateNative report rate and clone poll period

From medius_device_query_rate. Convert to Hz with medius_rate_native_hz(rate, &hz) (returns false when there's no continuous cadence).

MediusChipFirmwareWhat one chip is running

One chip's half of medius_device_firmware_info.

MediusFirmwareInfoBoth chips, and what is staged

From medius_device_firmware_info.

MediusUpdateErrorUpdate op the box refused, and why

From medius_last_error_update after MEDIUS_STATUS_ERR_UPDATE. A confirm that timed out gives op 0 and status 0x1B, the refusal the next update would meet.

MediusStatsBox-side delivery / telemetry counters

From medius_device_query_stats. Nonzero tx_drops or tx_wedges: input was lost between the box and the game PC. Nonzero link_rx_drops or host_rx_drops: input was lost between the box's two chips. relay_drops counts relayed traffic and commands that went no further, never lost native input.

MediusLocks & MediusLockEntryActive scales, as an entry list

From medius_device_query_locks: entries[0..n], one per weighed direction. Read one with medius_locks_scale_of(&locks, target, dir), or test for an outright block with medius_locks_is_locked. Both take a covering whole-class (is_blanket) entry into account. Wire layout on the native LOCKS reply.

MediusBearing & MediusBearingModeWhat WITH and AGAINST are measured against

struct MediusBearing {
    uint16_t          window_ms;  /* 0 = off */
    MediusBearingMode mode;
};

From medius_device_query_bearing, set with medius_device_set_bearing. See the native bearing.

MediusCatchState & MediusCatchEntryLive subscription table, plus the inter-chip clock estimate

From medius_device_query_catch: a header, then entries[0..n], one per accepted MediusCatchFilter. The inline cap, MEDIUS_MAX_CATCH_ENTRIES (32), is the box's table size, so the reply always carries the whole table.

Entries are in acceptance order, not match order; each event is matched by the ranking.

Delivery is ranked: under a busy mouse, bulk can go completely undrained (queue order: Delivery). The header's dropped says events are being lost; the per-entry one says which subscription loses them.

The box measures the difference with a four-timestamp exchange across the inter-chip link. Each frame is stamped as it reaches the wire, not when queued, because queueing is that link's largest and most variable delay.

MediusImperfectStatusImperfect-clone state (each 0 or 1)

From medius_device_query_imperfect. See Options.

MediusEmitPaceStatusEmit-rate pacing state

From medius_device_query_emit_pace. See Options.

MediusRenderStatusRendering texture

From medius_device_query_render. See Options.

MediusSpreadStatusHow far an injected delta is spread in time

From medius_device_query_spread. See Options.

MediusCountersSnapshotHost-side always-on link counters

From medius_device_counters. See Logs & counters.

MediusPortInfoDiscovered medius serial port

Filled by medius_find_ports. Canonical docs on PortInfo.

MediusBoxInfoOne discovered box: port, version, and cloned device

Filled by medius_list: one entry per connected box, each read in turn. See BoxInfo.

MediusBoxInfo boxes[8];
uintptr_t total = 0;
uintptr_t n = medius_list(boxes, 8, &total);
for (uintptr_t i = 0; i < n; i++) {
    const MediusBoxInfo *b = &boxes[i];
    if (b->has_device)
        printf("%s  %04x:%04x %s\n", b->port.path, b->device.vid, b->device.pid, b->device.product);
    else
        printf("%s  protocol %u: update its firmware\n", b->port.path, b->version.proto_ver);
}

Event & log typesFixed-size PODs off the streams

Values off the catch and log streams. Semantics on Catch; canonical docs on Structs.

MediusMotionEventOne native relative-axis snapshot

Native motion at the merge point, before locks or injection apply. The Motion arm of a MediusCatchEvent, raised by a MEDIUS_CATCH_CLASS_AXIS subscription.

The enclosing event's ts_us and clock stamp it; for motion the domain is always MEDIUS_CLOCK_DOMAIN_HOST_CHIP.

MediusUsageEventOne held-usage snapshot for a class

The held usages of one class (button, key, or media) in usages[0..n], one shape for every class. Modifiers are key usages 0xE0 to 0xE7. Test one with medius_usage_event_is_held(&event, usage). Raised by a BTN, KEY, or MEDIA subscription.

Like motion, it is stamped by the enclosing event's ts_us and clock, always MEDIUS_CLOCK_DOMAIN_HOST_CHIP.

The decoded-input stream diffs successive snapshots into press and release edges.

MediusTrafficEventOne captured packet off a traffic class

struct MediusTrafficEvent {
    MediusCatchClass class_;
    uint16_t         id;
    uint8_t          direction;
    uint8_t          flags;
    uint16_t         true_len;   /* length before capture truncation */
    uint16_t         len;        /* bytes actually kept              */
    uint8_t          bytes[MEDIUS_MAX_TRAFFIC_BYTES];
};

The Traffic arm of a MediusCatchEvent, raised by any of the byte-oriented catch classes.

bytes is an inline array capped at MEDIUS_MAX_TRAFFIC_BYTES (180), so the event is a fixed-size POD to copy, queue, and drop with nothing to free.

true_len separates a packet cut at your capture from a short one; medius_traffic_event_truncated(&ev) makes that comparison.

A CONTROL or CLIP_TRANSFER event is one completed transaction. bytes holds the 8-byte SETUP packet, then the data stage (IN data only on CLIP_TRANSFER); direction says which way the data went. Split them with medius_traffic_event_setup and medius_traffic_event_data.

A CONTROL event is the transaction as the game PC received it, on any control endpoint. IN data is the reply the PC received, after any reply rule or ANSWER. OUT data is what the PC sent, before any rule rewrote it. A request the box served from its value cache still produces an event.

A BUS event puts the kind in flags and up to two operands in bytes. medius_traffic_event_bus_event decodes both into a MediusBusEvent.

A chip reboot restarts its stamping clock. Call medius_timeline_reset for a chip that restarted; a device-chip restart raises MediusCountersSnapshot.restarts.

MediusCatchEventOne catch-stream event (a tagged union)

struct MediusCatchEvent {
    MediusCatchEventKind kind;
    uint32_t             ts_us;
    MediusClockDomain    clock;
    union MediusCatchEventData {
        MediusMotionEvent  motion;
        MediusUsageEvent   usages;
        MediusTrafficEvent traffic;
    } data;
}

Written by medius_event_stream_recv and its variants. Read the union member named by kind. See MediusClockDomain for which class lands in which domain.

An event is 1040 bytes whichever arm is live. Padding is the compiler's; use sizeof for the exact number.

MediusLogLineOne device log line

Written by medius_log_stream_recv; text is NUL-terminated.

MediusInputEventOne decoded press, release, or motion report

struct MediusInputEvent {
    MediusInputKind   kind;    /* PRESS = 0, RELEASE = 1, MOTION = 2   */
    uint32_t          ts_us;
    MediusClockDomain clock;   /* always HOST_CHIP for native input    */
    MediusUsage       usage;   /* the edge's usage; zeroed for MOTION  */
    int16_t           dx, dy, dz, pan;
};

Written by medius_input_stream_recv and its non-blocking siblings, as edges diffed from the box's held-usage snapshots.

MediusStampedOne event placed on this machine's clock

struct MediusStamped {
    uint64_t host_ns;     /* on the caller's monotonic scale     */
    uint64_t box_us;      /* unwrapped past the 32-bit rollover  */
    uint64_t excess_ns;   /* jitter above the measured floor     */
};

Written by medius_timeline_observe. host_ns comes back on the same scale as the now_ns you passed in.

MediusClipTriggerOne native-input binding that drives the clip

A managed binding added with medius_clip_bind: when on hits edge, the box runs action on the clip. Build on with the medius_usage_* helpers. See Clip.

MediusClipPacketTriggerOne packet binding that drives the clip

A managed binding added with medius_clip_bind_packet, keyed by (class_, id, direction, match_bytes, mask). When a packet's head matches under the mask, the box runs action on the frame clock's next tick. medius_clip_query_config reads back the same shape, so a trigger read back can be bound again as is. See Clip.

/* Report ID 7 on interface 2 carries a button in bit 5 of its second byte. Start once per hold. */
MediusClipPacketTrigger held = {
    .class_ = MEDIUS_CATCH_CLASS_HID_IN, .id = 2,
    .direction = MEDIUS_DIRECTION_POSITIVE,
    .action = MEDIUS_CLIP_ACTION_START,
    .once_per_run = 1, .selector_len = 1,
    .match_len = 2, .mask_len = 2,
    .match_bytes = { 0x07, 0x20 }, .mask = { 0xFF, 0x20 },
};
MediusStatus st = medius_clip_bind_packet(clip, &held);
if (st == MEDIUS_STATUS_ERR_CLIP_PACKET_TRIGGER) { /* medius_last_error_message() says why */ }

MediusClipSettings cfg;
medius_clip_query_config(clip, &cfg);
for (uint8_t i = 0; i < cfg.packet_n; i++)
    printf("action %u, %u hits\n", cfg.packet_triggers[i].action, cfg.packet_triggers[i].hits);

medius_clip_unbind_packet(clip, &held);   /* by key */

MediusClipSettingsClip configuration read back from the box

From medius_clip_query_config. See Clip.

MediusClipStatus & MediusClipStateBuffered-clip ring and playback state

From medius_clip_query_status; state is a MediusClipState. See Clip.

MediusSetupUSB control-transfer setup packet

Passed by value to medius_device_transfer and medius_clip_frame_transfer. The eight bytes of a USB §9.3 setup packet, little-endian on the wire. See Control transfers.

MediusTransferOutcomeReal device's reply to a control transfer

Filled by medius_device_transfer. MEDIUS_STATUS_OK means only that the box replied; status is the transfer's result.

MediusRewriteRuleOne rewrite rule, as set and read back in full

Passed to medius_device_set_rewrite and filled by medius_device_query_rewrite_entry. A rule is keyed by (class_, id, direction, match, mask). See Rewrite rules.

MediusRewriteTable & MediusRewriteEntryRewrite-table summary

Filled by medius_device_query_rewrite: a full flag, a generation counter, and one MediusRewriteEntry per rule (address, action, match_len, offset, payload_len, and saturating hits) without the bytes.

MediusPatchOne descriptor patch, as set and read back in full

Passed to medius_device_set_patch and filled by medius_device_query_patch_entry. Keyed by (section, cfg, index, offset); a len of 0 removes the patch at that key. See Descriptor patches.

MediusPatchSet & MediusPatchEntryStored patch set and its apply state

Filled by medius_device_query_patches: the four apply-state flags and one MediusPatchEntry per patch (section, cfg, index, offset, len) without the bytes.

MediusTransformOne field transform

Passed to medius_device_transform and returned in the query table. source and dest are MediusLockTargets, and may not name the same field. To weigh or reverse a field, use medius_device_scale (signed percent). See Transform.

MediusTransformsTransform-table summary

Filled by medius_device_query_transforms: a full flag and one MediusTransform per entry, up to MEDIUS_MAX_TRANSFORM_ENTRIES (32).

ErrorsMediusStatus plus a thread-local message

enum MediusStatus : int32_t   /* MEDIUS_STATUS_OK == 0; everything else is a failure */

Every fallible call returns a MediusStatus and writes its result through an out-param. On failure the detail is thread-local; read it before the next call on that thread overwrites it. Canonical mapping on Errors.