The event, lock, and log PODs embed fixed-cap arrays sized to the protocol's own limits, with a count field saying how many slots are live. 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 is never what truncates: a short len means the box cut the packet at your capture.

Each value is a wire byte; the canonical meaning lives on Enums. The *Kind enums (and MediusClass) tag which arm of a built value (MediusUsage, MediusMotion, MediusCatchEvent) is populated.

enum MediusDeviceKind : uint8_t

The kind field of a MediusDeviceInfo, from the cloned device's Boot-interface protocol. Also what medius_device_find_mouse_box / _find_keyboard_box select on. See DeviceKind.

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

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

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.

enum MediusAction : uint8_t

The override action shared by inject calls, whether a button, key, or media usage. See the injection model.

enum MediusClass : uint8_t

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

enum MediusMotionKind : uint8_t

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

enum MediusLockTargetKind : uint8_t

The kind of a MediusLockTarget. See Lock.

enum MediusDirection : uint8_t

One enum with three readings, picked by what it is attached to: an axis sign, a usage edge, or the transfer direction on 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 anywhere else is MEDIUS_STATUS_ERR_RELATIVE_DIRECTION. A media usage has no edges: an edge named on one goes out as MEDIUS_DIRECTION_BOTH, which is what MediusLocks reports it as.

Parameters and struct fields carrying a direction are declared uint8_t, so a value outside the enum reaches the boundary rather than the wire.

enum MediusEdge : uint8_t

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

enum MediusClipAction : uint8_t

What a bound MediusClipTrigger does to the clip on its edge; the same verbs as the medius_clip_start/_stop/... calls. See Clip.

enum MediusBlanket : uint8_t

A whole input group: which one medius_device_lock_all/_unlock_all block in one call, and the scope medius_clip_set_autolock auto-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.

enum MediusLedTarget : uint8_t

See LED.

enum MediusLedMode : uint8_t

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

enum MediusRebootTarget : uint8_t

See Admin.

enum MediusEmitMode : uint8_t

See Options.

enum MediusCatchEventKind : uint8_t

Tells you which member of the MediusCatchEvent union to read. Which arms you can see follows from the MediusCatchClass values you subscribed to: the four input classes decode into motion and usages, every byte-oriented class into traffic. See Catch.

enum MediusClockDomain : uint8_t

The clock field of a MediusCatchEvent, beside ts_us. Which domain an event carries is fixed by where it is tapped.

The box is two ESP32-S3s that boot independently, so a stamp is only meaningful against other stamps from the same domain.

Both clocks are box-local and unrelated to any PC clock. Each is a uint32_t of microseconds: it wraps every ~71.6 minutes and returns to zero when that chip reboots.

A stamp below the previous one is a wrap, a reboot, or a domain change.

To put both on this machine's clock, feed events to a MediusTimeline. To relate the two box domains directly, read the estimate on MediusCatchState.

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.

enum MediusLogLevel : uint8_t

The severity of a MediusLogLine. See Logs & counters.

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 the box's USB plumbing and surface 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 seven byte-oriented ones).

The four input classes are captured at the emission merge point before lock suppression and before injection, so a locked input still reports.

MEDIUS_CATCH_CLASS_EMIT is the mirror image: what the clone put on the wire after injection, locks, and the suppression gate.

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 you hand to medius_device_catch_events or medius_device_input_events. Build each one with a medius_catch_filter_* helper, then 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 spelled class_ because class is a C++ keyword and the header compiles as both.

The useful capture length differs between classes by orders of magnitude. A 64-byte vendor interrupt report is worth having whole; a bulk pipe traced only for framing is worth 16 bytes. So it lives on the entry that matched, not box-wide.

Matching is most-specific-first, and the winning entry is the one whose capture applies. That is what makes "everything at 16 bytes, except endpoint 0x83 in full" two entries rather than an impossibility.

  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

/* everything the box can see, first 16 bytes only */
MediusCatchFilter blanket =
    medius_catch_filter_with_capture(medius_catch_filter_everything(), 16);

/* except this endpoint's IN traffic, which we want 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 now fails the whole call with its own MediusStatus, rather than being dropped with no status. Two filters naming the same table entry, whatever their captures, are what medius_catch_filter_same_address tests.

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

A raw HID keyboard usage passed to the key calls. Pass any usage byte, or one of the MEDIUS_KEY_* macros. The full set of usages is on Usage IDs.

typedef uint16_t MediusMediaKey;

A raw Consumer usage passed to the media calls. Pass any 16-bit usage, or a MEDIUS_MEDIA_* macro. The full set is on Usage IDs.

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.

Three small PODs you build with a helper and hand to a call. The medius_*_* constructors set the kind tag and the right field for you.

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

enum MediusMoveTiming : uint8_t

The timing argument of medius_device_move_axis, against movement riding. See Move.

enum MediusPendingMotion : uint8_t

The pending argument of medius_device_move_axis. See Move.

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

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.

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

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

From medius_device_query_health.

From medius_device_device_info; all-zero/empty when nothing is cloned. product is a NUL-terminated UTF-8 string.

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.

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

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

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

One chip's half of medius_device_firmware_info.

From medius_device_firmware_info.

From medius_device_query_stats. A nonzero tx_drops or tx_wedges means delivery degraded under load.

From medius_device_query_locks: entries[0..n], one per weighed direction. Read one with medius_locks_scale_of(&locks, target, dir), or ask whether it is blocked outright with medius_locks_is_locked; both count a covering whole-class is_blanket entry. Wire layout on the native LOCKS reply.

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.

From medius_device_query_catch: a header followed by entries[0..n], one per accepted MediusCatchFilter. The array is inline and capped at MEDIUS_MAX_CATCH_ENTRIES (32), the box's own table size, so the reply always carries the whole table.

The order is the order the box accepted them in, not the order it matches in: matching is worked out per event, most-specific-first, with ties going to the earlier entry.

Delivery is four strict-priority queues: input and bus first, then the byte-oriented traffic classes, then control, then vendor bulk. Under a busy mouse, bulk can starve completely.

So the count is kept twice. The header's dropped says you are losing events; the per-entry one says which subscription is losing them, and those want different fixes.

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. Queueing is the largest and most variable delay on that link.

From medius_device_query_imperfect. See Options.

From medius_device_query_emit_pace. See Options.

From medius_device_counters. See Logs & counters.

Filled by medius_find_ports; path and serial are NUL-terminated. Canonical docs on PortInfo.

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

The values you read off the catch and log streams. Catch semantics on Catch; canonical docs on Structs.

The user's real motion at the merge point, before any lock suppression or injection. Surfaces as the Motion arm of a MediusCatchEvent, raised by a MEDIUS_CATCH_CLASS_AXIS subscription.

It carries no timestamp of its own: the enclosing event's ts_us and clock cover it, and for motion the domain is always MEDIUS_CLOCK_DOMAIN_HOST_CHIP.

The held usages of one class (button, key, or media; modifiers are key usages 0xE0 to 0xE7) in usages[0..n], buttons and keys the same shape. Test one with medius_usage_event_is_held(&event, usage). Raised by a BTN, KEY, or MEDIA subscription.

Like motion, it carries no timestamp of its own: it uses the enclosing event's ts_us and clock, which for a usage snapshot is always MEDIUS_CLOCK_DOMAIN_HOST_CHIP.

Diffing successive snapshots into press and release edges is what the decoded-input stream does for you.

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 rather than a pointer, capped at MEDIUS_MAX_TRAFFIC_BYTES (180), so the event stays a fixed-size POD you can copy, queue, and drop with nothing to free.

Without true_len, a packet the box cut at your capture and a genuinely short packet are indistinguishable. medius_traffic_event_truncated(&ev) is that comparison.

A CONTROL event covers a whole completed transaction, not one stage of one: bytes is the 8-byte SETUP packet followed by the data stage, and direction says which way that data went. Split them with medius_traffic_event_setup and medius_traffic_event_data.

A request the box answered from its own descriptor 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.

None of these announces a chip reboot, which is the only thing that restarts a stamping clock. Call medius_timeline_reset for a chip you know restarted.

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 friends. 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. The exact padding is the compiler's, so use sizeof if you need the number itself.

Written by medius_log_stream_recv; text is NUL-terminated.

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

Written by medius_input_stream_recv and its non-blocking siblings. The box sends held-usage snapshots; the stream diffs them, so a caller reads edges instead of sets.

struct MediusStamped {
    uint64_t host_ns;     /* on the caller's own 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.

A managed binding you add with medius_clip_bind: when on hits edge, the box runs action on the clip. Build the on usage with the medius_usage_* helpers. Concept on Clip.

From medius_clip_query_config: the auto-lock scope, the loop/retain/finalize scalars, and the live trigger set. Concept on Clip.

From medius_clip_query_status; state is a MediusClipState. Concept on Clip.

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 lives in thread-local state. Read it before the next call on that thread overwrites it. Canonical mapping on Errors.

MediusDevice *dev = NULL;
if (medius_device_find(&dev) != MEDIUS_STATUS_OK) {
    char buf[256];
    medius_last_error_message(buf, sizeof buf);
    fprintf(stderr, "open failed: %s\n", buf);
    return 1;
}