Skip to content

Commit 0c94918

Browse files
ripplebizripplebiz
authored
Merge pull request #338 from mattsains/payloads
initial try at documenting payload formats
2 parents 4449fd3 + bb5509d commit 0c94918

File tree

1 file changed

+176
-0
lines changed

1 file changed

+176
-0
lines changed

‎docs/payloads.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
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:
3+
4+
* Request (destination/source hashes + MAC).
5+
* Response to REQ or ANON_REQ.
6+
* Plain text message.
7+
* Acknowledgment.
8+
* Node advertisement.
9+
* Group text message (unverified).
10+
* Group datagram (unverified).
11+
* Anonymous request.
12+
* Returned path.
13+
* Custom packet (raw bytes, custom encryption).
14+
15+
This document defines the structure of each of these payload types
16+
17+
# Node advertisement
18+
This kind of payload notifies receivers that a node exists, and gives information about the node
19+
20+
| Field | Size (bytes) | Description |
21+
|---------------|-----------------|----------------------------------------------------------|
22+
| public key | 32 | Ed25519 public key |
23+
| timestamp | 4 | unix timestamp of advertisement |
24+
| signature | 64 | Ed25519 signature of public key, timestamp, and app data |
25+
| appdata | rest of payload | optional, see below |
26+
27+
Appdata
28+
29+
| Field | Size (bytes) | Description |
30+
|---------------|-----------------|-------------------------------------------------------|
31+
| flags | 1 | specifies which of the fields are present, see below |
32+
| latitude | 4 | decimal latitude multiplied by 1000000, integer |
33+
| longitude | 4 | decimal longitude multiplied by 1000000, integer |
34+
| feature 1 | 2 | reserved for future use |
35+
| feature 2 | 2 | reserved for future use |
36+
| name | rest of appdata | name of the node |
37+
38+
Appdata Flags
39+
40+
| Value | Name | Description |
41+
|--------|-----------|---------------------------------------|
42+
| `0x10` | location | appdata contains lat/long information |
43+
| `0x20` | feature 1 | Reserved for future use. |
44+
| `0x40` | feature 2 | Reserved for future use. |
45+
| `0x80` | name | appdata contains a node name |
46+
47+
# Acknowledgement
48+
| Field | Size (bytes) | Description |
49+
|----------|--------------|------------------------------------------------------------|
50+
| checksum | 4 | CRC checksum of message timestamp, text, and sender pubkey |
51+
52+
53+
# Returned path, request, response, and plain text message
54+
| Field | Size (bytes) | Description |
55+
|------------------|-----------------|------------------------------------------------------|
56+
| destination hash | 1 | first byte of destination node public key |
57+
| source hash | 1 | first byte of source node public key |
58+
| cipher MAC | 2 | MAC for encrypted data in next field |
59+
| ciphertext | rest of payload | encrypted message, see subsections below for details |
60+
61+
## Returned path
62+
63+
| Field | Size (bytes) | Description |
64+
|-------------|--------------|----------------------------------------------------------------------------------------------|
65+
| path length | 1 | length of next field |
66+
| path | see above | a list of node hashes (one byte each) describing the route from us to the packet author |
67+
| extra type | 1 | extra, bundled payload type, eg., acknowledgement or response. See packet structure spec |
68+
| extra | rest of data | extra, bundled payload content, follows same format as main content defined by this document |
69+
70+
## Request
71+
72+
| Field | Size (bytes) | Description |
73+
|--------------|-----------------|----------------------------|
74+
| timestamp | 4 | send time (unix timestamp) |
75+
| request type | 1 | see below |
76+
| request data | rest of payload | depends on request type |
77+
78+
Request type
79+
80+
| Value | Name | Description |
81+
|--------|--------------------|---------------------------------------|
82+
| `0x01` | get status | get status of repeater or room server |
83+
| `0x02` | keepalive | TODO |
84+
| `0x03` | get telemetry data | TODO |
85+
86+
### Get status
87+
88+
Gets information about the node, possibly including the following:
89+
90+
* Battery level (millivolts)
91+
* Current transmit queue length
92+
* Current free queue length
93+
* Last RSSI value
94+
* Number of received packets
95+
* Number of sent packets
96+
* Total airtime (seconds)
97+
* Total uptime (seconds)
98+
* Number of packets sent as flood
99+
* Number of packets sent directly
100+
* Number of packets received as flood
101+
* Number of packets received directly
102+
* Error flags
103+
* Last SNR value
104+
* Number of direct route duplicates
105+
* Number of flood route duplicates
106+
* Number posted (?)
107+
* Number of post pushes (?)
108+
109+
### Keepalive
110+
111+
No-op request.
112+
113+
### Get telemetry data
114+
115+
Request data about sensors on the node, including battery level.
116+
117+
## Response
118+
119+
| Field | Size (bytes) | Description |
120+
|---------|-----------------|-------------|
121+
| tag | 4 | TODO |
122+
| content | rest of payload | TODO |
123+
124+
## Plain text message
125+
126+
| Field | Size (bytes) | Description |
127+
|--------------|-----------------|--------------------------------------------------------------|
128+
| timestamp | 4 | send time (unix timestamp) |
129+
| flags + TODO | 1 | first six bits are flags (see below), last two bits are TODO |
130+
| message | rest of payload | the message content, see next table |
131+
132+
Flags
133+
134+
| Value | Description | Message content |
135+
|--------|---------------------------|------------------------------------------------------------|
136+
| `0x00` | plain text message | the plain text of the message |
137+
| `0x01` | CLI command | the command text of the message |
138+
| `0x02` | signed plain text message | two bytes of sender prefix, followed by plain text message |
139+
140+
# Anonymous request
141+
142+
| Field | Size (bytes) | Description |
143+
|------------------|-----------------|-------------------------------------------|
144+
| destination hash | 1 | first byte of destination node public key |
145+
| public key | 32 | sender's Ed25519 public key |
146+
| cipher MAC | 2 | MAC for encrypted data in next field |
147+
| ciphertext | rest of payload | encrypted message, see below for details |
148+
149+
Plaintext message
150+
151+
| Field | Size (bytes) | Description |
152+
|----------------|-----------------|-------------------------------------------------------------------------------|
153+
| timestamp | 4 | send time (unix timestamp) |
154+
| sync timestamp | 4 | for room server, otherwise absent: sender's "sync messages SINCE x" timestamp |
155+
| password | rest of message | password for repeater/room |
156+
157+
# Group text message / datagram
158+
159+
| Field | Size (bytes) | Description |
160+
|--------------|-----------------|------------------------------------------|
161+
| channel hash | 1 | TODO |
162+
| cipher MAC | 2 | MAC for encrypted data in next field |
163+
| ciphertext | rest of payload | encrypted message, see below for details |
164+
165+
Plaintext for text message
166+
167+
| Field | Size (bytes) | Description |
168+
|-----------|-----------------|----------------------------------|
169+
| timestamp | 4 | send time (unix timestamp) |
170+
| content | rest of message | plain group text message content |
171+
172+
TODO: describe what datagram looks like
173+
174+
# Custom packet
175+
176+
Custom packets have no defined format.

0 commit comments

Comments
 (0)