# ADR 009: Explicit Versioned Wire Protocol

- HTML version: https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/009-versioned-wire-protocol
- Project: Autonomic Satellite Swarm (https://robbiepalmer.me/projects/autonomic-satellite-swarm.md)
- Status: Accepted
- Date: 2026-09-04

# Context

The historical implementation packed messages into platform-dependent signed `long` values. Some
shifts were undefined, a target-ID mask selected the wrong bits, and coordinate requests contained no
origin ID. Sending 32 bits through Sony infrared framing also exceeded the standard Sony payload
sizes.

# Decision

Define a 12-byte version-one packet with explicit message type, origin, target, mission ID, signed
centidegree coordinates, score, and an eight-bit cyclic redundancy check (CRC-8). The receiver
recalculates this checksum and rejects the packet when the result does not match, which catches
accidental changes to the data. Encode multi-byte fields in big-endian order and validate the
complete packet before exposing it to the state machine.

NEC is the 32-bit message format used by many consumer infrared remote controls and supported by the
Arduino IRremote library. One NEC frame carries a chunk number and three bytes of the packet, so the
infrared adapter needs four frames for one packet. The receiver accepts a message only after all four
chunks arrive and discards an incomplete assembly after 250 milliseconds. This timeout belongs to
the infrared adapter rather than the wire protocol. Compile checks exercise the code, but no
measurements from the unavailable bench hardware support that duration. Hardware-in-the-loop
testing must measure NEC frame duration and inter-frame gaps before retaining or tuning it. ESP-NOW
transports the complete 12-byte packet directly.

Keep that fragmentation inside the infrared adapter. Do not shrink the domain message or spread its
limitations into other transports merely to accommodate a weak bench link. Wire compatibility with
the defective historical encoding is intentionally not preserved.

# Consequences

The protocol behaves consistently across 8-bit AVR and 32-bit ESP32 targets, corrupted packets are
rejected, and round-trip tests describe the contract.

Four infrared transmissions are less reliable than one. If one frame has probability `p` of arriving,
the chance of all four arriving is `p⁴`, assuming independent losses. A missing frame normally leaves
the message incomplete until the receiver discards it, and there is no fragment-level retry. Frames
from overlapping transmissions could also be combined. The CRC rejects most corrupted combinations,
but it cannot recover a missing frame. The negotiation retries some messages, while a request or
assignment can still be lost. This is an acknowledged weakness of the infrared demonstration, not a
constraint on the core protocol or future hardware.

A CRC detects accidental corruption but does not prove who sent a message. Authentication, replay
protection, and key lifecycle require a future protocol decision.

---

Markdown index of this site: https://robbiepalmer.me/llms.txt