@alteriom/painlessmesh 1.9.20 → 1.10.0

package/examples/tcpRetryConfig/tcpRetryConfig.ino

@@ -0,0 +1,154 @@
+//************************************************************
+// Tuning the TCP connection retry behaviour (issue #378)
+//
+// painlessMesh retries a failed TCP connection with exponential backoff
+// before giving up and falling back to a full WiFi reconnect. The defaults
+// (5 retries, 1s base delay -> 1s, 2s, 4s, 8s, 8s) are tuned for general
+// purpose meshes and deliberately favour reliability over speed.
+//
+// setTcpRetryConfig() lets you pick a different trade-off. Three ready-made
+// profiles are shown below; switch between them with ACTIVE_PROFILE.
+//
+// Read examples/tcpRetryConfig/README.md before changing these values - the
+// defaults exist because 1.9.x raised them to fix real mesh instability.
+//************************************************************
+#include <painlessMesh.h>
+
+#define   MESH_SSID       "whateverYouLike"
+#define   MESH_PASSWORD   "somethingSneaky"
+#define   MESH_PORT       5555
+
+// ---------------------------------------------------------------------------
+// Profiles
+// ---------------------------------------------------------------------------
+#define PROFILE_REALTIME  1   // low latency: fail fast, reconnect fast
+#define PROFILE_RELIABLE  2   // industrial: many retries, long backoff
+#define PROFILE_BATTERY   3   // conserve power: few retries, long block
+
+// >>> Change this line to try a different profile <<<
+#define ACTIVE_PROFILE    PROFILE_REALTIME
+
+// Prototypes
+void sendMessage();
+void receivedCallback(uint32_t from, String &msg);
+void newConnectionCallback(uint32_t nodeId);
+void droppedConnectionCallback(uint32_t nodeId);
+
+Scheduler     userScheduler;
+painlessMesh  mesh;
+
+Task taskSendMessage(TASK_SECOND * 5, TASK_FOREVER, &sendMessage);
+
+// Build the retry configuration for the selected profile.
+painlessmesh::tcp::TcpRetryConfig buildRetryConfig() {
+  painlessmesh::tcp::TcpRetryConfig cfg;  // starts at the library defaults
+
+#if ACTIVE_PROFILE == PROFILE_REALTIME
+  // Real-time sensor / LED meshes: a stalled node is worse than a dropped
+  // one. Give up on the TCP handshake almost immediately and go straight
+  // back to scanning for another parent.
+  cfg.maxRetries = 1;                    // default 5
+  cfg.retryDelayMs = 200;                // default 1000
+  cfg.stabilizationDelayMs = 100;        // default 500
+  cfg.exhaustionReconnectDelayMs = 1000; // default 10000
+  cfg.failureBlockDurationMs = 5000;     // default 60000
+
+#elif ACTIVE_PROFILE == PROFILE_RELIABLE
+  // Industrial / high-reliability meshes: connectivity matters more than
+  // how long it takes to get there. Retry patiently and keep a failed peer
+  // out of the running for a good while.
+  cfg.maxRetries = 10;                     // default 5 (this is the maximum)
+  cfg.retryDelayMs = 2000;                 // default 1000
+  cfg.stabilizationDelayMs = 1000;         // default 500
+  cfg.exhaustionReconnectDelayMs = 30000;  // default 10000
+  // Must exceed one full failure cycle (126s of retries + 30s reconnect),
+  // otherwise a dead peer leaves the blocklist before we finished failing
+  // over and gets re-selected immediately.
+  cfg.failureBlockDurationMs = 180000;     // default 60000
+
+#elif ACTIVE_PROFILE == PROFILE_BATTERY
+  // Battery-powered nodes: every retry is radio time. Few attempts, spaced
+  // widely, and a long blocklist so we do not keep waking up for a peer
+  // that is known to be down.
+  cfg.maxRetries = 2;                      // default 5
+  cfg.retryDelayMs = 3000;                 // default 1000
+  cfg.stabilizationDelayMs = 500;          // default 500
+  cfg.exhaustionReconnectDelayMs = 60000;  // default 10000
+  cfg.failureBlockDurationMs = 300000;     // default 60000
+
+#else
+  #error "ACTIVE_PROFILE must be one of PROFILE_REALTIME, PROFILE_RELIABLE, PROFILE_BATTERY"
+#endif
+
+  return cfg;
+}
+
+void setup() {
+  Serial.begin(115200);
+
+  mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+
+  // Apply the retry configuration BEFORE init() so the very first connection
+  // attempt already uses it.
+  mesh.setTcpRetryConfig(buildRetryConfig());
+
+  mesh.init(MESH_SSID, MESH_PASSWORD, &userScheduler, MESH_PORT);
+
+  // Read the configuration back. Values outside safe operating bounds are
+  // clamped by the setter, so this prints what is actually in effect - not
+  // necessarily what was requested.
+  painlessmesh::tcp::TcpRetryConfig active = mesh.getTcpRetryConfig();
+  Serial.println();
+  Serial.println(F("Effective TCP retry configuration:"));
+  Serial.printf("  maxRetries                 = %u\n",
+                (unsigned)active.maxRetries);
+  Serial.printf("  retryDelayMs               = %u\n",
+                (unsigned)active.retryDelayMs);
+  Serial.printf("  stabilizationDelayMs       = %u\n",
+                (unsigned)active.stabilizationDelayMs);
+  Serial.printf("  exhaustionReconnectDelayMs = %u\n",
+                (unsigned)active.exhaustionReconnectDelayMs);
+  Serial.printf("  failureBlockDurationMs     = %u\n",
+                (unsigned)active.failureBlockDurationMs);
+
+  // Worst-case time spent retrying before falling back to a WiFi reconnect.
+  uint32_t worstCase = 0;
+  for (uint8_t i = 0; i < active.maxRetries; ++i) {
+    worstCase += painlessmesh::tcp::retryBackoffDelay(active, i);
+  }
+  Serial.printf("  -> worst-case retry time   = %u ms\n", (unsigned)worstCase);
+  Serial.printf("  -> plus reconnect delay    = %u ms\n",
+                (unsigned)(worstCase + active.exhaustionReconnectDelayMs));
+  Serial.println();
+
+  mesh.onReceive(&receivedCallback);
+  mesh.onNewConnection(&newConnectionCallback);
+  mesh.onDroppedConnection(&droppedConnectionCallback);
+
+  userScheduler.addTask(taskSendMessage);
+  taskSendMessage.enable();
+}
+
+void loop() {
+  mesh.update();
+}
+
+void sendMessage() {
+  String msg = "Hello from node ";
+  msg += mesh.getNodeId();
+  mesh.sendBroadcast(msg);
+}
+
+void receivedCallback(uint32_t from, String &msg) {
+  Serial.printf("tcpRetryConfig: Received from %u msg=%s\n", from, msg.c_str());
+}
+
+void newConnectionCallback(uint32_t nodeId) {
+  Serial.printf("--> Connected to node %u\n", nodeId);
+}
+
+void droppedConnectionCallback(uint32_t nodeId) {
+  // With an aggressive profile you should expect to see this more often -
+  // and to see the reconnect that follows it happen much sooner.
+  Serial.printf("--> Dropped connection to node %u\n", nodeId);
+}

package/keywords.txt

@@ -4,6 +4,7 @@
 painlessMesh	KEYWORD1
 Scheduler	KEYWORD1
 Task	KEYWORD1
+TcpRetryConfig	KEYWORD1
 
 # Methods and Functions (KEYWORD2)
 init	KEYWORD2
@@ -18,6 +19,8 @@ getNodeList	KEYWORD2
 getNodeId	KEYWORD2
 getNodeTime	KEYWORD2
 setDebugMsgTypes	KEYWORD2
+setTcpRetryConfig	KEYWORD2
+getTcpRetryConfig	KEYWORD2
 subConnectionJson	KEYWORD2
 asNodeTree	KEYWORD2
 

package/library.json

@@ -6,7 +6,7 @@
     "type": "git",
     "url": "https://github.com/Alteriom/painlessMesh"
   },
-  "version": "1.9.20",
+  "version": "1.10.0",
   "frameworks": [
     "arduino"
   ],

package/library.properties

@@ -1,5 +1,5 @@
 name=Alteriom PainlessMesh
-version=1.9.20
+version=1.10.0
 author=Coopdis,Scotty Franzyshen,Edwin van Leeuwen,Germán Martín,Maximilian Schwarz,Doanh Doanh,Alteriom
 maintainer=Alteriom
 sentence=A painless way to setup a mesh with ESP8266 and ESP32 devices with Alteriom extensions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alteriom/painlessmesh",
-  "version": "1.9.20",
+  "version": "1.10.0",
   "description": "painlessMesh is a user-friendly library for creating mesh networks with ESP8266 and ESP32 devices. This Alteriom fork includes additional packages for sensor data (SensorPackage), device commands (CommandPackage), and status monitoring (StatusPackage). It handles routing and network management automatically, so you can focus on your application. The library uses JSON-based messaging and syncs time across all nodes, making it ideal for coordinated behaviour like synchronized light displays or sensor networks reporting to a central node.",
   "keywords": [
     "arduino",

package/src/AlteriomPainlessMesh.h

@@ -29,10 +29,10 @@
 /**
  * @brief AlteriomPainlessMesh library version information
  */
-#define ALTERIOM_PAINLESS_MESH_VERSION "1.9.20"
+#define ALTERIOM_PAINLESS_MESH_VERSION "1.10.0"
 #define ALTERIOM_PAINLESS_MESH_VERSION_MAJOR 1
-#define ALTERIOM_PAINLESS_MESH_VERSION_MINOR 9
-#define ALTERIOM_PAINLESS_MESH_VERSION_PATCH 20
+#define ALTERIOM_PAINLESS_MESH_VERSION_MINOR 10
+#define ALTERIOM_PAINLESS_MESH_VERSION_PATCH 0
 
 /**
  * @brief Library description and usage information

package/src/arduino/wifi.hpp

@@ -817,8 +817,9 @@ class Mesh : public painlessmesh::Mesh<Connection> {
    * TCP Connection Retry:
    * The TCP connection now includes automatic retry with exponential backoff.
    * If the initial connection fails (error -14 ERR_CONN or other errors),
-   * the system will retry up to TCP_CONNECT_MAX_RETRIES times before
-   * triggering a full WiFi reconnection cycle. This helps handle:
+   * the system will retry up to the configured maxRetries times before
+   * triggering a full WiFi reconnection cycle (see setTcpRetryConfig()).
+   * This helps handle:
    * - Timing issues where TCP server is not ready immediately
    * - Network stack stabilization after IP acquisition
    * - Transient network conditions
@@ -842,8 +843,11 @@ class Mesh : public painlessmesh::Mesh<Connection> {
       // This helps prevent error -14 (ERR_CONN) by allowing the network stack
       // and TCP server to be fully ready. The delay is added via task scheduler
       // to avoid blocking the event loop.
+      // The delay is read at schedule time, so calling setTcpRetryConfig()
+      // while a connect is already pending affects the next attempt, not the
+      // in-flight one.
       this->addTask(
-          painlessmesh::tcp::TCP_CONNECT_STABILIZATION_DELAY_MS, TASK_ONCE,
+          this->getTcpRetryConfig().stabilizationDelayMs, TASK_ONCE,
           [this, targetIP, targetPort]() {
             // Verify WiFi is still connected after the delay
             if (WiFi.status() != WL_CONNECTED || !WiFi.localIP()) {
@@ -1962,14 +1966,31 @@ class Mesh : public painlessmesh::Mesh<Connection> {
     for (int i = 0; i < 100; i++) { delay(10); yield(); }
     Log(STARTUP, "[OK] Takeover announcement sent on channel %d\n", _meshChannel);
 
-    // Save current mesh configuration to restore if bridge init fails
+    // Save current mesh configuration to restore if bridge init fails.
+    // The copies below are captured by value into the deferred lambda so the
+    // stop() call inside it cannot clear/mutate these members before the
+    // reinit reads them. (The Mesh object itself outlives the lambda; this
+    // protects against member mutation, not object lifetime.)
+    // TODO(#373 follow-up): if the mesh owns its scheduler
+    // (!isExternalScheduler), stop() deletes mScheduler and savedScheduler
+    // dangles before initAsBridge() uses it. Pre-existing limitation —
+    // bridge promotion requires a user-supplied scheduler.
     uint8_t savedChannel = _meshChannel;
+    TSTRING savedMeshSSID = _meshSSID;
+    TSTRING savedMeshPassword = _meshPassword;
+    TSTRING savedRouterSSID = routerSSID;
+    TSTRING savedRouterPassword = routerPassword;
+    Scheduler *savedScheduler = mScheduler;
+    auto savedBridgeRoleChangedCallback = bridgeRoleChangedCallback;
 
     // CRITICAL FIX: Schedule the stop/reinit work to run after current task completes
     // This prevents use-after-free crash when stop() clears taskList while
     // evaluateElection() task is still executing
     // Use minimal delay to allow current task to complete first
-    this->addTask(ASYNC_PROMOTION_DELAY_MS, TASK_ONCE, [this, savedChannel]() {
+    this->addTask(ASYNC_PROMOTION_DELAY_MS, TASK_ONCE,
+                  [this, savedChannel, savedMeshSSID, savedMeshPassword,
+                   savedRouterSSID, savedRouterPassword, savedScheduler,
+                   savedBridgeRoleChangedCallback]() {
       using namespace logger;
       
       Log(STARTUP, "Executing bridge promotion (stop/reinit cycle)\n");
@@ -1981,18 +2002,17 @@ class Mesh : public painlessmesh::Mesh<Connection> {
 
       // initAsBridge always returns true: bridge mesh functionality is active
       // regardless of router connection status (router connection is opportunistic)
-      this->initAsBridge(_meshSSID, _meshPassword, routerSSID, routerPassword,
-                         mScheduler, _meshPort);
+      this->initAsBridge(savedMeshSSID, savedMeshPassword, savedRouterSSID,
+                         savedRouterPassword, savedScheduler, _meshPort);
 
       lastRoleChangeTime = millis();
 
       Log(STARTUP, "[OK] Bridge promotion complete on channel %d\n", _meshChannel);
 
       // Notify via callback
-      // Use explicit TSTRING construction to ensure string lifetime safety
-      if (bridgeRoleChangedCallback) {
+      if (savedBridgeRoleChangedCallback) {
         static const TSTRING reason = "Election winner - best router signal";
-        bridgeRoleChangedCallback(true, reason);
+        savedBridgeRoleChangedCallback(true, reason);
       }
 
       // Note: The initial takeover announcement was already sent earlier
@@ -2065,14 +2085,27 @@ class Mesh : public painlessmesh::Mesh<Connection> {
     Log(CONNECTION,
         "Scheduling stop/reinit (async to avoid task corruption)\n");
 
-    // Save current mesh configuration
+    // Save current mesh configuration. Captured by value into the deferred
+    // lambda so stop() cannot clear/mutate these members before the reinit
+    // reads them (see the matching comment in promoteToBridge(); same
+    // TODO(#373 follow-up) about savedScheduler and internal schedulers
+    // applies here).
     uint8_t savedChannel = _meshChannel;
+    TSTRING savedMeshSSID = _meshSSID;
+    TSTRING savedMeshPassword = _meshPassword;
+    TSTRING savedRouterSSID = routerSSID;
+    TSTRING savedRouterPassword = routerPassword;
+    Scheduler *savedScheduler = mScheduler;
+    auto savedBridgeRoleChangedCallback = bridgeRoleChangedCallback;
 
     // CRITICAL FIX: Schedule the stop/reinit work to run after current task completes
     // This prevents use-after-free crash when stop() clears taskList while
     // the retry task is still executing
     // Use minimal delay to allow current task to complete first
-    this->addTask(ASYNC_PROMOTION_DELAY_MS, TASK_ONCE, [this, savedChannel]() {
+    this->addTask(ASYNC_PROMOTION_DELAY_MS, TASK_ONCE,
+                  [this, savedChannel, savedMeshSSID, savedMeshPassword,
+                   savedRouterSSID, savedRouterPassword, savedScheduler,
+                   savedBridgeRoleChangedCallback]() {
       using namespace logger;
       
       Log(CONNECTION, "Executing isolated bridge promotion (stop/reinit cycle)\n");
@@ -2084,8 +2117,8 @@ class Mesh : public painlessmesh::Mesh<Connection> {
 
       // initAsBridge always returns true: bridge mesh functionality is active
       // regardless of router connection status (router connection is opportunistic)
-      this->initAsBridge(_meshSSID, _meshPassword, routerSSID, routerPassword,
-                         mScheduler, _meshPort);
+      this->initAsBridge(savedMeshSSID, savedMeshPassword, savedRouterSSID,
+                         savedRouterPassword, savedScheduler, _meshPort);
 
       // Reset retry counter
       _isolatedBridgeRetryAttempts = 0;
@@ -2095,10 +2128,9 @@ class Mesh : public painlessmesh::Mesh<Connection> {
           _meshChannel);
 
       // Notify via callback
-      // Use explicit TSTRING construction to ensure string lifetime safety
-      if (bridgeRoleChangedCallback) {
+      if (savedBridgeRoleChangedCallback) {
         static const TSTRING reason = "Isolated node promoted to bridge";
-        bridgeRoleChangedCallback(true, reason);
+        savedBridgeRoleChangedCallback(true, reason);
       }
 
       // Note: Bridge status announcement will be sent automatically by

package/src/painlessMesh.h

@@ -5,8 +5,8 @@
  * @file painlessMesh.h
  * @brief Main header file for Alteriom painlessMesh library
  * 
- * @version 1.9.20
- * @date 2025-12-21
+ * @version 1.10.0
+ * @date 2026-08-12
  * 
  * painlessMesh is a user-friendly library for creating mesh networks with 
  * ESP8266 and ESP32 devices. This Alteriom fork includes additional packages 

package/src/painlessTaskOptions.h

@@ -2,6 +2,15 @@
 #define _TASK_PRIORITY      // Support for layered scheduling priority
 #define _TASK_STD_FUNCTION  // Support for std::function (ESP8266 and ESP32)
                             // Required for painlessMesh lambda callbacks
+#define _TASK_SELF_DESTRUCT // Scheduler-managed deletion of heap-allocated
+                            // one-shot tasks. The Scheduler deletes the Task
+                            // in execute(), after disable() has returned, so
+                            // a task never has to delete itself from inside
+                            // its own onDisable callback (which is a
+                            // use-after-free: Task::disable() writes to the
+                            // task object after onDisable returns). Used by
+                            // scheduleAsyncClientDeletion() in
+                            // connection.hpp. See issue #373.
 
 // NOTE: _TASK_THREAD_SAFE is currently DISABLED due to incompatibility
 // with _TASK_STD_FUNCTION in TaskScheduler v4.0.x

package/src/painlessmesh/buffer.hpp

@@ -37,7 +37,10 @@ class ReceiveBuffer {
     do {
       auto len = strnlen(data_ptr, length);
       do {
-        auto read_len = (std::min)(len, buf.length);
+        // Reserve one byte for the '\0' terminator below: read_len may be at
+        // most buf.length - 1, otherwise buf.buffer[read_len] writes one
+        // byte past the end of the buffer (caught by the ASan CI job).
+        auto read_len = (std::min)(len, buf.length - 1);
         memcpy(buf.buffer, data_ptr, read_len);
         buf.buffer[read_len] = '\0';
         auto newBuffer = T(buf.buffer);

package/src/painlessmesh/configuration.hpp

@@ -26,10 +26,21 @@
 // Enable OTA support
 #define PAINLESSMESH_ENABLE_OTA
 
-// Minimum free memory, besides here all packets in queue are discarded.
+// NOTE: `MIN_FREE_MEMORY` and `MAX_MESSAGE_QUEUE` are kept as deprecated
+// no-op compatibility macros. The library does not read either macro:
+// the auto-flushing message queue they were meant to tune never landed
+// (see #385, PR #383 review). `MessageQueue`
+// (`painlessmesh/message_queue.hpp`) is a manual priority buffer with
+// its own per-instance `maxSize` argument. Their historical default
+// values are preserved so downstream code that referenced them keeps
+// its prior behavior.
+#ifndef MIN_FREE_MEMORY
 #define MIN_FREE_MEMORY 4000
-// MAX number of unsent messages in queue. Newer messages are discarded
+#endif
+
+#ifndef MAX_MESSAGE_QUEUE
 #define MAX_MESSAGE_QUEUE 50
+#endif
 
 #define NODE_TIMEOUT 10 * TASK_SECOND
 #define SCAN_INTERVAL 30 * TASK_SECOND  // AP scan period in ms

package/src/painlessmesh/connection.hpp

@@ -123,12 +123,17 @@ inline void scheduleAsyncClientDeletion(Scheduler* scheduler, AsyncClient* clien
     delete client;
   });
 
-  // Self-cleanup: after execution, remove from scheduler and delete the Task.
-  // OnDisable fires after a TASK_ONCE task completes its single iteration.
-  cleanupTask->setOnDisable([cleanupTask, scheduler]() {
-    scheduler->deleteTask(*cleanupTask);
-    delete cleanupTask;
-  });
+  // Task cleanup (issue #373): the task must NOT delete itself from inside
+  // its own onDisable callback. TaskScheduler's Task::disable() keeps
+  // writing to the task object (iScheduler->iCurrent) after onDisable
+  // returns, so a self-delete there is a guaranteed use-after-free — this
+  // was crashing nodes on every connection teardown.
+  // Instead we mark the task self-destructing (_TASK_SELF_DESTRUCT, enabled
+  // in painlessTaskOptions.h): after the single iteration completes, the
+  // Scheduler itself disables the task, unlinks it from its chain, and
+  // deletes it — all from within Scheduler::execute(), safely outside the
+  // disable() call stack.
+  cleanupTask->setSelfDestruct(true);
 
   scheduler->addTask(*cleanupTask);
   cleanupTask->enableDelayed();
@@ -160,13 +165,28 @@ class BufferedConnection
     using namespace logger;
     Log.remote("~BufferedConnection");
     this->close();
-    if (!client->freeable()) {
-      client->close(true);
-    }
+    // Always call client->close() here, unconditionally - do NOT guard this
+    // behind client->freeable(). freeable() can return true while _pcb is
+    // still a valid, non-null pointer (e.g. pcb->state == CLOSED but not yet
+    // reclaimed by lwIP). If we skip close() in that case, _pcb stays
+    // non-null for the entire TCP_CLIENT_CLEANUP_DELAY_MS+ deferred-deletion
+    // window below - during which lwIP's own internal timers (e.g. TIME_WAIT
+    // expiry) can silently free/recycle that pcb without ever notifying
+    // AsyncClient (the tcp_err callback only fires on abnormal termination,
+    // not on routine timer-driven pcb reclamation). The deferred delete then
+    // finds a stale-but-non-null _pcb and tries to close/free it a second
+    // time, corrupting the heap (observed as heap_caps_free/memp_free
+    // assertion failures and wild-pointer crashes inside tcp_arg(), all
+    // several seconds after the connection actually died).
+    // close() internally handles "nothing to do" safely (AsyncTCP checks
+    // _pcb/*pcb before touching lwIP state), and reliably nulls _pcb via its
+    // synchronous tcpip_api_call round-trip - so calling it unconditionally
+    // here, right at destruction time, closes this exposure window entirely.
+    client->close();
     // Note: client->abort() removed - calling it before deferred deletion
     // can leave the client in an inconsistent state where AsyncTCP is still
-    // trying to clean up the aborted connection. The close() and close(true)
-    // calls above are sufficient for connection termination.
+    // trying to clean up the aborted connection. The close() call above is
+    // sufficient for connection termination.
     // See: AsyncTCP best practices - abort() should only be called immediately
     // before delete, not before a deferred deletion.
     

package/src/painlessmesh/mesh.hpp

@@ -344,7 +344,7 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
       (*conn)->close();
       this->eraseClosedConnections();
     }
-    plugin::PackageHandler<T>::stop();
+    plugin::PackageHandler<T>::stop(mScheduler);
 
     newConnectionCallbacks.clear();
     droppedConnectionCallbacks.clear();
@@ -1394,6 +1394,32 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
     internetRetryDelay = delayMs;
   }
 
+  /**
+   * Configure TCP connection retry behaviour
+   *
+   * Lets latency-sensitive, high-reliability or battery-powered deployments
+   * pick their own retry envelope. Values outside safe operating bounds are
+   * clamped - see painlessmesh::tcp::clampTcpRetryConfig(). Read the applied
+   * (post-clamp) values back with getTcpRetryConfig().
+   *
+   * The defaults reproduce the previous hardcoded behaviour exactly, so
+   * existing sketches that never call this see no change.
+   *
+   * @param config Retry parameters to apply
+   */
+  void setTcpRetryConfig(const painlessmesh::tcp::TcpRetryConfig &config) {
+    tcpRetryConfig = painlessmesh::tcp::clampTcpRetryConfig(config);
+  }
+
+  /**
+   * Get the active TCP retry configuration
+   *
+   * @return The configuration currently in effect, after clamping
+   */
+  painlessmesh::tcp::TcpRetryConfig getTcpRetryConfig() const {
+    return tcpRetryConfig;
+  }
+
   /**
    * Get number of pending Internet requests
    *
@@ -2060,16 +2086,34 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
   //
   
   /**
-   * Enable or disable message queueing for offline mode
-   * 
-   * When enabled, messages can be queued when Internet is unavailable
-   * and automatically flushed when connection is restored.
-   * 
+   * Enable or disable the manual message queue for offline mode
+   *
+   * When enabled, allocates a `MessageQueue` that your application can
+   * push into while an upstream (MQTT/HTTP/etc.) is unreachable. The
+   * mesh does NOT flush the queue automatically and does NOT observe
+   * connectivity changes — the app is responsible for detecting when
+   * to drain it via `flushMessageQueue()` + `removeQueuedMessage()`.
+   *
+   * Wire it to your own connectivity signal, for example
+   * `onLocalInternetChanged` on the bridge node or
+   * `onBridgeStatusChanged` on downstream nodes.
+   *
    * @param enabled True to enable queueing, false to disable
    * @param maxSize Maximum number of messages in queue (default 1000)
-   * 
+   *
    * \code
    * mesh.enableMessageQueue(true, 500);  // Enable with 500 message capacity
+   *
+   * mesh.onLocalInternetChanged([&mesh](bool available) {
+   *   if (available) {
+   *     auto messages = mesh.flushMessageQueue();
+   *     for (auto& msg : messages) {
+   *       if (sendToCloud(msg.payload, msg.destination)) {
+   *         mesh.removeQueuedMessage(msg.id);
+   *       }
+   *     }
+   *   }
+   * });
    * \endcode
    */
   void enableMessageQueue(bool enabled, uint32_t maxSize = 1000) {
@@ -2084,11 +2128,13 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
   }
   
   /**
-   * Queue a message with priority for later delivery
-   * 
-   * Use this to queue critical messages when Internet is unavailable.
-   * Messages are automatically delivered when connection is restored.
-   * 
+   * Queue a message with priority for later manual delivery
+   *
+   * Use this to buffer critical messages when your upstream
+   * (MQTT/HTTP/etc.) is unavailable. The library does NOT deliver these
+   * on its own — your app must call `flushMessageQueue()` and
+   * `removeQueuedMessage()` once its own connectivity check clears.
+   *
    * @param payload Message content to queue
    * @param destination Optional destination metadata (e.g., MQTT topic, HTTP endpoint)
    * @param priority Message priority (default: PRIORITY_NORMAL)
@@ -2115,16 +2161,14 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
   }
   
   /**
-   * Flush all queued messages
-   * 
-   * Attempts to send all queued messages. This is typically called
-   * automatically when Internet connection is restored, but can be
-   * called manually.
-   * 
-   * Note: This returns the messages for the application to send.
-   * The application is responsible for actually transmitting them
-   * and calling removeQueuedMessage() when successful.
-   * 
+   * Return a snapshot of all queued messages for manual delivery
+   *
+   * This does NOT transmit anything and does NOT clear the queue. The
+   * application is responsible for actually sending each message and
+   * calling `removeQueuedMessage(id)` for each one that succeeded.
+   * Messages left in the queue remain available for retry on the next
+   * flush.
+   *
    * @return Vector of queued messages to send
    * 
    * \code
@@ -3262,6 +3306,13 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
   uint32_t internetRetryDelay = 1000;        // Default 1 second base delay
   bool sendToInternetEnabled = false;
 
+  // TCP connect retry parameters, see setTcpRetryConfig().
+  // Public because tcp::connect<Connection, wifi::Mesh> reads it but is NOT a
+  // friend: the friend declaration below names connect<T, Mesh<T>>, whereas
+  // wifi::Mesh::tcpConnect() instantiates connect<Connection, wifi::Mesh> - a
+  // different specialisation. Same reason as the public: sections above.
+  painlessmesh::tcp::TcpRetryConfig tcpRetryConfig;
+
   friend T;
   friend void onDataCb(void *, AsyncClient *, void *, size_t);
   friend void tcpSentCb(void *, AsyncClient *, size_t, uint32_t);