@alteriom/painlessmesh 1.10.0 → 2.0.0

package/src/painlessmesh/configuration.hpp

@@ -23,8 +23,60 @@
 // Enable (arduino) wifi support
 #define PAINLESSMESH_ENABLE_ARDUINO_WIFI
 
-// Enable OTA support
+// Enable OTA support. Define PAINLESSMESH_DISABLE_OTA to compile the OTA
+// plugin out entirely (SECURITY.md, "OTA: integrity checked, not
+// authenticated").
+//
+// It must be a *build flag* -- `-DPAINLESSMESH_DISABLE_OTA`, or platformio.ini
+// `build_flags` -- so that every translation unit sees it. A `#define` above
+// the sketch's `#include <painlessMesh.h>` is not a narrower version of the
+// same thing, it is a bug: src/wifi.cpp and src/painlessMeshSTA.cpp compile
+// separately without it and would reach painlessmesh::Mesh with the OTA
+// members present, while the sketch sees the same class without them. That is
+// an ODR violation, and the standard requires no diagnostic for it.
+//
+// `#undef PAINLESSMESH_ENABLE_OTA` does not work either: it runs before
+// painlessMesh.h includes this header, which then defines the macro straight
+// back.
+#ifdef PAINLESSMESH_DISABLE_OTA
+// Opting out is not the same as declining to define. If the build already
+// supplies PAINLESSMESH_ENABLE_OTA -- redundantly, since it is the default --
+// then merely skipping the definition below leaves that one standing and every
+// #ifdef downstream still compiles OTA in, on a build that looks like it opted
+// out. That is a security control failing open and saying nothing, which is
+// the failure mode this opt-out exists to remove. Refuse the contradiction
+// rather than guessing which flag was meant.
+#ifdef PAINLESSMESH_ENABLE_OTA
+#error \
+    "PAINLESSMESH_DISABLE_OTA and PAINLESSMESH_ENABLE_OTA are both defined. Remove -DPAINLESSMESH_ENABLE_OTA from your build flags: OTA is on by default, so the disable flag alone is what you want."
+#endif
+#else
 #define PAINLESSMESH_ENABLE_OTA
+#endif
+
+// NOTE: there is deliberately no PAINLESSMESH_OTA_REQUIRE_SIGNATURE flag.
+// OTA acceptance (painlessmesh/ota.hpp, OTA_OP_CODES::DATA) authenticates
+// nothing -- it matches the sender-supplied md5/role/hardware tuple -- so a
+// flag that did not gate that path would read as a security control while
+// enforcing nothing. Defining it fails the build rather than passing
+// silently, so no fleet can ship believing its OTA images are verified.
+// Compiling OTA out is the only mitigation the library offers today.
+#ifdef PAINLESSMESH_OTA_REQUIRE_SIGNATURE
+#error \
+    "PAINLESSMESH_OTA_REQUIRE_SIGNATURE is not implemented: painlessMesh does not verify OTA image signatures. Use -DPAINLESSMESH_DISABLE_OTA to compile OTA out, or drop this define."
+#endif
+
+// NOTE: there is likewise no PAINLESSMESH_DISABLE_ACK flag. The one this
+// branch briefly carried gated only the (since-deleted, #386) dead
+// painlessmesh/message_tracker.hpp include, so the flag reclaimed nothing
+// and its advertised RAM saving was not real.
+//
+// That is NOT a claim that acknowledgment is free. The delivery-ack subsystem
+// (painlessmesh/ack.hpp) is a different thing and is genuinely allocated:
+// Mesh holds an ack::AckTracker member whose std::map grows with each
+// in-flight tracked message. Nothing compiles that out today. If a
+// memory-constrained target needs it gone, that is a design question for the
+// ack feature (#379), not a flag to reinstate here.
 
 // NOTE: `MIN_FREE_MEMORY` and `MAX_MESSAGE_QUEUE` are kept as deprecated
 // no-op compatibility macros. The library does not read either macro:
@@ -42,9 +94,25 @@
 #define MAX_MESSAGE_QUEUE 50
 #endif
 
+// The mesh watchdog. Overridable, because the documented remedy for an endpoint
+// that needs longer than the derived gateway budget is to raise this and
+// GATEWAY_HTTP_TIMEOUT_MS together (CHANGELOG, SECURITY.md). Unguarded, a
+// -DNODE_TIMEOUT on the build line was either silently overwritten here or a
+// macro-redefinition error under -Werror, so that remedy could not be followed
+// -- the same shape as the `#undef PAINLESSMESH_ENABLE_OTA` advice this
+// release also had to fix. Pinned by test/catch/catch_node_timeout_override.cpp.
+#ifndef NODE_TIMEOUT
 #define NODE_TIMEOUT 10 * TASK_SECOND
+#endif
 #define SCAN_INTERVAL 30 * TASK_SECOND  // AP scan period in ms
 
+// A gateway relays to the Internet with blocking HTTPClient calls, from inside
+// the cooperative scheduler. Those calls must finish well inside NODE_TIMEOUT
+// or the gateway's peers reap connections to a node that is perfectly healthy
+// (issues #318, #332). The socket-timeout budget that enforces this is derived
+// from NODE_TIMEOUT in painlessmesh/gateway.hpp -- see GATEWAY_HTTP_TIMEOUT_MS
+// there. Raising NODE_TIMEOUT raises that budget with it.
+
 #ifdef ESP32
 #include <AsyncTCP.h>
 #include <WiFi.h>

package/src/painlessmesh/connection.hpp

@@ -26,7 +26,7 @@ static const uint32_t TCP_CLIENT_CLEANUP_DELAY_MS = 1000; // 1000ms delay before
 // When multiple AsyncClients are deleted in rapid succession, the AsyncTCP library's
 // internal cleanup routines can interfere with each other, causing heap corruption
 // This spacing ensures each deletion completes before the next one begins
-// Increased from 250ms to 500ms (v1.9.14) then to 1000ms (v1.9.15) to support ESP32-C6
+// ESP32-C6 needs 1000ms spacing to avoid overlapping AsyncTCP cleanup.
 // ESP32-C6 uses RISC-V architecture with AsyncTCP v3.3.0+ which requires significantly
 // more time for internal cleanup operations compared to ESP32/ESP8266
 static const uint32_t TCP_CLIENT_DELETION_SPACING_MS = 1000; // 1000ms spacing between deletions
@@ -275,19 +275,26 @@ class BufferedConnection
   }
 
   bool write(const TSTRING &data, bool priority = false) {
-    sentBuffer.push(data, priority);
+    // A closed connection has no one to drain its buffer: queueing here and
+    // reporting success is a silent loss, and the sender then waits out an
+    // acknowledgement that can never come. Say no, so the caller can.
+    if (!mConnected) return false;
+    // false = outbound buffer at PAINLESSMESH_MAX_SENT_BUFFER_MESSAGES and
+    // nothing lower-priority to evict (issue #388)
+    if (!sentBuffer.push(data, priority)) return false;
     sentBufferTask.forceNextIteration();
     return true;
   }
-  
+
   /**
    * Write data with explicit priority level (0-3)
-   * 
+   *
    * \param data The data to send
    * \param priorityLevel Priority level: 0=CRITICAL, 1=HIGH, 2=NORMAL, 3=LOW
    */
   bool writeWithPriority(const TSTRING &data, uint8_t priorityLevel) {
-    sentBuffer.pushWithPriority(data, priorityLevel);
+    if (!mConnected) return false;
+    if (!sentBuffer.pushWithPriority(data, priorityLevel)) return false;
     sentBufferTask.forceNextIteration();
     return true;
   }

package/src/painlessmesh/gateway.hpp

@@ -33,16 +33,85 @@
 #include "Arduino.h"
 #include "painlessmesh/configuration.hpp"
 #include "painlessmesh/logger.hpp"
-#include "painlessmesh/message_tracker.hpp"
+
+#if defined(ESP32) || defined(ESP8266)
+#include <WiFiClient.h>
+#endif
 #include "painlessmesh/plugin.hpp"
 #include "painlessmesh/protocol.hpp"
 
 #include <functional>
 #include <map>
+#include <vector>
 
 namespace painlessmesh {
 namespace gateway {
 
+/** Return whether a channel can be announced for a 2.4 GHz mesh takeover. */
+constexpr bool isValidMeshChannel(uint8_t channel) {
+  return channel >= 1 && channel <= 13;
+}
+
+/** Decide whether a peer must follow an elected bridge to another channel. */
+constexpr bool shouldFollowBridgeChannel(uint32_t localNodeId,
+                                         uint32_t electedBridgeId,
+                                         uint8_t currentChannel,
+                                         uint8_t announcedChannel) {
+  return electedBridgeId != localNodeId &&
+         isValidMeshChannel(announcedChannel) &&
+         announcedChannel != currentChannel;
+}
+
+/**
+ * @brief One occurrence of the mesh SSID seen by an all-channel scan.
+ */
+struct MeshChannelCandidate {
+  uint8_t channel;
+  int32_t rssi;
+};
+
+/**
+ * @brief Where a node that has lost the mesh should go.
+ *
+ * Channel re-detection runs only after a node's own partition has produced
+ * nothing new for a while, so the mesh it can still see on its *current*
+ * channel is the partition it is stranded in. When the SSID is also visible
+ * on another channel, that is the rest of the network — a bridge that moved
+ * to its router's channel, most often — and the node should go there.
+ *
+ * Returning the first match, as this used to, made the outcome depend on
+ * scan order: a stranded node that happened to see its own partition first
+ * concluded nothing had changed and stayed stranded.
+ *
+ * A node that knows the router has a better signal than strength: a bridge's
+ * AP is on its router's channel, so a mesh with a bridge lives there. A
+ * failover backup that booted while the mesh was split across two channels
+ * saw one AP on each, two dB apart, and joined the one without the bridge;
+ * it had a partition of two to itself for the hundred seconds it took the
+ * re-detection rules to move it, and the election ran out of time.
+ *
+ * @param candidates  Every channel the mesh SSID was seen on, with RSSI.
+ * @param avoidChannel The node's current mesh channel; 0 = no preference.
+ * @param routerChannel The channel the router was seen on; 0 = unknown.
+ * @return The candidate on routerChannel if there is one; else the strongest
+ *         on a channel other than avoidChannel; failing that the strongest
+ *         on avoidChannel; 0 if there are none.
+ */
+inline uint8_t pickMeshChannel(const std::vector<MeshChannelCandidate>& candidates,
+                               uint8_t avoidChannel, uint8_t routerChannel = 0) {
+  const MeshChannelCandidate* elsewhere = nullptr;
+  const MeshChannelCandidate* here = nullptr;
+  for (const auto& c : candidates) {
+    if (!isValidMeshChannel(c.channel)) continue;
+    if (c.channel == routerChannel) return c.channel;
+    const MeshChannelCandidate*& slot = (c.channel == avoidChannel) ? here : elsewhere;
+    if (slot == nullptr || c.rssi > slot->rssi) slot = &c;
+  }
+  if (elsewhere != nullptr) return elsewhere->channel;
+  if (here != nullptr) return here->channel;
+  return 0;
+}
+
 /**
  * @brief Validation result structure for SharedGatewayConfig
  *
@@ -597,11 +666,31 @@ class InternetHealthChecker {
     }
     status_.lastError = "Mock: No Internet in test environment";
     return false;
+#elif defined(ESP32) || defined(ESP8266)
+    WiFiClient client;
+    uint32_t started = millis();
+#ifdef ESP32
+    bool connected = client.connect(checkHost_.c_str(), checkPort_, checkTimeout_);
+#else
+    // ESP8266's WiFiClient lacks ESP32's per-connect timeout overload, so the
+    // timeout is set on the client instead. It is milliseconds, not seconds:
+    // WiFiClient inherits Stream::setTimeout ("maximum milliseconds to wait")
+    // and connect() hands _timeout straight to WiFi.hostByName(), whose
+    // parameter is named timeout_ms. Dividing by 1000 here gave DNS five
+    // milliseconds to resolve, so the check failed every time and an ESP8266
+    // shared gateway never reported local Internet.
+    client.setTimeout(checkTimeout_);
+    bool connected = client.connect(checkHost_.c_str(), checkPort_);
+#endif
+    status_.lastLatencyMs = millis() - started;
+    if (!connected) {
+      status_.lastError = "TCP connectivity check failed";
+      return false;
+    }
+    client.stop();
+    return true;
 #else
-    // Arduino/ESP environment - actual TCP check
-    // Note: WiFiClient usage is handled in the arduino-specific code
-    // This base implementation returns false; override in wifi.hpp
-    status_.lastError = "Not implemented in base class";
+    status_.lastError = "Internet health checks are unsupported on this platform";
     return false;
 #endif
   }
@@ -1053,6 +1142,182 @@ class GatewayAckPackage : public plugin::SinglePackage {
 
 };
 
+// ===========================================================================
+// Scheduler-stall protection for blocking gateway requests
+// ===========================================================================
+
+// The socket timeouts below are derived from NODE_TIMEOUT rather than written
+// as absolute numbers, so a gateway request cannot outlast the mesh watchdog in
+// *any* build. That is not hypothetical tidiness: the host test environment
+// overrides NODE_TIMEOUT to 5s (test/catch/Arduino.h shadows configuration.hpp
+// wholesale via its include guard), so hardcoded defaults sized for the 10s
+// production watchdog would blow the assertion below there.
+//
+// They live in this header, not in configuration.hpp, for the same reason --
+// gateway.hpp is reached through both configurations, configuration.hpp is not.
+//
+// At the production NODE_TIMEOUT of 10s this gives 5000ms for the request and
+// 2000ms for the captive-portal probe. Dividing by TASK_MILLISECOND first
+// normalises out the scheduler resolution, so the result is milliseconds under
+// _TASK_MICRO_RES too.
+
+/** Socket timeout, in milliseconds, for a gateway Internet request.
+ *
+ * An HTTPClient call chain can wait on the socket twice — once sending the
+ * request/reading the headers and once reading the body — so the blocking
+ * budget below counts this value twice (issue #416). That is why the default
+ * is NODE_TIMEOUT/5 rather than the pre-2.0 NODE_TIMEOUT/2: the *wall-clock*
+ * worst case of the request, not one socket wait, has to fit inside the mesh
+ * watchdog. Endpoints that genuinely need longer must raise NODE_TIMEOUT
+ * along with this (the static_assert below enforces that). */
+#ifndef GATEWAY_HTTP_TIMEOUT_MS
+#define GATEWAY_HTTP_TIMEOUT_MS ((NODE_TIMEOUT) / TASK_MILLISECOND / 5)
+#endif
+
+/** Socket timeout, in milliseconds, for the captive-portal probe. Counted
+ * twice in the blocking budget, same as GATEWAY_HTTP_TIMEOUT_MS. */
+#ifndef GATEWAY_CAPTIVE_PORTAL_TIMEOUT_MS
+#define GATEWAY_CAPTIVE_PORTAL_TIMEOUT_MS ((NODE_TIMEOUT) / TASK_MILLISECOND / 10)
+#endif
+
+/** Timeout, in milliseconds, for the DNS reachability probe (issue #416).
+ *
+ * Only the ESP8266 core exposes a hostByName() overload with a timeout
+ * parameter; on ESP32 the probe is skipped entirely (the captive-portal
+ * probe, which is an HTTP round trip bounded by
+ * GATEWAY_CAPTIVE_PORTAL_TIMEOUT_MS, establishes reachability instead).
+ * The budget counts this term unconditionally, which is conservative on
+ * ESP32. */
+#ifndef GATEWAY_DNS_TIMEOUT_MS
+#define GATEWAY_DNS_TIMEOUT_MS ((NODE_TIMEOUT) / TASK_MILLISECOND / 10)
+#endif
+
+/** How long, in milliseconds, a connectivity probe result stays cached.
+ *
+ * Both the DNS reachability check and the captive-portal probe are network
+ * round trips. Running them per message would put an Internet round trip in
+ * front of every single mesh->Internet send.
+ */
+#ifndef GATEWAY_CONNECTIVITY_CACHE_MS
+#define GATEWAY_CONNECTIVITY_CACHE_MS 60000UL
+#endif
+
+/**
+ * @brief Wall-clock ceiling of the gateway's blocking calls on the
+ *        GATEWAY_DATA path, in milliseconds (issue #416).
+ *
+ * Each HTTPClient call chain is counted at *two* socket waits — GET()/POST()
+ * (send + header read) and getString() (body read) — because
+ * HTTPClient::setTimeout() bounds an individual socket wait, not the whole
+ * call. The captive-portal probe and the destination request both have that
+ * shape and run back to back, and the DNS reachability probe (bounded by
+ * GATEWAY_DNS_TIMEOUT_MS on ESP8266, skipped on ESP32) runs before them
+ * whenever the GATEWAY_CONNECTIVITY_CACHE_MS window has expired.
+ *
+ * @warning One residual is not in this budget: the HTTP calls resolve their
+ *          hostnames inside the platform core before their socket timeout
+ *          applies, and on ESP32 that in-request resolver wait is not
+ *          separately boundable in the cores this library targets. On a
+ *          network with blackholed DNS the request path can therefore still
+ *          exceed this ceiling on ESP32. See SECURITY.md "Gateway blocking:
+ *          the mesh partition risk".
+ */
+constexpr unsigned long gatewayBlockingBudgetMs() {
+  return 2UL * static_cast<unsigned long>(GATEWAY_HTTP_TIMEOUT_MS) +
+         2UL * static_cast<unsigned long>(GATEWAY_CAPTIVE_PORTAL_TIMEOUT_MS) +
+         static_cast<unsigned long>(GATEWAY_DNS_TIMEOUT_MS);
+}
+
+// A gateway that can block longer than the mesh watchdog partitions the mesh
+// around itself (issues #318, #332). Catch what is expressible at compile time
+// -- both socket waits of each HTTP call plus the DNS probe; see the ESP32
+// resolver caveat above for the one wait this cannot cover. TASK_ constants
+// are scaled by the scheduler's resolution, so the comparison is written in
+// scheduler units to stay correct under _TASK_MICRO_RES too.
+static_assert(gatewayBlockingBudgetMs() * TASK_MILLISECOND < NODE_TIMEOUT,
+              "Gateway blocking budget (2x GATEWAY_HTTP_TIMEOUT_MS + 2x "
+              "GATEWAY_CAPTIVE_PORTAL_TIMEOUT_MS + GATEWAY_DNS_TIMEOUT_MS) "
+              "must stay below NODE_TIMEOUT, or a gateway request stalls the "
+              "scheduler for longer than its peers are willing to wait and "
+              "the mesh partitions around the gateway. Raise NODE_TIMEOUT if "
+              "you need a longer HTTP timeout.");
+
+/**
+ * Reserve the blocking HTTP budget on the requester's route watchdog.
+ *
+ * A gateway compensates its own peer watchdogs after a blocking request, but
+ * it cannot modify the requester's timer. That timer may already be partly
+ * spent, so extend its existing deadline by the bounded gateway budget before
+ * sending. Disabled watchdogs remain disabled.
+ */
+template <typename T>
+bool reserveGatewayBlockingBudget(T& connection) {
+  if (!connection.timeOutTask.isEnabled()) return false;
+  connection.timeOutTask.adjust(static_cast<long>(
+      gatewayBlockingBudgetMs() * TASK_MILLISECOND));
+  return true;
+}
+
+/**
+ * @brief Give every peer's running watchdog back the time a blocking call hid.
+ *
+ * Call this immediately after returning from a blocking Internet call, before
+ * the scheduler next runs, passing the measured wall-clock duration of the
+ * stall.
+ *
+ * Nothing executes while the gateway is inside `HTTPClient::GET()`/`POST()`,
+ * but wall-clock time keeps passing. So a `timeOutTask` whose NODE_TIMEOUT
+ * deadline fell during the stall is already overdue when the scheduler
+ * resumes, and fires on the very next `execute()` -- closing a peer that never
+ * actually went missing (issues #318, #332).
+ *
+ * The compensation equals the measured stall, no more (issue #417): each
+ * enabled watchdog's existing deadline is postponed by `stalledMs` via
+ * `Task::adjust()`, which extends `iDelay` without touching the task's
+ * baseline. A peer's watchdog therefore measures only time the mesh was
+ * actually able to observe the peer. The earlier implementation restarted
+ * every watchdog from zero (`restartDelayed()`) on every exit path -- which
+ * meant any live peer's gateway traffic granted a genuinely dead peer a
+ * fresh full NODE_TIMEOUT, so the dead peer was never reaped.
+ * `Task::delay()` would be wrong in the other direction: it resets the
+ * baseline to now, shortening the deadline of a peer that still had more
+ * than `stalledMs` remaining and disconnecting healthy peers early.
+ *
+ * Paths that did not block must pass 0 and compensate nothing.
+ *
+ * Only *enabled* watchdogs are touched, and this matters: `timeOutTask` is
+ * armed by `nodeSyncTask` when a sync request goes out and disabled again when
+ * the reply lands, so a disabled watchdog means the peer has nothing
+ * outstanding. Enabling it here would invent a NODE_TIMEOUT deadline for an
+ * idle-but-healthy link whose callback is `Connection::close()` -- turning a
+ * reliability fix into a disconnect bug.
+ *
+ * This protects the gateway's own view of its peers. The peers' view of the
+ * gateway depends on keeping the stall shorter than their watchdog, which is
+ * what gatewayBlockingBudgetMs() is meant to bound -- though see the @warning
+ * there for why that bound is not airtight (#416). Request-side reservation
+ * plus gateway-side compensation are both needed.
+ *
+ * @tparam T   Mesh type exposing `subs` (see painlessmesh::layout::Layout).
+ * @param mesh The mesh whose direct peer connections should be refreshed.
+ * @param stalledMs Measured wall-clock duration of the blocking section, in
+ *        milliseconds. 0 means nothing blocked and nothing is compensated.
+ * @return Number of peers whose watchdog deadline was postponed.
+ */
+template <typename T>
+size_t refreshPeerWatchdogs(T& mesh, unsigned long stalledMs) {
+  if (stalledMs == 0) return 0;  // nothing blocked, nothing to give back
+  size_t refreshed = 0;
+  for (auto&& connection : mesh.subs) {
+    if (!connection) continue;
+    if (!connection->timeOutTask.isEnabled()) continue;
+    connection->timeOutTask.adjust(
+        static_cast<long>(stalledMs * TASK_MILLISECOND));
+    ++refreshed;
+  }
+  return refreshed;
+}
+
 }  // namespace gateway
 }  // namespace painlessmesh
 

package/src/painlessmesh/layout.hpp

@@ -23,6 +23,67 @@ inline bool contains(protocol::NodeTree nodeTree, uint32_t nodeId) {
   return false;
 }
 
+/**
+ * Remove the subtree rooted at nodeId from wherever it sits below tree.
+ *
+ * Only that node and what hangs under it go; the nodes on the way to it
+ * stay. Used when a node turns up on a fresh direct connection while a
+ * neighbour's tree still remembers its old place: a station has one
+ * uplink, so the old place is stale, and routing to it would send packets
+ * down a path that ends at a link that no longer exists.
+ *
+ * \return true if the node was found and removed.
+ */
+inline bool forget(protocol::NodeTree& tree, uint32_t nodeId) {
+  for (auto it = tree.subs.begin(); it != tree.subs.end(); ++it) {
+    if (it->nodeId == nodeId) {
+      tree.subs.erase(it);
+      return true;
+    }
+    if (forget(*it, nodeId)) return true;
+  }
+  return false;
+}
+
+/**
+ * Remove from tree every node that appears anywhere in `elsewhere`.
+ *
+ * A node is in one place. When a neighbour's sync presents the nodes
+ * below it, whatever another neighbour's cached tree still says about
+ * those nodes is older, and a packet routed by the older copy goes down a
+ * branch that ends at a link that no longer exists.
+ *
+ * \return how many nodes were removed.
+ */
+inline size_t forgetAll(protocol::NodeTree& tree,
+                        const protocol::NodeTree& elsewhere) {
+  size_t removed = forget(tree, elsewhere.nodeId) ? 1 : 0;
+  for (auto&& s : elsewhere.subs) removed += forgetAll(tree, s);
+  return removed;
+}
+
+/**
+ * A short identity for what a tree says: which nodes, in which order, which
+ * of them root or time authority. Never 0, so 0 can mean "nothing presented
+ * yet".
+ *
+ * A neighbour's sync is news only when this differs from its last one.
+ */
+inline uint32_t fingerprint(const protocol::NodeTree& tree,
+                            uint32_t hash = 2166136261u) {
+  auto mix = [&hash](uint32_t v) {
+    for (int i = 0; i < 4; ++i) {
+      hash ^= (v >> (8 * i)) & 0xff;
+      hash *= 16777619u;
+    }
+  };
+  mix(tree.nodeId);
+  mix((tree.root ? 1u : 0u) | (tree.hasTimeAuthority ? 2u : 0u));
+  for (auto&& s : tree.subs) hash = fingerprint(s, hash);
+  mix(0xffffffffu);  // end of this node's subs
+  return hash == 0 ? 1 : hash;
+}
+
 inline protocol::NodeTree excludeRoute(protocol::NodeTree&& tree,
                                        uint32_t exclude) {
   // Make sure to exclude any subs with nodeId == 0,
@@ -44,12 +105,12 @@ class Layout {
    * On the ESP hardware nodeId is uniquely calculated from the MAC address of
    * the node.
    */
-  uint32_t getNodeId() { return nodeId; }
+  uint32_t getNodeId() const { return nodeId; }
 
   /**
    * Check whether this node is a root node.
    */
-  bool isRoot() { return root; }
+  bool isRoot() const { return root; }
 
   protocol::NodeTree asNodeTree() {
     auto nt = protocol::NodeTree(nodeId, root, hasTimeAuthority);
@@ -84,6 +145,13 @@ class Neighbour : public protocol::NodeTree {
   // Inherit constructors
   using protocol::NodeTree::NodeTree;
 
+  /**
+   * fingerprint() of the tree this neighbour presented last, 0 before its
+   * first sync. A sync that restates it carries nothing the cached tree
+   * does not already reflect, however the cache has since been pruned.
+   */
+  uint32_t presented = 0;
+
   /**
    * Is the passed nodesync valid
    *

package/src/painlessmesh/logger.hpp

@@ -32,6 +32,14 @@ typedef enum {
 
 class LogClass {
  public:
+  // Where messages go instead of Serial. The sketch owns framing: on a board
+  // whose serial port carries a line protocol, mesh logs written straight to
+  // Serial from a Wi-Fi event task splice into the sketch's own frames, so
+  // the sketch queues them here and writes them between its frames. Called
+  // from whichever task logged, so keep it short and re-entrant.
+  typedef void (*Sink)(LogLevel type, const char *message);
+  void setSink(Sink newSink) { sink = newSink; }
+
   void setLogLevel(uint16_t newTypes) {
     // set the different kinds of debug messages you want to generate.
     types = newTypes;
@@ -82,6 +90,12 @@ class LogClass {
 
       vsnprintf(str, 200, format, args);
 
+      if (sink) {
+        sink(type, str);
+        va_end(args);
+        return;
+      }
+
       if (types) {
         switch (type) {
           case ERROR:
@@ -153,6 +167,7 @@ class LogClass {
 
  private:
   uint16_t types = 0;
+  Sink sink = nullptr;
   char str[200];
   std::list<std::pair<uint32_t, TSTRING>> remote_queue;
   uint32_t remote_uuid;