Skip to content

initial try at documenting payload formats #338

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 27, 2025
Merged

initial try at documenting payload formats #338

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
176 changes: 176 additions & 0 deletions docs/payloads.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.