docs(mqtt): document the neighbors feature
- MQTT_IMPLEMENTATION.md: neighbors topic, JSON message example, get/set command lists, and the MeshRank packets-only note. - docs/cli_commands.md: mqtt.neighbors / mqtt.neighbors.interval get/set and the discover.scopes command, with PSRAM-only notes. - MQTT_INTERNALS.md: the two-stage discovery + Core1->Core0 publish handoff, peer-overlay decryption, buffer sizing, and MeshRank exclusion.
This commit is contained in:
1 parent
d6f8a87183
commit
0ae6aa4df2
3 files changed
+110
No files matched your search
@@ -382,6 +382,8 @@ These settings apply across all MQTT slots:
|
||||
- `get mqtt.rx` - Get RX packet uplinking setting (on/off)
|
||||
- `get mqtt.tx` - Get TX packet uplinking setting (on/off/advert)
|
||||
- `get mqtt.interval` - Get status publish interval
|
||||
- `get mqtt.neighbors` - Get periodic neighbors publishing setting (on/off; PSRAM only)
|
||||
- `get mqtt.neighbors.interval` - Get neighbors publish interval in hours (PSRAM only)
|
||||
- `get mqtt.ntp` - Get effective NTP server hostname
|
||||
- `get mqtt.ntp.diag` - Probe every configured NTP server for connectivity (does not change the clock; serial console shows each server's reported time, LoRa shows a compact `<server> ok|fail` list)
|
||||
- `get mqtt.owner` - Get owner public key (serial console only)
|
||||
@@ -399,6 +401,8 @@ These settings apply across all MQTT slots:
|
||||
- `advert` - Uplink only this node's own advert packets (self-originated)
|
||||
- `off` - Disable TX packet uplinking
|
||||
- `set mqtt.interval <minutes>` - Set status publish interval (1-60 minutes)
|
||||
- `set mqtt.neighbors on|off` - Enable/disable periodic neighbors publishing (PSRAM only; read live, no restart)
|
||||
- `set mqtt.neighbors.interval <hours>` - Set neighbors publish interval (12-336 hours, default 24; PSRAM only)
|
||||
- `set mqtt.ntp <hostname>` - Set custom NTP server (validated with immediate sync); `none` reverts to default
|
||||
- `set mqtt.owner <64-hex-char-public-key>` - Set owner public key
|
||||
- `set mqtt.email <email>` - Set owner email address
|
||||
@@ -584,6 +588,12 @@ Full packet data with RF characteristics and metadata.
|
||||
### Raw Topic: `meshcore/{IATA}/{DEVICE_PUBLIC_KEY}/raw`
|
||||
Minimal raw packet data for map integration.
|
||||
|
||||
### Neighbors Topic: `meshcore/{IATA}/{DEVICE_PUBLIC_KEY}/neighbors`
|
||||
Periodic snapshot of this node's zero-hop neighbor table plus each neighbor's
|
||||
region scopes (PSRAM boards only; disabled by default). Published non-retained at
|
||||
QoS 1 on the interval set by `mqtt.neighbors.interval` (12–336 h, default 24 h).
|
||||
Like status/raw, this topic is **not** sent to MeshRank slots (packets-only contract).
|
||||
|
||||
**Note**: `{DEVICE_PUBLIC_KEY}` is the device's public key in hexadecimal format (64 characters).
|
||||
|
||||
## JSON Message Formats
|
||||
@@ -662,6 +672,28 @@ Minimal raw packet data for map integration.
|
||||
}
|
||||
```
|
||||
|
||||
### Neighbors Message
|
||||
```json
|
||||
{
|
||||
"timestamp": "2024-01-01T12:00:00.000000+00:00",
|
||||
"origin": "MeshCore-HOWL",
|
||||
"origin_id": "A1B2C3D4E5F67890...",
|
||||
"self": { "scopes": "DEN,APRS" },
|
||||
"neighbors": [
|
||||
{
|
||||
"pubkey": "0011223344556677...",
|
||||
"snr": 9.75,
|
||||
"heard_secs_ago": 42,
|
||||
"scopes": "DEN,APRS",
|
||||
"status": "responded"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
Entries are ordered most- to least-useful (most recently heard, then stronger
|
||||
SNR); the tail is dropped if the payload would exceed the 10 KB publish buffer.
|
||||
`status` is `responded`, `timeout`, or `send_failed` per neighbor.
|
||||
|
||||
## Key Features
|
||||
|
||||
### Slot-Based Preset System
|
||||
|
||||
@@ -57,6 +57,37 @@ scheduled time are expired at dequeue, so under throttle the queue holds only fr
|
||||
traffic and admin responses reach the trickle of TX budget. Non-observer builds keep
|
||||
the upstream pool behavior.
|
||||
|
||||
### Neighbors publication path (PSRAM only)
|
||||
|
||||
Periodic neighbors publishing is gated on `WITH_MQTT_NEIGHBORS`
|
||||
(`defined(BOARD_HAS_PSRAM) && defined(MAX_NEIGHBOURS) && MAX_NEIGHBOURS > 0`,
|
||||
defined in `MQTTBridge.h`). It spans two subsystems and two cores:
|
||||
|
||||
- **Mesh side (Core 1), `MyMesh`**: the `loop()` runs a two-stage refresh driven by
|
||||
`mqtt_neighbors_interval`. Stage 1 sends a zero-hop `sendNodeDiscoverReq()` and waits
|
||||
out its 60 s collection window to refresh `neighbours[]`. Stage 2
|
||||
(`startNeighborDiscover`) fires one anon-regions scope query per heard neighbor,
|
||||
overlaying them onto the peer-index space at `NEIGHBOR_DISCOVER_PEER_BASE` so their
|
||||
`PAYLOAD_TYPE_RESPONSE` packets decrypt via `searchPeersByHash`/`getPeerSharedSecret`/
|
||||
`onPeerDataRecv` even when the neighbor is not an ACL client. After all responses land
|
||||
or a 30 s window expires, `finishNeighborDiscover()` builds the JSON with
|
||||
`MQTTMessageBuilder::buildNeighborsMessage` into a transient PSRAM buffer and hands it
|
||||
to the bridge.
|
||||
- **Bridge side, handoff**: `requestPublishNeighbors(json, len)` (Core 1) memcpys into a
|
||||
persistent ~10 KB PSRAM buffer (`NEIGHBORS_JSON_BUFFER_SIZE`) and sets
|
||||
`_neighbors_publish_pending` with a release store; the MQTT task (`mqttTaskLoop`, Core 0)
|
||||
consumes it with an acquire load, calls `publishNeighbors()`, and clears the flag. A
|
||||
second snapshot is dropped while one is in flight. `publishNeighbors()` sends QoS 1,
|
||||
retain = `preset->allow_retain` (custom slots non-retained). MeshRank slots are skipped
|
||||
(the topic router rejects non-packets for MeshRank).
|
||||
- **Status reporting**: `MyMesh` reports the schedule each loop via
|
||||
`setNeighborsSchedule(phase, secs)`; `formatMqttStatusReply` renders it as the trailing
|
||||
`nbr: <when>/<last>` field in `get mqtt.status` while the feature is enabled.
|
||||
|
||||
The JSON builder lives in the pure, host-tested `MQTTPayloadBuilder`
|
||||
(`test/test_mqtt_payload_builder`); the topic type in `MQTTTopicRouter`
|
||||
(`test/test_mqtt_topic_router`). The mesh↔bridge orchestration above is on-target only.
|
||||
|
||||
### `/mqtt_prefs` file format
|
||||
|
||||
`/mqtt_prefs` is written with an 8-byte `MQTTPrefsHeader` (`magic`, `version`,
|
||||
|
||||
@@ -113,6 +113,20 @@ This document provides an overview of CLI commands that can be sent to MeshCore
|
||||
|
||||
---
|
||||
|
||||
### Discover neighbor scopes (MQTT observer, PSRAM only)
|
||||
|
||||
Refreshes the zero-hop neighbor table, then queries each neighbor for its region
|
||||
scopes and publishes the assembled table to the MQTT `neighbors` topic once.
|
||||
|
||||
**Usage:**
|
||||
- `discover.scopes`
|
||||
|
||||
**Note:** Requires a PSRAM board with the MQTT bridge running. On non-PSRAM MQTT
|
||||
builds it replies `Err - not supported (requires PSRAM)`. If a `discover.neighbors`
|
||||
refresh is already in flight, the scope pass is queued behind it.
|
||||
|
||||
---
|
||||
|
||||
## Statistics
|
||||
|
||||
### Clear Stats
|
||||
@@ -1076,6 +1090,39 @@ region save
|
||||
|
||||
---
|
||||
|
||||
#### View or change periodic neighbors publishing (MQTT observer, PSRAM only)
|
||||
**Usage:**
|
||||
- `get mqtt.neighbors`
|
||||
- `set mqtt.neighbors <on|off>`
|
||||
|
||||
**Parameters:**
|
||||
- `on`: periodically discover neighbor scopes and publish the neighbor table to the `neighbors` topic
|
||||
- `off`: disable periodic neighbors publishing
|
||||
|
||||
**Default:** `off`
|
||||
|
||||
> **Note:** Requires a PSRAM board. On non-PSRAM MQTT builds this replies
|
||||
> `Err - not supported (requires PSRAM)`. The setting is read live by the mesh
|
||||
> loop — no restart required; enabling it triggers a discovery on the next pass.
|
||||
> While enabled, `get mqtt.status` gains a trailing `nbr: <next>/<last>` field
|
||||
> (time to next publish, and how the last publish went).
|
||||
|
||||
---
|
||||
|
||||
#### View or change the neighbors publish interval (MQTT observer, PSRAM only)
|
||||
**Usage:**
|
||||
- `get mqtt.neighbors.interval`
|
||||
- `set mqtt.neighbors.interval <hours>`
|
||||
|
||||
**Parameters:**
|
||||
- `hours`: how often to publish the neighbor table (12–336, default 24)
|
||||
|
||||
**Default:** `24` (hours)
|
||||
|
||||
> **Note:** Out-of-range values are rejected (not clamped). Requires a PSRAM board.
|
||||
|
||||
---
|
||||
|
||||
#### View or change the NTP server (MQTT observer only)
|
||||
**Usage:**
|
||||
- `get mqtt.ntp`
|
||||
|
||||
Reference in new issue
Block a user