mirror of
https://github.com/meshcore-dev/MeshCore.git
synced 2026-03-30 17:05:52 +00:00
initial try at documenting payload formats
This commit is contained in:
Matthew Sainsbury
176
docs/payloads.md
Normal file
176
docs/payloads.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# Meshcore payloads
|
||||
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:
|
||||
|
||||
* Request (destination/source hashes + MAC).
|
||||
* Response to REQ or ANON_REQ.
|
||||
* Plain text message.
|
||||
* Acknowledgment.
|
||||
* Node advertisement.
|
||||
* Group text message (unverified).
|
||||
* Group datagram (unverified).
|
||||
* Anonymous request.
|
||||
* Returned path.
|
||||
* Custom packet (raw bytes, custom encryption).
|
||||
|
||||
This document defines the structure of each of these payload types
|
||||
|
||||
# Node advertisement
|
||||
This kind of payload notifies receivers that a node exists, and gives information about the node
|
||||
|
||||
| Field | Size (bytes) | Description |
|
||||
|---------------|-----------------|----------------------------------------------------------|
|
||||
| public key | 32 | Ed25519 public key |
|
||||
| timestamp | 4 | unix timestamp of advertisement |
|
||||
| signature | 64 | Ed25519 signature of public key, timestamp, and app data |
|
||||
| appdata | rest of payload | optional, see below |
|
||||
|
||||
Appdata
|
||||
|
||||
| Field | Size (bytes) | Description |
|
||||
|---------------|-----------------|-------------------------------------------------------|
|
||||
| flags | 1 | specifies which of the fields are present, see below |
|
||||
| latitude | 4 | decimal latitude multiplied by 1000000, integer |
|
||||
| longitude | 4 | decimal longitude multiplied by 1000000, integer |
|
||||
| feature 1 | 2 | reserved for future use |
|
||||
| feature 2 | 2 | reserved for future use |
|
||||
| name | rest of appdata | name of the node |
|
||||
|
||||
Appdata Flags
|
||||
|
||||
| Value | Name | Description |
|
||||
|--------|-----------|---------------------------------------|
|
||||
| `0x10` | location | appdata contains lat/long information |
|
||||
| `0x20` | feature 1 | Reserved for future use. |
|
||||
| `0x40` | feature 2 | Reserved for future use. |
|
||||
| `0x80` | name | appdata contains a node name |
|
||||
|
||||
# Acknowledgement
|
||||
| Field | Size (bytes) | Description |
|
||||
|----------|--------------|------------------------------------------------------------|
|
||||
| checksum | 4 | CRC checksum of message timestamp, text, and sender pubkey |
|
||||
|
||||
|
||||
# Returned path, request, response, and plain text message
|
||||
| Field | Size (bytes) | Description |
|
||||
|------------------|-----------------|------------------------------------------------------|
|
||||
| destination hash | 1 | first byte of destination node public key |
|
||||
| source hash | 1 | first byte of source node public key |
|
||||
| cipher MAC | 2 | MAC for encrypted data in next field |
|
||||
| ciphertext | rest of payload | encrypted message, see subsections below for details |
|
||||
|
||||
## Returned path
|
||||
|
||||
| Field | Size (bytes) | Description |
|
||||
|-------------|--------------|----------------------------------------------------------------------------------------------|
|
||||
| path length | 1 | length of next field |
|
||||
| path | see above | a list of node hashes (one byte each) describing the route from us to the packet author |
|
||||
| extra type | 1 | extra, bundled payload type, eg., acknowledgement or response. See packet structure spec |
|
||||
| extra | rest of data | extra, bundled payload content, follows same format as main content defined by this document |
|
||||
|
||||
## Request
|
||||
|
||||
| Field | Size (bytes) | Description |
|
||||
|--------------|-----------------|----------------------------|
|
||||
| timestamp | 4 | send time (unix timestamp) |
|
||||
| request type | 1 | see below |
|
||||
| request data | rest of payload | depends on request type |
|
||||
|
||||
Request type
|
||||
|
||||
| Value | Name | Description |
|
||||
|--------|--------------------|---------------------------------------|
|
||||
| `0x01` | get status | get status of repeater or room server |
|
||||
| `0x02` | keepalive | TODO |
|
||||
| `0x03` | get telemetry data | TODO |
|
||||
|
||||
### Get status
|
||||
|
||||
Gets information about the node, possibly including the following:
|
||||
|
||||
* Battery level (millivolts)
|
||||
* Current transmit queue length
|
||||
* Current free queue length
|
||||
* Last RSSI value
|
||||
* Number of received packets
|
||||
* Number of sent packets
|
||||
* Total airtime (seconds)
|
||||
* Total uptime (seconds)
|
||||
* Number of packets sent as flood
|
||||
* Number of packets sent directly
|
||||
* Number of packets received as flood
|
||||
* Number of packets received directly
|
||||
* Error flags
|
||||
* Last SNR value
|
||||
* Number of direct route duplicates
|
||||
* Number of flood route duplicates
|
||||
* Number posted (?)
|
||||
* Number of post pushes (?)
|
||||
|
||||
### Keepalive
|
||||
|
||||
No-op request.
|
||||
|
||||
### Get telemetry data
|
||||
|
||||
Request data about sensors on the node, including battery level.
|
||||
|
||||
## Response
|
||||
|
||||
| Field | Size (bytes) | Description |
|
||||
|---------|-----------------|-------------|
|
||||
| tag | 4 | TODO |
|
||||
| content | rest of payload | TODO |
|
||||
|
||||
## Plain text message
|
||||
|
||||
| Field | Size (bytes) | Description |
|
||||
|--------------|-----------------|--------------------------------------------------------------|
|
||||
| timestamp | 4 | send time (unix timestamp) |
|
||||
| flags + TODO | 1 | first six bits are flags (see below), last two bits are TODO |
|
||||
| message | rest of payload | the message content, see next table |
|
||||
|
||||
Flags
|
||||
|
||||
| Value | Description | Message content |
|
||||
|--------|---------------------------|------------------------------------------------------------|
|
||||
| `0x00` | plain text message | the plain text of the message |
|
||||
| `0x01` | CLI command | the command text of the message |
|
||||
| `0x02` | signed plain text message | two bytes of sender prefix, followed by plain text message |
|
||||
|
||||
# Anonymous request
|
||||
|
||||
| Field | Size (bytes) | Description |
|
||||
|------------------|-----------------|-------------------------------------------|
|
||||
| destination hash | 1 | first byte of destination node public key |
|
||||
| public key | 32 | sender's Ed25519 public key |
|
||||
| cipher MAC | 2 | MAC for encrypted data in next field |
|
||||
| ciphertext | rest of payload | encrypted message, see below for details |
|
||||
|
||||
Plaintext message
|
||||
|
||||
| Field | Size (bytes) | Description |
|
||||
|----------------|-----------------|-------------------------------------------------------------------------------|
|
||||
| timestamp | 4 | send time (unix timestamp) |
|
||||
| sync timestamp | 4 | for room server, otherwise absent: sender's "sync messages SINCE x" timestamp |
|
||||
| password | rest of message | password for repeater/room |
|
||||
|
||||
# Group text message / datagram
|
||||
|
||||
| Field | Size (bytes) | Description |
|
||||
|--------------|-----------------|------------------------------------------|
|
||||
| channel hash | 1 | TODO |
|
||||
| cipher MAC | 2 | MAC for encrypted data in next field |
|
||||
| ciphertext | rest of payload | encrypted message, see below for details |
|
||||
|
||||
Plaintext for text message
|
||||
|
||||
| Field | Size (bytes) | Description |
|
||||
|-----------|-----------------|----------------------------------|
|
||||
| timestamp | 4 | send time (unix timestamp) |
|
||||
| content | rest of message | plain group text message content |
|
||||
|
||||
TODO: describe what datagram looks like
|
||||
|
||||
# Custom packet
|
||||
|
||||
Custom packets have no defined format.
|
||||
Reference in New Issue
Block a user