Differences

This shows you the differences between two versions of the page.

--- mtrp:frame_format [2026/06/10 12:53] – created mosh
+++ mtrp:frame_format [2026/06/10 13:17] (current) – mosh
@@ Line 1: / Line 1: @@
-====== Frame Format ======
+====== 2. Frame Format ======
-MTRP frames consist of:
+===== 2.1 Purpose =====
-  * protocol header
+This document defines the on-wire frame structure currently used by MTRP.
-  * payload
-  * transport metadata used locally during processing
-===== Header Responsibilities =====
+===== 2.2 Scope =====
-The header carries protocol-visible information such as:
+This document describes:
-  * version
+  * the serialized MTRP header
-  * flags
+  * payload placement
-  * network ID
+  * optional CRC placement
-  * origin node ID
+  * compact and native header formats
-  * destination node ID
+  * the distinction between wire fields and local metadata
-  * previous hop node ID
-  * message ID
-  * TTL
-===== Compact Operation =====
+===== 2.3 Frame Model =====
-On constrained transports, MTRP may use a compact on-wire representation.
+An MTRP frame consists of:
-Compact mode is intended to preserve core routing behavior while reducing header cost on limited links such as NRF24-class paths.
+  * a serialized header
+  * a payload
+  * an optional CRC footer
+  * local metadata used internally by the router
-===== Important Note =====
+Only the serialized header, payload, and optional CRC are transmitted on the wire.
-Transport metadata used internally for routing decisions is not the same as the serialized on-wire header.
+Local metadata is not serialized as part of the MTRP frame.
+===== 2.4 Native Frame Layout =====
+In native mode, the serialized frame layout is:
+  * ''Flags'' (1 byte)
+  * ''Version'' (1 byte)
+  * ''Payload Length'' (2 bytes)
+  * ''Message ID'' (2 bytes)
+  * ''Origin Node ID'' (2 bytes)
+  * ''Destination Node ID'' (2 bytes)
+  * ''Previous Hop Node ID'' (2 bytes)
+  * ''Network ID'' (2 bytes)
+  * ''TTL'' (1 byte)
+  * ''Payload'' (variable)
+  * ''CRC16'' (optional, 2 bytes, only if ''WITH_CRC'' is set)
+Native header length is 15 bytes.
+===== 2.5 Compact Frame Layout =====
+In constrained mode, the serialized frame layout is:
+  * ''Flags'' (1 byte)
+  * ''Version/Length'' (1 byte)
+  * ''Message ID'' (2 bytes)
+  * ''Origin Node ID'' (2 bytes)
+  * ''Destination Node ID'' (2 bytes)
+  * ''Previous Hop Node ID'' (2 bytes)
+  * ''Network ID'' (2 bytes)
+  * ''TTL'' (1 byte)
+  * ''Payload'' (variable)
+  * ''CRC16'' (optional, 2 bytes, only if ''WITH_CRC'' is set)
+Compact header length is 13 bytes.
+===== 2.6 Header Field Order =====
+The current serialized field order is identical in both modes after the first header bytes.
+^ Order ^ Native ^ Compact ^ Size ^ Notes ^
+| 1 | Flags | Flags | 1 byte | protocol flags |
+| 2 | Version | Version/Length | 1 byte | compact mode packs version and payload length together |
+| 3 | Payload Length | Message ID | 2 bytes in native | compact mode does not store payload length separately |
+| 4 | Message ID | Origin Node ID | 2 bytes | per-origin message identifier |
+| 5 | Origin Node ID | Destination Node ID | 2 bytes | original sender |
+| 6 | Destination Node ID | Previous Hop Node ID | 2 bytes | intended recipient |
+| 7 | Previous Hop Node ID | Network ID | 2 bytes | most recent forwarding node |
+| 8 | Network ID | TTL | 2 bytes native / 1 byte compact | logical network identifier |
+| 9 | TTL | Payload | 1 byte | remaining hop count |
+For clarity, the actual compact order on wire is:
+  - Flags
+  - Version/Length
+  - Message ID
+  - Origin Node ID
+  - Destination Node ID
+  - Previous Hop Node ID
+  - Network ID
+  - TTL
+===== 2.7 Header Field Definitions =====
+==== 2.7.1 Flags ====
+The flags byte carries protocol behavior bits.
+Current flags are:
+^ Bit Mask ^ Name ^ Meaning ^
+| ''0x01'' | ''RELIABLE'' | frame requests acknowledgment |
+| ''0x02'' | ''ACK'' | frame is an acknowledgment |
+| ''0x04'' | ''FRAGMENT'' | frame is a fragment |
+| ''0x08'' | ''SECURE'' | frame is secured/encrypted |
+| ''0x10'' | ''RELAY_REQ'' | frame is intended for relaying |
+| ''0x20'' | ''IS_CONTROL'' | frame carries control-plane content |
+| ''0x40'' | ''IS_COMPACT'' | frame uses compact header format |
+| ''0x80'' | ''WITH_CRC'' | frame includes trailing CRC16 |
+==== 2.7.2 Version ====
+The version field identifies the protocol/header format in use.
+In native mode, version occupies one full byte.
+In compact mode, version occupies the upper 3 bits of the combined ''Version/Length'' byte.
+A received frame MUST match the implementation's configured protocol version.
+==== 2.7.3 Payload Length ====
+In native mode, payload length is stored as a 16-bit value.
+In compact mode, payload length is stored in the lower 5 bits of the combined ''Version/Length'' byte.
+As currently implemented, compact mode payload length is limited to 31 bytes.
+==== 2.7.4 Message ID ====
+The message ID is a per-origin identifier used for duplicate suppression and message tracking.
+==== 2.7.5 Origin Node ID ====
+The origin node ID identifies the original sender of the frame.
+==== 2.7.6 Destination Node ID ====
+The destination node ID identifies the intended recipient of the frame.
+==== 2.7.7 Previous Hop Node ID ====
+The previous hop node ID identifies the node that most recently forwarded or transmitted the frame.
+==== 2.7.8 Network ID ====
+The network ID distinguishes one logical MTRP network from another.
+==== 2.7.9 TTL ====
+The TTL field limits how many forwarding hops a frame may traverse.
+===== 2.8 Compact Version/Length Byte =====
+In compact mode, the second header byte is packed as follows:
+^ Bit Range ^ Meaning ^
+| bits 7..5 | version |
+| bits 4..0 | payload length |
+Equivalent expression:
+  * ''version = (byte >> 5) & 0x07''
+  * ''payloadLength = byte & 0x1F''
+This means:
+  * compact mode supports a 3-bit serialized version value
+  * compact mode supports a maximum serialized payload length of 31 bytes
+===== 2.9 Payload =====
+The payload immediately follows the serialized header.
+Payload length is determined by the serialized length field.
+The payload may carry:
+  * control messages
+  * route advertisements
+  * application data
+===== 2.10 Optional CRC Footer =====
+If the ''WITH_CRC'' flag is set, the frame includes a trailing 16-bit CRC after the payload.
+Current behavior:
+  * CRC algorithm: CRC-16/CCITT
+  * CRC is computed over ''header + payload''
+  * CRC bytes are appended after the payload
+  * received CRC is validated during deserialization
+If ''WITH_CRC'' is not set, no CRC footer is serialized.
+===== 2.11 Deserialization Rules =====
+On receive:
+  - the flags byte is read first
+  - ''IS_COMPACT'' determines whether compact or native header parsing is used
+  - version MUST match the current protocol version
+  - payload length MUST not exceed the configured maximum
+  - if ''WITH_CRC'' is set, CRC validation MUST succeed
+A frame that fails these checks MUST be rejected.
+===== 2.12 Local Metadata =====
+MTRP also carries internal metadata that is not serialized on wire.
+Examples include:
-Examples of local metadata include:
   * ingress path ID
   * ingress path metric
-  * resolved egress path ID
+  * egress path ID
-  * resolved next hop
+  * egress next hop
+  * route resolution state
+  * fragment bookkeeping
+  * transport-source metadata
+These values exist only for local router behavior.
+===== 2.13 Current Notes =====
+  * native mode uses a 15-byte header
+  * compact mode uses a 13-byte header
+  * compact mode payload length is currently limited to 31 bytes
+  * compact mode sets the ''IS_COMPACT'' flag on wire
+  * CRC is optional and controlled by the ''WITH_CRC'' flag