Skip to content

Commit 62d7ce1

Browse files
author
Scott Powell
committed
* packet format docs updated
1 parent 28b90c1 commit 62d7ce1

File tree

2 files changed

+48
-12
lines changed

2 files changed

+48
-12
lines changed

‎docs/packet_structure.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,10 @@ bit 0 means the lowest bit (1s place)
4444
| `0x08` | `PAYLOAD_TYPE_PATH` | Returned path. |
4545
| `0x09` | `PAYLOAD_TYPE_TRACE` | trace a path, collecting SNI for each hop. |
4646
| `0x0A` | `PAYLOAD_TYPE_MULTIPART` | packet is part of a sequence of packets. |
47+
| `0x0B` | `PAYLOAD_TYPE_CONTROL` | control packet data (unencrypted) |
48+
| `0x0C` | . | reserved |
49+
| `0x0D` | . | reserved |
50+
| `0x0E` | . | reserved |
4751
| `0x0F` | `PAYLOAD_TYPE_RAW_CUSTOM` | Custom packet (raw bytes, custom encryption). |
4852

4953
## Payload Version Values

‎docs/payloads.md‎

Lines changed: 44 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Inside of each [meshcore packet](./packet_structure.md) is a payload, identified
1111
* Group text message (unverified).
1212
* Group datagram (unverified).
1313
* Multi-part packet
14+
* Control data packet
1415
* Custom packet (raw bytes, custom encryption).
1516

1617
This document defines the structure of each of these payload types.
@@ -57,7 +58,7 @@ Appdata Flags
5758

5859
# Acknowledgement
5960

60-
An acknowledgement that a message was received. Note that for returned path messages, an acknowledgement will be sent in the "extra" payload (see [Returned Path](#returned-path)) and not as a discrete ackowledgement. CLI commands do not require an acknowledgement, neither discrete nor extra.
61+
An acknowledgement that a message was received. Note that for returned path messages, an acknowledgement can be sent in the "extra" payload (see [Returned Path](#returned-path)) instead of as a separate ackowledgement packet. CLI commands do not cause acknowledgement responses, neither discrete nor extra.
6162

6263
| Field | Size (bytes) | Description |
6364
|----------|--------------|------------------------------------------------------------|
@@ -140,13 +141,13 @@ Request data about sensors on the node, including battery level.
140141

141142
## Plain text message
142143

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 |
144+
| Field | Size (bytes) | Description |
145+
|--------------------|-----------------|--------------------------------------------------------------|
146+
| timestamp | 4 | send time (unix timestamp) |
147+
| txt_type + attempt | 1 | upper six bits are txt_type (see below), lower two bits are attempt number (0..3) |
148+
| message | rest of payload | the message content, see next table |
148149

149-
Flags
150+
txt_type
150151

151152
| Value | Description | Message content |
152153
|--------|---------------------------|------------------------------------------------------------|
@@ -163,13 +164,20 @@ Flags
163164
| cipher MAC | 2 | MAC for encrypted data in next field |
164165
| ciphertext | rest of payload | encrypted message, see below for details |
165166

166-
Plaintext message
167+
## Room server login
167168

168169
| Field | Size (bytes) | Description |
169170
|----------------|-----------------|-------------------------------------------------------------------------------|
170-
| timestamp | 4 | send time (unix timestamp) |
171-
| sync timestamp | 4 | NOTE: room server only! - sender's "sync messages SINCE x" timestamp |
172-
| password | rest of message | password for repeater/room |
171+
| timestamp | 4 | sender time (unix timestamp) |
172+
| sync timestamp | 4 | sender's "sync messages SINCE x" timestamp |
173+
| password | rest of message | password for room |
174+
175+
## Repeater/Sensor login
176+
177+
| Field | Size (bytes) | Description |
178+
|----------------|-----------------|-------------------------------------------------------------------------------|
179+
| timestamp | 4 | sender time (unix timestamp) |
180+
| password | rest of message | password for repeater/sensor |
173181

174182
# Group text message / datagram
175183

@@ -182,7 +190,31 @@ Plaintext message
182190
The plaintext contained in the ciphertext matches the format described in [plain text message](#plain-text-message). Specifically, it consists of a four byte timestamp, a flags byte, and the message. The flags byte will generally be `0x00` because it is a "plain text message". The message will be of the form `<sender name>: <message body>` (eg., `user123: I'm on my way`).
183191

184192

185-
TODO: describe what datagram looks like
193+
# Control data
194+
195+
| Field | Size (bytes) | Description |
196+
|--------------|-----------------|--------------------------------------------|
197+
| flags | 1 | upper 4 bits is sub_type |
198+
| data | rest of payload | typically unencrypted data |
199+
200+
## DISCOVER_REQ (sub_type)
201+
202+
| Field | Size (bytes) | Description |
203+
|--------------|-----------------|--------------------------------------------|
204+
| flags | 1 | 0x8 (upper 4 bits) |
205+
| type_filter | 1 | bit for each ADV_TYPE_* |
206+
| tag | 4 | randomly generate by sender |
207+
| since | 4 | (optional) epoch timestamp (0 by default) |
208+
209+
## DISCOVER_RESP (sub_type)
210+
211+
| Field | Size (bytes) | Description |
212+
|--------------|-----------------|--------------------------------------------|
213+
| flags | 1 | 0x9 (upper 4 bits), node_type (lower 4) |
214+
| snr | 1 | signed, SNR*4 |
215+
| tag | 4 | reflected back from DISCOVER_REQ |
216+
| pubkey | 32 | node's ID |
217+
186218

187219
# Custom packet
188220

0 commit comments

Comments
 (0)