@alteriom/painlessmesh 1.10.0 → 2.0.0

package/CHANGELOG.md

@@ -7,6 +7,488 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-09-07
+
+painlessMesh 2.0 is a major release. It adds per-message delivery
+confirmation and a unified send path, and it is the first release whose
+gateway, failover, routing and radio behaviour was validated on hardware:
+every entry in the *hardware-validated series* below was found in the serial
+logs of the Alteriom HIL rig — an ESP32, ESP32-C3, ESP32-C5, ESP32-C6,
+ESP32-S3 and ESP8266 in one mesh, with a real router and upstream — and
+confirmed there. The release candidate passed the rig's whole suite (26
+scenarios: mesh formation, delivery and acknowledgement, priorities,
+dedicated and shared gateways, Internet relay, gateway failover, mesh OTA,
+sustained soak) three times in a row, 25 passed and 1 skipped per run; the
+skip is the power-cut scenario, which needs per-port USB power the rig does
+not have.
+
+### Before you upgrade
+
+**Wire protocol.** 2.0 adds to the protocol; it does not change what 1.x
+nodes already send. A 1.x node forwards what it does not understand and
+ignores fields it does not know, so a mixed fleet keeps working, but the
+new behaviour only holds end-to-end once every node on the path runs 2.0:
+
+- `MESSAGE_ACK` (type 630) — the acknowledgement a 2.0 receiver returns for
+  a message sent with a delivery callback. A 1.x receiver never sends one,
+  so the sender's callback reports `delivered = false` for it.
+- `msgId` on `SINGLE` and `BROADCAST`, only when a callback was requested.
+- `prio` on `SINGLE` and `BROADCAST`, only when it differs from normal; a
+  1.x forwarder ignores it and forwards at normal priority.
+- `routerChannel` on `BRIDGE_ELECTION` and `BRIDGE_TAKEOVER`, so peers
+  follow an elected bridge to its channel at once; a peer that misses it
+  still recovers by scanning.
+- `leaving: true` on `BRIDGE_STATUS` when a bridge stops cleanly
+  (`mesh.stop()`), so candidates hold their election within seconds instead
+  of waiting for the bridge's last status to age out.
+
+**Upgrade receivers and forwarders before the senders that will rely on
+delivery callbacks or priorities**, and only read `delivered = false` as a
+loss signal once the whole mesh runs 2.0.
+
+**Defaults that changed.**
+
+- `GATEWAY_HTTP_TIMEOUT_MS` was a hardcoded 30 s; it is now derived from
+  `NODE_TIMEOUT` (2000 ms at the stock 10 s watchdog), the captive-portal
+  probe is bounded by `GATEWAY_CAPTIVE_PORTAL_TIMEOUT_MS` (1000 ms) and cached
+  for 60 s, and the DNS probe by `GATEWAY_DNS_TIMEOUT_MS`. A gateway that
+  needs longer must raise `NODE_TIMEOUT` with it; a `static_assert` says so.
+- A node that finds no mesh re-detects the channel after 2 empty scans
+  (about 30 s) instead of 6 (90 s).
+- The Arduino core's station auto-reconnect is off for the mesh link on
+  every core; the library reconnects by its own scan rules. A bridge's
+  router link keeps the core's auto-reconnect.
+- On ESP8266 the library checks free heap every 30 s and logs an `ERROR`
+  below 12 KB with more than one child attached; see the ESP8266 entry.
+
+**Arduino cores.** The ESP32 Arduino core 2.0.x and 3.x are both supported;
+the ESP32-C5 and ESP32-C6 need 3.x. Core 3.x dispatches Wi-Fi events under a
+lock that forbids reconfiguring the radio from inside a callback; 2.0
+processes scan results from the loop for that reason (see the ESP32 entry).
+
+### Added (hardware-validated series)
+
+- **`LogClass::setSink()`** (#427) — a sketch whose serial port carries a
+  line protocol can take the library's log lines through a callback and
+  frame them itself, instead of having them printed from the Wi-Fi event
+  task into the middle of its own output.
+- **`overCapacity()` and `apChildren()`** (#432) — whether an ESP8266 is
+  below 12 KB free with more than one child attached, and how many children
+  are attached, for sketches that want to warn or shed load.
+- **`setContainsRoot()`** is now what a mesh that contains a bridge should
+  set on every node: it lets a node that is connected to a partition the
+  bridge has left notice it has no root and go looking for the bridge's
+  channel (#427). `initAsBridge()` and the failover path set it.
+
+### Fixed — gateway and failover (hardware-validated series)
+
+- **Gateway takeover left the mesh partitioned on the old radio channel
+  (#424)** — a failover candidate correctly moved its AP+STA radio to the
+  Internet router's channel after election, but peers learned only that a
+  takeover occurred, not which channel to follow. They remained disconnected
+  until the slow all-channel recovery scan, exceeding the failover deadline
+  and leaving `getPrimaryGateway()` at zero. Election and takeover packages
+  now carry the candidate's router channel. Peers validate the announcement,
+  discard stale scan state, move both interfaces after the takeover has
+  propagated, and resume discovery immediately. A missed or older takeover
+  message remains compatible with the scan-based recovery path.
+
+- **A bridge that stops cleanly says so (#435)** — the backup that booted
+  beside a live primary took its status and held it healthy until the
+  status aged out (`bridgeTimeoutMs`, 60 s), then waited for the 30 s
+  monitor tick, and missed the rig's 120 s promotion window whenever the
+  primary left shortly after it came up. `mesh.stop()` on a bridge now
+  broadcasts a status marked `leaving` before closing its connections; every
+  node forgets that bridge at once (`forgetBridge()`), a candidate checks
+  for a bridge as soon as the startup period allows instead of at the next
+  tick, and the "too soon after last role change" hold schedules a retry
+  for when it ends rather than returning silently. A bridge that loses power
+  still announces nothing; that path is as slow as the status timeout.
+
+- **A backup joins the mesh on the router's channel (#435)** — a candidate
+  with router credentials used to pick the strongest mesh AP across a split
+  mesh; it now joins on the router's channel, where a bridge would be. The
+  election's router scan waits on the driver's scanning bit instead of
+  `WiFi.scanComplete()`, whose 20-dwell timeout declared the station's own
+  all-channel scan failed at 2.4 s and let the two scans collide.
+
+- **Home is the channel the bridge's status names (#435)** — a rootless
+  node keeps the channel it was last rooted on as home: it does not leave
+  home for a partition elsewhere, and away from home it goes back as soon as
+  the mesh is visible there, whatever the sizes, since a freshly promoted
+  bridge is one AP on the router's channel. Home is learned from the
+  bridge's status message, not from a cached tree that could still carry a
+  bridge that has gone, and it is forgotten after four re-detections that
+  found the mesh elsewhere and no root here. A topology change on the bridge
+  brings its status broadcast forward (at most once per 5 s), so a node
+  joining anywhere in the tree hears the bridge within seconds.
+
+- **A leaf at home, or a failover candidate, does not leave a rootless
+  partition (#435)** — the rule that sends a leaf looking for the root had
+  fired on the backup itself and dropped its own link in the middle of the
+  election.
+
+- **A failover candidate is the only node that runs the bridge check
+  (#435)** — regular nodes without router credentials no longer schedule
+  elections they cannot join.
+
+- **Shared-gateway local Internet health never became operational (#422)**
+  — the TCP probe used by `InternetHealthChecker` was unimplemented on
+  ESP32/ESP8266 and the health task was never started, so
+  `hasLocalInternet()` stayed false for the life of a node and every request
+  it could have served itself went to a mesh gateway. Shared-gateway
+  initialisation now configures and starts the health monitor, a node with
+  its own healthy uplink executes Internet requests locally, and local
+  gateway acknowledgements complete through the pending-request path.
+
+- **ESP8266 health check timeout was set in seconds, not milliseconds
+  (#426)** — the 5000 ms check became a 5 ms `WiFiClient` timeout, DNS never
+  resolved inside it, and an ESP8266 shared gateway never reported local
+  Internet.
+
+- **A promoted backup's HTTP result could not reach the requester (#423)**
+  — an armed requester-route watchdog is preserved across bounded gateway
+  HTTP work and `GATEWAY_ACK` returns through the request's ingress while
+  the newly promoted route converges. Automatic channel discovery retries
+  when a node first sees no peer, reconfiguring the AP once the channel is
+  known.
+
+- **A bridge whose TCP listener is not listening re-creates it, and a node
+  re-initialised in place keeps the one it has (#430, #435)** — `stop()`
+  deleted the listener and the re-bind hit `ERR_USE` for the 2×MSL
+  `TIME_WAIT` (120 s), so a node that re-initialised (a promotion, a return
+  to regular mode) accepted nobody for two minutes. A client accepted while
+  the mesh semaphore is held is closed rather than left half-open, and
+  `tcpServerInit()` logs the listener's state.
+
+- **Gateway Internet requests partitioned the mesh around the gateway
+  (#318, #332, #416, #417)** — the gateway relays messages from inside the
+  cooperative TaskScheduler using blocking `HTTPClient` calls, so nothing
+  else ran for the duration while wall-clock time kept passing. With a 30 s
+  HTTP timeout against a 10 s `NODE_TIMEOUT`, every peer watchdog that fell
+  due mid-request fired the instant the scheduler resumed, closing
+  connections to nodes that had never gone missing (*"Internet available via
+  gateway: YES / Mesh connections active: NO"*). The blocking budget is now a
+  wall-clock model derived from `NODE_TIMEOUT` — both socket waits of each
+  HTTP call, the captive-portal probe and the DNS probe — enforced by a
+  `static_assert`, and after a blocking request the gateway postpones every
+  running peer watchdog by exactly the measured stall (`Task::adjust()`),
+  so a genuinely dead peer is still reaped on schedule. One residual is
+  documented rather than closed: ESP32's in-request hostname resolution
+  happens inside the core before the socket timeout applies; `SECURITY.md`
+  states it plainly.
+
+- **Captive-portal probe ran on every gateway message** —
+  `detectCaptivePortal()` made an uncached HTTP round trip before *each*
+  mesh→Internet send. It is now cached for `GATEWAY_CONNECTIVITY_CACHE_MS`
+  (60 s) and bounded by `GATEWAY_CAPTIVE_PORTAL_TIMEOUT_MS`.
+
+### Fixed — channel following and the station scan (hardware-validated series)
+
+- **Stranded followers find the bridge's channel (#427, #428)** — when a
+  bridge moved the mesh to its router's channel, the nodes behind its direct
+  children stayed connected to each other on the old channel and were gated
+  out of re-detection for good. Re-detection now also runs for a connected
+  node that should have a root and has none; the scan collects every channel
+  the mesh is on and prefers one other than the node's own; the move closes
+  the station link so an orphan leaves its old partition; an unexpected
+  station loss scans at once instead of sleeping out a delay of up to two
+  minutes; a scan that could not start is retried in half an interval
+  instead of five minutes; an association that never gets an address is
+  dropped after half an interval; a connected node that keeps finding the
+  mesh only on its own channel backs off instead of scanning every 15 s;
+  and a stale scan-done event no longer consumes the scan still in flight
+  (#428 restored channel auto-detection after the first fix broke it).
+
+- **A connected node changes channel only for a strictly bigger partition;
+  a disconnected one follows the mesh wherever it is (#434, #435)** — a
+  node in a partition had followed any other channel it saw the mesh on,
+  including a lone node still in gateway mode during a teardown. Every
+  follow now waits for a second sighting one scan later (a teardown
+  straggler is seen once, a bridge twice); a rootless node follows a
+  partition that persists whatever its size; a leaf leaves a rootless
+  partition only if the mesh ever had a root; a re-init in place resets the
+  scan state.
+
+- **Re-detection with stations under the AP is done a channel at a time
+  (#435)** — an all-channel scan takes the AP off its channel for two to
+  three seconds, and the ESP8266 station under it did not survive that. A
+  node with stations hunts one channel per scan (300 ms dwell, 1.5 s at home
+  between slices) and decides on the own-channel scan after the last slice;
+  a node with nothing under its AP keeps the fast all-channel scan.
+
+- **Link loss and re-detection are judged by what was lost (#435)** — an
+  uplink lost in a rooted mesh re-detects the channel at once (the AP most
+  likely left for the bridge's channel); an uplink lost *at home* rescans
+  this channel, where the bridge's AP is, instead of hunting all thirteen
+  (the hunt cost a sender its request); the station drop a node's own
+  channel move causes, and an association attempt that never got an
+  address, are not losses (judged as losses they re-detected the channel
+  just left, found the remnant bigger, and moved back). The half-open guard
+  judges only an attempt still in progress; it had dropped a fresh
+  association by the clock of an attempt made 109 s earlier.
+
+- **The core's station auto-reconnect is off on every core (#435)** — on
+  Arduino core 2.x as on 3.x. The core's own reconnect raced the library's
+  scan and re-attached nodes to APs that were leaving; the bridge's router
+  link is the exception and keeps it.
+
+- **ESP32 Arduino core 3.x: the scan result is read from the loop, not on
+  the network-event task (#435)** — core 3.x dispatches Wi-Fi callbacks
+  under the lock it also takes in `removeEvent()`, and the library ran
+  `scanComplete()` inside the scan-done callback, where a channel follow
+  restarts the AP and waits for events only the blocked task can deliver.
+  Every ESP32-C5 and ESP32-C6 that followed the bridge's channel had gone
+  silent for the rest of its run — still answering the sketch, never
+  scanning again — and `stop()` then blocked on the same lock. The callback
+  now only yields the station task to `scanComplete()`.
+
+### Fixed — routing (hardware-validated series)
+
+- **A connection that has already dropped no longer refuses a live one, and
+  is no longer a route (#429)** — a closed connection stays in the layout
+  until the next cleanup, and `handleNodeSync()` had turned away a working
+  direct connection on its authority, moments before erasing it. Only live
+  connections count as routes now, for the duplicate check and for every
+  send; `write()` on a closed connection returns `false` instead of queueing
+  into the void (27 of 33 unacknowledged deliveries correlated on the rig
+  had never arrived). A partitioned leaf that sees nodes it has no route to
+  on two consecutive scans reconnects toward them; interior nodes do not
+  jump, since dropping an interior link fragments the subtree it carries.
+
+- **A node that comes back is not refused for where it used to be (#433)**
+  — after any restart, the returning node was associated by each AP in turn
+  and dropped a second later, for 30–100 s, because a neighbour's tree
+  still listed its old place. The loop check is now the tree the arriving
+  node presents; a stale direct link is closed at once and a stale place in
+  a neighbour's tree is forgotten (`layout::forget()`).
+
+- **A node is in one place (#435)** — when a neighbour's sync presents the
+  nodes below it, every other neighbour's cached tree forgets them
+  (`layout::forgetAll()`); every board on the rig had carried one node twice
+  and routed by the older copy. A restated sync is not news: a neighbour's
+  sync is adopted only when the tree it presents differs from its last one
+  (a fingerprint per neighbour, covering the time-authority flag), which
+  ended a sync storm of one exchange every 30–80 ms between two claimants;
+  and a neighbour that stops presenting a node lets the others' restatements
+  back in, so a pruned node can return. A stale mention of this node in a
+  presented tree is a loop only if there is another live route to the
+  presenter.
+
+### Fixed — ESP8266 (hardware-validated series)
+
+- **The ESP8266 is specified for small meshes, or as a leaf in larger ones
+  (#432)** — measured as an interior node of a seven-node mesh it runs at
+  10–13 KB free, and below about 8 KB a single 8 KB package or one OTA part
+  fails to allocate; every ESP32 family holds within a few percent of its
+  starting heap in the same mesh. Configure a leaf with
+  `init(..., maxconn = 0)`. The library checks every 30 s on ESP8266 and logs
+  an `ERROR` below 12 KB free with more than one child attached.
+
+### Security
+
+- **Corrected a false claim about gateway TLS.** The source comment on
+  `initGatewayInternetHandler()` asserted that "ESP32 uses default SSL settings
+  with certificate validation". Nothing in `src/` ever backed that: there is no
+  `setCACert`, no certificate bundle and no fingerprint API anywhere in the
+  library, and the ESP32 path calls bare `http.begin(url)`. Gateway HTTPS is
+  transport encryption **without** peer authentication on both targets.
+  No behaviour changed — only the claim.
+
+- **Added a threat model to `SECURITY.md`** covering mesh membership
+  (one shared password, no per-node identity or revocation), OTA (MD5 is an
+  integrity check against an unauthenticated announcer, not a signature),
+  gateway TLS, and the absence of rate limiting — along with which of these are
+  known-and-documented rather than reportable vulnerabilities.
+
+### Packaging and examples
+
+- **`mqttBridge` example fails to compile in Arduino IDE (#398)** — the
+  `PubSubClient` library was missing from `library.properties`'s `depends`
+  field, so installing this library through the Arduino IDE Library Manager
+  never pulled in `PubSubClient`. It is now listed, the example says so, and
+  `examples/mqttBridge/platformio.ini` pins the same `knolleary/PubSubClient`
+  package used by `examples/bridge`.
+- **`examples/alteriom/mppt_example` never compiled** — its sketch was named
+  differently from its directory, so the CI example loop skipped it, and it
+  included two headers from the parent example directory by bare name, which
+  the Arduino build cannot resolve. The sketch is now `mppt_example.ino`,
+  carries the two headers it needs, and is compiled for esp32 and esp8266 on
+  every PR like the other twenty.
+- `keywords.txt` now lists the bridge, gateway, failover, queue and capacity
+  API so the Arduino IDE highlights it.
+
+### Added (post-review series)
+
+- **Unified send path: `SendOptions` (#384)** — `sendSingle()` and
+  `sendBroadcast()` gained overloads taking a
+  `painlessmesh::SendOptions{priority, ackCallback, ackTimeoutMs}` struct,
+  so a message can be both prioritized and delivery-confirmed in one call —
+  something the separate priority and ack overload families could not
+  express. All pre-existing overloads still compile and now delegate to the
+  unified path.
+- **Priority is carried across hops (#384)** — the priority level is now
+  serialized on the wire (as `"prio"`, only when it deviates from NORMAL, so
+  default sends carry zero overhead) and every forwarding node re-enqueues
+  the package at the sender's priority. Previously priority only affected
+  the first hop's transmit queue and was silently dropped on forwarding.
+  Pre-2.0 nodes ignore the field and forward at normal priority. Named
+  constants `PRIORITY_CRITICAL/HIGH/NORMAL/LOW` are exposed in
+  `painlessmesh::protocol`.
+
+### Fixed (post-review series)
+
+- **Gateway blocking budget is now a wall-clock model, DNS included (#416)**
+  — `gatewayBlockingBudgetMs()` counts **both** socket waits of each HTTP
+  call (request/header read plus body read — `HTTPClient::setTimeout()`
+  bounds one wait, not a whole call) for the destination request *and* the
+  captive-portal probe, plus a new `GATEWAY_DNS_TIMEOUT_MS` term for the
+  DNS reachability probe. On ESP8266 the probe now uses the `hostByName()`
+  timeout overload; on ESP32, whose core has no resolver timeout, the
+  standalone probe is skipped and the (timed) captive-portal probe
+  establishes reachability instead. **Defaults changed to keep the honest
+  budget inside `NODE_TIMEOUT`:** at the stock 10 s watchdog,
+  `GATEWAY_HTTP_TIMEOUT_MS` is now 2000 ms (was 5000) and
+  `GATEWAY_CAPTIVE_PORTAL_TIMEOUT_MS` 1000 ms (was 2000); raise them
+  together with `NODE_TIMEOUT` if your endpoint needs longer — the
+  `static_assert` enforces the pairing. One residual is documented rather
+  than closed: ESP32's in-request hostname resolution happens inside the
+  core before the socket timeout applies and cannot be bounded there;
+  SECURITY.md states it plainly.
+- **Gateway watchdog compensation now equals the measured stall (#417)** —
+  `gateway::refreshPeerWatchdogs()` takes the measured blocking duration and
+  postpones each running peer watchdog by exactly that long via
+  `Task::adjust()`, instead of restarting every watchdog from zero on every
+  exit path. The full reset was strictly more generous than the time the
+  scheduler actually lost, and the excess starved the reaper: a genuinely
+  dead peer stayed connected indefinitely as long as any *live* peer
+  generated gateway traffic more often than `NODE_TIMEOUT`. Paths that never
+  blocked now compensate nothing. Regression-tested in
+  `catch_gateway_watchdog.cpp`, including the dead-peer-under-continuous-
+  traffic case.
+- **Outbound send buffer is bounded (#388)** — each connection's
+  `SentBuffer` now holds at most `PAINLESSMESH_MAX_SENT_BUFFER_MESSAGES`
+  (default 64, build-time overridable) messages. Previously a peer that
+  stopped draining (stalled TCP connection) grew the outbound list until
+  allocation failed on the ESP8266 heap. At the cap, an incoming message
+  evicts the newest message of a strictly lower priority class (mirroring
+  `MessageQueue::makeSpace()`); if nothing lower-priority is queued, the
+  push is rejected and the send reports failure. Drops are counted in
+  `getStats().dropped`; a partially-transmitted message is never evicted.
+
+### Removed (post-review series)
+
+- **`MessageTracker` dead code (#386)** — `message_tracker.hpp` defined a
+  full dedup/ack-tracking class that was `#include`d but never instantiated
+  or called anywhere in the tree, costing compile time and flash in every
+  build. Removed together with its unit test. Broadcast flood dedup, the
+  integration it was meant for, remains future work with its own design
+  pass.
+
+- **Routing no longer copies the connection list per packet (#387)** — every
+  `router::` send/broadcast/forward took the mesh layout **by value**,
+  copying a `std::list` of `shared_ptr`s (one heap allocation per
+  connection) on every packet sent, broadcast, or forwarded. All routing
+  functions now take the layout by const reference — measurable allocation
+  and fragmentation relief on ESP8266.
+
+Feature release adding per-message delivery confirmation (issue #379). The
+release is a major version bump because it introduces a new wire-protocol
+message type: pre-2.0 nodes forward acknowledgment packets but never send
+them, so delivery confirmation only works reliably once every participating
+node runs 2.0.0. All existing sketches compile and behave unchanged.
+
+### Mixed-fleet rollout order
+
+During a rolling upgrade, a v1.x node never replies with a `MESSAGE_ACK`, so
+a v2.0 sender's delivery callback fires `delivered = false` against every
+un-upgraded peer — indistinguishable from real packet loss. This is not a
+bug in the ACK feature; it is the expected behavior of a mixed fleet.
+**Upgrade leaf/receiver nodes before the senders that will use the ack
+callbacks**, and only rely on `delivered = false` as a loss signal once the
+whole mesh runs 2.0.0. The same applies to cross-hop priority: pre-2.0
+forwarders ignore the `prio` field and forward at normal priority, so
+priority guarantees only hold end-to-end on an upgraded path.
+
+### Added
+
+- **Per-message delivery confirmation and acknowledgment API (#379)** —
+  `sendSingle()` and `sendBroadcast()` gained overloads that accept a
+  `painlessmesh::ack::deliveryCallback_t` callback and an acknowledgment
+  timeout (default 5000 ms). When a callback is provided the outgoing
+  message is tagged with a unique `msgId`, the receiving node automatically
+  replies with a `MessageAckPackage` (new protocol type 630, routed as a
+  SINGLE package so it traverses multiple hops), and the callback fires
+  with `delivered = true` plus the measured round-trip latency — or
+  `delivered = false` when the timeout elapses. Broadcast tracking
+  snapshots the mesh layout at send time and fires the callback once per
+  expected node.
+- `checkAcks()` — non-blocking poll that processes acknowledgment timeouts
+  and returns the number of messages still pending (timeouts are also
+  processed automatically inside `mesh.update()`).
+- `pendingAcks()` — number of messages still awaiting acknowledgment.
+- New header `painlessmesh/ack.hpp` with the platform-independent
+  `AckTracker` (unit-tested, uint32 wraparound safe) and
+  `MessageAckPackage`.
+- Arduino examples `reliableSensorLogging` (buffered retries until the
+  gateway confirms) and `commandControl` (per-node broadcast confirmation).
+- Unit tests (`catch_message_ack.cpp`) covering serialization, ack
+  matching, timeout, duplicate/unknown acks, broadcast fan-in and clock
+  wraparound, plus an end-to-end multi-node scenario in the TCP
+  integration suite.
+
+### Changed
+
+- `protocol::Single` / `protocol::Broadcast` carry an optional `msgId`
+  field. It is only serialized when delivery confirmation was requested,
+  so plain sends have zero added wire overhead.
+- `protocol::Variant` gained lightweight `from()` and `msgId()` field
+  peeks; the receive-path ACK handlers use them instead of materializing
+  a full package (no per-message payload copy on the hot path).
+
+### Hardening (post-review, pre-release)
+
+A full adversarial review of the ACK feature before release led to:
+
+- `AckTracker::expire()` now collects and erases expired entries before
+  firing any callback — a delivery callback that reentered the tracker
+  (retry `track()`, `checkAcks()`, or `clear()` via `mesh.stop()`) could
+  previously invalidate the live iterator (use-after-free).
+- `mesh.stop()` reached from inside a scheduler callback no longer
+  deletes the internally-owned `Scheduler` out from under its own
+  `execute()` (same bug class as #373); the ack poll task is also
+  disabled before its handle is cleared so a reentrant stop cannot
+  orphan it.
+- Message ids are seeded from `validation::SecureRandom` at `init()` —
+  previously the counter restarted at 1 every boot, so a delayed
+  pre-reboot ACK could confirm a fresh message (false
+  `delivered = true`).
+- Pending acknowledgments are capped at `PAINLESSMESH_MAX_PENDING_ACKS`
+  (default 32, build-time overridable); sends beyond the cap are
+  rejected instead of growing the tracker unbounded on the ESP8266 heap.
+- Broadcast ACK replies are staggered by nodeId within a 50 ms window so
+  an N-node broadcast does not converge N simultaneous ACK unicasts on
+  the sender.
+- The ack timeout poll interval is build-time configurable
+  (`PAINLESSMESH_ACK_CHECK_INTERVAL_MS`, default 100 ms) and its
+  battery/light-sleep implications are documented.
+
+### CI / packaging fixes
+
+- Fixed the Arduino example-compile loop in CI (`ci.yml`): a quoted glob
+  meant **no example sketch was ever compiled** — the job reported green
+  while compiling nothing. All examples now build for esp32 and esp8266
+  on every PR.
+- Added the two new examples to `library.json`'s `examples` array so
+  they appear in the PlatformIO registry listing.
+- `doxygen/Doxyfile` `PROJECT_NUMBER` bumped from the stale v1.6.1 to
+  v2.0.0; stale 1.6.1 install snippets in the wiki docs updated.
+- Wiki sync now publishes `docsify-site/` documentation (it previously
+  copied from a `docs/` directory that does not exist) and triggers on
+  docsify changes.
+- Removed dead links from the docsify sidebar.
+
+
 ## [1.10.0] - 2026-08-12
 
 Feature release making the TCP connect-retry envelope tunable per mesh instance
@@ -82,6 +564,7 @@ macros keep their historical values for source compatibility.
   convention used across every other example (otaSender, namedMesh,
   alteriom_*).
 
+
 ## [1.9.21] - 2026-08-04
 
 Crash-fix release resolving a family of use-after-free bugs in the task and

package/CONTRIBUTING.md

@@ -1,79 +1,82 @@
 # Contributing
 
-We try to follow the [git flow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) development model. Which means that we have a `develop` branch and `main` branch. All development is done under feature branches, which are (when finished) merged into the development branch. When a new version is released we merge the `develop` branch into the `main` branch.
+## Branches
 
-## Git flow
+- `main` holds released code. A push to `main` that carries a version bump,
+  or whose head commit message starts with `release:`, is what tags and
+  publishes a release (see [RELEASE_GUIDE.md](RELEASE_GUIDE.md)).
+- `Feat/next-release` is the integration branch for the next version. Open
+  pull requests against it.
+- Work happens on short-lived feature branches (`fix/…`, `feat/…`, `docs/…`)
+  cut from `Feat/next-release`.
 
-If you would like to use [git flow tools](http://danielkummer.github.io/git-flow-cheatsheet/) you are more than welcome to. We use it and it's pretty nifty. If you see a `feature\` prefix on a comment then that is git flow automating branch creation. It does need more typing than just plain git so I suggest creating shell aliases for the commands.
+Maintainers merge quickly, often as a squash. Push every commit you describe
+before you describe it, and cut follow-up work from the merged base rather
+than from a stale branch.
 
-## Submit a pull request:
+## Submit a pull request
 
-* If your push triggered a 'you just pushed...' message from GitHub then click on the button provided by that pop up to create a pull request.
-* If not, then create a pull request and point it to your branch.
-* Make sure that you're attempting to merge into `develop` and not `main`.
-* Get your code reviewed by another contributor. If there are no contributors who possess the same set of skills then get them to review it anyway but explain what the code does beforehand and why. Use it as an opportunity for discussion around the feature set, to transfer knowledge, and to possibly [rubber duck](https://en.wikipedia.org/wiki/Rubber_duck_debugging) your code.
-* Once the code is reviewed then have your reviewer merge your code.
+- Point the pull request at `Feat/next-release`, not `main`.
+- Say what was wrong, how you know (a log, a test, a measurement), and what
+  the change does about it. For anything that touches the radio, routing,
+  the gateway or OTA, the evidence is a serial log or a run on the
+  hardware-in-the-loop rig; a unit test alone is not enough there, because
+  the unit tests mock the radio.
+- Get your code reviewed by another contributor, and let the reviewer merge.
 
-NOTE: Tests *must* pass in order for the code to be merged.
+Tests must pass for the code to be merged. Add a changelog entry under
+`## [Unreleased]` in [CHANGELOG.md](CHANGELOG.md) for any user-visible change.
 
-NOTE: Always do a `git pull` on `develop` before you start working to capture the latest changes.
+## Testing requirements
 
-## Testing Requirements
+### Running the desktop tests
 
-### Running Tests
-
-Before submitting a pull request, ensure all tests pass:
+Before submitting a pull request, build and run the Catch2 and Boost suites:
 
 ```bash
-# Build and run unit/integration tests
+git submodule update --init
 cmake -G Ninja .
 ninja
 run-parts --regex catch_ bin/
-
-# Run simulator tests (for examples)
-cd test/simulator
-mkdir build && cd build
-cmake -G Ninja .. && ninja
-bin/painlessmesh-simulator --config ../../../examples/basic/test/simulator/scenarios/basic_mesh_test.yaml
 ```
 
-### Adding Tests for New Features
-
-When adding new features or examples:
-
-1. **Unit Tests**: Add tests in `test/catch/` for new components
-2. **Integration Tests**: Add to `test/boost/tcp_integration.cpp` for core functionality
-3. **Simulator Tests**: Create test scenarios in `examples/your_example/test/simulator/` for new examples
-4. **Documentation**: Update relevant test documentation
-
-### Example Validation with Simulator
+The same suites run in CI under gcc, clang and AddressSanitizer, and CI also
+compiles every example for esp32 and esp8266 with `arduino-cli`, builds the
+PlatformIO projects under `test/ci/`, and checks formatting and library
+metadata.
 
-All example sketches should have simulator tests that validate behavior with multiple virtual nodes:
+### Simulator and hardware tests
 
-1. Create firmware adapter in `examples/your_example/test/simulator/firmware/`
-2. Create YAML test scenarios in `examples/your_example/test/simulator/scenarios/`
-3. Document test setup in `examples/your_example/test/simulator/README.md`
+Multi-node behaviour is tested with the external
+[painlessMesh-simulator](https://github.com/Alteriom/painlessMesh-simulator);
+scenarios for an example live under `examples/<example>/test/simulator/`
+(see `examples/basic/test/simulator/`). Radio, routing, gateway, failover
+and OTA behaviour is validated on the Alteriom hardware-in-the-loop farm; a
+maintainer runs it on a pull request by adding the `run-hil` label, and the
+release gate is three consecutive clean runs of the whole suite.
 
-See [Simulator Testing Guide](docs/SIMULATOR_TESTING.md) for complete instructions.
+### Adding tests for new features
 
-This ensures examples:
-- Work as documented with multiple nodes
-- Handle edge cases properly
-- Don't regress with library changes
-- Serve as validated references for users
+1. **Unit tests**: add to `test/catch/` for new components.
+2. **Integration tests**: add to `test/boost/tcp_integration.cpp` for core
+   behaviour that spans connections.
+3. **Simulator scenarios**: add YAML scenarios under
+   `examples/<example>/test/simulator/` for new examples.
+4. **Documentation**: keep `USER_GUIDE.md`, `README.md` and the example's
+   own README in step with the change.
 
 ## Versioning
 
-This project will try its best to adhere to [semver](http://semver.org/) i.e, a codified guide to versioning software. When a new feature is developed or a bug is fixed the version will need to be bumped to signify the change. 
-
-The semver string is built like this:
-
-Major.Minor.Patch
-
-A major version bump means that a massive change took place and that application will probably have to be redeployed because a *backwards incompatible* version was released. Example: A library => model relationship change which requires previous configuration options to become invalid.
-
-A minor version is a *backwards compatible* addition or change to the core software. Most development activity will be this type of version bump. Example: A new feature or model.
+This project follows [semver](https://semver.org/). Version 2.0 patch
+releases must remain wire-compatible with the 2.0 protocol; anything that
+changes what a node puts on the wire, or what an existing sketch has to do to
+keep working, is a major version.
 
-A patch version is a *backwards compatible* bug fix or application configuration change.
+- **Major**: a backwards-incompatible change (a new or changed protocol
+  message, a removed API).
+- **Minor**: a backwards-compatible addition.
+- **Patch**: a backwards-compatible fix.
 
-Documentation doesn't require a version bump.
+Documentation does not require a version bump. The three version files
+(`library.properties`, `library.json`, `package.json`) are changed together
+with `./scripts/bump-version.sh`.