Wire v3 Frame Format

This page defines the canonical on-wire layout for a Wire v3 frame. It documents the fixed header fields, byte offsets, endian rules, and size constraints used by the RadioLink protocol layer.

Canonical Frame Layout

A Wire v3 frame is serialized in this order:

+------------+---------+-------------------+----------------+------------+---------+------+
| version    | nodeId  | sessionSeqId_le   | msgCounter_le  | payloadLen | payload | CMAC |
| 1 byte     | 1 byte  | 4 bytes           | 4 bytes        | 1 byte     | N bytes | 16 B |
+------------+---------+-------------------+----------------+------------+---------+------+

Fixed Header Byte Map

The fixed Wire v3 header is 11 bytes long and occupies byte offsets 0..10.

Byte  0      version
Byte  1      nodeId
Bytes 2..5   sessionSeqId_le
Bytes 6..9   msgCounter_le
Byte  10     payloadLen
Byte  11...  payload begins

Header Field Definitions

version : Wire-format version discriminator. The current supported value is RADIOLINK_WIRE_V3_VERSION (0x03).

nodeId : Runtime node identifier for the sender.

sessionSeqId_le : Little-endian 32-bit session sequence identifier. This value advances once per TX boot epoch and is used as part of replay protection and nonce derivation.

msgCounter_le : Little-endian 32-bit per-session message counter. This value advances only after a successful transmission and is also used for replay protection and nonce derivation.

payloadLen : Length in bytes of the payload region that follows the fixed header. This is the plaintext length before encryption and the ciphertext length on wire after encryption. Wire v3 does not include the CMAC tag length in payloadLen.

payload : Variable-length application payload. The payload begins immediately after the fixed 11-byte header and is AES-CTR protected on wire.

CMAC : Fixed 16-byte AES-CMAC authentication tag appended after the payload. The tag authenticates the serialized header and ciphertext payload.

Wire v3 Protocol Invariants

The following conditions must always hold for any valid Wire v3 frame:

• The fixed header length is exactly 11 bytes.
• The CMAC tag length is exactly 16 bytes.
• payloadLen represents only the payload and never includes the CMAC tag.
• frameLen = 11 + payloadLen + 16.
• The payload begins immediately at byte offset 11.
• sessionSeqId_le and msgCounter_le are serialized little-endian.
• Any frame shorter than 27 bytes is structurally invalid.

Endian Rules

Multi-byte integer fields in the Wire v3 header are serialized in little-endian format:

• sessionSeqId_le
• msgCounter_le

The single-byte fields version, nodeId, and payloadLen have no endian ambiguity.

Frame Size Constraints

Total frame length is defined as:

frameLen = headerLen + payloadLen + cmacLen

Current fixed lengths:

headerLen = 11 bytes
cmacLen   = 16 bytes
overhead  = 27 bytes

With the current transport limit of 255 bytes, the maximum plaintext payload that fits in a single Wire v3 frame is:

maxPayloadLen = 255 - 11 - 16 = 228 bytes

Relationship to Implementation Constants

The canonical byte offsets documented on this page correspond to the derived offsetof()-based constants in radio_wire.h:

• RL_W3_OFF_VERSION = 0
• RL_W3_OFF_NODE_ID = 1
• RL_W3_OFF_SESSION_SEQ_ID = 2
• RL_W3_OFF_MSG_COUNTER = 6
• RL_W3_OFF_PAYLOAD_LEN = 10
• RL_W3_OFF_PAYLOAD = 11

The fixed header length is derived as:

• RADIOLINK_WIRE_V3_HEADER_LEN = 11

Forward Compatibility Note

Future protocol revisions may add new authenticated metadata fields to the fixed header. Any such change must be treated as a wire-format revision and must not silently alter the Wire v3 layout documented here.