painlessmesh

AlteriomPainlessMesh is a fork of the painlessMesh library for building self-organizing mesh networks on ESP8266 and ESP32 devices. It keeps the original ad-hoc networking model — no central controller or router required, nodes identified by 32-bit chip IDs, JSON-based messaging, time sync across nodes — and layers on structured packages aimed at IoT deployments. Core mesh behavior - True ad-hoc networking: any set of one or more nodes self-organizes into a mesh; size is bounded mainly by heap available for connection buffers. - JSON messaging for readability and easy integration with web/JavaScript front ends; the README notes some performance cost and that binary messaging would be a possible contribution. - Networking uses the native ESP32/ESP8266 SDK libraries rather than the Arduino WiFi libraries, for latency reasons. - Not IP networking: messages are broadcast or sent to a specific nodeId. - Documented caveats: avoid delay() (use TaskScheduler), beware WiFi event subscription conflicts, keep message rates conservative, and expect possible message loss under high traffic. Alteriom extensions The fork adds typed packages with serialization and JSON conversion, aligned with an mqtt-schema (v0.7.2/v0.7.3) for IoT integration: - SensorPackage (200): temperature, humidity, pressure, battery, sensor ID, timestamp. - StatusPackage (202): status flags, uptime, free memory, WiFi strength, firmware version. - CommandPackage (400): targeted commands with JSON parameters and unique IDs. - MetricsPackage (204): CPU, memory health, network throughput, packet stats, latency, RSSI. - HealthCheckPackage (605): health scoring, problem flags, memory-leak trend analysis, predictive maintenance, crash/reboot tracking. - MeshNodeListPackage (600), MeshTopologyPackage (601), MeshAlertPackage (602), MeshBridgePackage (603), EnhancedStatusPackage (604): node inventory, topology graph with link quality, alerts, protocol bridging, and detailed mesh statistics. - Bridge failover packages (610-614): bridge status, election, takeover, coordination, and NTP time sync. Operational features - Broadcast OTA distribution: the README claims roughly 98% network traffic reduction for 50+ node meshes and parallel updates scaling to 100+ nodes, enabled by a single parameter. - MQTT status bridge: publishes mesh status/topology for monitoring stacks such as Grafana, InfluxDB and Prometheus, with configurable intervals. - Automatic bridge failover: RSSI-based election (ties broken by uptime, free memory, node ID), heartbeat-based detection of a lost bridge, channel following after takeover, distributed consensus, and split-brain prevention via one election at a time, a 60 s hold between role changes, and a minimum RSSI for a lone candidate. - Multi-bridge coordination: multiple simultaneous bridges with priority levels (1-10), roles (primary/secondary/standby), peer discovery, and load-balancing strategies. - Message queue for offline mode: priority-based queuing (CRITICAL/HIGH/NORMAL/LOW) with eviction rules that protect critical messages, automatic online/offline detection, and auto-flush. - Shared gateway mode: all nodes connect to the same router and can relay to the Internet, with gateway election, deduplication, and delivery confirmation. Hardware validation The README states that 2.0 changes to failover, routing, channel following and station scan were validated on a hardware-in-the-loop rig combining ESP32, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-S3 and ESP8266 with a real router, with a release gate of three consecutive clean runs of the full suite. ESP8266 capacity note The README describes the ESP8266 as suited to small meshes or as a leaf node, reporting 10-13 KB free heap when acting as an interior node in a seven-node mesh, and notes that a single 8 KB package or one OTA part may fail to allocate at that level. It suggests configuring ESP8266 as a leaf with maxconn = 0 or 1, and provides overCapacity() and apChildren() helpers plus a periodic low-memory check. Installation and dependencies Available via Arduino Library Manager as "Alteriom PainlessMesh", via PlatformIO as sparck75/AlteriomPainlessMesh (the README notes an alteriom/ owner entry stops at 1.10.0), and on npm as @alteriom/painlessmesh. Dependencies include ArduinoJson, TaskScheduler, and AsyncTCP (ESP32) or ESPAsyncTCP (ESP8266). Examples in the repository cover a basic sensor node, bridge-to-Internet with auto channel detection, bridge failover, shared gateway, MQTT bridge, and an Alteriom sensor node using the structured packages.