This is an old revision of the document!
Table of Contents
MOSH Protocol Specification (v1 Draft)
Overview
MOSH (Modern Offline Smart Home) is a lightweight, transport-agnostic messaging protocol designed for embedded systems and distributed smart-home environments.
The protocol is optimized for:
- Small microcontrollers (e.g., ATmega128)
- Deterministic parsing
- Minimal memory usage
- Transport independence (nRF24, ESP-NOW, UART, etc.)
- Decentralized operation (no required central coordinator)
MOSH separates responsibilities into:
—–
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 Btyes) |
| 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 | 1 | Message domain (SYSTEM/NODE/ELEMENT/VWIRE) |
| Op Code | 1 | Operation within context |
| 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 | RESERVED | Reserved for future use |
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
Context and Op Codes
The Context byte determines which core manager processes the payload.
| 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