Differences

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

--- mtrp:frame_format [2026/06/10 13:14] – [2.4 Payload Responsibilities] mosh
+++ mtrp:frame_format [2026/06/10 13:17] (current) – mosh
@@ Line 3: / Line 3: @@
 ===== 2.1 Purpose =====
-This document defines the high-level structure of an MTRP frame.
+This document defines the on-wire frame structure currently used by MTRP.
-===== 2.2 Frame Model =====
+===== 2.2 Scope =====
+This document describes:
+  * the serialized MTRP header
+  * payload placement
+  * optional CRC placement
+  * compact and native header formats
+  * the distinction between wire fields and local metadata
+===== 2.3 Frame Model =====
 An MTRP frame consists of:
-  * a protocol header
+  * a serialized header
   * a payload
-  * implementation-local metadata used during processing
+  * an optional CRC footer
+  * local metadata used internally by the router
-Only the serialized protocol header and payload are transmitted on the wire as part of the MTRP frame representation.
+Only the serialized header, payload, and optional CRC are transmitted on the wire.
-===== 2.3 Header Layout =====
+Local metadata is not serialized as part of the MTRP frame.
-The MTRP header carries the core routing-visible fields used for forwarding and protocol handling.
+===== 2.4 Native Frame Layout =====
-A conceptual full header layout is shown below.
+In native mode, the serialized frame layout is:
-^ Field ^ Size ^ Purpose ^
+  * ''Flags'' (1 byte)
-| Version | 1 byte | Protocol version |
+  * ''Version'' (1 byte)
-| Flags | 1 byte | Control and behavior flags |
+  * ''Payload Length'' (2 bytes)
-| Network ID | 2 bytes | Logical network identifier |
+  * ''Message ID'' (2 bytes)
-| Origin Node ID | 2 bytes | Original sender node |
+  * ''Origin Node ID'' (2 bytes)
-| Destination Node ID | 2 bytes | Intended destination node |
+  * ''Destination Node ID'' (2 bytes)
-| Previous Hop Node ID | 2 bytes | Last forwarding node |
+  * ''Previous Hop Node ID'' (2 bytes)
-| Message ID | 2 bytes | Per-origin message identifier |
+  * ''Network ID'' (2 bytes)
-| TTL | 1 byte | Remaining hop count |
+  * ''TTL'' (1 byte)
+  * ''Payload'' (variable)
+  * ''CRC16'' (optional, 2 bytes, only if ''WITH_CRC'' is set)
-The exact serialized layout MUST match the implementation used by the current firmware.
+Native header length is 15 bytes.
-===== 2.4 Header Semantics =====
+===== 2.5 Compact Frame Layout =====
-==== 2.4.1 Version ====
+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.
-==== 2.4.2 Flags ====
+In native mode, version occupies one full byte.
-The flags field carries protocol behavior bits such as:
+In compact mode, version occupies the upper 3 bits of the combined ''Version/Length'' byte.
-  * control/data distinction
+A received frame MUST match the implementation's configured protocol version.
-  * relay requirement
-  * compact-header signaling
-  * future reliability signaling
-==== 2.4.3 Network ID ====
+==== 2.7.3 Payload Length ====
-The network ID distinguishes one logical MTRP network from another.
+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.4.4 Origin Node ID ====
+==== 2.7.5 Origin Node ID ====
 The origin node ID identifies the original sender of the frame.
-==== 2.4.5 Destination Node ID ====
+==== 2.7.6 Destination Node ID ====
 The destination node ID identifies the intended recipient of the frame.
-==== 2.4.6 Previous Hop Node ID ====
+==== 2.7.7 Previous Hop Node ID ====
 The previous hop node ID identifies the node that most recently forwarded or transmitted the frame.
-==== 2.4.7 Message ID ====
+==== 2.7.8 Network ID ====
-The message ID is used for duplicate suppression and message tracking.
+The network ID distinguishes one logical MTRP network from another.
-==== 2.4.8 TTL ====
+==== 2.7.9 TTL ====
 The TTL field limits how many forwarding hops a frame may traverse.
-===== 2.5 Local Metadata =====
+===== 2.8 Compact Version/Length Byte =====
-Local metadata is used by the router during internal processing and route resolution.
+In compact mode, the second header byte is packed as follows:
-Local metadata is not equivalent to the serialized wire header.
+^ Bit Range ^ Meaning ^
+| bits 7..5 | version |
+| bits 4..0 | payload length |
-Examples of local metadata include:
+Equivalent expression:
-  * ingress path identifier
+  * ''version = (byte >> 5) & 0x07''
-  * ingress path metric
+  * ''payloadLength = byte & 0x1F''
-  * resolved egress path identifier
-  * resolved next-hop identifier
-  * local delivery behavior flags
-===== 2.6 Compact Operation =====
+This means:
-On constrained transports, MTRP MAY use a compact on-wire representation.
+  * compact mode supports a 3-bit serialized version value
+  * compact mode supports a maximum serialized payload length of 31 bytes
-Compact operation SHOULD preserve core routing semantics while reducing header cost on limited transports.
+===== 2.9 Payload =====
-Compact operation does not remove the requirement for the receiver to correctly determine how the frame is to be interpreted.
+The payload immediately follows the serialized header.
-===== 2.7 Broadcast and Unicast Semantics =====
+Payload length is determined by the serialized length field.
-A frame MAY be addressed as either:
+The payload may carry:
-  * unicast, for a specific destination node
+  * control messages
-  * broadcast, for network-wide or local-scope distribution
+  * route advertisements
+  * application data
-Broadcast handling and unicast handling MAY differ in forwarding and reliability behavior.
+===== 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:
+  * ingress path ID
+  * ingress path metric
+  * egress path ID
+  * egress next hop
+  * route resolution state
+  * fragment bookkeeping
+  * transport-source metadata
-===== 2.8 Current Limitations =====
+These values exist only for local router behavior.
-The present documentation does not fully specify:
+===== 2.13 Current Notes =====
-  * fragmentation format
+  * native mode uses a 15-byte header
-  * reliable-delivery extensions
+  * compact mode uses a 13-byte header
-  * end-to-end acknowledgment fields
+  * compact mode payload length is currently limited to 31 bytes
-  * group-address wire format
+  * compact mode sets the ''IS_COMPACT'' flag on wire
+  * CRC is optional and controlled by the ''WITH_CRC'' flag