Port the observer doc cleanup from observer-firmware (4beb5472) onto dev,
keeping dev-specific content intact.
- move internal mechanics into MQTT_INTERNALS.md: deferred construction,
runtime slot memory, backoff/circuit breaker, message building, command
namespacing, and the legacy prefs key mapping
- drop the duplicated First-Time Setup, Command Architecture, and SNMP
Monitoring sections, folding their unique steps into Quick Start
- condense the partition/NVS prose and merge the five custom-broker
examples into one Custom Brokers section
- promote the preset list to a top-level Broker Presets section with an
Extra setup column, and document the presets the table was missing:
meshcore-fi, corecomms, mesh-chaun14, wcmesh, and meshtexas
- fix the coloradomesh port (443, not 1883)
- point flasher and changelog links at observer.gessaman.com
- restore the nbr: status field, which the code still emits, and correct
the neighbors topic to QoS 0 retained per allow_retain
Dev-specific content is preserved as-is: per-slot packet filters, the Web
Configuration Portal, local testing without hardware, MeshRank's raw
exclusion, and neighbors default_scope.
MeshRank slots previously took packets only. The broker tolerates status and
neighbors (and its maintainer intends to look at using the neighbors data), so
those now publish under meshrank/uplink/{token}/{device}/{type}, using the same
type suffixes as the MeshCore layout. Raw stays excluded: it is the
highest-volume topic and the broker does not consume it, so `set mqtt.raw on`
has no effect on a MeshRank slot.
All MeshRank gating funnels through the topic router, so relaxing that single
guard was sufficient - publishStatusToSlot, publishStatus, publishRaw,
publishNeighbors, and eligiblePacketSlots already skip slots that cannot form a
topic. A per-slot token is still required. Because eligiblePacketSlots resolves
topic support before serialising, raw JSON is never built for a MeshRank slot
rather than built and discarded.
observer-firmware sends raw to MeshRank; this supersedes that decision, so raw
must stay excluded when the branches merge. MeshRankTakesEveryTypeExceptRaw
fails if a merge re-enables it.
Enhance the neighbor discovery JSON structure by introducing a
default_scope field, which indicates the region name this node
floods to by default. This change improves clarity in the
neighbor discovery process and aligns with the unscoped flood
behavior when no default region is set. Updates include
modifications to the MyMesh class and related message building
functions to accommodate the new field.
Enhance the MQTT preferences handling by establishing a downgrade
contract that ensures compatibility between different firmware versions.
This contract allows nodes to read settings from newer builds while
safeguarding against data loss during downgrades. The implementation
includes updates to the classification logic, ensuring that longer
payloads from newer versions are handled correctly without rejecting
files, thus preserving critical WiFi credentials and broker settings.
Add support for named packet types in per-slot filters, allowing users
to specify packet types using descriptive names alongside numeric values.
This improves usability and clarity in configuring MQTT slot filters.
Updates include modifications to the parsing logic, WebConfig interface,
and related documentation to reflect the new naming conventions.
Introduce per-slot packet filters to allow users to specify which
packet types are uploaded for each MQTT slot. This feature enhances
the flexibility of the MQTT bridge by enabling users to configure
allowlists for packet types, improving the efficiency of data
transmissions. The implementation includes updates to the WebConfig
interface, internal handling of packet filters, and necessary
modifications to the MQTT preferences structure.
Introduce new methods to manage neighbor discovery JSON budget and
entries in MyMesh. This includes tracking the number of queried and
published neighbors, measuring JSON sizes, and handling truncation
when the buffer limit is reached. These improvements optimize the
neighbor discovery process and ensure efficient JSON message
construction for MQTT communications.
Add functionality to manage neighbor discovery requests in MyMesh.
This includes handling the status of requests, updating the state
upon transmission success or failure, and implementing a timeout
mechanism for neighbor discovery queries. The changes improve the
efficiency and reliability of neighbor discovery operations in
MQTT-enabled environments.
observer-firmware had a .build-wt-<sha> worktree committed as a gitlink, which
made every CI checkout warn "No url found for submodule path ... in .gitmodules"
and broke `git submodule` in fresh clones. This branch has no such entry; ignore
the pattern so it stays that way, and skip it in both channels' paths-ignore
since a build worktree can never change the binaries.
The production build workflow is taken from observer-firmware verbatim, keeping
the copy on this branch identical and conflict-free on promotion.
Concurrency groups are repo-wide, not per-branch, so the beta build sharing
`flasher-publish` with the production workflows meant an in-flight beta build
forced a production build into the pending state — where the next run queued into
that group cancelled it outright. That is what silently dropped the production
build of the eastidahomesh preset fix: the beta build held the group from
22:29:24 to 22:37:34, production's build queued at 22:31:26 and went pending, and
its docs sync evicted it a second later.
Beta now uses its own group and, since the channels are no longer serialized
against each other, its flasher push rebase-retries the same way production's
does (with --autostash, because the scoped add here leaves the checkout dirty).
Also refresh the two workflow copies this branch never received: they still
triggered on the retired mqtt-bridge-implementation-flex branch, so they were
dead on push while still sitting in the shared group. Taking production's current
versions verbatim keeps them inert here and conflict-free on promotion.
Stamp FIRMWARE_BUILD_NUMBER into FIRMWARE_VERSION_STRING (the output
filename), so dev assets become <env>-v1.16.0.N-dev-<hash>.bin and the web
flasher's Version dropdown (parsed from the asset name by the /releases
Worker) shows the true published build instead of the bare base version.
The build-number suffix is computed once, up front, and now feeds BOTH the
filename and the embedded -DFIRMWARE_VERSION (byte-for-byte unchanged, it
already carried .N). Local builds without the counter still produce
3-segment names, so OTA and every filename parser stay backward-compatible.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds an admin-password field to the setup wizard and the LAN editor, so a
node's password can be set during onboarding and rotated later without a
serial console.
The key maps to the top-level `password` CLI command rather than a `set`
handler, so it is classified separately from WC_ALLOWED_SET_KEYS. It is the
only key granted that treatment, which keeps the allowlist the sole route to
`set` and leaves no general path from a batch to arbitrary CLI commands.
Accepted in both modes: MODE_OFF is refused earlier in handleConfigPost, LAN
required a login to get that far, and the setup AP implies physical proximity.
Restricting rotation to the AP would have forced a bridge outage (`set bridge
off` + `start webconfig ap`) just to change a password.
First onboarding is gated server-side: while the setup AP is up and no WiFi is
configured, a batch that reboots or sets wifi.ssid must also carry a password,
so neither the Advanced editor nor a crafted request can save WiFi and strand
the node on the factory password. The flag is latched at AP start, so a save
that fails partway cannot drop the requirement on retry.
The CLI's `password` command echoes the new secret back in its reply, and
replies are served to the client over the open setup AP, so the reply is
overwritten with "OK" before it can be serialized.
UI: the field lives with the other NodePrefs settings (wizard step 2, and the
Node card on the Radio tab) rather than beside the WiFi password, which is a
different credential. Confirm fields mirror their password twin and are cleared
whenever it is, so a stale confirm value cannot fail a later save as a spurious
mismatch. Validation runs ahead of the WiFi-changed split so a password-only
save is still checked, and reveals the Radio tab before reporting, since the
save bar spans every tab.
Implement SNMP functionality in MyMesh to provide radio diagnostics
and statistics updates. This includes a new method for formatting
radio diagnostic replies and periodic updates to the SNMP agent
with radio stats, enhancing monitoring capabilities for users
with SNMP enabled.
Add functionality to schedule deferred OTA updates in the MyMesh class.
This includes a new member variable to track the update time and a method
to initiate the update process, allowing for a smoother OTA experience
by managing timing and state transitions effectively.
Cherry-picked from observer-firmware (76f44d7d). Resolved a conflict in
loop() where the WITH_WEBCONFIG block occupies the same anchor and shares
an identical closing tail; both blocks retained.
Introduce a new built-in MQTT preset for the meshtexas.org service,
increasing the total number of presets to 29. This addition enhances
connectivity options for users and supports broader integration
within the MQTT ecosystem.
Enhance the MQTT stats reply to include outbox drop statistics,
providing users with better insight into message handling and
memory pressure. This change improves the clarity of the status
message and aids in diagnosing potential issues with message
delivery.
Update the CommonCLI_Observer to mask sensitive data such as passwords
and WiFi credentials in responses when accessed remotely. This change
ensures that sensitive information is only visible over serial,
enhancing security and preventing accidental exposure of credentials.
Improve the response message for the `alert test` command to clarify
that a successful test send does not guarantee automatic alerts are
enabled. This change helps prevent confusion for operators regarding
the status of the alert system after testing.
Add a new classification mechanism for MQTT slot activation to inform
users whether a slot will connect on the current hardware. This includes
detailed handling of enabled slots and their limits, improving the CLI's
ability to provide accurate feedback during configuration. Additionally,
unit tests are introduced to validate the new functionality across various
scenarios, enhancing overall robustness.
Adjust the command handling in CommonCLI_Observer to prioritize the
more specific "timezone.offset" check before the general "timezone"
check. This change prevents incorrect responses when querying the
timezone offset, improving the clarity and correctness of command
responses.
Enhance the command handling in CommonCLI_Observer to clarify the
compilation behavior under different configurations. Additionally,
optimize memory pressure checks in MQTTBridge to reduce unnecessary
heap walks, improving performance during sustained memory pressure.
This change ensures that publishes are skipped only when necessary,
enhancing overall stability.
Eliminate unnecessary calls to gmtime and localtime in the
syncTimeWithNTP function. This cleanup improves code clarity
and reduces potential confusion regarding time handling.
Add checks to prevent null or zero-length hex buffers in the
bytesToHex and packetToHex functions. This guarantees that an
empty string is returned instead of an uninitialized buffer,
improving the safety of JSON serialization.
Introduce a mechanism to manage on-connect status publishing for MQTT
slots. This change allows the MQTT task to handle status updates
safely, ensuring that shared resources are accessed in a controlled
manner. The new flag `_status_publish_pending` is set in the onConnect
callback and processed in the main MQTT task loop, preventing race
conditions and improving overall stability.
Replace multiple snprintf calls with a single replyAppendf function to
improve buffer management and prevent overflow. This change enhances
the readability and maintainability of the code while ensuring that
the reply buffer is handled safely across various MQTT status and
diagnostic replies.
Enhance the documentation for the `start ota` command to clarify its
behavior when connected to a Wi-Fi network versus when using the
`start ota ap` option. This provides users with better guidance on
how to initiate OTA updates under different network conditions.
Add support for neighbor discovery and management in the MyMesh class.
This includes structures for neighbor information, methods for handling
neighbor advertisements, and control data reception. The new features
allow for dynamic neighbor management, enhancing the mesh network's
capabilities. Additionally, the maximum number of neighbors is set to
50 across various platform configurations.
Update commit logic to remove existing destination before renaming
the temporary file on ESP32. This change addresses the SPIFFS_ERR_CONFLICTING_NAME
issue, ensuring that the new preferences are published correctly.
Add tests to validate the new behavior and confirm that the
temporary file is handled appropriately.
- Allow mqtt.neighbors and mqtt.neighbors.interval in the WebConfigKeys set-key
allowlist (the CLI enforces the PSRAM guard; the stub reply handles non-PSRAM).
- Emit neighbors + neighbors_interval (hours) in the WebConfigServer config JSON.
- Add a "Publish neighbors" toggle and a "Neighbors interval (hours)" field
(12-336) to the Publishing card, with getVal() cases in webui/index.html.
- Cover both keys in test_webconfig_keys.
WebConfigHtml.h is a gitignored build artifact regenerated by the pre-build
hook from index.html, so it is not committed. Verified: test_webconfig_keys
passes and the T_Beam_S3_Supreme observer_mqtt firmware builds [SUCCESS].
Port the neighbors CLI from mqtt-bridge-implementation-flex:
- set mqtt.neighbors on|off - enable/disable periodic publishing
- set mqtt.neighbors.interval <h> - 12-336 hours (rejected, not clamped), stored ms
- get mqtt.neighbors - "on"/"off"
- get mqtt.neighbors.interval - "> <hours> hours (<ms> ms)" (ceiling division)
Both gated on WITH_MQTT_NEIGHBORS with a WITH_MQTT_BRIDGE stub replying
"Err - not supported (requires PSRAM)" on non-PSRAM builds. Handlers only write
prefs + savePrefs() — the mesh loop reads them live, so no bridge restart and no
direct bridge/MyMesh call (matches flex).
Token ordering preserved: SET tokens keep their trailing space so the shorter
"mqtt.neighbors " can precede "mqtt.neighbors.interval "; GET tokens have no
trailing space so the longer ".interval" is tested first.
Port the neighbor-discovery state machine from mqtt-bridge-implementation-flex,
adapted to this branch's MyMesh (WebConfig members shifted the insertion points;
applied by content).
- Two-stage periodic refresh in loop() driven by mqtt_neighbors_interval:
stage 1 is a zero-hop sendNodeDiscoverReq() (reuses the existing 60s window),
stage 2 (startNeighborDiscover) fires one anon-regions scope query per heard
neighbour, then finishNeighborDiscover() builds the table JSON via
MQTTMessageBuilder::buildNeighborsMessage and hands it to
bridge->requestPublishNeighbors().
- Peer overlay at NEIGHBOR_DISCOVER_PEER_BASE lets scope-query RESPONSE packets
from non-ACL neighbours decrypt: searchPeersByHash prepends heard neighbours
(bounded by MAX_CLIENTS), getPeerSharedSecret derives the secret on the fly,
and onPeerDataRecv routes both overlay-index and ACL-client-that-is-a-neighbour
responses into handleNeighborDiscoverResponse.
- Entries ordered most- to least-useful (recent, then stronger SNR) so the JSON
builder's tail-drop keeps the useful head.
- `discover.scopes` CLI command (manual trigger), with a WITH_MQTT_BRIDGE stub
replying "requires PSRAM" on non-PSRAM builds.
- Reports schedule to the bridge each loop via setNeighborsSchedule().
- Uses ArduinoJson v7 JsonDocument (not deprecated DynamicJsonDocument).
All gated on WITH_MQTT_NEIGHBORS. Reuses the existing MQTTBridge* member.
Verified: T_Beam_S3_Supreme_SX1262_repeater_observer_mqtt builds [SUCCESS].
Port the periodic-neighbors publication from mqtt-bridge-implementation-flex,
adapted to this branch's structure:
- Add MQTT_PUBLICATION_NEIGHBORS ("neighbors") to the pure MQTTTopicRouter
instead of flex's messageTypeSuffix() helper (this branch already routes
every publication type through mqttBuildPublicationTopic()). Neighbors is a
MeshCore/custom publication type, so it resolves to
meshcore/{iata}/{device}/neighbors and honors custom templates.
- Deliberately do NOT port flex's "all message types to MeshRank" change:
this branch documents and host-tests a packets-only MeshRank contract
(MQTTPresets.h, MQTT_IMPLEMENTATION.md, MeshRankContractIsPacketsOnly). So
neighbors follows status/raw and is rejected on MeshRank slots.
- WITH_MQTT_NEIGHBORS guard (PSRAM + MAX_NEIGHBOURS) gates all new surface.
- MSG_NEIGHBORS message type + enum-drift static_assert.
- Persistent ~10KB PSRAM neighbors buffer allocated/freed via the existing
MQTTRuntimeBufferLifecycle path (allocate/release), not the ctor as flex did.
- Core1->Core0 handoff: requestPublishNeighbors() (mesh) fills the buffer with
a release store; the MQTT task consumes it with an acquire load, publishes
via publishNeighbors() (QoS1, retain = preset->allow_retain, custom=false),
and clears the pending flag. A second snapshot is dropped while one is
in flight.
- setNeighborsSchedule()/NeighborsPhase let the mesh report the timer summary;
formatMqttStatusReply() gains a "nbr: <when>/<last>" field via formatDuration.
Also fix the on-connect status publish (publishStatusToSlot) to honor
preset->allow_retain instead of hardcoding retain=true, matching the periodic
publishStatus() path. Brokers with allow_retain=false (e.g. the waev MeshCore
preset) reject retained publishes, so the on-connect status was being dropped
there. This is flex followup 028a5dca, reconciled to this branch's custom-slot
default of non-retained.
Extends the host topic-router test to cover the neighbors type across all
routes and freezes the new enum value. Bridge itself is on-target only.
Add buildNeighborsMessage to the pure MQTTPayloadBuilder core and a thin
delegating wrapper + NeighborsMessageEntry alias on MQTTMessageBuilder, so
the neighbors topic is built by the same firmware-facing API as status/
packet/raw while the layout logic stays exercisable by native tests.
The document is bounded to the publish buffer: entries arrive ordered most-
to least-useful and the tail is dropped once the next entry would overflow,
so a fixed PSRAM buffer can never be handed truncated JSON.
Uses ArduinoJson v7 idioms (.to<JsonObject>()/.add<JsonObject>()) to stay
warning-clean under -Werror, unlike the deprecated createNested* forms.
Adds three test_mqtt_payload_builder cases: self+entry round-trip, empty
table / null scopes, and bounded-growth tail-drop under a tight buffer.
Append mqtt_neighbors_enabled(u8) + mqtt_neighbors_interval(u32) to the
observer tail of MQTTPrefs. The layout is kept byte-identical to the flex
neighbors build: the enable flag lands in the old struct's zeroed trailing
padding (offset 2857) and the interval begins exactly at the former baseline
(2860), so sizeof grows 2860 -> 2864 (net +4 bytes). offsetof static_asserts
lock the layout so a mismatch fails the build.
The codec now accepts three v1 payload sizes: register 2860 as a
"pre-neighbors" Current payload so an in-lineage upgrade reads its existing
/mqtt_prefs and defaults the neighbors tail (off / 24h). Because 2864 is the
shared Current baseline, a /mqtt_prefs written by either the flex build or this
firmware is interchangeable.
Add the 12/24/336h interval constants, neighbors defaults, and a load-time
interval clamp that keeps persisted values inside the signed-delta millis()
scheduling window. Extend the host codec suite with a pre-neighbors migration
case and neighbors round-trip coverage.
Dev-channel assets are now named <env>-v1.16.0-dev-<hash>.bin so a
downloaded file identifies its channel at a glance; production names are
unchanged (tag unset). The tag sits between version and hash, lowercase
letters only — the flasher-side parsers (gen-slim ASSET_RE, /releases
Worker label+dedupe, flasher.js stale-URL recovery) were made
tag-tolerant first and are already deployed. Filename-end hash
extraction (release pruning) is position-independent and unaffected.
Pushing this intentionally triggers a beta build: that publish is what
applies the new naming. The Worker's dedupe collapses the untagged
9276b6a generation and the new tagged one to the newest per env, so the
flasher never lists both.
The flasher's Version dropdown is feed-driven now (/releases on the
firmware-proxy Worker lists both channels), so the beta channel needs no
config of its own: drop the config-beta.json derivation and the
update-firmware.py --config call (which would exit nonzero once
config.json's observer entries become github defs with no embedded
filenames). The flasher commit is now scoped to beta/v/ and the counter.
The release body gets the dev-channel warning + firmware-notes.html via
gh_retry'd 'gh release edit' (non-fatal), serving as this channel's
dropdown changelog.
MUST land before the flasher config.json conversion, together with the
matching production-workflow change (26db31f6 on observer-firmware).
Workflow-only commit: pushing this triggers no build.
firmware-notes.html's setup-guide link feeds config.json's notes on the
next production build, so the fix propagates with the webconfig merge.
Kept identical to the MQTT_INTERNALS.md wording on observer-firmware to
avoid a merge conflict.
Flip gen-slim-manifests.py to its new --bin-dir mode (flasher repo PR #1):
beta/v manifests now come from out/ — the assets actually uploaded to the
release — instead of the derived config-beta.json, which the /releases
feed migration will retire. STATIC_PATH already exists in this workflow's
env and stays the manifest download host.
Workflow-only commit (.github/** is in paths-ignore): pushing this
triggers no build; the change is exercised by the next real push to
observer-firmware-dev.
agessaman