The protocol uses a layered packet structure. The "On-the-Wire" format is the raw data transmitted by the radio, which contains the logical Packet object.
This is the raw byte sequence sent over the air.
[Header (1)] [Transport Codes (4)?] [Path Length (1)] [Path (N)] [Payload (M)]
- Header (1 byte): A single byte containing bit-packed information about the packet. See below for details.
- Transport Codes (4 bytes, Optional): Present if the routing type is
TRANSPORT_FLOODorTRANSPORT_DIRECT. Their specific function is not detailed in this code but they are reserved. - Path Length (1 byte): The length
Nof thePathfield. A length of 0 inROUTE_TYPE_DIRECTmode indicates a "Zero Hop" broadcast to immediate neighbors. - Path (
Nbytes):- In Flood mode, this field is built up as the packet is re-transmitted, containing a sequence of node hashes (
PATH_HASH_SIZEeach) that have forwarded the packet. - In Direct mode, this field contains the pre-determined route (a sequence of node hashes) the packet must follow.
- In Flood mode, this field is built up as the packet is re-transmitted, containing a sequence of node hashes (
- Payload (
Mbytes): The application-level data. Its structure is determined by thePayload Typespecified in theHeader.
The 8-bit header is composed of three fields:
| Bits | Name | Description |
|---|---|---|
7-6 |
Payload Version | The version of the payload encoding/encryption scheme. PAYLOAD_VER_1 is primarily used. |
5-2 |
Payload Type | Defines the structure and purpose of the Payload field. This is the main application-level packet identifier. |
1-0 |
Routing Type | Defines how the packet is routed through the mesh (FLOOD vs DIRECT). |
The structure of the Payload field depends on the Payload Type from the header. Most peer-to-peer and group payloads follow an [Identifier(s)][Encrypted Data] pattern.
The Encrypted Data block is common to many payload types and has the following structure:
[HMAC (2 bytes)] [AES128 Encrypted Payload]
- HMAC: A 2-byte Hash-based Message Authentication Code to verify integrity.
- AES128 Encrypted Payload: The actual application data, encrypted with AES-128.
A simple, unencrypted acknowledgement packet.
- Purpose: To acknowledge receipt of a packet.
- Payload Structure:
[ACK CRC (4 bytes)]- ACK CRC: A 4-byte CRC hash of the original packet being acknowledged.
These types are for encrypted, one-to-one communication between known peers.
-
PAYLOAD_TYPE_REQ(0x00): A generic request. -
PAYLOAD_TYPE_RESPONSE(0x01): A response to a request. -
PAYLOAD_TYPE_TXT_MSG(0x02): A plain text message. -
PAYLOAD_TYPE_PATH(0x08): A message containing a path to the sender. -
Purpose: Secure peer-to-peer communication.
-
Payload Structure:
[Dest Hash (1)] [Src Hash (1)] [Encrypted Data]- Dest Hash: The 1-byte hash of the recipient's public key.
- Src Hash: The 1-byte hash of the sender's public key.
- Encrypted Data: The HMAC and AES encrypted data block. The decrypted content varies (e.g., text for
TXT_MSG, path data forPATH).
An anonymous, encrypted request to a specific node. The sender's identity is provided via their full public key, not a pre-shared hash.
- Purpose: To send a secure request without being a known/saved peer.
- Payload Structure:
[Dest Hash (1)] [Sender Public Key (32)] [Encrypted Data]- Dest Hash: The 1-byte hash of the recipient's public key.
- Sender Public Key: The full 32-byte public key of the sender, used to calculate the shared secret for decryption.
- Encrypted Data: The HMAC and AES encrypted data block.
These types are for encrypted group communication on a shared channel.
-
PAYLOAD_TYPE_GRP_TXT(0x05): A group text message. -
PAYLOAD_TYPE_GRP_DATA(0x06): Generic group data. -
Purpose: Secure multi-user communication on a shared channel.
-
Payload Structure:
[Channel Hash (1)] [Encrypted Data]- Channel Hash: The 1-byte hash identifying the group channel.
- Encrypted Data: The HMAC and AES encrypted data block, using the channel's shared secret.
A broadcast packet for node discovery, containing a node's identity and an optional data payload.
- Purpose: To advertise a node's presence and identity on the mesh.
- Payload Structure:
[Public Key (32)] [Timestamp (4)] [Signature (64)] [App Data (0-32)]- Public Key: The sender's full 32-byte public key.
- Timestamp: A 4-byte Unix timestamp of when the advertisement was created.
- Signature: A 64-byte Ed25519 signature of the
[Public Key | Timestamp | App Data]block, proving identity. - App Data: Optional application-specific data.
A special packet used for network diagnostics to trace a route and measure the signal quality at each hop.
- Purpose: To perform a "traceroute" across the mesh.
- Payload Structure:
[Tag (4)] [Auth Code (4)] [Flags (1)] [Path Hashes (N)]- Tag & Auth Code: 4-byte fields to identify and authenticate the trace request.
- Flags: 1-byte reserved for future use.
- Path Hashes: The sequence of node hashes (
PATH_HASH_SIZEeach) that form the route to be traced.
Note: For TRACE packets, the logical path field of the packet object is used on the return journey to store SNR values, while the route itself is carried in the payload.
A wrapper packet that contains another payload type. Used to send a sequence of related packets.
- Purpose: To frame other payloads as part of a multi-packet sequence.
- Payload Structure:
[Multipart Header (1)] [Inner Packet Payload]- Multipart Header (1 byte):
- Bits 7-4: Number of packets remaining in the sequence.
- Bits 3-0: The
Payload Typeof theInner Packet Payload.
- Inner Packet Payload: The payload of the encapsulated packet (e.g., the 4-byte CRC for a multipart
ACK).
- Multipart Header (1 byte):
A simple container for application-defined raw data. The mesh protocol does not interpret the payload.
- Purpose: A passthrough for applications that manage their own serialization and encryption.
- Payload Structure:
[Raw Data (up to 184 bytes)]