@alteriom/painlessmesh 1.7.2 → 1.7.3

package/docs/troubleshooting/debugging.md

@@ -0,0 +1,455 @@
+# Debugging Guide
+
+This guide provides tools and techniques for debugging painlessMesh applications.
+
+## Debug Message Types
+
+painlessMesh includes a built-in debugging system that lets you control which types of messages are logged.
+
+### Setting Debug Message Types
+
+```cpp
+#include "painlessMesh.h"
+
+painlessMesh mesh;
+
+void setup() {
+  Serial.begin(115200);
+  
+  // Set which message types to display
+  mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+  
+  // Initialize mesh
+  mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+}
+```
+
+### Available Debug Message Types
+
+| Type | Description |
+|------|-------------|
+| `ERROR` | Critical errors and failures |
+| `STARTUP` | Initialization and startup messages |
+| `CONNECTION` | Connection and disconnection events |
+| `SYNC` | Time synchronization messages |
+| `COMMUNICATION` | Message sending/receiving |
+| `GENERAL` | General informational messages |
+| `MSG_TYPES` | Message type information |
+| `REMOTE` | Remote node messages |
+| `APPLICATION` | Application-level messages |
+| `DEBUG` | Detailed debugging information |
+
+### Common Debug Configurations
+
+**Minimal (Production):**
+
+```cpp
+mesh.setDebugMsgTypes(ERROR | STARTUP);
+```
+
+**Standard (Development):**
+
+```cpp
+mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+```
+
+**Verbose (Troubleshooting):**
+
+```cpp
+mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION | SYNC | COMMUNICATION);
+```
+
+**Full Debug (Deep Dive):**
+
+```cpp
+mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION | SYNC | 
+                      COMMUNICATION | GENERAL | MSG_TYPES | 
+                      REMOTE | APPLICATION | DEBUG);
+```
+
+## Common Debugging Scenarios
+
+### 1. Nodes Not Connecting
+
+**Symptoms:**
+
+- Nodes don't appear in `mesh.getNodeList()`
+- `onNewConnection` callback never fires
+- Mesh appears to run but no communication
+
+**Debugging Steps:**
+
+```cpp
+// Enable connection debugging
+mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION | SYNC);
+
+void setup() {
+  Serial.begin(115200);
+  
+  // Add connection callbacks
+  mesh.onNewConnection([](uint32_t nodeId) {
+    Serial.printf("New connection: %u\n", nodeId);
+    Serial.printf("Total nodes: %d\n", mesh.getNodeList().size());
+  });
+  
+  mesh.onChangedConnections([]() {
+    Serial.printf("Connections changed. Current nodes: %d\n", 
+                  mesh.getNodeList().size());
+    auto nodes = mesh.getNodeList();
+    for (auto node : nodes) {
+      Serial.printf("  - Node: %u\n", node);
+    }
+  });
+  
+  mesh.onDroppedConnection([](uint32_t nodeId) {
+    Serial.printf("Lost connection: %u\n", nodeId);
+  });
+}
+```
+
+**Common Causes:**
+
+- Mismatched `MESH_PREFIX` or `MESH_PASSWORD`
+- Different `MESH_PORT` values
+- Wi-Fi channel conflicts
+- Power supply issues (voltage drops during connection)
+- Too many nodes (exceeds platform limits)
+
+### 2. Messages Not Received
+
+**Symptoms:**
+
+- `mesh.sendBroadcast()` or `mesh.sendSingle()` returns true but messages not received
+- `onReceive` callback never fires
+
+**Debugging Steps:**
+
+```cpp
+// Enable communication debugging
+mesh.setDebugMsgTypes(ERROR | COMMUNICATION | MSG_TYPES);
+
+void setup() {
+  Serial.begin(115200);
+  
+  mesh.onReceive([](uint32_t from, String& msg) {
+    Serial.printf("Received from %u: %s\n", from, msg.c_str());
+  });
+  
+  // Add send status checking
+  if (mesh.sendBroadcast(msg)) {
+    Serial.println("Broadcast sent successfully");
+  } else {
+    Serial.println("ERROR: Broadcast failed to send");
+  }
+}
+```
+
+**Common Causes:**
+
+- Message buffer overflow (message too large)
+- Network congestion (too many messages)
+- JSON parsing errors (malformed messages)
+- Node ID mismatch for `sendSingle()`
+- Memory constraints on receiving node
+
+### 3. Time Synchronization Issues
+
+**Symptoms:**
+
+- `mesh.getNodeTime()` returns unexpected values
+- Time-dependent features not working
+- `onNodeTimeAdjusted` fires frequently
+
+**Debugging Steps:**
+
+```cpp
+// Enable time sync debugging
+mesh.setDebugMsgTypes(ERROR | SYNC);
+
+void setup() {
+  Serial.begin(115200);
+  
+  mesh.onNodeTimeAdjusted([](int32_t offset) {
+    Serial.printf("Time adjusted by: %d microseconds\n", offset);
+    Serial.printf("Current mesh time: %u\n", mesh.getNodeTime());
+  });
+  
+  // Periodically check time
+  Task checkTime(TASK_SECOND * 10, TASK_FOREVER, []() {
+    Serial.printf("Mesh time: %u, System: %u\n", 
+                  mesh.getNodeTime(), micros());
+  });
+  userScheduler.addTask(checkTime);
+  checkTime.enable();
+}
+```
+
+### 4. Memory Issues
+
+**Symptoms:**
+
+- Random crashes or reboots
+- Mesh stops responding
+- `heap_caps_check_integrity` failures on ESP32
+
+**Debugging Steps:**
+
+```cpp
+void setup() {
+  Serial.begin(115200);
+  
+  // Monitor free memory
+  Task memoryCheck(TASK_SECOND * 5, TASK_FOREVER, []() {
+    Serial.printf("Free heap: %u bytes\n", ESP.getFreeHeap());
+    #ifdef ESP32
+    Serial.printf("Free PSRAM: %u bytes\n", ESP.getFreePsram());
+    Serial.printf("Largest free block: %u bytes\n", 
+                  heap_caps_get_largest_free_block(MALLOC_CAP_8BIT));
+    #endif
+  });
+  userScheduler.addTask(memoryCheck);
+  memoryCheck.enable();
+}
+```
+
+**Memory Optimization Tips:**
+
+- Use `String` sparingly, prefer `const char*`
+- Limit broadcast message frequency
+- Reduce node count for ESP8266
+- Clear unused tasks from scheduler
+- Use `F()` macro for string literals
+
+### 5. OTA Update Failures
+
+**Symptoms:**
+
+- OTA updates don't start
+- Updates fail partway through
+- Nodes become unresponsive during update
+
+**Debugging Steps:**
+
+```cpp
+// Enable OTA debugging
+mesh.setDebugMsgTypes(ERROR | STARTUP | COMMUNICATION);
+
+void setup() {
+  Serial.begin(115200);
+  
+  // Add OTA callbacks if using broadcast OTA
+  mesh.onOTAProgress([](size_t progress, size_t total) {
+    Serial.printf("OTA Progress: %u/%u bytes (%.1f%%)\n", 
+                  progress, total, (progress * 100.0) / total);
+  });
+  
+  mesh.onOTAComplete([]() {
+    Serial.println("OTA Update Complete - Rebooting...");
+  });
+  
+  mesh.onOTAError([](int error) {
+    Serial.printf("OTA Error: %d\n", error);
+  });
+}
+```
+
+**Common Causes:**
+
+- Insufficient flash memory
+- Power interruption during update
+- Network instability
+- Firmware size exceeds partition size
+- Memory fragmentation
+
+## Debugging Tools
+
+### 1. Serial Monitor
+
+**Arduino IDE:**
+
+- Tools → Serial Monitor
+- Set baud rate to 115200
+- Enable newline and carriage return
+
+**PlatformIO:**
+
+```bash
+pio device monitor --baud 115200
+```
+
+**Screen (Linux/Mac):**
+
+```bash
+screen /dev/ttyUSB0 115200
+```
+
+### 2. Network Analyzer
+
+**Wireshark:**
+
+- Capture Wi-Fi traffic to see mesh packets
+- Filter by ESP32/ESP8266 MAC addresses
+- Analyze packet timing and retransmissions
+
+### 3. Mesh Topology Visualization
+
+For MQTT-enabled setups:
+
+- Use MQTT Explorer to view mesh topology
+- Monitor `alteriom/mesh/topology` topic
+- Visualize node connections and status
+
+### 4. Remote Logging
+
+**Log Server Example:**
+
+```cpp
+// On one node, set up as log server
+mesh.onReceive([](uint32_t from, String& msg) {
+  DynamicJsonDocument doc(1024);
+  deserializeJson(doc, msg);
+  
+  if (doc["type"] == "log") {
+    Serial.printf("[%u] %s\n", from, doc["msg"].as<const char*>());
+  }
+});
+
+// On other nodes, send logs
+void logToServer(const char* message) {
+  DynamicJsonDocument doc(256);
+  doc["type"] = "log";
+  doc["msg"] = message;
+  
+  String msg;
+  serializeJson(doc, msg);
+  mesh.sendBroadcast(msg);
+}
+```
+
+## Performance Profiling
+
+### Measure Message Latency
+
+```cpp
+uint32_t sendTime = 0;
+
+void sendMessage() {
+  DynamicJsonDocument doc(256);
+  doc["type"] = "ping";
+  doc["timestamp"] = mesh.getNodeTime();
+  
+  String msg;
+  serializeJson(doc, msg);
+  
+  sendTime = millis();
+  mesh.sendBroadcast(msg);
+}
+
+void onMessageReceived(uint32_t from, String& msg) {
+  DynamicJsonDocument doc(256);
+  deserializeJson(doc, msg);
+  
+  if (doc["type"] == "ping") {
+    uint32_t latency = millis() - sendTime;
+    Serial.printf("Ping latency: %u ms\n", latency);
+  }
+}
+```
+
+### Monitor Task Execution
+
+```cpp
+void setup() {
+  // Enable TaskScheduler debugging
+  userScheduler.enableAll();
+  
+  Task debugTask(TASK_SECOND * 10, TASK_FOREVER, []() {
+    Serial.printf("Active tasks: %d\n", userScheduler.size());
+    // List all tasks
+    for (auto task = userScheduler.getFirstTask(); 
+         task != nullptr; 
+         task = task->getNext()) {
+      Serial.printf("  Task ID: %d, Enabled: %d\n", 
+                    task->getId(), task->isEnabled());
+    }
+  });
+  userScheduler.addTask(debugTask);
+  debugTask.enable();
+}
+```
+
+## Best Practices
+
+1. **Start Minimal:** Enable only ERROR and STARTUP for initial testing
+2. **Add Incrementally:** Add more debug types as needed
+3. **Use Callbacks:** Implement all mesh callbacks to catch events
+4. **Monitor Memory:** Regularly check free heap, especially on ESP8266
+5. **Test Incrementally:** Test with 2 nodes before scaling to larger networks
+6. **Power Management:** Ensure stable power supply during debugging
+7. **Version Control:** Use consistent firmware versions across all nodes
+8. **Document Issues:** Keep notes on error patterns and solutions
+
+## Advanced Debugging
+
+### Enable TaskScheduler Debug Mode
+
+```cpp
+// Add to top of sketch BEFORE including headers
+#define _TASK_DEBUG
+
+#include <TaskScheduler.h>
+#include "painlessMesh.h"
+```
+
+### Enable ArduinoJson Debug
+
+```cpp
+#define ARDUINOJSON_DEBUG 1
+#include <ArduinoJson.h>
+```
+
+### ESP32 Core Debug Level
+
+In `platformio.ini`:
+
+```ini
+build_flags =
+  -DCORE_DEBUG_LEVEL=5  ; 0=None, 5=Verbose
+```
+
+## Troubleshooting Checklist
+
+- [ ] All nodes use same MESH_PREFIX, MESH_PASSWORD, MESH_PORT
+- [ ] Serial baud rate set to 115200
+- [ ] Debug messages enabled for relevant types
+- [ ] Callbacks implemented (onReceive, onNewConnection, etc.)
+- [ ] Free heap monitored (especially on ESP8266)
+- [ ] Power supply stable (2A+ recommended)
+- [ ] Firmware versions consistent across nodes
+- [ ] JSON messages properly formatted
+- [ ] Message sizes within limits (< 1KB recommended)
+- [ ] Network not oversaturated (reasonable message frequency)
+
+## Getting Help
+
+If you're still experiencing issues:
+
+1. **Search Existing Issues:** Check [GitHub Issues](https://github.com/Alteriom/painlessMesh/issues)
+2. **Community Forum:** Post on [painlessMesh Discussions](https://github.com/Alteriom/painlessMesh/discussions)
+3. **Include Details:**
+   - Hardware (ESP32/ESP8266 model)
+   - Firmware version
+   - Number of nodes
+   - Debug output
+   - Minimal reproducible example
+4. **Check Documentation:**
+   - [Common Issues](common-issues.md)
+   - [FAQ](faq.md)
+   - [API Reference](../api/core-api.md)
+
+## See Also
+
+- [Common Issues](common-issues.md) - Known problems and solutions
+- [FAQ](faq.md) - Frequently asked questions
+- [Performance Optimization](../architecture/mesh-architecture.md) - Scaling best practices
+- [MQTT Bridge Commands](../MQTT_BRIDGE_COMMANDS.md) - MQTT debugging

package/library.json

@@ -6,7 +6,7 @@
         "type": "git",
         "url": "https://github.com/Alteriom/painlessMesh"
     },
-    "version": "1.7.2",
+    "version": "1.7.3",
     "frameworks": ["arduino"],
     "platforms": ["espressif8266", "espressif32"],
     "srcDir": "src",

package/library.properties

@@ -1,5 +1,5 @@
 name=AlteriomPainlessMesh
-version=1.7.2
+version=1.7.3
 author=Coopdis,Scotty Franzyshen,Edwin van Leeuwen,Germán Martín,Maximilian Schwarz,Doanh Doanh,Alteriom
 maintainer=Alteriom
 sentence=A painless way to setup a mesh with ESP8266 and ESP32 devices with Alteriom extensions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alteriom/painlessmesh",
-  "version": "1.7.2",
+  "version": "1.7.3",
   "description": "painlessMesh is a user-friendly library for creating mesh networks with ESP8266 and ESP32 devices. This Alteriom fork includes additional packages for sensor data (SensorPackage), device commands (CommandPackage), and status monitoring (StatusPackage). It handles routing and network management automatically, so you can focus on your application. The library uses JSON-based messaging and syncs time across all nodes, making it ideal for coordinated behaviour like synchronized light displays or sensor networks reporting to a central node.",
   "keywords": [
     "arduino",

package/src/painlessmesh/router.hpp

@@ -190,26 +190,42 @@ void routePackage(layout::Layout<T> layout, std::shared_ptr<T> connection,
     Log(DEBUG, "routePackage(): No callbacks executed; %u, %s\n",
         variant.type(), pkg.c_str());
 #else
-  static size_t baseCapacity = 512;
-  // Using a ptr so we can overwrite it if we need to grow capacity.
-  // Bug in copy constructor with grown capacity can cause segmentation fault
-  auto variant =
-      std::make_shared<protocol::Variant>(pkg, pkg.length() + baseCapacity);
-  while (variant->error == DeserializationError::NoMemory &&
-         baseCapacity <= 20480) {
-    // Not enough memory, adapt scaling (variant::capacityScaling) and log the
-    // new value
-    Log(DEBUG,
-        "routePackage(): parsing failed. err=%u, increasing capacity: %u\n",
-        variant->error, baseCapacity);
-    baseCapacity += 256;
-    variant =
-        std::make_shared<protocol::Variant>(pkg, pkg.length() + baseCapacity);
-  }
+  // Calculate required capacity based on message size and nesting depth
+  // Fixed capacity approach to avoid segmentation fault issues with
+  // dynamic reallocation (see issue #521 and CODE_REFACTORING_RECOMMENDATIONS.md)
+  size_t nestingDepth = std::count(pkg.begin(), pkg.end(), '{') + 
+                        std::count(pkg.begin(), pkg.end(), '[');
+  
+#if ARDUINOJSON_VERSION_MAJOR >= 7
+  // ArduinoJson v7: automatic capacity management, use generous buffer
+  size_t calculatedCapacity = pkg.length() + 1024;
+#else
+  // ArduinoJson v6: manual capacity calculation required
+  // Base capacity: message length + overhead for JSON structure
+  // Each nesting level adds overhead for pointers and metadata
+  size_t calculatedCapacity = pkg.length() + 
+                              JSON_OBJECT_SIZE(10) * std::max(nestingDepth, size_t(1)) + 
+                              512;  // Additional buffer for strings and padding
+#endif
+  
+  // Cap at 8KB for safety on ESP8266 (which has ~80KB total heap)
+  // Messages larger than this should be rejected
+  constexpr size_t MAX_MESSAGE_CAPACITY = 8192;
+  size_t capacity = std::min(calculatedCapacity, MAX_MESSAGE_CAPACITY);
+  
+  auto variant = std::make_shared<protocol::Variant>(pkg, capacity);
+  
   if (variant->error) {
-    Log(ERROR,
-        "routePackage(): parsing failed. err=%u, total_length=%d, data=%s<--\n",
-        variant->error, pkg.length(), pkg.c_str());
+    if (variant->error == DeserializationError::NoMemory) {
+      Log(ERROR,
+          "routePackage(): Message too large. length=%d, calculated_capacity=%u, "
+          "nesting_depth=%u. Consider increasing MAX_MESSAGE_CAPACITY if needed.\n",
+          pkg.length(), calculatedCapacity, nestingDepth);
+    } else {
+      Log(ERROR,
+          "routePackage(): parsing failed. err=%u, length=%d, data=%s<--\n",
+          variant->error, pkg.length(), pkg.c_str());
+    }
     return;
   }