Connection & handshake
Open, find, and handshakeThe handshake confirms the device on the serial port is a Medius box and speaks a protocol version you understand: one request, one reply.
- No baud negotiation.
- No login.
- No
115200startup step or baud-switch command.
Handshake
One round-trip to confirm the box- Open the serial port at
4,000,000baud (Transport). The box speaks framed binary from the first byte. - Catch the unsolicited hello the box sends on its own (below), or send a
QUERY(VERSION)yourself. Both produce the sameRESP(VERSION)frame. - Read
proto_verfrom that reply and check it equals5.
| Reply | Meaning |
|---|---|
proto_ver == 5 | Speaks the protocol these pages describe. |
proto_ver != 5 | Speaks a protocol these pages don't cover; don't assume the commands behave as described. |
| No reply | Not a Medius box, or the port or baud is wrong. |
The check is mandatory, not advisory. Firmware 3.1.x and earlier report 4, where LOCK's last byte was a state (1 = lock, 0 = unlock) rather than a scale. The two readings are an exact inversion.
a proto-5 host talking to a proto-4 box scale = 100 (unlock) -> state = 100, non-zero -> LOCKS it scale = 0 (block) -> state = 0 -> UNLOCKS it
Full detail on the Requests page.
| Offset | Field | Type | Notes |
|---|---|---|---|
| 0 | what | u8 | the selector byte, echoed back; 0x00 = VERSION |
| 1 | proto_ver | u8 | protocol version, expected 5 |
| 2 | fw_major | u8 | firmware major |
| 3 | fw_minor | u8 | firmware minor |
| 4 | fw_patch | u8 | firmware patch |
| 5 | mac | u8[6] | the box MAC, a stable per-box id |
| 11.. | name | ascii | the box's human-readable name (may be empty), delimited by the frame LEN |
The ready hello
Unsolicited RESP(VERSION) on link-upThe box sends one RESP(VERSION) on its own as soon as its serial link is up. Treat it as "box is here and ready" and skip your own QUERY(VERSION).
| Trigger | When it fires |
|---|---|
| Power-on | Once, as the box boots. |
| First contact | On the first valid frame after a program opens the port, so a program that connects after the power-on hello still gets one. |
The hello carries SEQ=0, and its payload is identical to a queried reply.
The medius library does all of this inside open and find: it sends QUERY(VERSION), retries a few times, and checks proto_ver == 5 before handing you a working connection.