@alteriom/painlessmesh 1.9.20 → 1.10.0

package/CHANGELOG.md

@@ -7,12 +7,133 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.10.0] - 2026-08-12
+
+Feature release making the TCP connect-retry envelope tunable per mesh instance
+(#378), alongside two documentation corrections that retire long-standing claims
+the library never actually implemented (#385) and an example build fix (#360).
+
+**Upgrading is behaviour-neutral.** Every new setting defaults to the value that
+was previously hardcoded, so a sketch that does not call `setTcpRetryConfig()`
+behaves exactly as it did on 1.9.21. Nothing was removed: the deprecated queue
+macros keep their historical values for source compatibility.
+
+> **Note for npm users:** v1.9.21 was never published to npm — the `NPM_TOKEN`
+> used by CI had expired (#381), which failed the npm publish job while the
+> GitHub Release, GitHub Packages, PlatformIO and Arduino channels all succeeded.
+> npm's previous version is therefore **1.9.20**, and upgrading from npm brings
+> in both 1.9.21 and 1.10.0. See the 1.9.21 entry below for what that release
+> contained — it was a crash-fix release, and npm users have been missing it.
+
 ### Added
 
+- **User-configurable TCP retry parameters (#378)** — the five TCP connect
+  retry values that were hardcoded as `static const` in
+  `src/painlessmesh/tcp.hpp` are now tunable per mesh instance via
+  `mesh.setTcpRetryConfig()` / `mesh.getTcpRetryConfig()`, using the new
+  `painlessmesh::tcp::TcpRetryConfig` struct (`maxRetries`, `retryDelayMs`,
+  `stabilizationDelayMs`, `exhaustionReconnectDelayMs`,
+  `failureBlockDurationMs`). This lets latency-sensitive meshes (see
+  discussion #368), high-reliability industrial deployments and
+  battery-powered nodes each pick their own retry envelope without forking
+  the library.
+
+  The struct's defaults are spelled as the existing constants, so **behaviour
+  is unchanged for any sketch that does not call the new setter**, and the
+  constants themselves remain in place. `maxRetries` is clamped to 10 and
+  `retryDelayMs` to 50–60000 ms, since an unbounded retry count is a
+  heap/recursion hazard and a zero delay produces a hot reconnect loop; the
+  remaining fields accept 0 as a meaningful "disable this step" value.
+  New `examples/tcpRetryConfig/` demonstrates real-time, high-reliability and
+  battery-saver profiles.
+
 ### Changed
 
+- **`MessageQueue` documented honestly as a manual buffer (#385)** —
+  removed the "messages are automatically delivered when connection is
+  restored" claim from `MessageQueue` and the `mesh.enableMessageQueue`
+  / `queueMessage` / `flushMessageQueue` doc comments. Nothing in the
+  library ever transmitted queued messages or observed connectivity
+  changes; the app has always owned the send loop. The docs now say so,
+  and the `flushMessageQueue` example shows the intended pattern of
+  wiring the drain into `onLocalInternetChanged`.
+
+### Deprecated
+
+- **Compatibility queue macros kept as ignored no-ops (#385)** —
+  `MIN_FREE_MEMORY` and `MAX_MESSAGE_QUEUE` remain defined in
+  `painlessmesh/configuration.hpp` (and `test/boost/Arduino.h`) for
+  source compatibility, but nothing in the library reads them. They were
+  placeholders for the auto-flush behavior that never landed.
+  `MessageQueue` has always taken its own per-instance `maxSize`
+  constructor argument. Their historical default values
+  (`MIN_FREE_MEMORY 4000`, `MAX_MESSAGE_QUEUE 50`) are preserved so any
+  downstream code that referenced the macros keeps its prior behavior.
+
 ### Fixed
 
+- **`bridge_failover` example failed to compile (#360)** — the two
+  `mesh.onBridgeCoordination*` lambdas referenced
+  `plugin::BridgeCoordinationPackage` with a bare `plugin::` prefix, but
+  `painlessMesh.h` only lifts `painlessmesh::logger` to global scope, so
+  the type did not resolve (`'plugin' does not name a type`). Both lambda
+  parameters are now fully qualified as
+  `painlessmesh::plugin::BridgeCoordinationPackage`, matching the
+  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
+TCP-connection lifecycle. Root-caused and fixed by @vaz82 (PR #376) with
+reports and field testing from @fidla73 and @miloshev (issue #373); finalized
+with TaskScheduler's native self-destruct mechanism and regression coverage.
+
+### Fixed
+
+- **Use-after-free in `Task::disable()` on connection teardown (#373)** —
+  `scheduleAsyncClientDeletion()`'s cleanup task deleted itself inside its
+  own `onDisable` callback, but TaskScheduler's `Task::disable()` writes to
+  the task object after `onDisable` returns. Crashed nodes (StoreProhibited,
+  `EXCVADDR 0x8`) on every peer disconnect. The cleanup task now uses
+  TaskScheduler's `_TASK_SELF_DESTRUCT` support (enabled in
+  `painlessTaskOptions.h`): the Scheduler deletes the task from within
+  `execute()`, safely outside the `disable()` call stack.
+- **`PackageHandler::stop()` destroying the currently-executing task** —
+  when `stop()` runs from within a task's own callback (bridge promotion
+  path), it destroyed that task's closure mid-execution via
+  `setCallback(NULL)`/`shared_ptr` release. `stop()` now accepts the
+  scheduler, detects the running task via `getCurrentTask()`, and leaves it
+  in `taskList` for safe reuse by `addTask()`.
+- **Stale `_pcb` window in `~BufferedConnection()`** — `client->close()` was
+  skipped when `freeable()` returned true, leaving a non-null-but-stale pcb
+  that lwIP's timers could recycle during the deferred-deletion window
+  (`heap_caps_free`/`memp_free` assertion failures, `tcp_arg()` wild-pointer
+  stores). `close()` is now called unconditionally at destruction.
+- **`onError`/`onConnect` double-handling race in `tcp::connect()`** — if
+  WiFi dropped as the TCP handshake completed, AsyncTCP could fire both
+  callbacks for the same `AsyncClient`, handing it to two owners and
+  scheduling its deletion twice. A shared claim guard now ensures exactly
+  one callback processes the client.
+- **Bridge promotion state capture** — the deferred stop/reinit lambda in
+  `promoteToBridge()` (and the isolated-node variant) now captures mesh
+  credentials, scheduler, and callback by value so `stop()` cannot mutate
+  them before the reinit reads them.
+- **Off-by-one buffer overflow in `ReceiveBuffer::push()`** — when a
+  received chunk was ≥ `TCP_MSS`, the null terminator was written one byte
+  past the end of the shared temp buffer, corrupting adjacent memory on
+  every large read. Found by the new AddressSanitizer CI job on its first
+  run; `read_len` now reserves one byte for the terminator.
+
+### Added
+
+- Regression test `catch_connection_cleanup.cpp` covering the #373
+  schedule → fire → self-destruct cleanup lifecycle and
+  `~BufferedConnection` churn.
+- AddressSanitizer job in CI (gcc + `-fsanitize=address`) so use-after-free
+  and double-free regressions in the task/connection lifecycle fail the
+  build instead of crashing devices in the field.
+
 ## [1.9.20] - 2026-03-27
 
 ### Added

package/README.md

@@ -4,7 +4,7 @@
 
 <div align="center">
 
-**Version 1.9.20** - Full repo cleanup, bug fixes, and documentation consistency
+**Version 1.10.0** - Tunable TCP connect-retry behaviour via `setTcpRetryConfig()` (#378)
 
 [![CI/CD Pipeline](https://github.com/Alteriom/painlessMesh/actions/workflows/ci.yml/badge.svg)](https://github.com/Alteriom/painlessMesh/actions/workflows/ci.yml)
 [![Documentation](https://github.com/Alteriom/painlessMesh/actions/workflows/docs.yml/badge.svg)](https://github.com/Alteriom/painlessMesh/actions/workflows/docs.yml)
@@ -560,9 +560,29 @@ These are the message types used by applications built on painlessMesh:
 - **Event Coordination** - Synchronized displays, distributed processing
 - **Bridge Networks** - Connect mesh to WiFi/Internet/MQTT - [📖 Bridge Guide](BRIDGE_TO_INTERNET.md)
 
-## Latest Release: v1.9.20 (March 27, 2026)
+## Latest Release: v1.10.0 (August 12, 2026)
 
-**Full Repo Cleanup, Bug Fixes & Bridge Coordination Callbacks**
+**Tunable TCP Connect-Retry Behaviour (issue #378)**
+
+- The five TCP connect-retry values that were hardcoded in `tcp.hpp` are now tunable per mesh instance via `mesh.setTcpRetryConfig()` / `mesh.getTcpRetryConfig()` (#378, PR #395)
+- Defaults match the previous constants exactly — **no behaviour change unless you call the setter**
+- New `examples/tcpRetryConfig/` with real-time, high-reliability and battery-saver profiles
+- `MessageQueue` documentation corrected: it is a manual buffer, never an auto-flush queue (#385)
+- `MIN_FREE_MEMORY` / `MAX_MESSAGE_QUEUE` deprecated as ignored no-ops, values preserved for source compatibility (#385)
+- Fixed `bridge_failover` example failing to compile on an unqualified `plugin::` type (#360)
+
+> **npm users:** v1.9.21 was never published to npm ([#381](https://github.com/Alteriom/painlessMesh/issues/381) — expired token). npm's previous version is 1.9.20, so upgrading from npm picks up both releases. GitHub, PlatformIO and Arduino were unaffected.
+
+**Previous Release: v1.9.21 (August 4, 2026)**
+
+**Crash Fixes: Task & TCP Connection Lifecycle (issue #373)**
+
+- Fixed use-after-free in `Task::disable()` that crashed nodes on every peer disconnect (#373, PR #376 by @vaz82)
+- Fixed `PackageHandler::stop()` destroying the currently-executing task during bridge promotion
+- Fixed stale-pcb heap corruption window in `~BufferedConnection()` and an `onError`/`onConnect` double-handling race
+- New AddressSanitizer CI job and regression test for the task/connection cleanup lifecycle
+
+**Previous Release: v1.9.20 (March 27, 2026)** — Full repo cleanup, bug fixes & bridge coordination callbacks:
 
 - New `onBridgeCoordination()` and `onBridgeCoordinationChanged()` monitoring callbacks
 - Fixed 13 critical/high/medium bugs (double-free, RSSI overflow, memory leaks, blocking delays)

package/RELEASE_GUIDE.md

@@ -209,11 +209,22 @@ Each release triggers the **PlatformIO Library Publishing** workflow:
 
 #### Automatic Workflow Trigger
 
-The PlatformIO workflow automatically triggers on:
+The PlatformIO workflow is started by:
 
-- New GitHub releases (tags)
+- The `platformio-dispatch` job in **Automated Release**, which calls
+  `gh workflow run platformio-publish.yml --ref v<version> -f version=<version>`
+  right after the release is created
+- A GitHub release published by a human (via the UI or a PAT)
 - Manual workflow dispatch for testing
 
+> **Why the explicit dispatch?** `platformio-publish.yml` also listens for
+> `release: published`, but that event never fires for releases created by
+> `release.yml`: GitHub suppresses events raised by the built-in `GITHUB_TOKEN`.
+> `workflow_dispatch` is one of the two documented exceptions to that rule, so
+> the release workflow dispatches the publish explicitly and then verifies a run
+> actually appeared. Before this was added, PlatformIO publication silently did
+> not happen and had to be dispatched by hand (v1.9.21).
+
 ### PlatformIO Package Contents
 
 Published package includes:
@@ -454,13 +465,127 @@ npm run build
 npm run test
 ```
 
-**NPM Token Invalid**
+**NPM Token Expired / Invalid (`E401 Unauthorized`)**
+
+Symptom: the `npm-publish` job fails at *Verify NPM authentication* with
+`401 Unauthorized - GET https://registry.npmjs.org/-/whoami`. npm tokens
+expire; everything else in the release (tag, GitHub Release, zip asset,
+GitHub Packages, PlatformIO) succeeds independently, so **the release can look
+green-ish while npmjs.org is missing the version**. Always confirm with
+`npm view @alteriom/painlessmesh version`.
+
+Rotating the token is operator-only — it cannot be automated from CI:
+
 ```bash
-# Verify NPM authentication
-npm whoami
-# If not logged in: npm login
+# 1. Mint a fresh granular token, scoped to @alteriom/painlessmesh, with
+#    "Read and write" AND the "Bypass 2FA" option enabled  <-- see EOTP below
+#    https://www.npmjs.com/settings/tokens
+# 2. Verify the new token before saving it (recommended).
+#    Ask the registry directly — do NOT use a bare `npm whoami`, which answers
+#    for whatever credential your local ~/.npmrc already holds and will happily
+#    pass while the new token is bad:
+curl -sS -H "Authorization: Bearer <new-token>" \
+  https://registry.npmjs.org/-/whoami          # -> {"username":"..."} , not 401
+
+# 3. Update the NPM_TOKEN *organisation* secret — NOT a repository secret.
+#    painlessMesh has no repo-level NPM_TOKEN and must not gain one; see
+#    "Where NPM_TOKEN actually lives" below.
+#    https://github.com/organizations/Alteriom/settings/secrets/actions
+
+# 4a. Re-run the failed release job (keeps the original run's context)
+gh run rerun <run-id> --failed --repo Alteriom/painlessMesh
+
+# 4b. …or republish a missed version out-of-band. Pass the TAG as ref:
+#     without it the workflow builds the default branch, and if main has moved
+#     on since the tag it would upload today's code under the old version
+#     number. The workflow now refuses that outright — pass ref so you never
+#     have to rely on the guard catching it.
+gh workflow run manual-publish.yml --repo Alteriom/painlessMesh \
+  -f ref=v1.9.21 -f publish_npm=true -f publish_github=false
+
+# 5. Confirm the version actually landed
+npm view @alteriom/painlessmesh version
 ```
 
+#### Where NPM_TOKEN actually lives
+
+`NPM_TOKEN` is an **organisation** secret on `Alteriom`, shared by every repo
+that publishes to npm. painlessMesh has **no repository-level copy**, and adding
+one is a trap rather than a tightening:
+
+> A repository secret silently takes precedence over an organisation secret of
+> the same name. The repo then stops seeing org-wide rotations and keeps using
+> its own copy until that copy expires — which is invisible until a release day
+> fails.
+
+Two sibling repos already sit in that state, with repo-level `NPM_TOKEN` copies
+that shadow the org secret (`webhook-client`, `repository-metadata-manager`).
+Rotate the org secret and those two are still broken; delete the repo-level copy
+and they inherit the fresh one. Check before assuming a rotation reached a repo:
+
+```bash
+# Empty output = good (inherits the org secret)
+gh api repos/Alteriom/<repo>/actions/secrets \
+  --jq '.secrets[] | select(.name=="NPM_TOKEN") | "SHADOWED, updated \(.updated_at)"'
+```
+
+While rotating `NPM_TOKEN`, check `PLATFORMIO_AUTH_TOKEN` too — it expires the
+same way and `platformio-publish.yml` hard-fails on an invalid one.
+
+**NPM asks for a one-time password (`EOTP`)**
+
+Symptom: authentication *succeeds* — `npm whoami` prints the username — and then
+`npm publish` fails with:
+
+```
+npm error code EOTP
+npm error This operation requires a one-time password from your authenticator.
+```
+
+The token is valid but is not allowed to bypass 2FA, and CI has no authenticator
+to answer the challenge with. **A rotation that fixes `E401` lands here if the
+replacement token is minted without the bypass option** — which is what happened
+on the second rotation attempt for #381.
+
+npm removed the legacy token types (`read-only` / `automation` / `publish`) in
+**November 2025**; only granular access tokens exist now. The old *Automation*
+token bypassed 2FA by virtue of its type, so this was never a decision anyone had
+to make. On a granular token it is an explicit checkbox, and a token minted from
+muscle memory does not have it:
+
+> **Bypass 2FA** — required. Takes precedence over account-level and
+> package-level 2FA settings for publishing.
+
+Re-mint at <https://www.npmjs.com/settings/tokens> with *Read and write* on
+`@alteriom/painlessmesh` **and Bypass 2FA enabled**, update the secret, re-run.
+`npm whoami` cannot detect this ahead of time — it passes for both token kinds,
+so the failure necessarily surfaces at the publish call.
+
+### Trusted publishing (OIDC) — the way out of token rotation
+
+Both failures above are symptoms of the same thing: a long-lived credential that
+expires silently and is only exercised on release day. npm's replacement is
+**trusted publishing** — the workflow authenticates to npm over OIDC, and
+`NPM_TOKEN` stops existing.
+
+This is on a clock rather than merely being nicer: as of **2026-07-31** bypass-2FA
+tokens can no longer manage tokens, package access, or trusted-publishing config,
+and npm has targeted **January 2027** for removing *direct publish* from them —
+after which they can only stage a publish for a maintainer to approve with 2FA.
+The current setup stops working at that point.
+
+Requirements, none of which this repo blocks on today:
+
+| Requirement | Status here |
+|---|---|
+| `id-token: write` permission | ✅ already set in `release.yml` and `manual-publish.yml` |
+| npm CLI ≥ 11.5.1, Node ≥ 22.14.0 | ❌ workflows pin `node-version: '18'` — needs a bump |
+| Trusted publisher registered on npmjs.com | ❌ operator, one-time, per workflow file |
+
+The npmjs.com side is under *Package settings → Trusted publisher*: org
+`Alteriom`, repository `painlessMesh`, workflow filename `release.yml` (add a
+second entry for `manual-publish.yml` if that path should keep working).
+
 **GitHub Packages Authentication**
 ```bash
 # Check if GITHUB_TOKEN has packages:write permission
@@ -508,11 +633,18 @@ If this happens, you can manually publish packages:
 4. Click **Run workflow**
 
 The manual workflow will:
-- Read the current version from `library.properties`
+- Read the current version from `library.properties` and refuse to run if it
+  disagrees with `package.json` (npm publishes the `package.json` version)
+- Validate `NPM_TOKEN` against the registry before attempting to publish, so an
+  expired token fails immediately with rotation instructions
 - Publish to NPM (if selected)
 - Publish to GitHub Packages (if selected)
 - Show success/failure status for each
 
+It does **not** publish to the PlatformIO registry — use
+`gh workflow run platformio-publish.yml --ref v<version> -f version=<version>`
+for that.
+
 Alternatively, from command line:
 ```bash
 # Trigger via GitHub CLI
@@ -647,9 +779,16 @@ Monitor your releases:
 ### Required GitHub Secrets
 
 - `GITHUB_TOKEN`: Automatically provided by GitHub Actions
-- `NPM_TOKEN`: Required for NPM publishing (add in repository secrets)
+- `NPM_TOKEN`: Required for NPM publishing. Lives in the **Alteriom
+  organisation** secrets and is inherited — do not add a repository-level copy,
+  which would shadow it (see [Where NPM_TOKEN actually lives](#where-npm_token-actually-lives))
 - `PLATFORMIO_AUTH_TOKEN`: Required for PlatformIO Library Registry publishing
 
+Both `NPM_TOKEN` and `PLATFORMIO_AUTH_TOKEN` are user-minted tokens that
+**expire**. Their expiry is invisible until a release fails, so rotate them
+together and re-check after any expiry date you set. See
+[NPM Token Expired / Invalid](#-troubleshooting) for the rotation runbook.
+
 ### Repository Settings
 - **Actions**: Enabled with write permissions
 - **Packages**: Enabled for GitHub Packages publication

package/examples/alteriom/alteriom_custom_package_template.hpp

@@ -17,7 +17,7 @@
  * QUICK START
  * -----------
  * To create your own custom package:
- *   1. Pick an unused Type ID from the table below (use 203+ range)
+ *   1. Pick an unused Type ID from the table below (use 206+ range)
  *   2. Choose a base class: BroadcastPackage (all nodes) or SinglePackage (one
  *      node)
  *   3. Add your data fields with appropriate types
@@ -30,8 +30,8 @@
  *
  *   200 : SensorPackage      (environmental sensors: temp, humidity, pressure)
  *   202 : StatusPackage      (device health and configuration)
- *   203 : MpptPackage        (MPPT solar charge controller data)  <-- this file
  *   204 : MetricsPackage     (network performance metrics)
+ *   205 : MpptPackage        (MPPT solar charge controller data)  <-- this file
  *   400 : CommandPackage     (device control commands)
  *   600 : MeshNodeListPackage
  *   601 : MeshTopologyPackage
@@ -44,7 +44,7 @@
  *   612 : BridgeTakeoverPackage
  *   614 : NTPTimeSyncPackage
  *
- * Available ranges: 205-399 (add your package here and update this table).
+ * Available ranges: 206-399 (add your package here and update this table).
  *
  *
  * CHOOSING BASE CLASS
@@ -138,15 +138,15 @@
  *   TSTRING  myText  = "";
  *
  *   // MQTT message_type (set to your chosen type ID)
- *   uint16_t messageType = 205;
+ *   uint16_t messageType = 206;
  *
- *   MyCustomPackage() : BroadcastPackage(205) {}
+ *   MyCustomPackage() : BroadcastPackage(206) {}
  *
  *   MyCustomPackage(JsonObject jsonObj) : BroadcastPackage(jsonObj) {
  *     myId        = jsonObj["id"];
  *     myValue     = jsonObj["val"];
  *     myText      = jsonObj["txt"].as<TSTRING>();
- *     messageType = jsonObj["message_type"] | 205;
+ *     messageType = jsonObj["message_type"] | 206;
  *   }
  *
  *   JsonObject addTo(JsonObject&& jsonObj) const {
@@ -173,7 +173,7 @@
  * CONCRETE EXAMPLE: MpptPackage
  * ==============================
  *
- * The MpptPackage (Type 203) transmits real-time telemetry from an MPPT solar
+ * The MpptPackage (Type 205) transmits real-time telemetry from an MPPT solar
  * charge controller (e.g. Renegy, Epever, Victron).  It is a BroadcastPackage
  * so every node in the mesh receives the data automatically.
  *
@@ -219,7 +219,7 @@ enum ChargeState : uint8_t {
  * values from your hardware, assign them to the struct fields, then call
  * sendBroadcast() as shown in alteriom_mppt_example.ino.
  *
- * Type ID: 203
+ * Type ID: 205
  */
 class MpptPackage : public painlessmesh::plugin::BroadcastPackage {
  public:
@@ -247,13 +247,13 @@ class MpptPackage : public painlessmesh::plugin::BroadcastPackage {
   uint32_t timestamp = 0;
 
   // MQTT Schema message_type for fast classification at the bridge
-  uint16_t messageType = 203;  // MPPT_DATA
+  uint16_t messageType = 205;  // MPPT_DATA
 
   // -------------------------------------------------------------------------
   // Constructors
   // -------------------------------------------------------------------------
 
-  MpptPackage() : BroadcastPackage(203) {}
+  MpptPackage() : BroadcastPackage(205) {}
 
   /**
    * @brief Deserialise from a JSON object received over the mesh
@@ -272,7 +272,7 @@ class MpptPackage : public painlessmesh::plugin::BroadcastPackage {
     controllerTemp = jsonObj["ct"];
     deviceId = jsonObj["did"];
     timestamp = jsonObj["ts"];
-    messageType = jsonObj["message_type"] | 203;
+    messageType = jsonObj["message_type"] | 205;
   }
 
   // -------------------------------------------------------------------------

package/examples/alteriom/mppt_example/alteriom_mppt_example.ino

@@ -149,7 +149,7 @@ void handleIncomingPackage(uint32_t from, String& msg) {
   uint16_t msgType = obj["type"];
 
   switch (msgType) {
-    case 203: {  // MpptPackage
+    case 205: {  // MpptPackage
       MpptPackage received(obj);
       Serial.printf(
           "MPPT from %u: PV=%.1fV/%.1fA/%dW  Bat=%.1fV/%d%%  "

package/examples/bridge_failover/bridge_failover.ino

@@ -240,7 +240,7 @@ void setup() {
 
   // Monitor bridge coordination (fires every ~30s per bridge)
   mesh.onBridgeCoordination(
-    [](const plugin::BridgeCoordinationPackage& pkg, uint32_t fromNode) {
+    [](const painlessmesh::plugin::BridgeCoordinationPackage& pkg, uint32_t fromNode) {
       Serial.printf("Bridge %u: priority=%d, load=%d%%\n",
                     fromNode, pkg.priority, pkg.load);
     }
@@ -248,7 +248,7 @@ void setup() {
 
   // Get notified when bridge state changes (new/updated/lost)
   mesh.onBridgeCoordinationChanged(
-    [](const plugin::BridgeCoordinationPackage& pkg, uint32_t fromNode,
+    [](const painlessmesh::plugin::BridgeCoordinationPackage& pkg, uint32_t fromNode,
        TSTRING changeType) {
       Serial.printf("Bridge %s: %u (role=%s)\n",
                     changeType.c_str(), fromNode, pkg.role.c_str());

package/examples/tcpRetryConfig/README.md

@@ -0,0 +1,110 @@
+# tcpRetryConfig
+
+Tuning painlessMesh's TCP connection retry behaviour with
+`setTcpRetryConfig()` (issue
+[#378](https://github.com/Alteriom/painlessMesh/issues/378)).
+
+## What this controls
+
+When a node acquires an IP and tries to open its TCP connection to the mesh,
+that connection can fail — the parent's TCP server may not be ready yet, the
+network stack may still be settling, or several nodes may be connecting at
+once. painlessMesh retries with exponential backoff before giving up and
+falling back to a full WiFi reconnect.
+
+Five parameters describe that behaviour:
+
+| Field | Default | Meaning |
+|---|---|---|
+| `maxRetries` | 5 | TCP connect attempts after the first before giving up |
+| `retryDelayMs` | 1000 | Base delay between retries; scaled 1x, 2x, 4x, 8x, 8x |
+| `stabilizationDelayMs` | 500 | Wait after IP acquisition before the first attempt |
+| `exhaustionReconnectDelayMs` | 10000 | Wait before the WiFi reconnect that follows exhaustion |
+| `failureBlockDurationMs` | 60000 | How long a failed peer is skipped during AP selection |
+
+With the defaults, a node that cannot reach its parent spends
+1 + 2 + 4 + 8 + 8 = **23 s** retrying, then waits another **10 s** before
+reconnecting WiFi, and will not re-select that same peer for **60 s**.
+
+## Profiles in this sketch
+
+Switch with `#define ACTIVE_PROFILE`.
+
+| | `PROFILE_REALTIME` | default | `PROFILE_RELIABLE` | `PROFILE_BATTERY` |
+|---|---|---|---|---|
+| `maxRetries` | 1 | 5 | 10 | 2 |
+| `retryDelayMs` | 200 | 1000 | 2000 | 3000 |
+| `stabilizationDelayMs` | 100 | 500 | 1000 | 500 |
+| `exhaustionReconnectDelayMs` | 1000 | 10000 | 30000 | 60000 |
+| `failureBlockDurationMs` | 5000 | 60000 | 180000 | 300000 |
+| worst-case retry time | 0.2 s | 23 s | 126 s | 9 s |
+| full failure cycle | 1.2 s | 33 s | 156 s | 69 s |
+
+- **`PROFILE_REALTIME`** — real-time sensor and LED meshes, the use case from
+  [discussion #368](https://github.com/Alteriom/painlessMesh/discussions/368).
+  A node stuck in a 23 s backoff is worse than one that drops and re-scans, so
+  fail fast and move on.
+- **`PROFILE_RELIABLE`** — industrial meshes where getting connected matters
+  more than how long it takes. `maxRetries = 10` is the maximum the library
+  accepts.
+- **`PROFILE_BATTERY`** — every retry is radio-on time. Few attempts, spaced
+  widely, and a long blocklist so the node stops waking up for a peer that is
+  known to be down.
+
+## Clamping
+
+`setTcpRetryConfig()` coerces the two values that can render a node unusable:
+
+- `maxRetries` is capped at **10**. Each retry allocates an `AsyncClient` and
+  schedules a task, so an unbounded value is a heap and recursion-depth hazard
+  on ESP8266.
+- `retryDelayMs` is held between **50 ms** and **60000 ms**. A zero delay would
+  schedule retries with no spacing — a hot loop allocating an `AsyncClient`
+  every scheduler tick. The ceiling keeps `retryDelayMs * 8` clear of `uint32_t`
+  overflow.
+
+Everything else passes through untouched, including zeros, which are
+meaningful:
+
+- `maxRetries = 0` — do not retry at all; fall straight back to a WiFi
+  reconnect on the first TCP error.
+- `stabilizationDelayMs = 0` — attempt the TCP connection immediately on IP
+  acquisition.
+- `exhaustionReconnectDelayMs = 0` — reconnect WiFi immediately after
+  exhaustion.
+- `failureBlockDurationMs = 0` — never blocklist a failed peer.
+
+Call `getTcpRetryConfig()` after setting to see what actually took effect; the
+sketch prints this at startup.
+
+## The defaults exist for a reason
+
+painlessMesh 1.9.x deliberately *raised* these values (retries 3 → 5, base
+delay 500 ms → 1000 ms) to fix real-world mesh instability. Tuning them back
+down reintroduces the problems that change fixed. Symptoms of an over-aggressive
+profile:
+
+- **Connection churn** — nodes repeatedly connect and drop. `maxRetries` is too
+  low for how long your parent actually takes to be ready; raise it or raise
+  `stabilizationDelayMs`.
+- **Rapid reconnect loops / network congestion** — a node hammers a parent whose
+  TCP server is down. `exhaustionReconnectDelayMs` is too short.
+- **The same dead peer is picked over and over** — `failureBlockDurationMs` is
+  shorter than one full retry-plus-reconnect cycle, so the peer comes off the
+  blocklist before the node has finished failing over. Keep
+  `failureBlockDurationMs` greater than
+  `(sum of retry backoffs) + exhaustionReconnectDelayMs`. All three profiles
+  above satisfy this; `catch_tcp_blocklist.cpp` pins it as a test.
+
+Change one parameter at a time and watch the serial log with
+`mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION)`.
+
+## Building
+
+```bash
+# PlatformIO
+pio run -e esp32     # or -e esp8266
+
+# Arduino CLI
+arduino-cli compile --fqbn esp32:esp32:esp32 examples/tcpRetryConfig/tcpRetryConfig.ino
+```

package/examples/tcpRetryConfig/platformio.ini

@@ -0,0 +1,26 @@
+[platformio]
+src_dir = .
+
+[env]
+lib_deps =
+    bblanchon/ArduinoJson
+    arkhipenko/TaskScheduler
+
+lib_ldf_mode = deep+
+[env:esp8266]
+platform = espressif8266
+board = nodemcuv2
+framework = arduino
+lib_extra_dirs = ../../
+lib_deps =
+    ${env.lib_deps}  ; Inherit common dependencies
+    esp32async/ESPAsyncTCP@^2.0.0  ; Only for ESP8266
+
+[env:esp32]
+platform = espressif32
+board = esp32dev
+framework = arduino
+lib_extra_dirs = ../../
+lib_deps =
+    ${env.lib_deps}  ; Inherit common dependencies
+    esp32async/AsyncTCP