# 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](#header-format) - 1 byte
- 8-bit Format: `0bVVPPPPRR` - `V=Version` - `P=PayloadType` - `R=RouteType`
- Bits 0-1 - 2-bits - [Route Type](#route-types)
- `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](#payload-types)
- `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](#payload-versions)
- `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](https://github.com/meshcore-dev/MeshCore/blob/e812632235274ffd2382adf5354168aec765d416/src/Dispatcher.cpp#L144)
- `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](https://github.com/meshcore-dev/MeshCore/blob/e812632235274ffd2382adf5354168aec765d416/src/Dispatcher.cpp#L152)

#### Packet Format

<table id="bkmrk-fieldsize-%28bytes%29des"><thead><tr><th>Field</th><th>Size (bytes)</th><th>Description</th></tr></thead><tbody><tr><td>header</td><td>1</td><td>Contains routing type, payload type, and payload version</td></tr><tr><td>transport\_codes</td><td>4 (optional)</td><td>2x 16-bit transport codes (if ROUTE\_TYPE\_TRANSPORT\_\*)</td></tr><tr><td>path\_length</td><td>1</td><td>Encodes path hash size in bits 6-7 and hop count in bits 0-5</td></tr><tr><td>path</td><td>up to 64 (`MAX_PATH_SIZE`)</td><td>Stores `hop_count * hash_size` bytes of path data if applicable</td></tr><tr><td>payload</td><td>up to 184 (`MAX_PACKET_PAYLOAD`)</td><td>Data for the provided Payload Type</td></tr></tbody></table>

> NOTE: see the [Payloads](./payloads.md) documentation for more information about the content of specific payload types.

#### Header Format

Bit 0 means the lowest bit (1s place)

<table id="bkmrk-bitsmaskfielddescrip"><thead><tr><th>Bits</th><th>Mask</th><th>Field</th><th>Description</th></tr></thead><tbody><tr><td>0-1</td><td>`0x03`</td><td>Route Type</td><td>Flood, Direct, etc</td></tr><tr><td>2-5</td><td>`0x3C`</td><td>Payload Type</td><td>Request, Response, ACK, etc</td></tr><tr><td>6-7</td><td>`0xC0`</td><td>Payload Version</td><td>Versioning of the payload format</td></tr></tbody></table>

#### Route Types

<table id="bkmrk-valuenamedescription"><thead><tr><th>Value</th><th>Name</th><th>Description</th></tr></thead><tbody><tr><td>`0x00`</td><td>`ROUTE_TYPE_TRANSPORT_FLOOD`</td><td>Flood Routing + Transport Codes</td></tr><tr><td>`0x01`</td><td>`ROUTE_TYPE_FLOOD`</td><td>Flood Routing</td></tr><tr><td>`0x02`</td><td>`ROUTE_TYPE_DIRECT`</td><td>Direct Routing</td></tr><tr><td>`0x03`</td><td>`ROUTE_TYPE_TRANSPORT_DIRECT`</td><td>Direct Routing + Transport Codes</td></tr></tbody></table>

#### Path Length Encoding

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

<table id="bkmrk-bitsfieldmeaning-0-5"><thead><tr><th>Bits</th><th>Field</th><th>Meaning</th></tr></thead><tbody><tr><td>0-5</td><td>Hop Count</td><td>Number of path hashes (`0-63`)</td></tr><tr><td>6-7</td><td>Hash Size Code</td><td>Stored as `hash_size - 1`</td></tr></tbody></table>

Hash size codes:

<table id="bkmrk-bits-6-7hash-sizenot"><thead><tr><th>Bits 6-7</th><th>Hash Size</th><th>Notes</th></tr></thead><tbody><tr><td>`0b00`</td><td>1 byte</td><td>Legacy / default mode</td></tr><tr><td>`0b01`</td><td>2 bytes</td><td>Supported in current firmware</td></tr><tr><td>`0b10`</td><td>3 bytes</td><td>Supported in current firmware</td></tr><tr><td>`0b11`</td><td>4 bytes</td><td>Reserved / invalid</td></tr></tbody></table>

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

<table id="bkmrk-valuenamedescription-1"><thead><tr><th>Value</th><th>Name</th><th>Description</th></tr></thead><tbody><tr><td>`0x00`</td><td>`PAYLOAD_TYPE_REQ`</td><td>Request (destination/source hashes + MAC)</td></tr><tr><td>`0x01`</td><td>`PAYLOAD_TYPE_RESPONSE`</td><td>Response to `REQ` or `ANON_REQ`</td></tr><tr><td>`0x02`</td><td>`PAYLOAD_TYPE_TXT_MSG`</td><td>Plain text message</td></tr><tr><td>`0x03`</td><td>`PAYLOAD_TYPE_ACK`</td><td>Acknowledgment</td></tr><tr><td>`0x04`</td><td>`PAYLOAD_TYPE_ADVERT`</td><td>Node advertisement</td></tr><tr><td>`0x05`</td><td>`PAYLOAD_TYPE_GRP_TXT`</td><td>Group text message (unverified)</td></tr><tr><td>`0x06`</td><td>`PAYLOAD_TYPE_GRP_DATA`</td><td>Group datagram (unverified)</td></tr><tr><td>`0x07`</td><td>`PAYLOAD_TYPE_ANON_REQ`</td><td>Anonymous request</td></tr><tr><td>`0x08`</td><td>`PAYLOAD_TYPE_PATH`</td><td>Returned path</td></tr><tr><td>`0x09`</td><td>`PAYLOAD_TYPE_TRACE`</td><td>Trace a path, collecting SNR for each hop</td></tr><tr><td>`0x0A`</td><td>`PAYLOAD_TYPE_MULTIPART`</td><td>Packet is part of a sequence of packets</td></tr><tr><td>`0x0B`</td><td>`PAYLOAD_TYPE_CONTROL`</td><td>Control packet data (unencrypted)</td></tr><tr><td>`0x0C`</td><td>reserved</td><td>reserved</td></tr><tr><td>`0x0D`</td><td>reserved</td><td>reserved</td></tr><tr><td>`0x0E`</td><td>reserved</td><td>reserved</td></tr><tr><td>`0x0F`</td><td>`PAYLOAD_TYPE_RAW_CUSTOM`</td><td>Custom packet (raw bytes, custom encryption)</td></tr></tbody></table>

#### Payload Versions

<table id="bkmrk-valueversiondescript"><thead><tr><th>Value</th><th>Version</th><th>Description</th></tr></thead><tbody><tr><td>`0x00`</td><td>1</td><td>1-byte src/dest hashes, 2-byte MAC</td></tr><tr><td>`0x01`</td><td>2</td><td>Future version (e.g., 2-byte hashes, 4-byte MAC)</td></tr><tr><td>`0x02`</td><td>3</td><td>Future version</td></tr><tr><td>`0x03`</td><td>4</td><td>Future version</td></tr></tbody></table>