swaitsandClaude Opus 4.7
44305a06db
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>
126 lines
4.7 KiB
Markdown
126 lines
4.7 KiB
Markdown
# 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](01-wire-format.md) — Overall packet structure
|
|
- [Section 3: Path](03-path.md) — 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`
|