This is an old revision of the document!
Table of Contents
Framing Overview
Framing defines how raw byte streams are structured into discrete MOSH frames.
Responsibilities include:
Start-of-frame detection (SOF) Field layout and byte ordering Payload length encoding CRC calculation and validation Frame boundary recovery in noisy streams
Framing ensures that receivers can:
Synchronize to incoming data streams Validate structural integrity before processing Recover from partial or corrupted transmissions
This layer is strictly deterministic and must be bit-for-bit compatible across all implementations.
Frame Structure
A MOSH frame is a maximum 1470 bytes. Depending on the transport, frames can/will be segmented if the frames length is longer than the transport maximum.
All MOSH packets follow this structure:
| Header (12 Bytes) |
| Payload (1,456 Bytes max) |
| Footer (CRC16) (2 Bytes) |
Note: All multi-byte fields are serialized little-endian.
Header Layout (12 Bytes)
| Field | Length (Bytes) | Description |
|---|---|---|
| Start of Frame | 1 | Fixed marker for frame synchronization |
| TTL | 1 | Time-to-live (decremented on forwarding) |
| Message ID | 2 | Unique ID per message (for ACK/retry/dedupe) |
| Version + Flags | 1 | Upper 4 bits = protocol version, lower 4 bits = flags |
| Source Address | 2 | 6-bit Network ID + 10-bit Node ID |
| Destination Address | 2 | 6-bit Network ID + 10-bit Node ID |
| Context | 2 | 3-bit Domain, 5-bit Operations Code, 8-bit Context ID |
| Payload Length | 1 | Length of payload in bytes |
Footer (2 Bytes)
| Field | Size (Bytes) | Description |
|---|---|---|
| CRC16 | 2 | Frame integrity check |
Version and Flags
Version (Upper nibble)
Protocol version (0–15).
Flags (Lower Nibble)
| Bit | Name | Description |
|---|---|---|
| 0x00 | NONE | No flags are set |
| 0x01 | ACK_REQUIRED | Sender requests acknowledgment |
| 0x02 | ACK | Frame is an acknowledgment |
| 0x04 | IS_RETRY | Frame is a retransmission |
| 0x08 | IS_FRAGMENT | Frame is part of a fragment |
Addressing
Each address field is 16 bits: [ Network ID (6 bits) | Node ID (10 bits) ]
Network ID
- Range: 0–63
- Used to segment MOSH domains
Node ID
- Range: 0–1023
- Unique within a network
Domains, Operations Codes, and Context ID
The Context byte determines which manager processes the payload.
Domain (3-bits)
| Domain | Context | Description |
|---|---|---|
| 0 | Core | Core/system messages (discovery, sync, error) |
| 1 | Node | Node-level (hardware) operations |
| 2 | Element | Element-level operations |
| 3 | VWire | Virtual wire messaging |
| 4–7 | RESERVED | Future expansion |
The Context ID byte is the ID of the element or virtual wire being targeted.
Payload
The payload format will vary based on the various message types.
The transport layer does not interpret payload contents.
Footer (CRC16)
16-bit error detection code generated per frame