@alteriom/painlessmesh 1.10.0 → 2.0.1

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`.

package/README.md

@@ -4,15 +4,14 @@
 
 <div align="center">
 
-**Version 1.10.0** - Tunable TCP connect-retry behaviour via `setTcpRetryConfig()` (#378)
+**Version 2.0.0** — delivery confirmation, a unified send path, and gateway failover, routing and channel following validated on a six-family hardware rig
 
 [![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)
 [![Release](https://github.com/Alteriom/painlessMesh/actions/workflows/release.yml/badge.svg)](https://github.com/Alteriom/painlessMesh/actions/workflows/release.yml)
 [![GitHub release](https://img.shields.io/github/v/release/Alteriom/painlessMesh?label=version)](https://github.com/Alteriom/painlessMesh/releases)
 [![NPM Version](https://img.shields.io/npm/v/@alteriom/painlessmesh?label=npm)](https://www.npmjs.com/package/@alteriom/painlessmesh)
-[![PlatformIO Registry](https://badges.registry.platformio.org/packages/alteriom/library/AlteriomPainlessMesh.svg)](https://registry.platformio.org/libraries/alteriom/AlteriomPainlessMesh)
-[![Arduino Library Manager](https://img.shields.io/badge/Arduino-Library%20Manager-blue.svg)](https://www.arduino.cc/reference/en/libraries/alteriompainlessmesh/)
+[![PlatformIO Registry](https://badges.registry.platformio.org/packages/sparck75/library/AlteriomPainlessMesh.svg)](https://registry.platformio.org/libraries/sparck75/AlteriomPainlessMesh)
 
 </div>
 
@@ -156,12 +155,13 @@ See [BRIDGE_TO_INTERNET.md](BRIDGE_TO_INTERNET.md) for complete documentation.
 
 **High Availability for Critical Systems**
 
-- 🎯 **RSSI-Based Election** - Best signal strength wins bridge role
-- 🔍 **Automatic Detection** - 60-second failure detection via heartbeats
-- ⚡ **Fast Failover** - 60-70 second typical recovery time
-- 🌐 **Distributed Consensus** - No single coordinator, deterministic winner selection
-- 🛡️ **Split-Brain Prevention** - State machine prevents concurrent elections
-- 📊 **Tiebreaker Rules** - RSSI → Uptime → Memory → Node ID
+- 🎯 **RSSI-Based Election** - Best router signal wins the bridge role; ties go to uptime, then free memory, then node ID
+- 📣 **A bridge that stops cleanly says so** - `mesh.stop()` on a bridge announces it is leaving, and the candidates hold their election within seconds
+- 🔍 **Heartbeat Detection** - A bridge that loses power is noticed when its last status ages out: the bridge timeout (60 s) plus up to one 30 s monitor tick
+- 🏠 **The mesh follows the bridge** - Peers learn the elected bridge's channel from the takeover message and treat it as home; a node that loses its uplink there rescans that channel first
+- 🌐 **Distributed Consensus** - No single coordinator; every node evaluates the same candidates by the same rules
+- 🛡️ **Split-Brain Prevention** - One election at a time, a 60 s hold between role changes, and a minimum router RSSI for a lone candidate
+- 🔬 **Validated on hardware** - The failover scenario runs on the Alteriom rig with a real router; see [CHANGELOG.md](CHANGELOG.md)
 
 **Use Cases:**
 - Fish farm alarm systems requiring 24/7 Internet connectivity
@@ -184,7 +184,7 @@ void bridgeRoleCallback(bool isBridge, const String& reason) {
 
 See [bridge_failover example](examples/bridge_failover/) for complete documentation.
 
-#### 🌉 Multi-Bridge Coordination (v1.8.2)
+#### 🌉 Multi-Bridge Coordination
 
 **Enterprise Load Balancing and Geographic Redundancy**
 
@@ -232,7 +232,7 @@ mesh.onBridgeCoordinationChanged(
 
 See [BRIDGE_TO_INTERNET.md](BRIDGE_TO_INTERNET.md) for multi-bridge documentation.
 
-#### 📬 Message Queue for Offline Mode (v1.8.2)
+#### 📬 Message Queue for Offline Mode
 
 **Zero Data Loss During Internet Outages**
 
@@ -255,14 +255,15 @@ See [BRIDGE_TO_INTERNET.md](BRIDGE_TO_INTERNET.md) for multi-bridge documentatio
 // Enable message queue with max 100 messages
 mesh.enableMessageQueue(true, 100);
 
-// Queue critical alarm message
+// Queue a critical alarm for the Internet endpoint; it is sent when a
+// gateway with Internet is available and never evicted by lower priorities
 String criticalAlarm = "{\"sensor\":\"O2\",\"value\":2.5,\"alarm\":true}";
-mesh.queueMessage(bridgeNodeId, criticalAlarm);
+mesh.queueMessage(criticalAlarm, "https://api.example.com/alarm", PRIORITY_CRITICAL);
 ```
 
 See [BRIDGE_TO_INTERNET.md](BRIDGE_TO_INTERNET.md) for message queue documentation.
 
-#### 🌐 Shared Gateway Mode (v1.9.0+)
+#### 🌐 Shared Gateway Mode
 
 **All Nodes as Internet Gateways with Automatic Failover**
 
@@ -298,8 +299,8 @@ mesh.sendToInternet(
 );
 
 // Monitor gateway changes
-mesh.onGatewayChanged([](uint32_t newGateway) {
-    Serial.printf("Primary gateway: %u\n", newGateway);
+mesh.onGatewayChanged([](uint32_t oldGateway, uint32_t newGateway) {
+    Serial.printf("Primary gateway: %u -> %u\n", oldGateway, newGateway);
 });
 ```
 
@@ -331,6 +332,32 @@ The library handles routing and network management automatically, so you can foc
 
 painlessMesh is a true ad-hoc network, meaning that no-planning, central controller, or router is required. Any system of 1 or more nodes will self-organize into fully functional mesh. The maximum size of the mesh is limited (we think) by the amount of memory in the heap that can be allocated to the sub-connections buffer and so should be really quite high.
 
+### ESP8266 capacity
+
+The ESP8266 is specified for **small meshes**, or as a **leaf** in larger ones.
+Measured as an interior node of a seven-node mesh it runs at 10–13 KB free —
+a working set that tracks its live connections and the traffic through them,
+not a leak — and at that level a single 8 KB package or one OTA part can fail
+to allocate. That is the part's limit, not a library defect. Every ESP32
+family holds within a few percent of its starting heap in the same mesh.
+
+Configure an ESP8266 as a leaf with `init(..., maxconn = 0)` (or `1` to allow
+one child). The library checks every thirty seconds on ESP8266 and logs an
+`ERROR` when the node is below 12 KB free with more than one child attached;
+`mesh.overCapacity()` reports the same condition to the sketch, and
+`mesh.apChildren()` says how many are attached.
+
+### Validated on hardware
+
+Every 2.0 change to failover, routing, channel following and the station
+scan was found in the serial logs of the Alteriom hardware-in-the-loop rig —
+an ESP32, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-S3 and ESP8266 in one mesh with
+a real router — and confirmed there. The release gate is three consecutive
+clean runs of the rig's whole suite (mesh formation, delivery and
+acknowledgement, priorities, dedicated and shared gateways, Internet relay,
+gateway failover, mesh OTA, sustained soak). Each fix in the changelog names
+the run that found it.
+
 ### JSON based
 
 painlessMesh uses JSON objects for all its messaging. There are a couple of reasons for this. First, it makes the code and the messages human readable and painless to understand and second, it makes it painless to integrate painlessMesh with javascript front-ends, web applications, and other apps. Some performance is lost, but I haven’t been running into performance issues yet. Converting to binary messaging would be fairly straight forward if someone wants to contribute.
@@ -341,29 +368,29 @@ painlessMesh is designed to be used with Arduino, but it does not use the Arduin
 
 ### painlessMesh is not IP networking
 
-painlessMesh does not create a TCP/IP network of nodes. Rather each of the nodes is uniquely identified by its 32bit chipId which is retrieved from the esp8266/esp32 using the `system_get_chip_id()` call in the SDK. Every node will have a unique number. Messages can either be broadcast to all the nodes on the mesh, or sent specifically to an individual node which is identified by its `nodeId.
+painlessMesh does not create a TCP/IP network of nodes. Rather each of the nodes is uniquely identified by its 32bit chipId which is retrieved from the esp8266/esp32 using the `system_get_chip_id()` call in the SDK. Every node will have a unique number. Messages can either be broadcast to all the nodes on the mesh, or sent specifically to an individual node which is identified by its `nodeId`.
 
 ### Limitations and caveats
 
 - Try to avoid using `delay()` in your code. To maintain the mesh we need to perform some tasks in the background. Using `delay()` will stop these tasks from happening and can cause the mesh to lose stability/fall apart. Instead, we recommend using [TaskScheduler](http://playground.arduino.cc/Code/TaskScheduler) which is used in `painlessMesh` itself. Documentation can be found [here](https://github.com/arkhipenko/TaskScheduler/wiki/Full-Document). For other examples on how to use the scheduler see the example folder.
 - `painlessMesh` subscribes to WiFi events. Please be aware that as a result `painlessMesh` can be incompatible with user programs/other libraries that try to bind to the same events.
 - Try to be conservative in the number of messages (and especially broadcast messages) you sent per minute. This is to prevent the hardware from overloading. Both esp8266 and esp32 are limited in processing power/memory, making it easy to overload the mesh and destabilize it. And while `painlessMesh` tries to prevent this from happening, it is not always possible to do so.
-- Messages can go missing or be dropped due to high traffic and you can not rely on all messages to be delivered. One suggestion to work around is to resend messages every so often. Even if some go missing, most should go through. Another option is to have your nodes send replies when they receive a message. The sending nodes can the resend the message if they haven’t gotten a reply in a certain amount of time.
+- Messages can go missing or be dropped due to high traffic and you can not rely on all messages to be delivered. One suggestion to work around is to resend messages every so often. Even if some go missing, most should go through. Another option is to have your nodes send replies when they receive a message. The sending nodes can then resend the message if they haven’t gotten a reply in a certain amount of time.
 
 ## Installation
 
 ### Arduino Library Manager
 
-**Once registered**, installation will be available via Arduino IDE:
+The library is in the Arduino Library Manager as **Alteriom PainlessMesh**:
 
 1. Open Arduino IDE
 2. Go to **Tools** → **Manage Libraries...**
-3. Search for **"AlteriomPainlessMesh"**
-4. Click **Install**
+3. Search for **"Alteriom PainlessMesh"** and click **Install**; accept the dependencies it offers (ArduinoJson, TaskScheduler, PubSubClient)
+4. Also install **AsyncTCP** (ESP32) or **ESPAsyncTCP** (ESP8266) from the same dialog; the Library Manager cannot pick one per platform, so they are not listed as dependencies
 
-The library includes the header file `AlteriomPainlessMesh.h` which provides access to both the core painlessMesh functionality and Alteriom-specific extensions.
+The index follows a GitHub release within a day. The header `AlteriomPainlessMesh.h` gives access to the core painlessMesh functionality and the Alteriom extensions; `painlessMesh.h` alone gives the core.
 
-#### Manual Installation (Current Method)
+#### Manual Installation
 
 **Option 1: Download ZIP from GitHub Release**
 
@@ -383,7 +410,12 @@ git clone https://github.com/Alteriom/painlessMesh.git AlteriomPainlessMesh
 
 ### PlatformIO
 
-`painlessMesh` is included in both the Arduino Library Manager and the platformio library registry and can easily be installed via either of those methods.
+The library is published on the [PlatformIO registry](https://registry.platformio.org/libraries/sparck75/AlteriomPainlessMesh) as `sparck75/AlteriomPainlessMesh`. The registry also lists an `alteriom/AlteriomPainlessMesh` that stops at 1.10.0; its owner account is not one the project can publish from, so 2.0.0 and later live under `sparck75`, which has carried every automated release since 1.7.6. Name the owner in `lib_deps`, since the bare name matches both:
+
+```ini
+lib_deps =
+    sparck75/AlteriomPainlessMesh@^2.0.0
+```
 
 ### Dependencies
 
@@ -392,7 +424,7 @@ painlessMesh makes use of the following libraries, which can be installed throug
 - [ArduinoJson](https://github.com/bblanchon/ArduinoJson)
 - [TaskScheduler](https://github.com/arkhipenko/TaskScheduler)
 - [ESPAsyncTCP](https://github.com/me-no-dev/ESPAsyncTCP) (ESP8266)
-- [AsyncTCP](https://github.com/ESP32Async/AsyncTCP) (ESP32) - v3.3.0+ required for ESP32-C6
+- [AsyncTCP](https://github.com/ESP32Async/AsyncTCP) (ESP32) - v3.4.7 or later (v3.3.0 was the first to work on the ESP32-C6)
 
 If platformio is used to install the library, then the dependencies will be installed automatically.
 
@@ -502,9 +534,13 @@ These types are used internally by painlessMesh for mesh management and are hand
 | 4 | `TIME_SYNC` | Time synchronization protocol messages |
 | 5 | `NODE_SYNC_REQUEST` | Node discovery and topology requests |
 | 6 | `NODE_SYNC_REPLY` | Node discovery and topology responses |
-| 7 | `CONTROL` | Deprecated control messages |
-| 8 | `BROADCAST` | Internal broadcast routing indicator |
-| 9 | `SINGLE` | Internal single-node routing indicator |
+| 7 | `CONTROL` | Deprecated, unused |
+| 8 | `BROADCAST` | Application data for every node |
+| 9 | `SINGLE` | Application data for one node |
+| 620 | `GATEWAY_DATA` | An Internet request routed to a gateway (`sendToInternet()`) |
+| 621 | `GATEWAY_ACK` | The gateway's answer to it |
+| 622 | `GATEWAY_HEARTBEAT` | Gateway health monitoring |
+| 630 | `MESSAGE_ACK` | Delivery confirmation for a message sent with a callback (2.0) |
 
 **Note**: These protocol types are managed automatically by painlessMesh and are not typically used in application code.
 
@@ -516,19 +552,19 @@ These are the message types used by applications built on painlessMesh:
 |------|-------|---------|--------|
 | 200 | `SensorPackage` | Environmental data | `temperature`, `humidity`, `pressure`, `sensorId`, `timestamp`, `batteryLevel` |
 | 202 | `StatusPackage` | Health monitoring | `deviceStatus`, `uptime`, `freeMemory`, `wifiStrength`, `firmwareVersion` |
-| 204 | `MetricsPackage` | Sensor metrics (v1.7.7+, aligns with schema v0.7.2+) | `cpuUsage`, `freeHeap`, `bytesReceived`, `currentThroughput`, `connectionQuality`, `wifiRSSI` |
-| 400 | `CommandPackage` | Device control (v1.7.7+, moved from 201) | `command`, `targetDevice`, `parameters`, `commandId` |
-| 600 | `MeshNodeListPackage` | Mesh node list (v1.7.7+, MESH_NODE_LIST) | `nodes[]` (nodeId, status, lastSeen, signalStrength), `nodeCount`, `meshId` |
-| 601 | `MeshTopologyPackage` | Mesh topology (v1.7.7+, MESH_TOPOLOGY) | `connections[]` (fromNode, toNode, linkQuality, latencyMs), `rootNode` |
-| 602 | `MeshAlertPackage` | Mesh alerts (v1.7.7+, MESH_ALERT) | `alerts[]` (alertType, severity, message, nodeId), `alertCount` |
-| 603 | `MeshBridgePackage` | Mesh bridge (v1.7.7+, MESH_BRIDGE) | `meshProtocol`, `fromNodeId`, `toNodeId`, `meshType`, `rawPayload`, `rssi`, `hopCount` |
+| 204 | `MetricsPackage` | Sensor metrics (schema v0.7.2+) | `cpuUsage`, `freeHeap`, `bytesReceived`, `currentThroughput`, `connectionQuality`, `wifiRSSI` |
+| 400 | `CommandPackage` | Device control | `command`, `targetDevice`, `parameters`, `commandId` |
+| 600 | `MeshNodeListPackage` | Mesh node list (`MESH_NODE_LIST`) | `nodes[]` (nodeId, status, lastSeen, signalStrength), `nodeCount`, `meshId` |
+| 601 | `MeshTopologyPackage` | Mesh topology (`MESH_TOPOLOGY`) | `connections[]` (fromNode, toNode, linkQuality, latencyMs), `rootNode` |
+| 602 | `MeshAlertPackage` | Mesh alerts (`MESH_ALERT`) | `alerts[]` (alertType, severity, message, nodeId), `alertCount` |
+| 603 | `MeshBridgePackage` | Mesh bridge (`MESH_BRIDGE`) | `meshProtocol`, `fromNodeId`, `toNodeId`, `meshType`, `rawPayload`, `rssi`, `hopCount` |
 | 604 | `EnhancedStatusPackage` | Mesh status (MESH_STATUS per schema v0.7.2+) | `nodeCount`, `connectionCount`, `messagesReceived`, `messagesSent`, `avgLatency`, `packetLossRate` |
-| 605 | `HealthCheckPackage` | Mesh metrics (v1.7.7+, MESH_METRICS per schema v0.7.2+) | `healthStatus`, `problemFlags`, `memoryHealth`, `networkHealth`, `performanceHealth`, `recommendations` |
-| 610 | `BridgeStatusPackage` | Bridge health monitoring (v1.8.0+, BRIDGE_STATUS per schema v0.7.3+) | `internetConnected`, `routerRSSI`, `routerChannel`, `uptime`, `gatewayIP`, `timestamp` |
-| 611 | `BridgeElectionPackage` | Bridge failover election (v1.8.0+, BRIDGE_ELECTION per schema v0.7.3+) | `routerRSSI`, `uptime`, `freeMemory`, `timestamp`, `routerSSID` |
-| 612 | `BridgeTakeoverPackage` | Bridge role announcement (v1.8.0+, BRIDGE_TAKEOVER per schema v0.7.3+) | `previousBridge`, `reason`, `timestamp` |
-| 613 | `BridgeCoordinationPackage` | Multi-bridge coordination (v1.8.2+, BRIDGE_COORDINATION) | `priority`, `role`, `peerBridges[]`, `load`, `timestamp` |
-| 614 | `NTPTimeSyncPackage` | NTP time synchronization (v1.8.0+, TIME_SYNC_NTP per schema v0.7.3+) | `ntpTime`, `accuracy`, `source`, `timestamp` |
+| 605 | `HealthCheckPackage` | Mesh metrics (`MESH_METRICS`, schema v0.7.2+) | `healthStatus`, `problemFlags`, `memoryHealth`, `networkHealth`, `performanceHealth`, `recommendations` |
+| 610 | `BridgeStatusPackage` | Bridge health monitoring (`BRIDGE_STATUS`) | `internetConnected`, `routerRSSI`, `routerChannel`, `uptime`, `gatewayIP`, `timestamp` |
+| 611 | `BridgeElectionPackage` | Bridge failover election (`BRIDGE_ELECTION`) | `routerRSSI`, `routerChannel`, `uptime`, `freeMemory`, `timestamp`, `routerSSID` |
+| 612 | `BridgeTakeoverPackage` | Bridge role announcement (`BRIDGE_TAKEOVER`) | `previousBridge`, `reason`, `routerChannel`, `timestamp` |
+| 613 | `BridgeCoordinationPackage` | Multi-bridge coordination (`BRIDGE_COORDINATION`) | `priority`, `role`, `peerBridges[]`, `load`, `timestamp` |
+| 614 | `NTPTimeSyncPackage` | NTP time synchronization (`TIME_SYNC_NTP`) | `ntpTime`, `accuracy`, `source`, `timestamp` |
 
 ## Key Features
 
@@ -560,54 +596,25 @@ 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.10.0 (August 12, 2026)
-
-**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)**
+## Latest Release: v2.0.1 (September 7, 2026)
 
-- 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
+**A packaging fix over 2.0.0 — no library behaviour changed.** 2.0.0's installation instructions named a PlatformIO package that has no 2.0.0 (`alteriom/…` stops at 1.10.0; releases go out under `sparck75`), and its GitHub release carries no library archive because the upload was refused by an immutable release. Both are fixed; upgrading from 2.0.0 is optional.
 
-**Previous Release: v1.9.20 (March 27, 2026)** — Full repo cleanup, bug fixes & bridge coordination callbacks:
+**2.0.0 — delivery confirmation, a unified send path, and a mesh that holds together on real hardware**
 
-- New `onBridgeCoordination()` and `onBridgeCoordinationChanged()` monitoring callbacks
-- Fixed 13 critical/high/medium bugs (double-free, RSSI overflow, memory leaks, blocking delays)
-- Removed ~3,600 lines of dead code and 40 AI-generated docs
-- Fixed all CI/CD workflows (corrected action versions)
-- Removed 15 fake test files, fixed test infrastructure
-- Documentation consistency audit — fixed broken links, API examples, version references
-
-**Recent Key Features (v1.9.0 - v1.9.16):**
-
-- 🔍 **Mesh Connectivity Detection** - New `hasActiveMeshConnections()` and `getLastKnownBridge()` APIs
-- 🌉 **Improved Bridge Detection** - `getPrimaryBridge()` returns last known bridge when disconnected
-- ⚡ **Enhanced TCP Reliability** - Exponential backoff and increased retries for mesh connections
-- 🛡️ **Race Condition Fixes** - Improved bridge status and connection validation
-- 📦 **Consolidated Examples** - Streamlined to 15 essential examples
-- ⚙️ **Configurable Election Timing** - Prevent split-brain with `setElectionStartupDelay()` and `setElectionRandomDelay()`
+- `sendSingle()` and `sendBroadcast()` accept a delivery callback — it fires with `delivered=true` and the round-trip latency on acknowledgment, or `delivered=false` on timeout — and a `SendOptions` struct that carries a priority and a callback in one call. Priority is kept across hops.
+- Thirty-odd defects in gateway failover, channel following, routing and the station scan, every one found in the serial logs of a six-family hardware rig and fixed there: a bridge that stops says so, the mesh follows an elected bridge to its channel and treats it as home, a node is in one place in every neighbour's tree, a dead connection is not a route, a stale scan does not consume a live one.
+- The ESP32-C5 and ESP32-C6 (Arduino core 3.x) no longer hang after a channel follow; the ESP8266 is specified for small meshes or as a leaf, and says so at runtime.
+- Gateway HTTP work is bounded by `NODE_TIMEOUT`, so an Internet request can no longer partition the mesh around its own gateway.
+- The release candidate passed the rig's whole suite three times in a row. Delivery confirmation and cross-hop priority need 2.0 on every node of the path.
 
 **[📋 Full CHANGELOG](CHANGELOG.md)**
 
 ## Getting Help
 
-- **[FAQ](USER_GUIDE.md)** - Common questions and solutions
-- **[Common Issues](USER_GUIDE.md)** - Troubleshooting guide
+- **[Troubleshooting](USER_GUIDE.md#troubleshooting)** - Common issues, debug configuration, best practices
+- **[FAQ](docsify-site/troubleshooting/faq.md)** - Frequently asked questions
 - **[GitHub Issues](https://github.com/Alteriom/painlessMesh/issues)** - Bug reports and feature requests
-- **[Community Forum](https://groups.google.com/forum/#!forum/painlessmesh-user)** - Community support
 - **[API Documentation](https://alteriom.github.io/painlessMesh/#/api/doxygen)** - Generated API docs
 
 ## Development
@@ -625,7 +632,8 @@ run-parts --regex catch_ bin/  # Run tests
 
 ### Requirements
 
-- **ESP32/ESP8266**: Arduino Core 2.0.0+
+- **ESP32**: Arduino core 2.0.x or 3.x; the ESP32-C5 and ESP32-C6 need 3.x
+- **ESP8266**: Arduino core 3.x
 - **Dependencies**: ArduinoJson 7.x, TaskScheduler 4.x  
 - **Development**: CMake, Ninja, Boost (for desktop testing)
 
@@ -678,7 +686,7 @@ painlessMesh features a state-of-the-art automated CI/CD pipeline:
 ./scripts/validate-release.sh    # Validate release readiness
 
 # Edit CHANGELOG.md, then commit with release prefix
-git commit -am "release: v1.5.7"
+git commit -am "release: vX.Y.Z"
 git push origin main  # Triggers automated release
 ```
 
@@ -686,13 +694,8 @@ See [RELEASE_GUIDE.md](RELEASE_GUIDE.md) for complete release documentation.
 
 ## 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. For more details see the [CONTRIBUTING.md](CONTRIBUTING.md) file.
-
-## Funding
-
-If you like the library please consider supporting its development. Your contributions help me spend more time improving painlessMesh.
+Pull requests go to `Feat/next-release`, the integration branch for the next version; `main` holds released code and a push to it publishes a release. For branches, tests and what a pull request needs to show, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
-**[Donate via PayPal](https://www.paypal.com/paypalme/domlavoie)** • [dominic.lavoie@gmail.com](mailto:dominic.lavoie@gmail.com)
 
 ## 📚 Documentation
 
@@ -708,18 +711,18 @@ If you like the library please consider supporting its development. Your contrib
 ### 🚀 Quick Links
 
 **New to AlteriomPainlessMesh?**
-- [Quick Start](USER_GUIDE.md) - Get your first mesh running in 5 minutes
-- [Installation](USER_GUIDE.md) - Arduino IDE and PlatformIO setup
-- [First Mesh](USER_GUIDE.md) - Build a multi-node network
+- [Quick Start](USER_GUIDE.md#getting-started) - Get your first mesh running in 5 minutes
+- [Installation](USER_GUIDE.md#installation) - Arduino IDE and PlatformIO setup
+- [First Mesh](USER_GUIDE.md#your-first-mesh-network) - Build a multi-node network
 
 **Reference Documentation:**
-- [Core API](USER_GUIDE.md) - painlessMesh class methods
+- [Core API](USER_GUIDE.md#api-reference) - painlessMesh class methods
 - [Alteriom Extensions](examples/alteriom/README.md) - SensorPackage, CommandPackage, StatusPackage
-- [Examples](examples/) - 15 working examples for common scenarios
+- [Examples](examples/) - 18 example directories, 21 sketches, every one compiled for esp32 and esp8266 on each pull request; [.github/DOCUMENTATION.md](.github/DOCUMENTATION.md) lists what each shows
 
 **Need Help?**
-- [FAQ](USER_GUIDE.md) - Frequently asked questions
-- [Common Issues](USER_GUIDE.md) - Troubleshooting guide
+- [Troubleshooting](USER_GUIDE.md#troubleshooting) - Common issues and how to read the logs
+- [FAQ](docsify-site/troubleshooting/faq.md) - Frequently asked questions
 - [GitHub Issues](https://github.com/Alteriom/painlessMesh/issues) - Bug reports and support
 
 ## 🔧 Quick API Reference
@@ -755,7 +758,11 @@ mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
 
 **For complete API documentation, see [USER_GUIDE.md](USER_GUIDE.md#api-reference) or [online docs](https://alteriom.github.io/painlessMesh/#/api/core-api).**
 
-# Funding
+## Funding
+
+If you like the library please consider supporting its development. Your contributions help me spend more time improving painlessMesh.
+
+**[Donate via PayPal](https://www.paypal.com/paypalme/domlavoie)** • [dominic.lavoie@gmail.com](mailto:dominic.lavoie@gmail.com)
 
 Most development of painlessMesh has been done as a hobby, but some specific features have been funded by the companies listed below: