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 |
| Footer (CRC16) (2 Bytes) |
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 |
|---|---|---|
| 0 | ACK_REQUIRED | Sender requests acknowledgment |
| 1 | ACK | Frame is an acknowledgment |
| 2 | IS_RETRY | Frame is a retransmission |
| 3 | 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.
| Context Value | Context | Description |
|---|---|---|
| 0 | Core | Core/system messages (discovery, sync, error) |
| 1 | Node | Node-level operations |
| 2 | Element | Element-level operations |
| 3 | VWire | Virtual wire messaging |
| 4–7 | RESERVED | Future expansion |
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