MeshCore Packet Format Reference

Packet Format

This document describes the MeshCore packet format.

• 0xYY indicates YY in hex notation.
• 0bYY indicates YY in binary notation.
• Bit 0 indicates the bit furthest to the right: 0000000X
• Bit 7 indicates the bit furthest to the left: X0000000

Version 1 Packet Format

This is the protocol level packet structure used in MeshCore firmware v1.12.0

[header][transport_codes(optional)][path_length][path][payload]

• header - 1 byte
• 8-bit Format: 0bVVPPPPRR - V=Version - P=PayloadType - R=RouteType
• Bits 0-1 - 2-bits - Route Type
• 0x00/0b00 - ROUTE_TYPE_TRANSPORT_FLOOD - Flood Routing + Transport Codes
• 0x01/0b01 - ROUTE_TYPE_FLOOD - Flood Routing
• 0x02/0b10 - ROUTE_TYPE_DIRECT - Direct Routing
• 0x03/0b11 - ROUTE_TYPE_TRANSPORT_DIRECT - Direct Routing + Transport Codes
• Bits 2-5 - 4-bits - Payload Type
• 0x00/0b0000 - PAYLOAD_TYPE_REQ - Request (destination/source hashes + MAC)
• 0x01/0b0001 - PAYLOAD_TYPE_RESPONSE - Response to REQ or ANON_REQ
• 0x02/0b0010 - PAYLOAD_TYPE_TXT_MSG - Plain text message
• 0x03/0b0011 - PAYLOAD_TYPE_ACK - Acknowledgment
• 0x04/0b0100 - PAYLOAD_TYPE_ADVERT - Node advertisement
• 0x05/0b0101 - PAYLOAD_TYPE_GRP_TXT - Group text message (unverified)
• 0x06/0b0110 - PAYLOAD_TYPE_GRP_DATA - Group datagram (unverified)
• 0x07/0b0111 - PAYLOAD_TYPE_ANON_REQ - Anonymous request
• 0x08/0b1000 - PAYLOAD_TYPE_PATH - Returned path
• 0x09/0b1001 - PAYLOAD_TYPE_TRACE - Trace a path, collecting SNR for each hop
• 0x0A/0b1010 - PAYLOAD_TYPE_MULTIPART - Packet is part of a sequence of packets
• 0x0B/0b1011 - PAYLOAD_TYPE_CONTROL - Control packet data (unencrypted)
• 0x0C/0b1100 - reserved
• 0x0D/0b1101 - reserved
• 0x0E/0b1110 - reserved
• 0x0F/0b1111 - PAYLOAD_TYPE_RAW_CUSTOM - Custom packet (raw bytes, custom encryption)
• Bits 6-7 - 2-bits - Payload Version
• 0x00/0b00 - v1 - 1-byte src/dest hashes, 2-byte MAC
• 0x01/0b01 - v2 - Future version (e.g., 2-byte hashes, 4-byte MAC)
• 0x02/0b10 - v3 - Future version
• 0x03/0b11 - v4 - Future version
• transport_codes - 4 bytes (optional)
• Only present for ROUTE_TYPE_TRANSPORT_FLOOD and ROUTE_TYPE_TRANSPORT_DIRECT
• transport_code_1 - 2 bytes - uint16_t - calculated from region scope
• transport_code_2 - 2 bytes - uint16_t - reserved
• path_length - 1 byte - Encoded path metadata
• Bits 0-5 store path hash count / hop count (0-63)
• Bits 6-7 store path hash size minus 1
• 0b00: 1-byte path hashes
• 0b01: 2-byte path hashes
• 0b10: 3-byte path hashes
• 0b11: reserved / unsupported
• path - hop_count * hash_size bytes - Path to use for Direct Routing or flood path tracking
• Up to a maximum of 64 bytes, defined by MAX_PATH_SIZE
• Effective byte length is calculated from the encoded hop count and hash size, not taken directly from path_length
• v1.12.0 firmware and older only handled legacy 1-byte path hashes and dropped packets whose path bytes exceeded 64 bytes
• payload - variable length - Payload Data
• Up to a maximum 184 bytes, defined by MAX_PACKET_PAYLOAD
• Generally this is the remainder of the raw packet data
• The firmware parses this data based on the provided Payload Type
• v1.12.0 firmware and older drops packets with payload sizes larger than 184

Packet Format

NOTE: see the Payloads documentation for more information about the content of specific payload types.

Header Format

Bit 0 means the lowest bit (1s place)

Route Types

Path Length Encoding

path_length is not a raw byte count. It packs both hash size and hop count:

Hash size codes:

Examples:

• 0x00: zero-hop packet, no path bytes
• 0x05: 5 hops using 1-byte hashes, so path is 5 bytes
• 0x45: 5 hops using 2-byte hashes, so path is 10 bytes
• 0x8A: 10 hops using 3-byte hashes, so path is 30 bytes

Payload Types

Payload Versions