Types & errors

Section

Bindings

Getting Started

Usage

Reference

Build

AI Access

Medius - BindingsTypes & errors

Reference for the values the API takes and returns. Field meanings live with each command, so this page links to the Library types and Native API. Raw HID id meanings (keycodes, button slots, Consumer usages) are on Usage IDs.

Every enum subclasses enum.IntEnum, except CatchMask, which is an enum.IntFlag. A member is its wire byte: int(Button.LEFT) == 0, and anywhere an enum is accepted you can pass a bare int instead (handy for a raw HID id with no named member). CatchMask members combine with |.

See the injection model for what each Action means; button slots on Usage IDs.

Button

Member	Value
`LEFT`	`0`
`RIGHT`	`1`
`MIDDLE`	`2`
`SIDE1`	`3`
`SIDE2`	`4`

Action

Member	Value	Meaning
`SOFT_RELEASE`	`0`	release unless the user is physically holding it
`PRESS`	`1`	hold down
`FORCE_RELEASE`	`2`	release even against a physical hold

See Lock for what a direction and a blanket class mean.

LockDirection

Member	Value	Blocks
`BOTH`	`0`	either direction
`POSITIVE`	`1`	+x / +y / wheel-up only
`NEGATIVE`	`2`	-x / -y / wheel-down only

LockTargetKind

Member	Value
`X`	`0`
`Y`	`1`
`WHEEL`	`2`
`USAGE`	`3`

Built for you by LockTarget.x/y/wheel/usage (and the button/key/media shortcuts); you rarely name it directly.

Blanket

Member	Value	Class
`AIM`	`0`	the X and Y cursor axes
`WHEEL`	`1`	the wheel
`BUTTONS`	`2`	every mouse button
`KEYS`	`3`	every keyboard key and modifier
`MEDIA`	`4`	every media usage

These are ABI-local ordinals (matching the crate's Blanket order), not the clip auto-lock scope bits.

Named subsets of the HID usage tables. The full list of ids and what they do is on Usage IDs (keys) and Usage IDs (media). Any call that takes a Key or MediaKey also accepts a raw int usage.

Key

Members	Values
`A` … `Z`	`4` to `29`
`N1` … `N9`, `N0`	`30` to `39`
`ENTER` `ESCAPE` `BACKSPACE` `TAB` `SPACE`	`40` to `44`
`CAPS_LOCK`	`57`
`F1` … `F12`	`58` to `69`
`INSERT` `HOME` `PAGE_UP` `DELETE` `END` `PAGE_DOWN`	`73` to `78`
`RIGHT` `LEFT` `DOWN` `UP` (arrows)	`79` to `82`
`LEFT_CTRL` `LEFT_SHIFT` `LEFT_ALT` `LEFT_GUI`	`224` to `227`
`RIGHT_CTRL` `RIGHT_SHIFT` `RIGHT_ALT` `RIGHT_GUI`	`228` to `231`

MediaKey

Member	Value
`PLAY`	`176`
`PAUSE`	`177`
`NEXT_TRACK`	`181`
`PREV_TRACK`	`182`
`STOP`	`183`
`PLAY_PAUSE`	`205`
`MUTE`	`226`
`VOLUME_UP`	`233`
`VOLUME_DOWN`	`234`

See LED and Admin.

LedTarget

Member	Value
`DEVICE`	`0`
`HOST`	`1`
`BOTH`	`2`

LedMode

Member	Value
`AUTO`	`0`
`OFF`	`1`
`SOLID`	`2`
`BLINK`	`3`

RebootTarget

Member	Value
`DEVICE_DOWNLOAD`	`0`
`HOST_DOWNLOAD`	`1`
`DEVICE_RUN`	`2`
`HOST_RUN`	`3`

Passed to dev.set_emit_pace(). See Options.

EmitMode

Member	Value
`LEARNED`	`0`
`INTERVAL`	`1`
`FIXED`	`2`

EmitPace

A frozen dataclass carrying mode and hz. Build it with EmitPace.learned(), EmitPace.interval(), or EmitPace.fixed(hz) (the rate snaps to 1000/n and caps at 1 kHz).

The buffered-clip types. Concept on Clip.

ClipState

Member	Value	Meaning
`IDLE`	`0`	No clip playing.
`PLAYING`	`1`	Draining the ring, one entry per native frame.
`PAUSED`	`2`	Halted mid-clip; the cursor and any held input are retained.
`FAULTED`	`3`	An append was dropped or the ring overflowed; `clear` to recover.

Edge

Member	Value	Fires on
`BOTH`	`0`	either edge of the trigger usage
`PRESS`	`1`	the physical press edge
`RELEASE`	`2`	the physical release edge

Which edge of a ClipTrigger runs its action.

ClipAction

Member	Value	Runs
`START`	`0`	rewind and play
`STOP`	`1`	stop and release
`PAUSE`	`2`	halt mid-clip
`RESUME`	`3`	continue from the pause
`RESTART`	`4`	force a rewind and play
`TOGGLE`	`5`	play if idle/paused, stop if playing

The action a bound trigger runs on the box, matching the clip.start/stop/pause/resume/restart/toggle methods.

ClipTrigger

A dataclass binding a physical usage's edge to a clip action, passed to clip.bind(). The box runs the action itself with no host round-trip.

Field	Type	Meaning
`on`	`Usage`	the trigger usage (button, key, or media)
`edge`	`Edge`	which edge fires the action
`action`	`ClipAction`	what the box runs
`consume`	`bool`	swallow the physical edge so it doesn't pass through (default `False`)

Construct it directly, e.g. ClipTrigger(Usage.button(Button.SIDE1), Edge.PRESS, ClipAction.TOGGLE, consume=True).

ClipSettings (clip.query_config())

Field	Type	Meaning
`autolock`	`List[Blanket]`	the input groups auto-locked while the clip plays
`loop`	`bool`	playback loops at the clip end (retained mode only)
`retain`	`bool`	the loaded clip is retained so it can rewind and replay
`finalized`	`bool`	a retained clip's end is fixed, ready to replay and loop
`triggers`	`List[ClipTrigger]`	the bound trigger set (up to 8)

ClipStatus (clip.query_status())

Field / method	Type	Meaning
`state`	`ClipState`	the lifecycle state
`free` / `total`	`int`	ring bytes free (pace top-ups off this) / retained clip size in bytes (streaming: buffered-but-undrained)
`played`	`int`	bytes played from the clip start (retained progress; ~0 while streaming)
`ticks`	`int`	content frames emitted since the last start (gap runs excluded)
`underruns` / `overruns` / `seq_gaps`	`int`	empty-ring / ring-full / dropped-append counts
`held`	`List[Usage]`	the held-usage snapshot: the buttons, keys, and media the clip is holding down (one shape, like a `UsageSnapshot`)
`is_held(usage)`	`bool`	test one `Usage` in `held`

See Catch and Logs & counters; consuming events is on Streams.

CatchMask (IntFlag)

Member	Value	Subscribes to
`MOTION`	`1`	cursor motion
`WHEEL`	`2`	wheel
`BUTTONS`	`4`	mouse buttons
`KEYS`	`8`	keyboard keys
`MEDIA`	`16`	media keys
`ALL`	`31`	everything (default)

Combine with |, e.g. CatchMask.BUTTONS | CatchMask.KEYS.

CatchEventKind

Member	Value	`CatchEvent.payload` type
`MOTION`	`0`	`MotionEvent`
`USAGES`	`1`	`UsageSnapshot`

LogLevel

Member	Value
`ERROR`	`0`
`WARN`	`1`
`INFO`	`2`
`DEBUG`	`3`
`VERBOSE`	`4`

Mostly internal. MotionKind and Class tag the structs the Usage and Motion builders produce; FrameType names a wire frame for MockBox.saw() and RecordedFrame.type. Frame semantics are on Frames and Library frames.

MotionKind

Member	Value
`CURSOR`	`0`
`WHEEL`	`1`

Class

Member	Value
`BUTTON`	`0`
`KEY`	`1`
`MEDIA`	`2`

FrameType

Member	Value	Member	Value
`MOVE`	`1`	`LOCK`	`10`
`INJECT`	`3`	`CATCH`	`11`
`RESET`	`4`	`MOTION_EVENT`	`12`
`QUERY`	`5`	`USAGE_EVENT`	`15`
`RESP`	`6`	`OPTION`	`17`
`REBOOT_DL`	`7`	`CLIP_APPEND`	`18`
`LOG`	`8`	`CLIP_CTRL`	`19`
`LED`	`9`	`CLIP_SET`	`20`
		`CLIP_TRIGGER`	`21`

Small classes that wrap a native struct. Build them with their class methods and pass the result to the matching call. Never construct one field by field.

Usage

Usage.button(button) -> Usage
Usage.key(key)       -> Usage
Usage.media(media)   -> Usage

An injection target for dev.inject(input, action). See Inject.

Motion

Motion.cursor(dx, dy) -> Motion
Motion.wheel(delta)   -> Motion

A relative axis drive for dev.move_axis(motion). See Move.

LockTarget

LockTarget.x()            -> LockTarget
LockTarget.y()            -> LockTarget
LockTarget.wheel()        -> LockTarget
LockTarget.usage(usage)   -> LockTarget
LockTarget.button(button) -> LockTarget
LockTarget.key(key)       -> LockTarget
LockTarget.media(media)   -> LockTarget

An axis or usage to lock for dev.lock(target, direction); the button/key/media shortcuts wrap usage(). See Lock.

The cloned device's kind, on DeviceInfo.kind, and what Device.find_mouse_box() / find_keyboard_box() select on. See DeviceKind.

DeviceKind

Member	Value
`UNKNOWN`	`0`
`KEYBOARD`	`1`
`MOUSE`	`2`

Dataclasses returned by the queries. Canonical field docs: Library structs.

Version (query_version())

Field / property	Type	Meaning
`proto_ver`	`int`	control-protocol version
`fw_major`	`int`	firmware major
`fw_minor`	`int`	firmware minor
`fw_patch`	`int`	firmware patch
`mac`	`bytes`	the device chip's base MAC (6 bytes), a stable per-box id
`mac_hex`	`str`	the MAC as 12 lowercase hex digits
`name`	`str`	the box's human-readable name (a synthesized default when unset), set with `set_name`

Health (query_health())

Field	Type
`link_up`	`bool`
`mouse_attached`	`bool`
`clone_configured`	`bool`
`injection_active`	`bool`
`rate_confident`	`bool`
`lock_on`	`bool`
`catch_on`	`bool`
`kbd_attached`	`bool`

DeviceInfo (device_info())

Field	Type	Meaning
`vid`	`int`	USB vendor id
`pid`	`int`	USB product id
`bcd_device`	`int`	device release (BCD)
`bcd_usb`	`int`	USB spec (BCD)
`has_serial`	`bool`	exposes a serial string
`has_bos`	`bool`	exposes a BOS descriptor
`kind`	`DeviceKind`	the device's primary kind (Boot-interface protocol)
`product`	`str`	the product string (empty when none)

Caps (caps())

Field / method	Type	Meaning
`mouse`	`MouseCaps`	mouse capabilities
`keyboard`	`KbdCaps`	keyboard capabilities
`mouse_change_driven`	`bool`	mouse reports only on change
`kbd_change_driven`	`bool`	keyboard reports only on change
`has_mouse()`	`bool`	a mouse interface is present
`has_keyboard()`	`bool`	a keyboard interface is present
`is_composite()`	`bool`	the clone has more than one HID interface (`n_hid > 1`)

MouseCaps

Field	Type	Meaning
`n_buttons`	`int`	button count
`has_x`	`bool`	X axis present
`has_y`	`bool`	Y axis present
`has_wheel`	`bool`	wheel present
`has_report_id`	`bool`	reports carry a report id
`n_hid`	`int`	HID interface count

KbdCaps

Field	Type	Meaning
`n_keys`	`int`	rollover key count
`nkro`	`bool`	n-key rollover
`has_consumer`	`bool`	Consumer (media) page
`has_system`	`bool`	System-control page
`has_report_id`	`bool`	reports carry a report id

More query results, plus PortInfo from find_ports(). Canonical field docs: Library structs.

Rate (query_rate())

Field / method	Type	Meaning
`native_period_us`	`int`	mouse report period, µs
`poll_period_us`	`int`	poll period, µs
`confident`	`bool`	estimate is settled
`change_driven`	`bool`	reports only on change
`native_hz()`	`float \| None`	rate in Hz, or `None` if unknown

Stats (query_stats())

Field	Type	Meaning
`inject_emits`	`int`	injected reports emitted
`tx_drops`	`int`	dropped TX frames
`tx_merges`	`int`	coalesced TX frames
`tx_maxdepth`	`int`	peak TX queue depth
`tx_wedges`	`int`	TX stalls
`wakeups`	`int`	scheduler wakeups
`reset_count`	`int`	resets seen
`config_count`	`int`	clone configures

Locks (query_locks())

Field / method	Type	Meaning
`entries`	`List[LockEntry]`	one `LockEntry` per active lock
`is_locked(target, direction)`	`bool`	test one `LockTarget` + `LockDirection`; also true when a whole-class blanket covers it

LockEntry

Field	Type	Meaning
`target`	`LockTarget`	what is locked (an axis or a usage)
`is_blanket`	`bool`	a whole-class lock, where `target` names only the class
`positive`	`bool`	the +x / +y / wheel-up / press edge is locked
`negative`	`bool`	the -x / -y / wheel-down / release edge is locked

CatchState (query_catch())

Field	Type	Meaning
`mask`	`int`	active `CatchMask` bits
`dropped`	`int`	events dropped by the box

ImperfectStatus (query_imperfect())

Field	Type	Meaning
`allowed`	`bool`	imperfect clones opted in
`over_capacity`	`bool`	mouse exceeds clone capacity
`clone_imperfect`	`bool`	the live clone is imperfect

See Options.

EmitPaceStatus (query_emit_pace())

Field	Type	Meaning
`mode`	`EmitPace`	the selected mode
`resolved_hz`	`int`	the ceiling in effect; 0 = learned/adaptive or no device yet

See Options.

Counters (counters())

Field	Type	Meaning
`frames_tx`	`int`	host-side frames sent
`frames_rx`	`int`	host-side frames received
`crc_drops`	`int`	frames dropped on CRC
`reconnects`	`int`	link reconnects

PortInfo (find_ports())

Field	Type	Meaning
`path`	`str`	serial path, e.g. `/dev/ttyACM0` or `COM3`
`vid`	`int`	USB vendor id
`pid`	`int`	USB product id
`serial`	`Optional[str]`	the CH343 adapter's serial, when it serves one

Pass path to Device.open(path). Canonical: PortInfo.

BoxInfo (list_boxes())

Field / property	Type	Meaning
`port`	`PortInfo`	the box's control port
`version`	`Version`	its firmware version, with the box MAC and name
`device`	`DeviceInfo`	the device it clones
`id`	`str`	the box identity (the MAC hex)
`serial`	`Optional[str]`	the CH343 serial

Pass id or serial to Device.open_by_id(id). Canonical: BoxInfo.

Payloads from streams. dev.catch_events() yields CatchEvent and dev.logs() yields LogLine. What catch reports lives on Catch.

CatchEvent

Field / member	Type	Meaning
`kind`	`CatchEventKind`	which payload is set
`payload`	`MotionEvent \| UsageSnapshot`	the decoded event
`motion`	`MotionEvent` `\| None`	payload when `kind == MOTION`
`usages`	`UsageSnapshot` `\| None`	payload when `kind == USAGES`

MotionEvent

Field	Type	Meaning
`dx`	`int`	X delta
`dy`	`int`	Y delta
`dz`	`int`	wheel delta

UsageSnapshot

Field / method	Type	Meaning
`usages`	`List[Usage]`	every held `Usage` (button, key, or media; modifiers are key usages `0xE0` to `0xE7`)
`is_held(usage)`	`bool`	test a `Usage` in the snapshot

LogLine

Field	Type	Meaning
`level`	`LogLevel`	severity
`text`	`str`	the log message

RecordedFrame (MockBox.recorded_frame(idx))

Field	Type	Meaning
`type`	`FrameType` `\| int`	frame type (raw `int` if unknown)
`seq`	`int`	frame sequence byte
`payload`	`bytes`	raw frame payload

Only meaningful with the mock feature.

Every Blocks call (and any that fails on the wire) raises a MediusError or one of its subclasses. Catch the base class to catch them all. Canonical mapping: Library errors.

MediusError (Exception)

Attribute	Type	Meaning
`status`	`Status`	the failure code
`message`	`str`	the box's last error text
`proto_ver`	`int`	offending version byte (bad-proto-version only)

from medius import Device, MediusError, NotFoundError

try:
    dev = Device.find()
except NotFoundError:
    ...                      # no box plugged in
except MediusError as e:     # any other failure
    print(e.status, e.message)

Subclass per Status

Exception	Raised on
`IoError`	`ERR_IO`
`NotFoundError`	`ERR_NOT_FOUND`
`NoReplyError`	`ERR_NO_REPLY`
`BadProtoVerError`	`ERR_BAD_PROTO_VER`
`QueryTimeoutError`	`ERR_QUERY_TIMEOUT`
`DisconnectedError`	`ERR_DISCONNECTED`
`FrameTooLongError`	`ERR_FRAME_TOO_LONG`
`FlashToolError`	`ERR_FLASH_TOOL`
`InvalidArgError`	`ERR_INVALID_ARG`
`PanicError`	`ERR_PANIC`

DisconnectedError ends a stream iteration cleanly rather than propagating. OK and ERR_UNKNOWN have no dedicated subclass; ERR_UNKNOWN raises the base MediusError.

Status

Member	Value	Member	Value
`OK`	`0`	`ERR_DISCONNECTED`	`6`
`ERR_IO`	`1`	`ERR_FRAME_TOO_LONG`	`7`
`ERR_NOT_FOUND`	`2`	`ERR_FLASH_TOOL`	`8`
`ERR_NO_REPLY`	`3`	`ERR_INVALID_ARG`	`9`
`ERR_BAD_PROTO_VER`	`4`	`ERR_PANIC`	`10`
`ERR_QUERY_TIMEOUT`	`5`	`ERR_UNKNOWN`	`11`

Injection enums

Lock & blanket enums

Keycode enums

LED & admin enums

Emit pace

Clip

Stream enums

Wire enums

Parameter builders

Device enums

Identity & capability types

State & telemetry types

Event & log types

Errors