Skip to content

Commit 855e483

Browse files
author
Scott Powell
committed
* updates to packet/payload structure docs
1 parent e9a8fcb commit 855e483

File tree

2 files changed

+34
-30
lines changed

2 files changed

+34
-30
lines changed

‎docs/packet_structure.md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
# Packet Structure
22

3-
| Field | Size (bytes) | Description |
4-
|----------|----------------------------------|-----------------------------------------------------------|
5-
| header | 1 | Contains routing type, payload type, and payload version. |
6-
| path_len | 1 | Length of the path field in bytes. |
7-
| path | up to 64 (`MAX_PATH_SIZE`) | Stores the routing path if applicable. |
8-
| payload | up to 184 (`MAX_PACKET_PAYLOAD`) | The actual data being transmitted. |
3+
| Field | Size (bytes) | Description |
4+
|-----------------|----------------------------------|-----------------------------------------------------------|
5+
| header | 1 | Contains routing type, payload type, and payload version. |
6+
| transport_codes | 4 (optional) | 2x 16-bit transport codes (if ROUTE_TYPE_TRANSPORT_*) |
7+
| path_len | 1 | Length of the path field in bytes. |
8+
| path | up to 64 (`MAX_PATH_SIZE`) | Stores the routing path if applicable. |
9+
| payload | up to 184 (`MAX_PACKET_PAYLOAD`) | The actual data being transmitted. |
910

1011
Note: see the [payloads doc](./payloads.md) for more information about the content of payload.
1112

@@ -42,6 +43,7 @@ bit 0 means the lowest bit (1s place)
4243
| `0x07` | `PAYLOAD_TYPE_ANON_REQ` | Anonymous request. |
4344
| `0x08` | `PAYLOAD_TYPE_PATH` | Returned path. |
4445
| `0x09` | `PAYLOAD_TYPE_TRACE` | trace a path, collecting SNI for each hop. |
46+
| `0x0A` | `PAYLOAD_TYPE_MULTIPART` | packet is part of a sequence of packets. |
4547
| `0x0F` | `PAYLOAD_TYPE_RAW_CUSTOM` | Custom packet (raw bytes, custom encryption). |
4648

4749
## Payload Version Values

‎docs/payloads.md‎

Lines changed: 26 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,16 @@ Inside of each [meshcore packet](./packet_structure.md) is a payload, identified
1010
* Anonymous request.
1111
* Group text message (unverified).
1212
* Group datagram (unverified).
13+
* Multi-part packet
1314
* Custom packet (raw bytes, custom encryption).
1415

15-
This document defines the structure of each of these payload types
16+
This document defines the structure of each of these payload types.
17+
18+
NOTE: all 16 and 32-bit integer fields are Little Endian.
1619

1720
## Important concepts:
1821

19-
* Node/channel hash: the first byte of the node or channel's public key
22+
* Node hash: the first byte of the node's public key
2023

2124
# Node advertisement
2225
This kind of payload notifies receivers that a node exists, and gives information about the node
@@ -33,10 +36,10 @@ Appdata
3336
| Field | Size (bytes) | Description |
3437
|---------------|-----------------|-------------------------------------------------------|
3538
| flags | 1 | specifies which of the fields are present, see below |
36-
| latitude | 4 | decimal latitude multiplied by 1000000, integer |
37-
| longitude | 4 | decimal longitude multiplied by 1000000, integer |
38-
| feature 1 | 2 | reserved for future use |
39-
| feature 2 | 2 | reserved for future use |
39+
| latitude | 4 (optional) | decimal latitude multiplied by 1000000, integer |
40+
| longitude | 4 (optional) | decimal longitude multiplied by 1000000, integer |
41+
| feature 1 | 2 (optional) | reserved for future use |
42+
| feature 2 | 2 (optional) | reserved for future use |
4043
| name | rest of appdata | name of the node |
4144

4245
Appdata Flags
@@ -46,6 +49,7 @@ Appdata Flags
4649
| `0x01` | is chat node | advert is for a chat node |
4750
| `0x02` | is repeater | advert is for a repeater |
4851
| `0x03` | is room server | advert is for a room server |
52+
| `0x04` | is sensor | advert is for a sensor server |
4953
| `0x10` | has location | appdata contains lat/long information |
5054
| `0x20` | has feature 1 | Reserved for future use. |
5155
| `0x40` | has feature 2 | Reserved for future use. |
@@ -92,13 +96,15 @@ Returned path messages provide a description of the route a packet took from the
9296

9397
Request type
9498

95-
| Value | Name | Description |
96-
|--------|--------------------|---------------------------------------|
97-
| `0x01` | get status | get status of repeater or room server |
98-
| `0x02` | keepalive | TODO |
99-
| `0x03` | get telemetry data | TODO |
99+
| Value | Name | Description |
100+
|--------|----------------------|---------------------------------------|
101+
| `0x01` | get stats | get stats of repeater or room server |
102+
| `0x02` | keepalive | (deprecated) |
103+
| `0x03` | get telemetry data | TODO |
104+
| `0x04` | get min,max,avg data | sensor nodes - get min, max, average for given time span |
105+
| `0x05` | get access list | get node's approved access list |
100106

101-
### Get status
107+
### Get stats
102108

103109
Gets information about the node, possibly including the following:
104110

@@ -121,10 +127,6 @@ Gets information about the node, possibly including the following:
121127
* Number posted (?)
122128
* Number of post pushes (?)
123129

124-
### Keepalive
125-
126-
No-op request.
127-
128130
### Get telemetry data
129131

130132
Request data about sensors on the node, including battery level.
@@ -138,19 +140,19 @@ Request data about sensors on the node, including battery level.
138140

139141
## Plain text message
140142

141-
| Field | Size (bytes) | Description |
142-
|--------------|-----------------|--------------------------------------------------------------|
143-
| timestamp | 4 | send time (unix timestamp) |
144-
| flags + TODO | 1 | first six bits are flags (see below), last two bits are TODO |
145-
| message | rest of payload | the message content, see next table |
143+
| Field | Size (bytes) | Description |
144+
|-----------------|-----------------|--------------------------------------------------------------|
145+
| timestamp | 4 | send time (unix timestamp) |
146+
| flags + attempt | 1 | upper six bits are flags (see below), lower two bits are attempt number (0..3) |
147+
| message | rest of payload | the message content, see next table |
146148

147149
Flags
148150

149151
| Value | Description | Message content |
150152
|--------|---------------------------|------------------------------------------------------------|
151153
| `0x00` | plain text message | the plain text of the message |
152154
| `0x01` | CLI command | the command text of the message |
153-
| `0x02` | signed plain text message | two bytes of sender prefix, followed by plain text message |
155+
| `0x02` | signed plain text message | first four bytes is sender pubkey prefix, followed by plain text message |
154156

155157
# Anonymous request
156158

@@ -166,14 +168,14 @@ Plaintext message
166168
| Field | Size (bytes) | Description |
167169
|----------------|-----------------|-------------------------------------------------------------------------------|
168170
| timestamp | 4 | send time (unix timestamp) |
169-
| sync timestamp | 4 | for room server, otherwise absent: sender's "sync messages SINCE x" timestamp |
171+
| sync timestamp | 4 | NOTE: room server only! - sender's "sync messages SINCE x" timestamp |
170172
| password | rest of message | password for repeater/room |
171173

172174
# Group text message / datagram
173175

174176
| Field | Size (bytes) | Description |
175177
|--------------|-----------------|--------------------------------------------|
176-
| channel hash | 1 | the first byte of the channel's public key |
178+
| channel hash | 1 | first byte of SHA256 of channel's shared key |
177179
| cipher MAC | 2 | MAC for encrypted data in next field |
178180
| ciphertext | rest of payload | encrypted message, see below for details |
179181

0 commit comments

Comments
 (0)