Skip to content

Increase header levels on "Payloads" documentation page to fix table of contents #3040

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
liamcottle merged 1 commit into from
Jul 27, 2026
+26 −26
Merged

Increase header levels on "Payloads" documentation page to fix table of contents #3040

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
52 changes: 26 additions & 26 deletions docs/payloads.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ NOTE: all 16 and 32-bit integer fields are Little Endian.

* Node hash: the first byte of the node's public key

# Node advertisement
## Node advertisement
This kind of payload notifies receivers that a node exists, and gives information about the node

| Field | Size (bytes) | Description |
Expand Down Expand Up @@ -57,7 +57,7 @@ Appdata Flags
| `0x40` | has feature 2 | Reserved for future use. |
| `0x80` | has name | appdata contains a node name |

# Acknowledgement
## Acknowledgement

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 acknowledgement packet. CLI commands do not cause acknowledgement responses, neither discrete nor extra.

Expand All @@ -66,7 +66,7 @@ An acknowledgement that a message was received. Note that for returned path mess
| checksum | 4 | CRC checksum of message timestamp, text, and sender pubkey |


# Returned path, request, response, and plain text message
## Returned path, request, response, and plain text message

Returned path, request, response, and plain text messages are all formatted in the same way. See the subsection for more details about the ciphertext's associated plaintext representation.

Expand All @@ -77,7 +77,7 @@ Returned path, request, response, and plain text messages are all formatted in t
| cipher MAC | 2 | MAC for encrypted data in next field |
| ciphertext | rest of payload | encrypted message, see subsections below for details |

## Returned path
### Returned path

Returned path messages provide a description of the route a packet took from the original author. Receivers will send returned path messages to the author of the original message.

Expand All @@ -88,7 +88,7 @@ Returned path messages provide a description of the route a packet took from the
| extra type | 1 | extra, bundled payload type, eg., acknowledgement or response. Same values as in [Packet Format](./packet_format.md) |
| extra | rest of data | extra, bundled payload content, follows same format as main content defined by this document |

## Request
### Request

| Field | Size (bytes) | Description |
|--------------|-----------------|------------------------------------------|
Expand All @@ -102,7 +102,7 @@ For the common chat/server helpers in `BaseChatMesh`, the current request type v
| `0x01` | get stats | get stats of repeater or room server |
| `0x02` | keepalive | keep-alive request used for maintained connections |

### Get stats
#### Get stats

Gets information about the node, possibly including the following:

Expand All @@ -125,40 +125,40 @@ Gets information about the node, possibly including the following:
* Number posted (?)
* Number of post pushes (?)

### Get telemetry data
#### Get telemetry data

Not defined in `BaseChatMesh`. Sensor- and application-specific request payloads may be implemented by higher-level firmware.

### Get Telemetry
#### Get Telemetry

Not defined in `BaseChatMesh`.

### Get Min/Max/Ave (Sensor nodes)
#### Get Min/Max/Ave (Sensor nodes)

Not defined in `BaseChatMesh`.

### Get Access List
#### Get Access List

Not defined in `BaseChatMesh`.

### Get Neighbors
#### Get Neighbors

Not defined in `BaseChatMesh`.

### Get Owner Info
#### Get Owner Info

Not defined in `BaseChatMesh`.


## Response
### Response

| Field | Size (bytes) | Description |
|---------|-----------------|-----------------------------------|
| content | rest of payload | application-defined response body |

Response contents are opaque application data. There is no single generic response envelope beyond the encrypted payload wrapper shown above.

## Plain text message
### Plain text message

| Field | Size (bytes) | Description |
|--------------------|-----------------|-----------------------------------------------------------------------------------|
Expand All @@ -174,7 +174,7 @@ txt_type
| `0x01` | CLI command | the command text of the message |
| `0x02` | signed plain text message | first four bytes is sender pubkey prefix, followed by plain text message |

# Anonymous request
## Anonymous request

| Field | Size (bytes) | Description |
|------------------|-----------------|-------------------------------------------|
Expand All @@ -183,22 +183,22 @@ txt_type
| cipher MAC | 2 | MAC for encrypted data in next field |
| ciphertext | rest of payload | encrypted message, see below for details |

## Room server login
### Room server login

| Field | Size (bytes) | Description |
|----------------|-----------------|-------------------------------------------------------------------------------|
| timestamp | 4 | sender time (unix timestamp) |
| sync timestamp | 4 | sender's "sync messages SINCE x" timestamp |
| password | rest of message | password for room |

## Repeater/Sensor login
### Repeater/Sensor login

| Field | Size (bytes) | Description |
|----------------|-----------------|-------------------------------------------------------------------------------|
| timestamp | 4 | sender time (unix timestamp) |
| password | rest of message | password for repeater/sensor |

## Repeater - Regions request
### Repeater - Regions request

| Field | Size (bytes) | Description |
|----------------|--------------|------------------------------|
Expand All @@ -207,7 +207,7 @@ txt_type
| reply path len | 1 | path len for reply |
| reply path | (variable) | reply path |

## Repeater - Owner info request
### Repeater - Owner info request

| Field | Size (bytes) | Description |
|----------------|--------------|------------------------------|
Expand All @@ -216,7 +216,7 @@ txt_type
| reply path len | 1 | path len for reply |
| reply path | (variable) | reply path |

## Repeater - Clock and status request
### Repeater - Clock and status request

| Field | Size (bytes) | Description |
|----------------|--------------|------------------------------|
Expand All @@ -226,7 +226,7 @@ txt_type
| reply path | (variable) | reply path |


# Group text message
## Group text message

| Field | Size (bytes) | Description |
|--------------|-----------------|----------------------------------------------|
Expand All @@ -236,7 +236,7 @@ txt_type

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`).

# Group datagram
## Group datagram

| Field | Size (bytes) | Description |
|--------------|-----------------|----------------------------------------------|
Expand All @@ -253,14 +253,14 @@ The data contained in the ciphertext uses the format below:
| data | rest of payload | (depends on data type) |


# Control data
## Control data

| Field | Size (bytes) | Description |
|--------------|-----------------|--------------------------------------------|
| flags | 1 | upper 4 bits is sub_type |
| data | rest of payload | typically unencrypted data |

## DISCOVER_REQ (sub_type)
### DISCOVER_REQ (sub_type)

| Field | Size (bytes) | Description |
|--------------|-----------------|----------------------------------------------|
Expand All @@ -269,7 +269,7 @@ The data contained in the ciphertext uses the format below:
| tag | 4 | randomly generate by sender |
| since | 4 | (optional) epoch timestamp (0 by default) |

## DISCOVER_RESP (sub_type)
### DISCOVER_RESP (sub_type)

| Field | Size (bytes) | Description |
|--------------|-----------------|--------------------------------------------|
Expand All @@ -279,6 +279,6 @@ The data contained in the ciphertext uses the format below:
| pubkey | 8 or 32 | node's ID (or prefix) |


# Custom packet
## Custom packet

Custom packets have no defined format.