shade/MeshCore
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Merge branch 'dev'

Browse Source
This commit is contained in:
Scott Powell committed 2026-10-15 19:42:40 +11:00
2 parents a366955cb2 07a833bbbe
commit 81dbae592f
199 files changed
+7082 -978
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/cli_commands.md
+11 -6
View File
@@ -211,7 +211,7 @@ This document provides an overview of CLI commands that can be sent to MeshCore
**Set by build flag:** `LORA_FREQ`, `LORA_BW`, `LORA_SF`, `LORA_CR`
**Default:** `869.525,250,11,5`
**Default:** `869.618,62.5,8,5`
**Note:** Requires reboot to apply
@@ -256,7 +256,7 @@ This document provides an overview of CLI commands that can be sent to MeshCore
**Parameters:**
- `frequency`: Frequency in MHz
**Default:** `869.525`
**Default:** `869.618`
**Note:** Requires reboot to apply
**Serial Only:** `set freq <frequency>`
@@ -537,7 +537,7 @@ This document provides an overview of CLI commands that can be sent to MeshCore
**Parameters:**
- `value`: Direct transmit delay factor (0-2)
**Default:** `0.2`
**Default:** `0.3` (Repeater) - `0.2` (Room Server, Sensor)
**Note:** Same collision-avoidance random window as `txdelay`, but applied to direct (non-flood, routed) traffic. The default is lower because direct packets are addressed to a specific next hop, so far fewer nodes compete to retransmit them.
@@ -628,7 +628,7 @@ This document provides an overview of CLI commands that can be sent to MeshCore
- `set agc.reset.interval <value>`
**Parameters:**
- `value`: Interval in seconds rounded down to a multiple of 4 (17 becomes 16). 0 to disable.
- `value`: Interval in seconds, 0-1020, rounded down to a multiple of 4 (17 becomes 16). 0 to disable.
**Default:** `0.0`
@@ -654,7 +654,7 @@ This document provides an overview of CLI commands that can be sent to MeshCore
**Parameters:**
- `hours`: Interval in hours (3-168)
**Default:** `12` (Repeater) - `0` (Sensor)
**Default:** `47` (Repeater, Room Server) - `0`, disabled (Sensor)
---
@@ -666,7 +666,12 @@ This document provides an overview of CLI commands that can be sent to MeshCore
**Parameters:**
- `minutes`: Interval in minutes rounded down to the nearest multiple of 2 (61 becomes 60) (60-240)
**Default:** `0`
**Default:** `2` on a factory-fresh node, then `0` (disabled) once configured.
**Note:** A new install ships with a 2 minute zero-hop advert interval. Saving
any setting resets an interval below the 60 minute minimum to `0`, on the
assumption that the node has now been deliberately configured. To keep zero-hop
adverts running, set an explicit value in the 60-240 range.
---
docs/companion_protocol.md
+39 -15
View File
@@ -206,7 +206,7 @@ Byte 1: 0x03
**Command Format**:
```
Byte 0: 0x1F
Byte 1: Channel Index (0-7)
Byte 1: Channel Index (0 .. max_channels-1)
```
**Example** (get channel 1):
@@ -225,7 +225,7 @@ Byte 1: Channel Index (0-7)
**Command Format**:
```
Byte 0: 0x20
Byte 1: Channel Index (0-7)
Byte 1: Channel Index (0 .. max_channels-1)
Bytes 2-33: Channel Name (32 bytes, UTF-8, null-padded)
Bytes 34-49: Secret (16 bytes)
```
@@ -233,8 +233,12 @@ Bytes 34-49: Secret (16 bytes)
**Total Length**: 50 bytes
**Channel Index**:
- Index 0: Reserved for public channels (no secret)
- Indices 1-7: Available for private channels
- Valid range is `0` to `max_channels - 1`. Read `max_channels` from byte 3 of
the `PACKET_DEVICE_INFO` response; do not assume 8. Builds ship with
`MAX_GROUP_CHANNELS` set to 1, 8 or 40 depending on the board.
- Index 0: pre-populated by the firmware with the built-in "Public" channel.
It can be overwritten like any other slot.
- An out-of-range index is rejected with `PACKET_ERROR` / `ERR_CODE_NOT_FOUND`.
**Channel Name**:
- UTF-8 encoded
@@ -242,8 +246,18 @@ Bytes 34-49: Secret (16 bytes)
- Padded with null bytes (0x00) if shorter
**Secret Field** (16 bytes):
- For **private channels**: 16-byte secret
- For **public channels**: All zeros (0x00)
- Always a real 16-byte key; the firmware derives the channel hash from
`SHA256(secret)` (`BaseChatMesh.cpp:936-942`). There is no "no secret" form.
- Do **not** write an all-zero secret. `SHA256` over 16 zero bytes is a fixed,
globally identical value, so a zero-secret channel is a well-known channel
with an all-zero AES key that any node can read — not a private one. The
firmware skips *unnamed* slots when matching inbound group traffic for
exactly this reason (`BaseChatMesh.cpp:392-401`), but a slot that has been
given a name and a zero secret is not skipped, and will absorb null-key
group traffic from any node on the mesh.
- The built-in public channel uses the well-known key
`izOH6cXN6mrJ5e26oRXNcg==` (base64), i.e.
`8b3387e9c5cdea6ac9e5edbaa115cd72` in hex.
**Example** (create channel "YourChannelName" at index 1 with secret):
```
@@ -265,7 +279,7 @@ Bytes 34-49: Secret (16 bytes)
```
Byte 0: 0x03
Byte 1: 0x00
Byte 2: Channel Index (0-7)
Byte 2: Channel Index (0 .. max_channels-1)
Bytes 3-6: Timestamp (32-bit little-endian Unix timestamp, seconds)
Bytes 7+: Message Text (UTF-8, variable length)
```
@@ -288,7 +302,7 @@ Bytes 7+: Message Text (UTF-8, variable length)
**Command Format**:
```
Byte 0: 0x3E
Byte 1: Channel Index (0-7)
Byte 1: Channel Index (0 .. max_channels-1)
Byte 2: Path Length (0xFF = flood, otherwise actual path length)
Bytes 3 .. 2+path_len: Path (omitted when path_len == 0xFF)
Next 2 bytes (little-endian): Data Type (`data_type`, uint16)
@@ -306,13 +320,23 @@ Remaining bytes: Binary payload (variable length)
- Values `0x0001`–`0xFFFE` are available for registered application/community namespaces. See the [Registered data_type values](#registered-data_type-values) table below.
**Limits**:
- Maximum payload length is `MAX_CHANNEL_DATA_LENGTH = MAX_FRAME_SIZE - 9 = 163` bytes.
- Larger payloads are rejected with `PACKET_ERROR` (`ERR_CODE_ILLEGAL_ARG`).
- Maximum payload length is **165** bytes — `MAX_GROUP_DATA_LENGTH =
MAX_PACKET_PAYLOAD - CIPHER_BLOCK_SIZE - 3` (`src/MeshCore.h:21`). This is the
radio-side limit and the one clients should enforce.
- Two different bounds are checked, and they do not agree. The host-frame check
uses the larger `MAX_CHANNEL_DATA_LENGTH = MAX_FRAME_SIZE - 9 = 167`
(`companion_radio/MyMesh.cpp:1265`); the radio-side check uses 165
(`BaseChatMesh.cpp:544`).
- Payloads **above 167** are rejected with `ERR_CODE_ILLEGAL_ARG` (6).
- Payloads of **166 or 167** pass the frame check, then fail the radio-side
check and return `ERR_CODE_TABLE_FULL` (3). Despite that code's usual
meaning, such a send can never succeed — do not retry it. Keep payloads at
165 bytes or fewer and this case cannot arise.
**Response**: `PACKET_OK` (0x00) on success, or `PACKET_ERROR` (0x01) with one of:
- `ERR_CODE_NOT_FOUND` (2) — unknown `channel_idx`
- `ERR_CODE_ILLEGAL_ARG` (6) — invalid `path_len`, reserved `data_type` (`0x0000`), or payload larger than `MAX_CHANNEL_DATA_LENGTH`
- `ERR_CODE_TABLE_FULL` (3) — outbound send queue is full; retry later
- `ERR_CODE_ILLEGAL_ARG` (6) — invalid `path_len`, reserved `data_type` (`0x0000`), or payload larger than `MAX_CHANNEL_DATA_LENGTH` (167)
- `ERR_CODE_TABLE_FULL` (3) — outbound send queue is full (retry later), **or** a payload of 166-167 bytes that exceeds the radio-side limit (permanent; see Limits above)
**Inbound datagrams** are delivered to the host via `RESP_CODE_CHANNEL_DATA_RECV` (0x1B); see [Receive Channel Data Datagram](#receive-channel-data-datagram).
@@ -341,7 +365,7 @@ Inbound group datagrams (radio-level `PAYLOAD_TYPE_GRP_DATA`, 0x06) are forwarde
Byte 0: 0x1B (packet type)
Byte 1: SNR (signed int8, scaled ×4 — divide by 4.0 to recover dB)
Bytes 2-3: Reserved (clients MUST ignore)
Byte 4: Channel Index (0-7)
Byte 4: Channel Index (0 .. max_channels-1)
Byte 5: Path Length (actual path length when flooded, otherwise 0xFF for direct)
Bytes 6-7: Data Type (uint16 little-endian)
Byte 8: Data Length
@@ -550,7 +574,7 @@ def parse_contact_message(data):
**Standard Format** (`PACKET_CHANNEL_MSG_RECV`, 0x08):
```
Byte 0: 0x08 (packet type)
Byte 1: Channel Index (0-7)
Byte 1: Channel Index (0 .. max_channels-1)
Byte 2: Path Length
Byte 3: Text Type
Bytes 4-7: Timestamp (32-bit little-endian)
@@ -562,7 +586,7 @@ Bytes 8+: Message Text (UTF-8)
Byte 0: 0x11 (packet type)
Byte 1: SNR (signed byte, multiplied by 4)
Bytes 2-3: Reserved
Byte 4: Channel Index (0-7)
Byte 4: Channel Index (0 .. max_channels-1)
Byte 5: Path Length
Byte 6: Text Type
Bytes 7-10: Timestamp (32-bit little-endian)
docs/faq.md
+9 -9
View File
@@ -537,18 +537,18 @@ Mac: python3 should be already installed.
Then it should be the same for all platforms:
```
python3 -m venv meshcore
cd meshcore && source bin/activate
python3 -m venv meshcore-venv
cd meshcore-venv && source bin/activate
pip install -U platformio
git clone https://github.com/ripplebiz/MeshCore.git
cd MeshCore
git clone https://github.com/meshcore-dev/meshcore.git
cd meshcore
```
open platformio.ini and in `[arduino_base]` edit the `LORA_FREQ=867.5`
save, then run:
open platformio.ini and in `[arduino_base]` edit `LORA_FREQ` (it defaults to
`869.618`) to the frequency for your region, save, then run:
```
pio run -e RAK_4631_Repeater
pio run -e RAK_4631_repeater
```
then you'll find `firmware.zip` in `.pio/build/RAK_4631_Repeater`
then you'll find `firmware.zip` in `.pio/build/RAK_4631_repeater`
### 5.10. Q: Are there other MeshCore related open source projects?
@@ -592,7 +592,7 @@ For ESP-based devices (e.g. Heltec V3) you need:
1. Download the firmware file from <https://flasher.meshcore.io>.
- Go to the website in a browser and find the section that has the firmware you need.
- Click the Download button, right-click on the file you need, for example:
- `Heltec_V3_companion_radio_ble-v1.7.1-165fb33.bin`
- `Heltec_v3_companion_radio_ble-v1.7.1-165fb33.bin`
- Non-merged bin keeps the existing Bluetooth pairing database.
- `Heltec_v3_companion_radio_usb-v1.7.1-165fb33-merged.bin`
- Merged bin overwrites everything including the bootloader and existing Bluetooth pairing database, but keeps configurations.
docs/nrf52_power_management.md
+9 -1
View File
@@ -186,11 +186,19 @@ Power management status can be queried via the CLI:
| `get pwrmgt.bootreason` | Returns reset and shutdown reason strings |
| `get pwrmgt.bootmv` | Returns boot voltage in millivolts |
On boards without power management enabled, all commands except `get pwrmgt.support` return:
On boards without power management enabled, `get pwrmgt.source` and
`get pwrmgt.bootmv` return:
```
ERROR: Power management not supported
```
`get pwrmgt.support` returns `unsupported`. `get pwrmgt.bootreason` is not
compiled out at all and answers on every board: `getResetReason()` and
`getShutdownReason()` are virtuals on the base board class, so a board that
does not override them reports `Not available` rather than an error. ESP32
boards override the reset half with `esp_reset_reason()`, so they return a real
reset reason and `Not available` for the shutdown reason.
## Debug Output
When `MESH_DEBUG=1` is enabled, the power management module outputs:
docs/number_allocations.md
+1
View File
@@ -19,6 +19,7 @@ Once you have a working app/project, you need to be able to demonstrate it exist
| 0110 - 011F | Ripple | ripple_biz@protonmail.com — https://buymeacoffee.com/ripplebiz |
| 0120 | MCO Advanced | most.original.address@gmail.com — https://hdden.ru/MCOa/ |
| 0130 - 013F | StreamSensor | william@housedillon.com - https://housedillon.com/blog/lora-e5-with-seeed-fusion |
| 0140 | Nelos | support@nelos.app — https://nelos.app |
| FF00 - FFFF | -reserved for testing/dev- | |
(add rows, inside the range 0100 - FEFF for custom apps)
docs/payloads.md
+46 -9
View File
@@ -93,6 +93,7 @@ Returned path messages provide a description of the route a packet took from the
| Field | Size (bytes) | Description |
|--------------|-----------------|------------------------------------------|
| timestamp | 4 | sender time (unix timestamp) |
| req type | 1 | request sub type |
| request data | rest of payload | application-defined request payload body |
For the common chat/server helpers in `BaseChatMesh`, the current request type values are:
@@ -100,7 +101,13 @@ For the common chat/server helpers in `BaseChatMesh`, the current request type v
| Value | Name | Description |
|--------|-----------|----------------------------------------------------|
| `0x01` | get stats | get stats of repeater or room server |
| `0x02` | keepalive | keep-alive request used for maintained connections |
| `0x02` | keepalive | (deprecated) |
| `0x03` | get telemetry | request node telemetry |
| `0x04` | get min/max/avg | get sensor node stats on time series data |
| `0x05` | get acl | node ACL query |
| `0x06` | get neighbors | node neighbors query |
| `0x08` | subscribe | subscribe to telemetry push |
| `0x09` | ubsubscribe | unsubscribe from telemetry push |
#### Get stats
@@ -125,21 +132,50 @@ Gets information about the node, possibly including the following:
* Number posted (?)
* Number of post pushes (?)
#### Get telemetry data
Not defined in `BaseChatMesh`. Sensor- and application-specific request payloads may be implemented by higher-level firmware.
#### Get Telemetry
Not defined in `BaseChatMesh`.
| Field | Size (bytes) | Description |
|----------------|--------------|------------------------------|
| timestamp | 4 | sender time (unix timestamp) |
| req type | 1 | 0x03 (request sub type) |
| permission mask | 1 | bitwise inverse mask to AND to permissions (0 = get ALL telem values) |
#### Get Min/Max/Ave (Sensor nodes)
Not defined in `BaseChatMesh`.
| Field | Size (bytes) | Description |
|----------------|--------------|------------------------------|
| timestamp | 4 | sender time (unix timestamp) |
| req type | 1 | 0x04 (request sub type) |
| start | 4 | starting time, seconds ago |
| end | 4 | ending time, seconds ago |
| reserved | 2 | should be zeroes |
#### Subscribe to Telemetry push - (Sensor nodes)
| Field | Size (bytes) | Description |
|----------------|--------------|------------------------------|
| timestamp | 4 | sender time (unix timestamp) |
| req type | 1 | 0x08 (request sub type) |
| push tag | 4 | 32-bit tag to be used in telemetry push _REPLY payloads |
| timeout secs | 2 | subscription timeout (seconds) |
| reserved | 1 | should be zero |
| min deltas len | 1 | byte length of LPP encoded min_deltas |
| min deltas | (variable) | LPP encoded min_deltas |
#### Unsubscribe from Telemetry push - (Sensor nodes)
| Field | Size (bytes) | Description |
|----------------|--------------|------------------------------|
| timestamp | 4 | sender time (unix timestamp) |
| req type | 1 | 0x09 (request sub type) |
#### Get Access List
Not defined in `BaseChatMesh`.
| Field | Size (bytes) | Description |
|----------------|--------------|------------------------------|
| timestamp | 4 | sender time (unix timestamp) |
| req type | 1 | 0x05 (request sub type) |
| reserved | 2 | should be zeroes |
#### Get Neighbors
@@ -171,8 +207,9 @@ txt_type
| Value | Description | Message content |
|--------|---------------------------|--------------------------------------------------------------------------|
| `0x00` | plain text message | the plain text of the message |
| `0x01` | CLI command | the command text of the message |
| `0x01` | CLI data | CLI command OR reply text |
| `0x02` | signed plain text message | first four bytes is sender pubkey prefix, followed by plain text message |
| `0x03` | CLI command | (since v1.18+) CLI command text (explicit) |
## Anonymous request
docs/terminal_chat_cli.md
+13 -6
View File
@@ -27,15 +27,17 @@ set lon {longitude}
```
Sets your advertisement map longitude. (decimal degrees)
```
set dutycycle {percent}
```
Sets the transmit duty cycle limit (1-100%). Example: `set dutycycle 10` for 10%.
```
set af {air-time-factor}
```
Sets the transmit air-time-factor. Deprecated — use `set dutycycle` instead.
Sets the transmit air-time-factor.
> **Note:** `set dutycycle` is *not* available in Terminal Chat. Every other
> firmware — Repeater, Room Server, Sensor and Companion Radio — routes its
> `set`/`get` commands through the shared radio prefs handler and does support
> it (see [CLI Commands](./cli_commands.md)). Terminal Chat is the sole
> exception: it has its own inline `set` handler covering only the six options
> listed above.
```
@@ -99,3 +101,8 @@ Resets the path to current recipient, for new path discovery.
public {text}
```
Sends the text message to the built-in 'public' group channel
```
help
```
Lists the available commands.