# Troubleshooting _Common failures and what they mean_ Every message in either direction is a [`frame`](/native/frame.md) (one packet on the wire). Most commands are [fire-and-forget](/native/injection.md#fire-and-forget): you send, the box stays silent. The exception is [`QUERY`](/native/commands/requests.md#requests), which asks for a piece of the box's state and gets back one [`RESP`](/native/commands/requests.md#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)`](/native/commands/requests.md#version) asks for the firmware and protocol version; the reply is a [`RESP(VERSION)`](/native/commands/requests.md#version) frame. If none comes back, check: - The port wasn't opened at `4,000,000` baud. The box speaks [framed binary](/native/frame.md) 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)`](/native/commands/requests.md#version) the box sends on its own once the control link comes up. Missing it costs nothing: send [`QUERY(VERSION)`](/native/commands/requests.md#version) and read the reply. See [the ready hello](/native/connection.md#hello). ## Injection does nothing _Check HEALTH before you rely on it_ [Injection](/native/injection.md) 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)`](/native/commands/requests.md#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`](/native/hardware.md)), and `CLONE_CONFIGURED` (the PC has enumerated the clone). The full flags byte is on [HEALTH](/native/commands/requests.md#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. | Event | Effect | | --- | --- | | 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](/native/frame.md#crc) (including a [`QUERY`](/native/commands/requests.md#requests)) | Resets the timer. | To hold an injected button, keep the link busy with periodic frames (a [`QUERY(HEALTH)`](/native/commands/requests.md#health) is enough), or let [the library's keepalive](/library/guides/connection.md#keepalive) do it. > **Note** > > See [Injection](/native/injection.md#safety) for the safety state machine. ## A machine shuts off or drains its battery _USB1 and USB3 on the same machine_ [`USB1`](/native/hardware.md) and [`USB3`](/native/hardware.md) share one internal rail, and the [`USB3`](/native/hardware.md) 5V rail can't be pulled low in firmware, so wiring both to one machine back-feeds power into it. Keep them apart: | Port | Carries | Connects to | | --- | --- | --- | | [`USB1`](/native/hardware.md) | the clone to the PC | the game PC | | [`USB2`](/native/hardware.md) | the control link | the control PC | | [`USB3`](/native/hardware.md) | the real mouse | the mouse | > **Danger** > > ⚠️ [`USB1`](/native/hardware.md) and [`USB3`](/native/hardware.md) must never both connect to the same machine. See [Hardware](/native/hardware.md). ## The serial port disappeared after a REBOOT _The chip is in ROM download mode_ A download [`REBOOT`](/native/commands/admin.md#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](/native/flashing.md). ## No LOG frames arrive _Only sent while a control PC is attached_ [`LOG`](/native/commands/admin.md#log) is the box's unsolicited diagnostic frame (box to PC). If none arrive, check: - No control PC is attached. [`LOG`](/native/commands/admin.md#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.