Serial protocol

Every line the board sends is a JSON object with an evt field. Every line you send is a JSON object with a cmd field. Lines that are not valid JSON are ignored, so bootloader chatter at reset will not desynchronise a reader.

The board emits hello once at boot. A host that attaches to an already-running board has missed it, so the first thing to send is get_info, which re-emits it on demand. The standard opening sequence is three queries that fully restore host-side state:

{"cmd":"get_info"}    -> hello       (identity + firmware hash)
{"cmd":"get_state"}   -> state       (enabled? mode? timed period?)
{"cmd":"get_timer"}   -> timer_state (remaining_ms of any running period)

This is what makes reattaching mid-match safe: the board keeps running its countdown across a disconnect, and these three replies tell a reconnecting host exactly where the match stands.

Losing the host mid-match is normal, not exceptional — the page reloads, the operator reopens it, the cable is replugged. The problem that creates is that a reconnecting host cannot tell the board "this is the period you are already running" without the board hearing "start a new one". Protocol 3 fixes that with a token: match_id (opaque, up to 32 characters) plus period_seq, sent on start_period and carried by resync and end_period.

Binding to a board. Every OpenFC enumerates under the same USB name, so on a multi-field event an operator can select the wrong port — and a token cannot catch it, because the token is perfectly valid, just meant for another field. Send the board's device_id from hello alongside the token and a mismatch is rejected with wrong_device before anything moves. Binding is sticky: a period started with a device_id can only be resynced or ended by commands that also carry one. estop is never gated on any of this.

Correcting drift. resync adjusts the deadline of the running period and nothing else — it never enables, disables, changes mode or re-fires a start. Shortening is unrestricted; extending is capped at 2000 ms, because the board's clock is the more trustworthy of the two. millis() runs off the 40 MHz crystal and drifts on the order of 12 ms across a two-minute period, whereas a backgrounded browser tab has its timers throttled. A host asking for a large extension has a wrong clock, not a longer match.

There are two independent mechanisms, and which one applies depends on how the robots were enabled.

A timed period is deliberately immune to the comms watchdog: a match must finish even if the laptop sleeps or the cable is pulled. The countdown is owned by the board, not the host. Backing that up, an on-chip task watchdog is armed to duration_ms + 10 s, so a firmware hang reboots the chip into the disabled state rather than leaving robots live.

Outside a timed period the opposite is true: anything that enables the robots requires the host to keep sending commands at least every 600 ms, or the board disables itself and reports {"evt":"estop","source":"watchdog"}. Send ping every 250 ms; any command resets the timer.

The board boots into DISABLED with the enable lines held at their safe level, so a power cycle or reset can never enable robots.

All four ports are driven in unison through optocouplers. Each V5 Competition Switch port carries two signals. Polarity differs between them, which is why the safe level is not the same for both.