diff --git a/MQTT_IMPLEMENTATION.md b/MQTT_IMPLEMENTATION.md index 0da06dc51..ba0fe5d2c 100644 --- a/MQTT_IMPLEMENTATION.md +++ b/MQTT_IMPLEMENTATION.md @@ -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 ` 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 ` - 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 ` - Set neighbors publish interval (12-336 hours, default 24; PSRAM only) - `set mqtt.ntp ` - 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 ` - 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 diff --git a/MQTT_INTERNALS.md b/MQTT_INTERNALS.md index 426d4b9cf..83e10a516 100644 --- a/MQTT_INTERNALS.md +++ b/MQTT_INTERNALS.md @@ -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: /` 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`, diff --git a/docs/cli_commands.md b/docs/cli_commands.md index b0badbcd3..c4bb5d9df 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -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 ` + +**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: /` 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 ` + +**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`