0 Fork 0

Files

T

release: v0.1.0

First cut release. Snapshots ./src/ as ./versions/v0.1.0/ via
`just cut-version v0.1.0` (22 files: 21 chapter MDs + SUMMARY.md).
Deployed alongside `latest` at:

  https://swaits.github.io/meshcore-spec/v0.1.0/

Also:

- CHANGELOG.md adopts Keep a Changelog-style version sections.
  Future entries land under [Unreleased] and graduate to a version
  heading when cut. The existing date-stamped pass entries stay
  put as a historical record of the work captured in v0.1.0.
- README.md fixes a stale "per vX.Y.Z tag" mention left over from
  the tag-based versioning model, and links the current release
  explicitly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-12 10:04:40 -06:00

4.7 KiB

Raw Blame History

MeshCore Protocol Specification

Section 2: Header

Overview

The header is the first byte of every MeshCore packet. It encodes three fields using bit packing: the route type (2 bits), the payload type (4 bits), and the protocol version (2 bits).

Bit Layout

  Bit:  7   6   5   4   3   2   1   0
      +---+---+---+---+---+---+---+---+
      | V1  V0| P3  P2  P1  P0| R1  R0|
      +---+---+---+---+---+---+---+---+
             |         |           |
             |         |           +-- Route Type (bits 0-1)
             |         +-------------- Payload Type (bits 2-5)
             +------------------------ Protocol Version (bits 6-7)

The header byte value is computed as:

header = (version << 6) | (payload_type << 2) | route_type

And fields are extracted as:

route_type   = header & 0x03
payload_type = (header >> 2) & 0x0F
version      = (header >> 6) & 0x03

Route Type (bits 0-1)

The route type determines how the packet is routed through the mesh and whether transport codes are present.

Value	Name	Transport Codes	Description
0x00	TRANSPORT_FLOOD	Yes (4 bytes)	Flood routing with transport codes for regional scoping
0x01	FLOOD	No	Standard flood routing; path is built up by intermediate nodes
0x02	DIRECT	No	Direct routing; path is supplied by the sender
0x03	TRANSPORT_DIRECT	Yes (4 bytes)	Direct routing with transport codes

Transport codes MUST be present in the wire format when route type is 0x00 or 0x03, and MUST NOT be present when route type is 0x01 or 0x02.

Payload Type (bits 2-5)

The payload type identifies the structure of the payload data.

Value	Name	Description
0x00	REQUEST	Encrypted request (dest_hash + src_hash + MAC + ciphertext)
0x01	RESPONSE	Encrypted response to REQ or ANON_REQ
0x02	TXT_MSG	Encrypted text message
0x03	ACK	Simple acknowledgment (4-byte CRC)
0x04	ADVERT	Node identity advertisement
0x05	GRP_TXT	Encrypted group text message
0x06	GRP_DATA	Encrypted group datagram
0x07	ANON_REQ	Anonymous request (full public key instead of hash)
0x08	PATH	Encrypted returned path information
0x09	TRACE	Path trace with per-hop SNR collection
0x0A	MULTIPART	One part of a multi-packet sequence
0x0B	CONTROL	Control/discovery packet
0x0C	(reserved)	Reserved for future use
0x0D	(reserved)	Reserved for future use
0x0E	(reserved)	Reserved for future use
0x0F	RAW_CUSTOM	Custom raw bytes for application-defined payloads

Implementations SHOULD silently discard packets with reserved payload type values (0x0C-0x0E) unless they have explicit support for extended types.

Protocol Version (bits 6-7)

Value	Name	Description
0x00	V1	Current version: 1-byte src/dest hashes, 2-byte MAC
0x01	V2	Reserved for future use
0x02	V3	Reserved for future use
0x03	V4	Reserved for future use

Implementations MUST support version 0x00 (V1). Implementations SHOULD reject packets with unrecognized version values.

Special Header Values

The header value 0xFF is used internally as a "do not retransmit" marker. This is an in-memory sentinel only and MUST NOT appear on the wire. A header of 0xFF would decode as version=3, payload_type=0x0F (RAW_CUSTOM), route_type=3 (TRANSPORT_DIRECT).

Encoding Examples

Header Byte	Binary	Version	Payload Type	Route Type
`0x01`	`00 000000 01`	V1 (0)	REQUEST (0)	FLOOD (1)
`0x05`	`00 000001 01`	V1 (0)	RESPONSE (1)	FLOOD (1)
`0x09`	`00 000010 01`	V1 (0)	TXT_MSG (2)	FLOOD (1)
`0x0D`	`00 000011 01`	V1 (0)	ACK (3)	FLOOD (1)
`0x11`	`00 000100 01`	V1 (0)	ADVERT (4)	FLOOD (1)
`0x0C`	`00 000011 00`	V1 (0)	ACK (3)	TRANSPORT_FLOOD (0)
`0x0E`	`00 000011 10`	V1 (0)	ACK (3)	DIRECT (2)
`0x0F`	`00 000011 11`	V1 (0)	ACK (3)	TRANSPORT_DIRECT (3)
`0x4D`	`01 000011 01`	V2 (1, reserved)	ACK (3)	FLOOD (1)

Cross-References

Section 1: Wire Format — Overall packet structure
Section 3: Path — Path encoding
Test vectors: corpus/wire-format/header/

Reference Implementation

Packet::getRouteType() in src/Packet.h — header & 0x03
Packet::getPayloadType() in src/Packet.h — (header >> 2) & 0x0F
Packet::getPayloadVer() in src/Packet.h — (header >> 6) & 0x03
Packet::hasTransportCodes() in src/Packet.h — route type 0x00 or 0x03
Route type constants in src/Packet.h
Payload type constants in src/Packet.h

4.7 KiB Raw Blame History