Skip to content

Commit 4224ddf

Browse files
liamcottleliamcottle
committed
refactor packet format docs
1 parent 85aa052 commit 4224ddf

File tree

4 files changed

+130
-69
lines changed

4 files changed

+130
-69
lines changed

‎docs/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Below are a few quick start guides.
77
- [Frequently Asked Questions](./faq.md)
88
- [CLI Commands](./cli_commands.md)
99
- [Companion Protocol](./companion_protocol.md)
10-
- [Packet Structure](./packet_structure.md)
10+
- [Packet Format](./packet_format.md)
1111
- [QR Codes](./qr_codes.md)
1212

1313
If you find a mistake in any of our documentation, or find something is missing, please feel free to open a pull request for us to review.

‎docs/packet_format.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Packet Format
2+
3+
This document describes the MeshCore packet format.
4+
5+
- `0xYY` indicates `YY` in hex notation.
6+
- `0bYY` indicates `YY` in binary notation.
7+
- Bit 0 indicates the bit furthest to the right: `0000000X`
8+
- Bit 7 indicates the bit furthest to the left: `X0000000`
9+
10+
## Version 1 Packet Format
11+
12+
This is the protocol level packet structure used in MeshCore firmware v1.12.0
13+
14+
```
15+
[header][transport_codes(optional)][path_length][path][payload]
16+
```
17+
18+
- [header](#header-format) - 1 byte
19+
- 8-bit Format: `0bVVPPPPRR` - `V=Version` - `P=PayloadType` - `R=RouteType`
20+
- Bits 0-1 - 2-bits - [Route Type](#route-types)
21+
- `0x00`/`0b00` - `ROUTE_TYPE_TRANSPORT_FLOOD` - Flood Routing + Transport Codes
22+
- `0x01`/`0b01` - `ROUTE_TYPE_FLOOD` - Flood Routing
23+
- `0x02`/`0b10` - `ROUTE_TYPE_DIRECT` - Direct Routing
24+
- `0x03`/`0b11` - `ROUTE_TYPE_TRANSPORT_DIRECT` - Direct Routing + Transport Codes
25+
- Bits 2-5 - 4-bits - [Payload Type](#payload-types)
26+
- `0x00`/`0b0000` - `PAYLOAD_TYPE_REQ` - Request (destination/source hashes + MAC)
27+
- `0x01`/`0b0001` - `PAYLOAD_TYPE_RESPONSE` - Response to `REQ` or `ANON_REQ`
28+
- `0x02`/`0b0010` - `PAYLOAD_TYPE_TXT_MSG` - Plain text message
29+
- `0x03`/`0b0011` - `PAYLOAD_TYPE_ACK` - Acknowledgment
30+
- `0x04`/`0b0100` - `PAYLOAD_TYPE_ADVERT` - Node advertisement
31+
- `0x05`/`0b0101` - `PAYLOAD_TYPE_GRP_TXT` - Group text message (unverified)
32+
- `0x06`/`0b0110` - `PAYLOAD_TYPE_GRP_DATA` - Group datagram (unverified)
33+
- `0x07`/`0b0111` - `PAYLOAD_TYPE_ANON_REQ` - Anonymous request
34+
- `0x08`/`0b1000` - `PAYLOAD_TYPE_PATH` - Returned path
35+
- `0x09`/`0b1001` - `PAYLOAD_TYPE_TRACE` - Trace a path, collecting SNR for each hop
36+
- `0x0A`/`0b1010` - `PAYLOAD_TYPE_MULTIPART` - Packet is part of a sequence of packets
37+
- `0x0B`/`0b1011` - `PAYLOAD_TYPE_CONTROL` - Control packet data (unencrypted)
38+
- `0x0C`/`0b1100` - reserved
39+
- `0x0D`/`0b1101` - reserved
40+
- `0x0E`/`0b1110` - reserved
41+
- `0x0F`/`0b1111` - `PAYLOAD_TYPE_RAW_CUSTOM` - Custom packet (raw bytes, custom encryption)
42+
- Bits 6-7 - 2-bits - [Payload Version](#payload-versions)
43+
- `0x00`/`0b00` - v1 - 1-byte src/dest hashes, 2-byte MAC
44+
- `0x01`/`0b01` - v2 - Future version (e.g., 2-byte hashes, 4-byte MAC)
45+
- `0x02`/`0b10` - v3 - Future version
46+
- `0x03`/`0b11` - v4 - Future version
47+
- `transport_codes` - 4 bytes (optional)
48+
- Only present for `ROUTE_TYPE_TRANSPORT_FLOOD` and `ROUTE_TYPE_TRANSPORT_DIRECT`
49+
- `transport_code_1` - 2 bytes - `uint16_t` - calculated from region scope
50+
- `transport_code_2` - 2 bytes - `uint16_t` - reserved
51+
- `path_length` - 1 byte - Length of the path field in bytes
52+
- `path` - size provided by `path_length` - Path to use for Direct Routing
53+
- Up to a maximum of 64 bytes, defined by `MAX_PATH_SIZE`
54+
- v1.12.0 firmware and older drops packets with `path_length` [larger than 64](https://github.com/meshcore-dev/MeshCore/blob/e812632235274ffd2382adf5354168aec765d416/src/Dispatcher.cpp#L144)
55+
- `payload` - variable length - Payload Data
56+
- Up to a maximum 184 bytes, defined by `MAX_PACKET_PAYLOAD`
57+
- Generally this is the remainder of the raw packet data
58+
- The firmware parses this data based on the provided Payload Type
59+
- 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)
60+
61+
### Packet Format
62+
63+
| Field | Size (bytes) | Description |
64+
|-----------------|----------------------------------|----------------------------------------------------------|
65+
| header | 1 | Contains routing type, payload type, and payload version |
66+
| transport_codes | 4 (optional) | 2x 16-bit transport codes (if ROUTE_TYPE_TRANSPORT_*) |
67+
| path_length | 1 | Length of the path field in bytes |
68+
| path | up to 64 (`MAX_PATH_SIZE`) | Stores the routing path if applicable |
69+
| payload | up to 184 (`MAX_PACKET_PAYLOAD`) | Data for the provided Payload Type |
70+
71+
> NOTE: see the [Payloads](./payloads.md) documentation for more information about the content of specific payload types.
72+
73+
### Header Format
74+
75+
Bit 0 means the lowest bit (1s place)
76+
77+
| Bits | Mask | Field | Description |
78+
|------|--------|-----------------|----------------------------------|
79+
| 0-1 | `0x03` | Route Type | Flood, Direct, etc |
80+
| 2-5 | `0x3C` | Payload Type | Request, Response, ACK, etc |
81+
| 6-7 | `0xC0` | Payload Version | Versioning of the payload format |
82+
83+
### Route Types
84+
85+
| Value | Name | Description |
86+
|--------|-------------------------------|----------------------------------|
87+
| `0x00` | `ROUTE_TYPE_TRANSPORT_FLOOD` | Flood Routing + Transport Codes |
88+
| `0x01` | `ROUTE_TYPE_FLOOD` | Flood Routing |
89+
| `0x02` | `ROUTE_TYPE_DIRECT` | Direct Routing |
90+
| `0x03` | `ROUTE_TYPE_TRANSPORT_DIRECT` | Direct Routing + Transport Codes |
91+
92+
### Payload Types
93+
94+
| Value | Name | Description |
95+
|--------|---------------------------|----------------------------------------------|
96+
| `0x00` | `PAYLOAD_TYPE_REQ` | Request (destination/source hashes + MAC) |
97+
| `0x01` | `PAYLOAD_TYPE_RESPONSE` | Response to `REQ` or `ANON_REQ` |
98+
| `0x02` | `PAYLOAD_TYPE_TXT_MSG` | Plain text message |
99+
| `0x03` | `PAYLOAD_TYPE_ACK` | Acknowledgment |
100+
| `0x04` | `PAYLOAD_TYPE_ADVERT` | Node advertisement |
101+
| `0x05` | `PAYLOAD_TYPE_GRP_TXT` | Group text message (unverified) |
102+
| `0x06` | `PAYLOAD_TYPE_GRP_DATA` | Group datagram (unverified) |
103+
| `0x07` | `PAYLOAD_TYPE_ANON_REQ` | Anonymous request |
104+
| `0x08` | `PAYLOAD_TYPE_PATH` | Returned path |
105+
| `0x09` | `PAYLOAD_TYPE_TRACE` | Trace a path, collecting SNR for each hop |
106+
| `0x0A` | `PAYLOAD_TYPE_MULTIPART` | Packet is part of a sequence of packets |
107+
| `0x0B` | `PAYLOAD_TYPE_CONTROL` | Control packet data (unencrypted) |
108+
| `0x0C` | reserved | reserved |
109+
| `0x0D` | reserved | reserved |
110+
| `0x0E` | reserved | reserved |
111+
| `0x0F` | `PAYLOAD_TYPE_RAW_CUSTOM` | Custom packet (raw bytes, custom encryption) |
112+
113+
### Payload Versions
114+
115+
| Value | Version | Description |
116+
|--------|---------|--------------------------------------------------|
117+
| `0x00` | 1 | 1-byte src/dest hashes, 2-byte MAC |
118+
| `0x01` | 2 | Future version (e.g., 2-byte hashes, 4-byte MAC) |
119+
| `0x02` | 3 | Future version |
120+
| `0x03` | 4 | Future version |

‎docs/packet_structure.md‎

Lines changed: 0 additions & 60 deletions
This file was deleted.

‎docs/payloads.md‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
1-
# Meshcore payloads
2-
Inside of each [meshcore packet](./packet_structure.md) is a payload, identified by the payload type in the packet header. The types of payloads are:
1+
# Payload Format
2+
3+
Inside each [MeshCore Packet](./packet_format.md) is a payload, identified by the payload type in the packet header. The types of payloads are:
34

45
* Node advertisement.
56
* Acknowledgment.
@@ -80,12 +81,12 @@ Returned path, request, response, and plain text messages are all formatted in t
8081

8182
Returned path messages provide a description of the route a packet took from the original author. Receivers will send returned path messages to the author of the original message.
8283

83-
| Field | Size (bytes) | Description |
84-
|-------------|--------------|----------------------------------------------------------------------------------------------|
85-
| path length | 1 | length of next field |
86-
| path | see above | a list of node hashes (one byte each) |
87-
| extra type | 1 | extra, bundled payload type, eg., acknowledgement or response. Same values as in [packet structure](./packet_structure.md) |
88-
| extra | rest of data | extra, bundled payload content, follows same format as main content defined by this document |
84+
| Field | Size (bytes) | Description |
85+
|-------------|--------------|----------------------------------------------------------------------------------------------------------------------|
86+
| path length | 1 | length of next field |
87+
| path | see above | a list of node hashes (one byte each) |
88+
| extra type | 1 | extra, bundled payload type, eg., acknowledgement or response. Same values as in [Packet Format](./packet_format.md) |
89+
| extra | rest of data | extra, bundled payload content, follows same format as main content defined by this document |
8990

9091
## Request
9192

0 commit comments

Comments
 (0)