@alteriom/painlessmesh 1.7.8 → 1.8.0

package/docs/troubleshooting/common-issues.md

@@ -2,6 +2,34 @@
 
 This guide covers the most frequently encountered problems when working with painlessMesh and their solutions.
 
+## Platform-Specific Issues
+
+### ESP32-C6 Crashes on Startup
+
+**Symptoms:**
+- Device crashes immediately after mesh initialization
+- Endless reboot loop
+- Error message: `assert failed: tcp_alloc ... (Required to lock TCPIP core functionality!)`
+
+**Solution:**
+
+This is a known compatibility issue with ESP32-C6 and newer ESP32 variants. See the dedicated guide:
+
+📖 **[ESP32-C6 Compatibility Guide](ESP32_C6_COMPATIBILITY.md)**
+
+**Quick Fix:**
+Update your AsyncTCP library to version 3.3.0 or newer, or use the ESP32Async library which includes proper LWIP locking for Arduino ESP32 core 3.1.0+.
+
+For PlatformIO, add to your `platformio.ini`:
+```ini
+lib_deps =
+    esp32async/AsyncTCP @ ^3.4.7
+```
+
+For Arduino IDE, download and install manually from: https://github.com/ESP32Async/AsyncTCP
+
+---
+
 ## Connection Issues
 
 ### Nodes Not Connecting

package/examples/alteriom/alteriom_sensor_package.hpp

@@ -153,6 +153,9 @@ class SensorPackage : public painlessmesh::plugin::BroadcastPackage {
   // Battery level percentage
   uint8_t batteryLevel = 0;
 
+  // MQTT Schema v0.7.3+ message_type for faster classification
+  uint16_t messageType = 200;  // SENSOR_DATA
+
   // Type ID 200 for Alteriom sensors
   SensorPackage() : BroadcastPackage(200) {}
 
@@ -163,6 +166,7 @@ class SensorPackage : public painlessmesh::plugin::BroadcastPackage {
     sensorId = jsonObj["sid"];
     timestamp = jsonObj["ts"];
     batteryLevel = jsonObj["bat"];
+    messageType = jsonObj["message_type"] | 200;
   }
 
   JsonObject addTo(JsonObject&& jsonObj) const {
@@ -173,6 +177,7 @@ class SensorPackage : public painlessmesh::plugin::BroadcastPackage {
     jsonObj["sid"] = sensorId;
     jsonObj["ts"] = timestamp;
     jsonObj["bat"] = batteryLevel;
+    jsonObj["message_type"] = messageType;
     return jsonObj;
   }
 
@@ -193,14 +198,18 @@ class CommandPackage : public painlessmesh::plugin::SinglePackage {
   TSTRING parameters = "";    // Command parameters as JSON string
   uint32_t commandId = 0;     // Unique command identifier for tracking
 
+  // MQTT Schema v0.7.3+ message_type for faster classification
+  uint16_t messageType = 400;  // COMMAND
+
   CommandPackage()
-      : SinglePackage(400) {}  // Type ID 400 (COMMAND per mqtt-schema v0.7.2+)
+      : SinglePackage(400) {}  // Type ID 400 (COMMAND per mqtt-schema v0.7.3+)
 
   CommandPackage(JsonObject jsonObj) : SinglePackage(jsonObj) {
     command = jsonObj["cmd"];
     targetDevice = jsonObj["target"];
     parameters = jsonObj["params"].as<TSTRING>();
     commandId = jsonObj["cid"];
+    messageType = jsonObj["message_type"] | 400;
   }
 
   JsonObject addTo(JsonObject&& jsonObj) const {
@@ -209,6 +218,7 @@ class CommandPackage : public painlessmesh::plugin::SinglePackage {
     jsonObj["target"] = targetDevice;
     jsonObj["params"] = parameters;
     jsonObj["cid"] = commandId;
+    jsonObj["message_type"] = messageType;
     return jsonObj;
   }
 
@@ -305,6 +315,9 @@ class StatusPackage : public painlessmesh::plugin::BroadcastPackage {
   float mqttBackoffMultiplier =
       0.0;  // Backoff multiplier for exponential backoff
 
+  // MQTT Schema v0.7.3+ message_type for faster classification
+  uint16_t messageType = 202;  // SENSOR_STATUS
+
   StatusPackage() : BroadcastPackage(202) {}  // Type ID 202 for Alteriom status
 
   StatusPackage(JsonObject jsonObj) : BroadcastPackage(jsonObj) {
@@ -378,6 +391,9 @@ class StatusPackage : public painlessmesh::plugin::BroadcastPackage {
       mqttMaxRetryMs = mqttRetry["max_retry_ms"] | 0;
       mqttBackoffMultiplier = mqttRetry["backoff_multiplier"] | 0.0;
     }
+
+    // Deserialize message_type field
+    messageType = jsonObj["message_type"] | 202;
   }
 
   JsonObject addTo(JsonObject&& jsonObj) const {
@@ -451,6 +467,9 @@ class StatusPackage : public painlessmesh::plugin::BroadcastPackage {
     mqttRetry["max_retry_s"] = mqttMaxRetryMs / 1000;
     mqttRetry["backoff_multiplier"] = mqttBackoffMultiplier;
 
+    // Serialize message_type field
+    jsonObj["message_type"] = messageType;
+
     return jsonObj;
   }
 
@@ -1146,6 +1165,219 @@ class MeshBridgePackage : public painlessmesh::plugin::BroadcastPackage {
 #endif
 };
 
+/**
+ * @brief Bridge status package for monitoring Internet connectivity (Type 610
+ * - BRIDGE_STATUS)
+ *
+ * This package is broadcast by bridge nodes to inform the mesh about their
+ * Internet connectivity status. Regular nodes can use this information to
+ * decide whether to send data, queue messages, or failover to backup bridges.
+ *
+ * Broadcast interval: Configurable, default 30 seconds
+ * Timeout threshold: 60 seconds (nodes consider bridge offline if no heartbeat)
+ *
+ * Type ID 610 for BRIDGE_STATUS per mqtt-schema v0.7.3+.
+ */
+class BridgeStatusPackage : public painlessmesh::plugin::BroadcastPackage {
+ public:
+  // Bridge connectivity status
+  bool internetConnected = false;  // Is the bridge connected to Internet?
+  int8_t routerRSSI = 0;           // Router WiFi signal strength in dBm
+  uint8_t routerChannel = 0;       // Router WiFi channel
+  uint32_t uptime = 0;             // Bridge uptime in milliseconds
+  TSTRING gatewayIP = "";          // Router gateway IP address
+  uint32_t timestamp = 0;          // Timestamp of status check
+
+  // MQTT Schema v0.7.3+ message_type
+  uint16_t messageType = 610;  // BRIDGE_STATUS
+
+  BridgeStatusPackage() : BroadcastPackage(610) {}
+
+  BridgeStatusPackage(JsonObject jsonObj) : BroadcastPackage(jsonObj) {
+    internetConnected = jsonObj["internetConnected"] | false;
+    routerRSSI = jsonObj["routerRSSI"] | 0;
+    routerChannel = jsonObj["routerChannel"] | 0;
+    uptime = jsonObj["uptime"] | 0;
+    gatewayIP = jsonObj["gatewayIP"].as<TSTRING>();
+    timestamp = jsonObj["timestamp"] | 0;
+    messageType = jsonObj["message_type"] | 610;
+  }
+
+  JsonObject addTo(JsonObject&& jsonObj) const {
+    jsonObj = BroadcastPackage::addTo(std::move(jsonObj));
+    jsonObj["internetConnected"] = internetConnected;
+    jsonObj["routerRSSI"] = routerRSSI;
+    jsonObj["routerChannel"] = routerChannel;
+    jsonObj["uptime"] = uptime;
+    jsonObj["gatewayIP"] = gatewayIP;
+    jsonObj["timestamp"] = timestamp;
+    jsonObj["message_type"] = messageType;
+    return jsonObj;
+  }
+
+#if ARDUINOJSON_VERSION_MAJOR < 7
+  size_t jsonObjectSize() const {
+    return JSON_OBJECT_SIZE(noJsonFields + 7) + gatewayIP.length();
+  }
+#endif
+};
+
+/**
+ * @brief Bridge election package for automatic failover (Type 611 -
+ * BRIDGE_ELECTION)
+ *
+ * When a bridge node goes offline, regular nodes with router credentials can
+ * participate in an election to become the new bridge. Each candidate
+ * broadcasts its RSSI to the router, uptime, and available memory. The node
+ * with the best RSSI wins the election.
+ *
+ * Election process:
+ * 1. Bridge failure detected (no heartbeat for 60+ seconds)
+ * 2. Nodes broadcast BridgeElectionPackage with their router RSSI
+ * 3. 5-second collection window for all candidates
+ * 4. Each node evaluates all candidates locally (deterministic)
+ * 5. Winner promotes itself to bridge, others remain as regular nodes
+ *
+ * Type ID 611 for BRIDGE_ELECTION per mqtt-schema v0.7.3+.
+ */
+class BridgeElectionPackage : public painlessmesh::plugin::BroadcastPackage {
+ public:
+  int8_t routerRSSI = 0;    // Router WiFi signal strength in dBm (-127 to 0)
+  uint32_t uptime = 0;      // Node uptime in milliseconds
+  uint32_t freeMemory = 0;  // Free memory in bytes
+  uint32_t timestamp = 0;   // Election timestamp
+  TSTRING routerSSID = "";  // Router SSID (for verification)
+
+  // MQTT Schema v0.7.3+ message_type
+  uint16_t messageType = 611;  // BRIDGE_ELECTION
+
+  BridgeElectionPackage() : BroadcastPackage(611) {}
+
+  BridgeElectionPackage(JsonObject jsonObj) : BroadcastPackage(jsonObj) {
+    routerRSSI = jsonObj["routerRSSI"] | 0;
+    uptime = jsonObj["uptime"] | 0;
+    freeMemory = jsonObj["freeMemory"] | 0;
+    timestamp = jsonObj["timestamp"] | 0;
+    routerSSID = jsonObj["routerSSID"].as<TSTRING>();
+    messageType = jsonObj["message_type"] | 611;
+  }
+
+  JsonObject addTo(JsonObject&& jsonObj) const {
+    jsonObj = BroadcastPackage::addTo(std::move(jsonObj));
+    jsonObj["routerRSSI"] = routerRSSI;
+    jsonObj["uptime"] = uptime;
+    jsonObj["freeMemory"] = freeMemory;
+    jsonObj["timestamp"] = timestamp;
+    jsonObj["routerSSID"] = routerSSID;
+    jsonObj["message_type"] = messageType;
+    return jsonObj;
+  }
+
+#if ARDUINOJSON_VERSION_MAJOR < 7
+  size_t jsonObjectSize() const {
+    return JSON_OBJECT_SIZE(noJsonFields + 6) + routerSSID.length();
+  }
+#endif
+};
+
+/**
+ * @brief Bridge takeover announcement package (Type 612 - BRIDGE_TAKEOVER)
+ *
+ * After winning the bridge election, the new bridge node broadcasts this
+ * package to inform all mesh nodes that it is now the primary bridge.
+ * This allows nodes to update their bridge tracking and routing tables.
+ *
+ * Type ID 612 for BRIDGE_TAKEOVER per mqtt-schema v0.7.3+.
+ */
+class BridgeTakeoverPackage : public painlessmesh::plugin::BroadcastPackage {
+ public:
+  uint32_t previousBridge = 0;  // Previous bridge node ID (0 if none)
+  TSTRING reason =
+      "";  // Reason for takeover (e.g., "Election winner - best router signal")
+  int8_t routerRSSI = 0;   // New bridge's router signal strength
+  uint32_t timestamp = 0;  // Takeover timestamp
+
+  // MQTT Schema v0.7.3+ message_type
+  uint16_t messageType = 612;  // BRIDGE_TAKEOVER
+
+  BridgeTakeoverPackage() : BroadcastPackage(612) {}
+
+  BridgeTakeoverPackage(JsonObject jsonObj) : BroadcastPackage(jsonObj) {
+    previousBridge = jsonObj["previousBridge"] | 0;
+    reason = jsonObj["reason"].as<TSTRING>();
+    routerRSSI = jsonObj["routerRSSI"] | 0;
+    timestamp = jsonObj["timestamp"] | 0;
+    messageType = jsonObj["message_type"] | 612;
+  }
+
+  JsonObject addTo(JsonObject&& jsonObj) const {
+    jsonObj = BroadcastPackage::addTo(std::move(jsonObj));
+    jsonObj["previousBridge"] = previousBridge;
+    jsonObj["reason"] = reason;
+    jsonObj["routerRSSI"] = routerRSSI;
+    jsonObj["timestamp"] = timestamp;
+    jsonObj["message_type"] = messageType;
+    return jsonObj;
+  }
+
+#if ARDUINOJSON_VERSION_MAJOR < 7
+  size_t jsonObjectSize() const {
+    return JSON_OBJECT_SIZE(noJsonFields + 5) + reason.length();
+  }
+#endif
+};
+
+/**
+ * @brief NTP time synchronization package (Type 614 - TIME_SYNC_NTP)
+ *
+ * Broadcast by bridge nodes to distribute authoritative NTP time to the mesh.
+ * When a bridge has Internet connectivity, it can provide NTP time to improve
+ * accuracy across the entire mesh network.
+ *
+ * Regular nodes should:
+ * 1. Accept time from bridge nodes (verify sender is bridge)
+ * 2. Update local time with mesh.setTimeFromNTP(ntpTime)
+ * 3. Optionally sync RTC modules if available
+ *
+ * Type ID 614 for TIME_SYNC_NTP.
+ */
+class NTPTimeSyncPackage : public painlessmesh::plugin::BroadcastPackage {
+ public:
+  uint32_t ntpTime = 0;    // Unix timestamp from NTP server
+  uint16_t accuracy = 0;   // Milliseconds uncertainty/precision
+  TSTRING source = "";     // NTP server source (e.g., "pool.ntp.org")
+  uint32_t timestamp = 0;  // Collection timestamp
+
+  // MQTT Schema message_type
+  uint16_t messageType = 614;  // TIME_SYNC_NTP
+
+  NTPTimeSyncPackage() : BroadcastPackage(614) {}
+
+  NTPTimeSyncPackage(JsonObject jsonObj) : BroadcastPackage(jsonObj) {
+    ntpTime = jsonObj["ntpTime"];
+    accuracy = jsonObj["accuracy"];
+    source = jsonObj["source"].as<TSTRING>();
+    timestamp = jsonObj["timestamp"];
+    messageType = jsonObj["message_type"] | 614;
+  }
+
+  JsonObject addTo(JsonObject&& jsonObj) const {
+    jsonObj = BroadcastPackage::addTo(std::move(jsonObj));
+    jsonObj["ntpTime"] = ntpTime;
+    jsonObj["accuracy"] = accuracy;
+    jsonObj["source"] = source;
+    jsonObj["timestamp"] = timestamp;
+    jsonObj["message_type"] = messageType;
+    return jsonObj;
+  }
+
+#if ARDUINOJSON_VERSION_MAJOR < 7
+  size_t jsonObjectSize() const {
+    return JSON_OBJECT_SIZE(noJsonFields + 5) + source.length();
+  }
+#endif
+};
+
 }  // namespace alteriom
 
 #endif  // ALTERIOM_SENSOR_PACKAGE_HPP

package/examples/alteriom/platformio.ini

@@ -14,7 +14,7 @@ framework = arduino
 lib_extra_dirs = ../../  ; Load the local copy of painlessmesh. For your own example add painlessmesh to the lib_deps
 lib_deps =
     ${env.lib_deps}  ; Inherit common dependencies
-    esp32async/ESPAsyncTCP  ; Only for ESP8266
+    esp32async/ESPAsyncTCP@^2.0.0  ; Only for ESP8266
 
 [env:esp32]
 platform = espressif32

package/examples/alteriomImproved/platformio.ini

@@ -20,7 +20,7 @@ framework = arduino
 lib_extra_dirs = ../../  ; Load the local copy of painlessmesh. For your own example add painlessmesh to the lib_deps
 lib_deps =
     ${env.lib_deps}  ; Inherit common dependencies
-    esp32async/ESPAsyncTCP  ; Only for ESP8266
+    esp32async/ESPAsyncTCP@^2.0.0  ; Only for ESP8266
 
 [env:esp32]
 platform = espressif32

package/examples/alteriomMetricsHealth/metrics_health_node.ino

@@ -116,7 +116,8 @@ void sendMetrics() {
   // CPU and Processing
   metrics.loopIterations = ((loopCount - lastLoopCount) * 1000) / timeDelta;
   metrics.cpuUsage = calculateCPUUsage();
-  metrics.taskQueueSize = userScheduler.size();
+  // Note: TaskScheduler doesn't provide a size() method, so we'll use 0 or estimate
+  metrics.taskQueueSize = 0;  // TaskScheduler API doesn't expose queue size
   
   // Memory Metrics
   metrics.freeHeap = ESP.getFreeHeap();
@@ -155,8 +156,13 @@ void sendMetrics() {
   metrics.collectionTimestamp = mesh.getNodeTime();
   metrics.collectionInterval = METRICS_INTERVAL;
   
-  // Send the metrics
-  String msg = metrics.toJsonString();
+  // Serialize and send the metrics
+  JsonDocument doc;
+  JsonObject obj = doc.to<JsonObject>();
+  metrics.addTo(std::move(obj));
+  
+  String msg;
+  serializeJson(doc, msg);
   bool sent = mesh.sendBroadcast(msg);
   
   if (sent) {
@@ -266,8 +272,13 @@ void sendHealthCheck() {
   health.checkTimestamp = mesh.getNodeTime();
   health.nextCheckDue = health.checkTimestamp + (HEALTH_INTERVAL * 1000);
   
-  // Send the health check
-  String msg = health.toJsonString();
+  // Serialize and send the health check
+  JsonDocument doc;
+  JsonObject obj = doc.to<JsonObject>();
+  health.addTo(std::move(obj));
+  
+  String msg;
+  serializeJson(doc, msg);
   bool sent = mesh.sendBroadcast(msg);
   
   if (sent) {
@@ -372,10 +383,10 @@ void receivedCallback(uint32_t from, String& msg) {
   totalPacketsRx++;
   
   // Parse message type
-  DynamicJsonDocument doc(1024);
+  JsonDocument doc;
   deserializeJson(doc, msg);
   JsonObject obj = doc.as<JsonObject>();
-  uint8_t msgType = obj["type"];
+  uint16_t msgType = obj["type"];
   
   Serial.printf("\nReceived Type %d from %u\n", msgType, from);
   

package/examples/alteriomMetricsHealth/platformio.ini

@@ -14,7 +14,7 @@ framework = arduino
 lib_extra_dirs = ../../  ; Load the local copy of painlessmesh. For your own example add painlessmesh to the lib_deps
 lib_deps =
     ${env.lib_deps}  ; Inherit common dependencies
-    esp32async/ESPAsyncTCP  ; Only for ESP8266
+    esp32async/ESPAsyncTCP@^2.0.0  ; Only for ESP8266
 
 [env:esp32]
 platform = espressif32

package/examples/alteriomPhase1/platformio.ini

@@ -14,7 +14,7 @@ framework = arduino
 lib_extra_dirs = ../../  ; Load the local copy of painlessmesh. For your own example add painlessmesh to the lib_deps
 lib_deps =
     ${env.lib_deps}  ; Inherit common dependencies
-    esp32async/ESPAsyncTCP  ; Only for ESP8266
+    esp32async/ESPAsyncTCP@^2.0.0  ; Only for ESP8266
 
 [env:esp32]
 platform = espressif32

package/examples/alteriomPhase2/platformio.ini

@@ -14,7 +14,7 @@ framework = arduino
 lib_extra_dirs = ../../  ; Load the local copy of painlessmesh. For your own example add painlessmesh to the lib_deps
 lib_deps =
     ${env.lib_deps}  ; Inherit common dependencies
-    esp32async/ESPAsyncTCP  ; Only for ESP8266
+    esp32async/ESPAsyncTCP@^2.0.0  ; Only for ESP8266
 
 [env:esp32]
 platform = espressif32