@alteriom/painlessmesh 1.7.8 → 1.7.9

package/docs/troubleshooting/ESP32_C6_COMPATIBILITY.md

@@ -0,0 +1,157 @@
+# ESP32-C6 Compatibility Guide
+
+## Overview
+
+ESP32-C6 is a newer ESP32 variant that requires updated dependencies to work correctly with painlessMesh. This guide addresses common issues and solutions for using painlessMesh on ESP32-C6.
+
+## Known Issue: TCP Allocation Crash
+
+### Symptom
+
+The device crashes on startup or during mesh initialization with the following error:
+
+```
+assert failed: tcp_alloc /IDF/components/lwip/lwip/src/core/tcp.c:1854 (Required to lock TCPIP core functionality!)
+```
+
+The device enters an endless reboot loop, preventing normal mesh operation.
+
+### Root Cause
+
+This issue is caused by incompatibility between:
+- ESP32-C6 hardware
+- Arduino ESP32 core v3.1.0 or later
+- Older versions of the AsyncTCP library
+
+The newer ESP32 Arduino core enforces stricter LWIP (Lightweight IP) thread safety requirements. Operations that modify TCP/IP data structures must now be protected with proper mutex locking. Older AsyncTCP versions (< v3.3.0) do not implement this locking, causing runtime assertions and crashes.
+
+### Solution
+
+#### Option 1: Update AsyncTCP Library (Recommended)
+
+Use the latest version of AsyncTCP that includes proper LWIP locking:
+
+**For PlatformIO:**
+
+Update your `platformio.ini`:
+
+```ini
+[env:esp32c6]
+platform = espressif32
+board = esp32-c6-devkitc-1  ; or your specific board
+framework = arduino
+
+lib_deps =
+    https://github.com/Alteriom/painlessMesh.git
+    esp32async/AsyncTCP @ ^3.4.7  ; Use latest version with LWIP locking
+    bblanchon/ArduinoJson @ ^7.4.2
+    arkhipenko/TaskScheduler @ ^4.0.0
+```
+
+**For Arduino IDE:**
+
+1. Remove any existing AsyncTCP library installation
+2. Download the latest AsyncTCP from: https://github.com/ESP32Async/AsyncTCP
+3. Install using "Sketch" → "Include Library" → "Add .ZIP Library"
+4. **Important:** Do not use the Arduino Library Manager for AsyncTCP, as it may install an outdated version
+
+#### Option 2: Downgrade Arduino Core (Temporary Workaround)
+
+If you need an immediate solution and cannot update AsyncTCP:
+
+1. In Arduino IDE: Tools → Board Manager → ESP32 by Espressif Systems
+2. Install version **3.0.7** instead of 3.1.0+
+3. This is not recommended long-term as you'll miss security updates and new features
+
+#### Option 3: Use Recommended Build Flags
+
+Add these configuration options to improve stability (PlatformIO):
+
+```ini
+build_flags =
+    -D CONFIG_ASYNC_TCP_MAX_ACK_TIME=5000
+    -D CONFIG_ASYNC_TCP_PRIORITY=10
+    -D CONFIG_ASYNC_TCP_QUEUE_SIZE=64
+    -D CONFIG_ASYNC_TCP_RUNNING_CORE=1
+    -D CONFIG_ASYNC_TCP_STACK_SIZE=4096
+```
+
+These flags help maintain proper task scheduling and LWIP event handling.
+
+## Verification
+
+After applying the fix, verify your setup:
+
+1. Upload a simple bridge example
+2. Monitor serial output for clean startup
+3. Check for successful mesh initialization without crashes
+4. Verify mesh connectivity with other nodes
+
+Example verification output:
+```
+setLogLevel: ERROR | STARTUP | CONNECTION |
+STARTUP: init(): 1
+STARTUP: stationManual() Starting WiFi connection
+STARTUP: Connection established
+STARTUP: IP address: 192.168.1.100
+```
+
+## Additional ESP32-C6 Considerations
+
+### Hardware-Specific Notes
+
+- ESP32-C6 uses RISC-V architecture (not Xtensa like older ESP32)
+- Built-in WiFi 6 (802.11ax) support - but mesh uses 802.11n
+- Lower power consumption compared to ESP32
+- Different GPIO pinout - verify your pin assignments
+
+### Memory Constraints
+
+ESP32-C6 typically has:
+- 320 KB SRAM
+- 4 MB Flash (typical configuration)
+
+This is adequate for painlessMesh, but be mindful of:
+- Maximum node count in mesh (recommend < 20 nodes)
+- Message queue sizes
+- JSON message complexity
+
+### Performance Optimization
+
+For best results on ESP32-C6:
+
+1. **WiFi Channel Selection**: Use channels 1, 6, or 11 for best performance
+2. **Mesh Size**: Keep mesh networks under 15-20 nodes
+3. **Message Frequency**: Avoid sending messages more than once per second per node
+4. **Power Management**: Consider WiFi power save modes for battery operation
+
+## Troubleshooting Checklist
+
+If you're still experiencing issues:
+
+- [ ] Confirmed AsyncTCP version is 3.3.0 or newer
+- [ ] Removed all old AsyncTCP library installations
+- [ ] Arduino ESP32 core is 3.0.7 or 3.1.0+ with updated AsyncTCP
+- [ ] Verified board definition matches your hardware
+- [ ] Checked serial monitor for actual error messages
+- [ ] Tested with minimal example (examples/basic/basic.ino)
+- [ ] Verified WiFi credentials are correct
+- [ ] Confirmed router and mesh use same WiFi channel (for bridge mode)
+
+## References
+
+- [AsyncTCP Library (ESP32Async)](https://github.com/ESP32Async/AsyncTCP)
+- [ESP32 Arduino Core Release Notes](https://github.com/espressif/arduino-esp32/releases)
+- [painlessMesh GitHub Issues](https://github.com/Alteriom/painlessMesh/issues)
+
+## Related Documentation
+
+- [Common Issues](common-issues.md)
+- [FAQ](faq.md)
+- [Bridge to Internet Guide](../../BRIDGE_TO_INTERNET.md)
+- [Debugging Guide](debugging.md)
+
+---
+
+**Last Updated:** 2025-11-05  
+**Applies to:** painlessMesh v1.7.8+, ESP32-C6, Arduino ESP32 Core 3.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;
   }
 

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

package/examples/alteriomSensorNode/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/basic/platformio.ini

@@ -14,7 +14,7 @@ framework = arduino
 lib_extra_dirs = ../../
 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