Report the repeaters an observer hears and their regions
An observer can list the repeaters it hears directly (zero hops) and ask each one which
flood regions it serves. It publishes the result to its MQTT brokers as a /neighbors
report, which a map service such as CoreScope uses to show which region each repeater
belongs to, from the repeater itself rather than from guesswork.
Applies to
WiFi companion-observer images: Heltec V3, Heltec V4 OLED/TFT, Heltec V4 R8, Heltec
RCC6 and XIAO S3 WIO. Needs firmware newer than offband-v1.6.0-beta1.
Before you start
Connect to the observer the way you send other observer commands: the reserved
_sys @ <8hex> channel in the app, or the USB serial console. The repeaters you want
to see must be in direct radio range. A repeater answers discover.neighbors only with
forwarding on; it answers the regions request either way, if its firmware has it.
To publish, the observer needs at least one MQTT broker enabled and connected (mqtt
status), and its clock set: a report is never sent with an unset clock.
Steps
1. Fill the neighbor list
The observer adds a repeater to its list whenever it hears that repeater's advert directly. To ask nearby repeaters to answer now instead of waiting:
discover.neighbors
Reply: discover.neighbors: request queued; <N> neighbors in table, answers arrive over
the next minute. Answers keep arriving for one minute. Sending the command again
inside that minute replies still collecting answers to the last request (<S> s left)
and sends nothing.
2. Ask each neighbor for its regions, and publish
discover.scopes
Reply: discover.scopes: querying <N> neighbors, one at a time (up to 20 s each), then
publishing /neighbors. The observer asks one repeater at a time and waits up to 20
seconds for each, so a long list takes a while; normal traffic and the app connection
keep working meanwhile. When the last one is done, the report goes to every connected
broker, whether or not periodic publishing is on.
Send discover.scopes again to see progress:
discover.scopes: running, <D> of <M> done (<R> responded, <T> timeout, <F> send_failed).
While a query is running the command reports progress and does not restart it.
3. Publish on a schedule (optional)
Periodic publishing is off until you turn it on:
set mqtt.neighbors on
Reply: mqtt.neighbors = on, every 24 h. The first cycle starts ten minutes after the
observer starts, or within a minute of turning this on if that is later; after that,
one per interval. Each one refreshes the
neighbor list, queries every neighbor and publishes. To change the interval (12 to 336
hours):
set mqtt.neighbors.interval 48
Both settings are saved and survive a restart. get mqtt.neighbors and
get mqtt.neighbors.interval show them; set mqtt.neighbors off stops it.
Check it worked
mqtt status shows where publishing stands on its second line, for example
nbr: on, every 24 h, next in 3h12m, last 20h48m ago. last never means no report has
gone out yet.
When a query finishes, discover.scopes starts a new one and reports how the last one
ended on a second line: last walk: <R> responded, <T> timeout, <F> send_failed of <M>.
responded means the repeater answered with its regions (an empty answer is still an
answer).
On the broker, the report is retained on <prefix>/<iata>/<device>/neighbors.
Troubleshooting
no neighbors yet: the observer has not heard a repeater directly. Rundiscover.neighbors, wait a minute, and try again.- Many
timeout: a repeater answers only a few such requests every few minutes, and a repeater whose firmware lacks this request type does not answer at all. Try again later. A timeout does not mean the repeater serves no regions. send_failed: the observer was briefly out of packet buffers. Try again.no memory for the query: on boards with PSRAM the query needs it; report this with the board model.nbr: ... due (waiting for clock and a broker): a report is due but the observer has no clock or no connected broker. It starts as soon as it has both. Checkmqtt statusand the observer's time.- A report on a board without PSRAM is smaller and may list fewer neighbors; the report
then says so (
truncated).
Limits and recovery
The neighbor list and query results are kept in memory only and start empty after a
restart. mqtt.neighbors and mqtt.neighbors.interval are saved; set them back with
set mqtt.neighbors off and set mqtt.neighbors.interval 24.