Packet Structure¶

Complete reference for the MeshCore over-the-air packet format. All transmissions between nodes follow this layout.

Wire Format Overview¶

Every MeshCore packet on the LoRa channel follows this layout:

[Header: 1 byte]
[Transport Codes: 4 bytes]  ← only present for TRANSPORT_FLOOD or TRANSPORT_DIRECT route types
[Path Length: 1 byte]
[Path: 0–64 bytes]
[Payload: 0–184 bytes]

Maximum total packet size: 255 bytes (MAX_TRANS_UNIT = 255)

Packets are dropped by the firmware if: - path_length > 64 - payload > 184 bytes - Total exceeds 255 bytes

Header Byte¶

The single-byte header is a bitfield packed as 0bVVPPPPRR:

Route Types¶

Payload Types¶

Path Field¶

The path field serves dual purpose depending on route type:

During FLOOD: starts empty; each forwarding node appends its 1-byte node ID (first byte of its Ed25519 public key) before retransmitting. By the time the packet reaches its destination, the path field is an ordered log of every hop traversed.

During DIRECT: contains the pre-determined sequence of 1-byte node IDs for each intermediate hop. Each forwarding node checks if path[0] matches its own ID. On match, it strips the first byte and retransmits. When path_length == 0, the node is the final destination.

Key constant: PATH_HASH_SIZE = 1 byte per hop. Maximum 64 hops.

Transport Codes¶

When route type is TRANSPORT_FLOOD or TRANSPORT_DIRECT, four bytes of transport codes follow the header:

[region_code: uint16_t, little-endian]
[sub_region_code: uint16_t, little-endian]

Repeaters check these against their regional configuration and can selectively suppress forwarding via REGION_DENY_FLOOD or REGION_DENY_DIRECT flags. This allows geographic scoping — preventing network floods from crossing administrative boundaries.

Payload Layouts by Type¶

ADVERT (0x04) — Node Advertisement¶

Broadcast periodically by all node types. Unencrypted but signed.

[public_key:  32 bytes]  Ed25519 public key (node identity)
[timestamp:    4 bytes]  Unix epoch, little-endian
[signature:   64 bytes]  Ed25519 signature over public_key || timestamp
[appdata:   variable]    See flags below

Appdata flags byte (bitmask):

TXT_MSG (0x02) — Encrypted Text Message¶

Peer-to-peer private message. All content from cipher_mac onward is encrypted.

[dest_hash:     1 byte]  First byte of destination's public key
[src_hash:      1 byte]  First byte of sender's public key
[cipher_mac:    2 bytes] HMAC-SHA256 truncated to 2 bytes (authentication tag)
[timestamp:     4 bytes] Unix epoch, little-endian
[type_attempt:  1 byte]  Lower 2 bits = retry attempt number; upper bits = message subtype
[message:    variable]   UTF-8 text, null terminated

type_attempt upper bits subtypes: 0 = plain text, 1 = CLI data, 2 = signed plain text.

ACK (0x03) — Acknowledgement¶

Sent in reply to confirm receipt of a message.

[crc: 4 bytes]  SHA256(timestamp || attempt || text || sender_pubkey), truncated to 4 bytes

The receiving node verifies the CRC matches the previously sent message. This also serves as a round-trip-time measurement point.

PATH (0x08) — Path Return¶

Sent by the destination after receiving a flood packet, carrying the reverse route back to the originator.

[dest_hash:      1 byte]
[src_hash:       1 byte]
[cipher_mac:     2 bytes]
[path_length:    1 byte]
[path:        variable]  Ordered 1-byte node hashes (reverse of the flood path)
[extra_type:     1 byte]
[extra_payload: variable]

GRP_TXT / GRP_DATA (0x05, 0x06) — Group Channel Messages¶

Group/channel messages are keyed per-channel rather than per-contact.

[channel_hash: 1 byte]  First byte of the channel's hash
[cipher_mac:   2 bytes] HMAC-SHA256 truncated, over ciphertext
[ciphertext: variable]  AES-128-ECB encrypted content

ANON_REQ (0x07) — Anonymous Encrypted Request¶

Used primarily for room server login — the ephemeral key prevents linking requests to a known identity.

[dest_hash:          1 byte]
[ephemeral_pubkey:  32 bytes] One-time X25519 public key
[cipher_mac:         2 bytes]
[ciphertext:      variable]  Encrypted credentials/request

TRACE (0x09) — Path Trace¶

Diagnostic packet that collects per-hop SNR as it traverses the mesh.

[dest_hash:   1 byte]
[src_hash:    1 byte]
[hop_data:  variable]  Sequence of [node_hash(1 byte) + snr(1 byte)] pairs appended at each hop

SNR bytes are stored as int8_t in quarter-dB units (divide by 4 for dBm float).

CONTROL (0x0B) — Control/Discovery¶

[flags:    1 byte]  Upper 4 bits = sub_type
[data:  variable]

Size Constants Reference¶

Example: Decoding a Header Byte¶

Given header byte 0x12:

Binary:       0 0 0 1 0 0 1 0
Bits 6–7:     00  → Version = 0 (VER_1)
Bits 2–5:   0100  → Payload type = 0x04 = ADVERT
Bits 0–1:     10  → Route type = 0x02 = DIRECT

This is a directly-routed advertisement packet.

Related Pages¶

• Routing Algorithm
• Encryption & Authentication
• Channels & Keys
• Firmware Internals