Medius - Native APITroubleshooting

Troubleshooting

Common failures and what they mean

Every message in either direction is a frame (one packet on the wire). Most commands are fire-and-forget: you send, the box stays silent. The exception is QUERY, which asks for a piece of the box's state and gets back one RESP frame. Most checks below use that round-trip.

No reply to QUERY(VERSION)

Wrong baud, a held port, or not a Medius box

QUERY(VERSION) asks for the firmware and protocol version; the reply is a RESP(VERSION) frame. If none comes back, check:

  • The port wasn't opened at 4,000,000 baud. The box speaks framed binary from the first byte, with no slower startup speed.
  • Another process holds the port. Only one program can have it open.
  • It isn't a Medius box, or you opened the wrong port.
  • You opened the port after the hello already fired.

The hello is a RESP(VERSION) the box sends on its own once the control link comes up. Missing it costs nothing: send QUERY(VERSION) and read the reply. See the ready hello.

Injection does nothing

Check HEALTH before you rely on it

Injection is the input your program adds on top of the real mouse's passthrough (movement, buttons, scroll). If it has no effect, send QUERY(HEALTH) and read the flags byte. The box only merges injection once the first three flags are set: LINK_UP, MOUSE_ATTACHED (a mouse is on USB3), and CLONE_CONFIGURED (the PC has enumerated the clone). The full flags byte is on HEALTH.

A held button releases on its own

The silence auto-clear dropped it

The box clears all injection if your program goes quiet, so input can't get stuck.

EventEffect
Silence timeout (default 1000 ms with no valid inbound frame)Drops every held button and pending move, returns to plain passthrough.
Any frame that passes its checksum (including a QUERY)Resets the timer.

To hold an injected button, keep the link busy with periodic frames (a QUERY(HEALTH) is enough), or let the library's keepalive do it.

See Injection for the safety state machine.

A machine shuts off or drains its battery

USB1 and USB3 on the same machine

USB1 and USB3 share one internal rail, and the USB3 5V rail can't be pulled low in firmware, so wiring both to one machine back-feeds power into it. Keep them apart:

PortCarriesConnects to
USB1the clone to the PCthe game PC
USB2the control linkthe control PC
USB3the real mousethe mouse

⚠️ USB1 and USB3 must never both connect to the same machine. See Hardware.

The serial port disappeared after a REBOOT

The chip is in ROM download mode

A download REBOOT (target 0 or 1) drops a chip into ROM download mode, so its running firmware, and the serial port that firmware provides, goes away. Flash the chip or power-cycle the box to get the port back. See Flashing.

No LOG frames arrive

Only sent while a control PC is attached

LOG is the box's unsolicited diagnostic frame (box to PC). If none arrive, check:

  • No control PC is attached. LOG is only emitted while one is.
  • It logged before first contact. That output is dropped, not buffered.
  • It's early ROM-bootloader output, which is plain ASCII the frame decoder ignores.