@alteriom/painlessmesh 1.9.19 → 1.10.0

package/src/painlessmesh/plugin.hpp

@@ -173,12 +173,34 @@ class BridgeCoordinationPackage : public plugin::BroadcastPackage {
 template <typename T>
 class PackageHandler : public layout::Layout<T> {
  public:
-  void stop() {
-    for (auto&& task : taskList) {
-      task->disable();
-      task->setCallback(NULL);
+  // NOTE: scheduler is optional (defaults to nullptr) for backward
+  // compatibility with existing call sites; without it we can't detect
+  // the "current" task and behaviour falls back to the original one.
+  // Passing the scheduler (mesh.hpp already has it as mScheduler) avoids
+  // the use-after-free described below.
+  void stop(Scheduler* scheduler = nullptr) {
+    // If stop() is called from within the callback of one of the tasks in
+    // taskList (e.g. promoteToBridge()), that task is
+    // "scheduler->getCurrentTask()" at this exact moment. Disabling it,
+    // clearing its callback, or letting its shared_ptr refcount drop to
+    // zero here would destroy its closure - which is still on the stack,
+    // in the middle of its own execution - causing a use-after-free crash
+    // (same bug family as upstream issue #373, but triggered by the
+    // shared_ptr refcount instead of a raw delete in onDisable).
+    // We simply leave it in the list: addTask() will recognise it as
+    // "disabled with a single reference" and reuse it on the next call,
+    // exactly like it already does for disabled anonymous tasks (see the
+    // comment on addTask() above).
+    Task* current = scheduler ? scheduler->getCurrentTask() : nullptr;
+    for (auto it = taskList.begin(); it != taskList.end();) {
+      if (current != nullptr && it->get() == current) {
+        ++it;
+        continue;
+      }
+      (*it)->disable();
+      (*it)->setCallback(NULL);
+      it = taskList.erase(it);
     }
-    taskList.clear();
     callbackList.clear();
   }
 

package/src/painlessmesh/tcp.hpp

@@ -30,6 +30,84 @@ static const uint32_t TCP_EXHAUSTION_RECONNECT_DELAY_MS = 10000; // 10 seconds b
 // This prevents repeatedly trying to connect to nodes with unresponsive TCP servers
 static const uint32_t TCP_FAILURE_BLOCK_DURATION_MS = 60000;
 
+// Safe operating bounds applied by clampTcpRetryConfig().
+// Each retry allocates a new AsyncClient and schedules a task, so an unbounded
+// maxRetries is a heap and recursion-depth hazard on ESP8266. A zero retry
+// delay would schedule retry tasks with no spacing, i.e. a hot loop allocating
+// an AsyncClient per scheduler tick.
+static const uint8_t TCP_RETRY_MAX_RETRIES_LIMIT = 10;
+static const uint32_t TCP_RETRY_MIN_DELAY_MS = 50;
+static const uint32_t TCP_RETRY_MAX_DELAY_MS = 60000;
+
+/**
+ * User-tunable TCP connection retry parameters
+ *
+ * One instance is stored per mesh (painlessmesh::Mesh), configured through
+ * Mesh::setTcpRetryConfig(). The member defaults are spelled as the legacy
+ * constants above rather than as literals, so the "defaults match the previous
+ * hardcoded behaviour exactly" guarantee is enforced by the compiler and cannot
+ * silently drift.
+ *
+ * NOTE: this deliberately lives on the mesh instance rather than at namespace
+ * scope. A mutable namespace-scope instance in this header would give every
+ * translation unit its own private copy, so a sketch that configured the mesh
+ * in one TU and connected from another would silently fall back to defaults
+ * with no diagnostic.
+ */
+struct TcpRetryConfig {
+  /// Max TCP connect retry attempts before falling back to a WiFi reconnect
+  uint8_t maxRetries = TCP_CONNECT_MAX_RETRIES;
+  /// Base delay between retry attempts (ms), scaled by exponential backoff
+  uint32_t retryDelayMs = TCP_CONNECT_RETRY_DELAY_MS;
+  /// Delay after IP acquisition before the TCP connect is attempted (ms)
+  uint32_t stabilizationDelayMs = TCP_CONNECT_STABILIZATION_DELAY_MS;
+  /// Delay before the WiFi reconnect that follows retry exhaustion (ms)
+  uint32_t exhaustionReconnectDelayMs = TCP_EXHAUSTION_RECONNECT_DELAY_MS;
+  /// Duration a node is blocklisted after retry exhaustion (ms, 0 = never)
+  uint32_t failureBlockDurationMs = TCP_FAILURE_BLOCK_DURATION_MS;
+};
+
+/**
+ * Delay before retry attempt number `retryCount`
+ *
+ * Exponential backoff with the multiplier capped at 8, giving the default
+ * sequence 1s, 2s, 4s, 8s, 8s. Capping prevents excessive delays and keeps the
+ * product clear of uint32_t overflow.
+ *
+ * @param cfg Active retry configuration
+ * @param retryCount Zero-based retry attempt number
+ * @return Delay in milliseconds
+ */
+inline uint32_t retryBackoffDelay(const TcpRetryConfig &cfg,
+                                  uint8_t retryCount) {
+  uint8_t backoffMultiplier = (retryCount < 3) ? (1U << retryCount) : 8;
+  return cfg.retryDelayMs * backoffMultiplier;
+}
+
+/**
+ * Coerce a retry configuration into safe operating bounds
+ *
+ * Only the two values that can render a node unusable are clamped:
+ * maxRetries (heap/recursion pressure) and retryDelayMs (hot-loop floor and
+ * overflow ceiling). maxRetries == 0 is explicitly allowed - it means "fall
+ * back to a WiFi reconnect on the first TCP error", which is the whole point
+ * of the low-latency profile. stabilizationDelayMs, exhaustionReconnectDelayMs
+ * and failureBlockDurationMs are left alone because 0 is meaningful for each
+ * (skip stabilization / reconnect immediately / never blocklist).
+ *
+ * @param cfg Configuration to clamp (taken by value, returned clamped)
+ * @return The clamped configuration
+ */
+inline TcpRetryConfig clampTcpRetryConfig(TcpRetryConfig cfg) {
+  if (cfg.maxRetries > TCP_RETRY_MAX_RETRIES_LIMIT)
+    cfg.maxRetries = TCP_RETRY_MAX_RETRIES_LIMIT;
+  if (cfg.retryDelayMs < TCP_RETRY_MIN_DELAY_MS)
+    cfg.retryDelayMs = TCP_RETRY_MIN_DELAY_MS;
+  if (cfg.retryDelayMs > TCP_RETRY_MAX_DELAY_MS)
+    cfg.retryDelayMs = TCP_RETRY_MAX_DELAY_MS;
+  return cfg;
+}
+
 inline uint32_t encodeNodeId(const uint8_t *hwaddr) {
   using namespace painlessmesh::logger;
   Log(GENERAL, "encodeNodeId():\n");
@@ -93,8 +171,9 @@ void initServer(AsyncServer &server, M &mesh) {
  * 
  * This function attempts to connect to the mesh network via TCP.
  * If the connection fails (error -14 ERR_CONN or other errors), it will
- * retry up to TCP_CONNECT_MAX_RETRIES times before triggering a full
- * WiFi reconnection cycle.
+ * retry up to the configured maxRetries times before triggering a full
+ * WiFi reconnection cycle. See Mesh::setTcpRetryConfig() to tune the retry
+ * envelope; the defaults reproduce the historic hardcoded behaviour.
  * 
  * The retry mechanism helps handle timing issues where:
  * - The TCP server may not be immediately ready after AP initialization
@@ -117,16 +196,49 @@ template <class T, class M>
 void connect(AsyncClient &client, IPAddress ip, uint16_t port, M &mesh, 
              uint8_t retryCount = 0) {
   using namespace logger;
-  
+
+  // Snapshot the retry configuration once, before any lambda is built. The
+  // onError lambda outlives this stack frame, so it captures this snapshot by
+  // value rather than reading mesh's member later: a user callback could
+  // otherwise mutate the config between the connect attempt and the error,
+  // tearing the backoff schedule mid-sequence. Each retry re-enters connect()
+  // and re-snapshots, so a config change still takes effect on the next
+  // attempt.
+  const TcpRetryConfig cfg = mesh.getTcpRetryConfig();
+
   Log(CONNECTION, "tcp::connect(): Attempting connection to port %d (attempt %d/%d)\n",
-      port, retryCount + 1, TCP_CONNECT_MAX_RETRIES + 1);
+      port, retryCount + 1, cfg.maxRetries + 1);
+
+  // Guard shared between onError and onConnect: under normal conditions a
+  // TCP connection attempt leads to only ONE of the two outcomes. But if
+  // WiFi drops right as the TCP handshake completes, AsyncTCP can queue
+  // BOTH events (connection succeeded at the TCP level + abort due to the
+  // WiFi link being lost) for the same AsyncClient, and both callbacks end
+  // up firing for the SAME object. Without this guard, the client would be
+  // "handed over" twice: once to a BufferedConnection (via onConnect, which
+  // becomes its owner and will delete it via its own destructor) and once
+  // to the retry path (via onError, which schedules it again for deletion)
+  // - two scheduleAsyncClientDeletion() calls on the same pointer, and
+  // therefore a double deferred deletion on the same object once both
+  // tasks fire.
+  auto claimed = std::make_shared<bool>(false);
   
   // Store retry count and connection parameters for the error handler
   // We need to capture these by value since they're used in the lambda
-  client.onError([&mesh, ip, port, retryCount](void *, AsyncClient *client, int8_t err) {
+  client.onError([&mesh, ip, port, retryCount, claimed, cfg](void *, AsyncClient *client, int8_t err) {
+    if (*claimed) {
+      // onConnect has already claimed this client (the connection actually
+      // succeeded, and it's already been wrapped in a BufferedConnection
+      // that owns it): don't touch the same object again.
+      Log(CONNECTION,
+          "tcp_err(): onError fired after onConnect had already claimed "
+          "the client - ignored to avoid double handling\n");
+      return;
+    }
+    *claimed = true;
     if (mesh.semaphoreTake()) {
-      Log(CONNECTION, "tcp_err(): error trying to connect %d (attempt %d/%d)\n", 
-          err, retryCount + 1, TCP_CONNECT_MAX_RETRIES + 1);
+      Log(CONNECTION, "tcp_err(): error trying to connect %d (attempt %d/%d)\n",
+          err, retryCount + 1, cfg.maxRetries + 1);
       
       // Check if we have retries left - retry logic only works on real hardware
       // In test environment (PAINLESSMESH_BOOST), fall through to dropped connection
@@ -134,27 +246,21 @@ void connect(AsyncClient &client, IPAddress ip, uint16_t port, M &mesh,
       (void)ip;
       (void)port;
 #if !defined(PAINLESSMESH_BOOST) && (defined(ESP32) || defined(ESP8266))
-      if (retryCount < TCP_CONNECT_MAX_RETRIES) {
-        // Calculate delay with exponential backoff: base_delay * 2^retryCount
-        // This gives increasing time between retries as failures accumulate:
-        // - retryCount=0: 1000ms * 1 = 1s
-        // - retryCount=1: 1000ms * 2 = 2s
-        // - retryCount=2: 1000ms * 4 = 4s
-        // - retryCount=3: 1000ms * 8 = 8s (capped at 8)
-        // - retryCount=4: 1000ms * 8 = 8s (capped at 8)
-        // Cap multiplier at 8 to prevent excessive delays
-        uint8_t backoffMultiplier = (retryCount < 3) ? (1U << retryCount) : 8;
-        uint32_t retryDelay = TCP_CONNECT_RETRY_DELAY_MS * backoffMultiplier;
-        
-        Log(CONNECTION, "tcp_err(): Scheduling retry in %u ms (backoff x%d)\n", 
-            retryDelay, backoffMultiplier);
+      if (retryCount < cfg.maxRetries) {
+        // Delay grows with exponential backoff, multiplier capped at 8.
+        // With the default 1000ms base that is: 1s, 2s, 4s, 8s, 8s.
+        uint32_t retryDelay = retryBackoffDelay(cfg, retryCount);
+
+        Log(CONNECTION, "tcp_err(): Scheduling retry in %u ms\n", retryDelay);
         
         // Schedule a retry after a delay using the mesh's task scheduler
         // Note: &mesh is captured by reference because:
         // 1. Mesh is a singleton that lives for the program's lifetime
         // 2. The task scheduler belongs to the mesh, so mesh is always valid when task runs
         // 3. Copying the mesh object is not possible/allowed
-        // Recursion depth is strictly bounded by TCP_CONNECT_MAX_RETRIES (default: 5)
+        // Recursion depth is strictly bounded by cfg.maxRetries (default 5),
+        // which clampTcpRetryConfig() never lets exceed
+        // TCP_RETRY_MAX_RETRIES_LIMIT (10).
         mesh.addTask([&mesh, ip, port, retryCount]() {
           Log(CONNECTION, "tcp_err(): Retrying TCP connection...\n");
           
@@ -178,7 +284,7 @@ void connect(AsyncClient &client, IPAddress ip, uint16_t port, M &mesh,
       // Adding a significant delay before reconnection prevents rapid reconnection loops
       // when the TCP server is persistently unavailable or overloaded
       Log(CONNECTION, "tcp_err(): All %d retries exhausted for IP %s\n",
-          TCP_CONNECT_MAX_RETRIES + 1, ip.toString().c_str());
+          cfg.maxRetries + 1, ip.toString().c_str());
       
       // Block this node temporarily to prevent immediate reconnection to the same unresponsive node
       // This helps when the bridge's TCP server is down but WiFi AP is still running
@@ -186,15 +292,19 @@ void connect(AsyncClient &client, IPAddress ip, uint16_t port, M &mesh,
       #if !defined(PAINLESSMESH_BOOST)
       // Try to decode nodeId from IP and block it
       // Only works for mesh IPs (format: 10.x.x.1)
+      // A failureBlockDurationMs of 0 is an explicit "never blocklist" opt-out.
+      // Passing it through would set blockUntil = millis() + 0, which
+      // isNodeBlocked() reads as already expired - so the entry would do
+      // nothing except linger in the blocklist until cleanup sweeps it.
       uint32_t failedNodeId = decodeNodeIdFromIP(ip);
-      if (failedNodeId != 0) {
+      if (failedNodeId != 0 && cfg.failureBlockDurationMs > 0) {
         // Note: This requires M to be wifi::Mesh which has blockNodeAfterTCPFailure
-        mesh.blockNodeAfterTCPFailure(ip, TCP_FAILURE_BLOCK_DURATION_MS);
+        mesh.blockNodeAfterTCPFailure(ip, cfg.failureBlockDurationMs);
       }
       #endif
-      
+
       Log(CONNECTION, "tcp_err(): Scheduling WiFi reconnection in %u ms\n",
-          TCP_EXHAUSTION_RECONNECT_DELAY_MS);
+          cfg.exhaustionReconnectDelayMs);
       
       // Defer deletion of the failed AsyncClient to prevent heap corruption
       // Use the centralized deletion scheduler to ensure proper spacing between deletions
@@ -208,13 +318,32 @@ void connect(AsyncClient &client, IPAddress ip, uint16_t port, M &mesh,
       mesh.addTask([&mesh]() {
         Log(CONNECTION, "tcp_err(): Executing delayed WiFi reconnection after retry exhaustion\n");
         mesh.droppedConnectionCallbacks.execute(0, true);
-      }, TCP_EXHAUSTION_RECONNECT_DELAY_MS);
+      }, cfg.exhaustionReconnectDelayMs);
       mesh.semaphoreGive();
     }
   });
 
   client.onConnect(
-      [&mesh](void *, AsyncClient *client) {
+      [&mesh, claimed](void *, AsyncClient *client) {
+        if (*claimed) {
+          // onError has already fired for this client (e.g. an abort
+          // caused by losing WiFi right while the TCP handshake was
+          // completing): the client is already scheduled for deletion by
+          // the retry path. Wrapping it in a new BufferedConnection now
+          // would give it two owners at once. This connection did however
+          // genuinely succeed at the TCP level (that's why onConnect
+          // fired): close it explicitly here, so that when the deferred
+          // deletion already scheduled by onError fires, it finds a
+          // properly closed client instead of one still "connected" -
+          // otherwise we'd fall right back into the bug we're fixing.
+          Log(CONNECTION,
+              "tcp::connect(): onConnect fired after onError had already "
+              "claimed the client - closing the connection and discarding "
+              "it\n");
+          client->close();
+          return;
+        }
+        *claimed = true;
         if (mesh.semaphoreTake()) {
           Log(CONNECTION, "New STA connection incoming\n");
           auto conn = std::make_shared<T>(client, &mesh, true);

package/src/painlessmesh/validation.hpp

@@ -8,12 +8,9 @@
  * security and robustness of the mesh network.
  */
 
-#include <list>
-#include <map>
 #ifndef ARDUINO
 #include <chrono>
 #endif
-#include "ArduinoJson.h"
 #include "painlessmesh/configuration.hpp"
 
 namespace painlessmesh {
@@ -45,146 +42,6 @@ struct ValidationConfig {
   bool strict_type_checking = true;   // Enable strict type validation
 };
 
-/**
- * Rate limiting for preventing message spam
- */
-class RateLimiter {
- public:
-  RateLimiter(size_t max_messages_per_second = 10, size_t window_size_ms = 1000)
-      : max_messages_(max_messages_per_second), window_size_(window_size_ms) {}
-
-  bool allow_message(uint32_t node_id) {
-    uint32_t current_time = get_current_time();
-    auto& history = node_history_[node_id];
-
-    // Remove old entries outside the window
-    while (!history.empty() &&
-           (current_time - history.front()) > window_size_) {
-      history.pop_front();
-    }
-
-    // Check if limit is exceeded
-    if (history.size() >= max_messages_) {
-      return false;
-    }
-
-    // Record this message
-    history.push_back(current_time);
-    return true;
-  }
-
-  void clear_node_history(uint32_t node_id) { node_history_.erase(node_id); }
-
-  void clear_all_history() { node_history_.clear(); }
-
- private:
-  uint32_t get_current_time() const {
-#ifdef ARDUINO
-    return millis();
-#else
-    auto now = std::chrono::steady_clock::now();
-    auto duration = now.time_since_epoch();
-    return std::chrono::duration_cast<std::chrono::milliseconds>(duration)
-        .count();
-#endif
-  }
-
-  size_t max_messages_;
-  size_t window_size_;
-  std::map<uint32_t, std::list<uint32_t>> node_history_;
-};
-
-/**
- * JSON message validator
- */
-class MessageValidator {
- public:
-  explicit MessageValidator(const ValidationConfig& config = ValidationConfig{})
-      : config_(config) {}
-
-  /**
-   * Validate a JSON message for basic structure and security
-   */
-  ValidationResult validate_message(const JsonObject& obj,
-                                    size_t message_size = 0) const {
-    // Check message size
-    if (message_size > config_.max_message_size) {
-      return ValidationResult::MESSAGE_TOO_LARGE;
-    }
-
-    // Check required fields based on message type
-    if (!obj["type"].is<int>()) {
-      return ValidationResult::MISSING_REQUIRED_FIELD;
-    }
-
-    // Validate node IDs if present
-    if (obj["from"].is<uint32_t>()) {
-      uint32_t from_id = obj["from"].as<uint32_t>();
-      if (!is_valid_node_id(from_id)) {
-        return ValidationResult::INVALID_NODE_ID;
-      }
-    }
-
-    if (obj["dest"].is<uint32_t>()) {
-      uint32_t dest_id = obj["dest"].as<uint32_t>();
-      if (dest_id != 0 && !is_valid_node_id(dest_id)) {  // 0 is broadcast
-        return ValidationResult::INVALID_NODE_ID;
-      }
-    }
-
-    // Validate string fields
-    for (JsonPair pair : obj) {
-      if (pair.value().is<const char*>()) {
-        const char* str_value = pair.value().as<const char*>();
-        if (strlen(str_value) > config_.max_string_length) {
-          return ValidationResult::INVALID_FIELD_VALUE;
-        }
-      }
-    }
-
-    return ValidationResult::VALID;
-  }
-
-  /**
-   * Validate node ID range
-   */
-  bool is_valid_node_id(uint32_t node_id) const {
-    return node_id >= config_.min_node_id && node_id <= config_.max_node_id;
-  }
-
-  /**
-   * Get validation error message
-   */
-  const char* get_error_message(ValidationResult result) const {
-    switch (result) {
-      case ValidationResult::VALID:
-        return "Valid";
-      case ValidationResult::INVALID_JSON:
-        return "Invalid JSON format";
-      case ValidationResult::MISSING_REQUIRED_FIELD:
-        return "Missing required field";
-      case ValidationResult::INVALID_FIELD_TYPE:
-        return "Invalid field type";
-      case ValidationResult::INVALID_FIELD_VALUE:
-        return "Invalid field value";
-      case ValidationResult::MESSAGE_TOO_LARGE:
-        return "Message too large";
-      case ValidationResult::INVALID_NODE_ID:
-        return "Invalid node ID";
-      case ValidationResult::RATE_LIMIT_EXCEEDED:
-        return "Rate limit exceeded";
-      default:
-        return "Unknown error";
-    }
-  }
-
-  const ValidationConfig& get_config() const { return config_; }
-  void set_config(const ValidationConfig& config) { config_ = config; }
-
- private:
-  ValidationConfig config_;
-};
-
 /**
  * Secure random number generation for mesh operations
  */

package/docs/README.md

@@ -1,132 +0,0 @@
-# 📚 AlteriomPainlessMesh Documentation
-
-Welcome to the comprehensive documentation for the Alteriom fork of painlessMesh - a user-friendly ESP8266/ESP32 mesh networking library with advanced OTA updates, MQTT integration, and structured IoT packages.
-
-## 🌟 What's New in Alteriom Fork
-
-- **Broadcast OTA Distribution** - 98% network traffic reduction for large meshes
-- **MQTT Status Bridge** - Enterprise monitoring integration (Grafana, InfluxDB)
-- **Structured Packages** - SensorPackage, CommandPackage, StatusPackage
-- **Enhanced CI/CD** - Automated releases to NPM, PlatformIO, Arduino Library Manager
-
-## 📖 Documentation Structure
-
-### Getting Started
-
-- [Quick Start Guide](getting-started/quickstart.md) - Get up and running in minutes
-- [Installation](getting-started/installation.md) - Detailed installation instructions
-- [First Mesh Network](getting-started/first-mesh.md) - Your first working mesh
-
-### Architecture & Design  
-
-- [Mesh Architecture](architecture/mesh-architecture.md) - How painlessMesh works internally
-- [Plugin System](architecture/plugin-system.md) - Understanding the plugin architecture
-- [Message Routing](architecture/routing.md) - Message routing algorithms and strategies
-- [Time Synchronization](architecture/time-sync.md) - Mesh-wide time synchronization
-
-### API Reference
-
-- [Core API](api/core-api.md) - Main painlessMesh class methods
-- [Shared Gateway API](api/shared-gateway.md) - Shared Gateway Mode reference (v1.9.0+)
-- [Plugin API](api/plugin-api.md) - Creating custom packages and plugins
-- [Configuration](api/configuration.md) - Configuration options and constants
-- [Callbacks](api/callbacks.md) - Event handling and callbacks
-
-### Tutorials & Examples
-
-- [Basic Examples](tutorials/basic-examples.md) - Simple mesh networking examples
-- [Custom Packages](tutorials/custom-packages.md) - Creating your own message types
-- [Sensor Networks](tutorials/sensor-networks.md) - Building IoT sensor networks
-- [Bridge to Internet](../BRIDGE_TO_INTERNET.md) - Connecting mesh to WiFi/Internet/MQTT
-
-### Alteriom Extensions
-
-- [Alteriom Overview](alteriom/overview.md) - Alteriom-specific functionality
-- [Sensor Packages](alteriom/sensor-packages.md) - Environmental sensor data handling
-- [Command System](alteriom/command-system.md) - Device command and control
-- [Status Monitoring](alteriom/status-monitoring.md) - Device health and diagnostics
-
-### 📡 MQTT Integration
-
-- **[MQTT Bridge Commands](MQTT_BRIDGE_COMMANDS.md)** - Complete MQTT command API
-- **[MQTT Bridge Implementation](MQTT_BRIDGE_IMPLEMENTATION_SUMMARY.md)** - Implementation details
-- **[MQTT Schema Compliance](MQTT_SCHEMA_COMPLIANCE.md)** - Schema validation
-- **[OTA Commands Reference](OTA_COMMANDS_REFERENCE.md)** - OTA update commands
-- **[Mesh Topology Guide](MESH_TOPOLOGY_GUIDE.md)** - Topology reporting over MQTT
-
-### Advanced Topics
-
-- [Performance Optimization](advanced/performance.md) - Optimizing mesh performance
-- [Memory Management](advanced/memory.md) - Managing ESP8266/ESP32 memory constraints
-- [Security Considerations](advanced/security.md) - Securing your mesh network
-- [OTA Updates](advanced/ota.md) - Over-the-air firmware updates in mesh
-
-### Troubleshooting
-
-- [Common Issues](troubleshooting/common-issues.md) - Solutions to frequent problems
-- [ESP32-C6 Compatibility](troubleshooting/ESP32_C6_COMPATIBILITY.md) - ESP32-C6 specific issues and solutions
-- [Debugging Guide](troubleshooting/debugging.md) - Tools and techniques for debugging
-- [FAQ](troubleshooting/faq.md) - Frequently asked questions
-- [Network Issues](troubleshooting/network-issues.md) - Connectivity and mesh topology problems
-
-### Development
-
-- [Contributing](development/contributing.md) - How to contribute to painlessMesh
-- [Building & Testing](development/building.md) - Development environment setup
-- [Documentation](development/documentation.md) - Contributing to documentation
-- [Release Process](development/releases.md) - Understanding releases and versioning
-- **[Docker Testing](development/DOCKER_TESTING.md)** - Containerized testing environment
-- **[Testing Summary](development/TESTING_SUMMARY.md)** - Complete test suite overview
-- **[Arduino Compliance](development/ARDUINO_COMPLIANCE_SUMMARY.md)** - Arduino Library Manager standards
-- **[PlatformIO Usage](development/PLATFORMIO_USAGE.md)** - PlatformIO integration guide
-
-### 📦 Releases & Changelogs
-
-- **[Feature History](releases/FEATURE_HISTORY.md)** - ⭐ Consolidated Phase 1 & 2 development history
-- **[Release Notes v1.7.0](releases/RELEASE_NOTES_1.7.0.md)** - Detailed v1.7.0 release notes
-- **[CHANGELOG](../CHANGELOG.md)** - Complete version history
-- **[RELEASE_GUIDE](../RELEASE_GUIDE.md)** - Maintainer release process
-- [Phase 1 Details](releases/PHASE1_SUMMARY.md) - v1.6.x detailed summary (archived)
-- [Phase 2 Details](releases/PHASE2_SUMMARY.md) - v1.7.x detailed summary (archived)
-
-### 🗂️ Core Documentation (Root)
-
-- **[Main README](../README.md)** - Project overview and quick start
-- **[CONTRIBUTING](../CONTRIBUTING.md)** - Contribution guidelines
-- **[LICENSE](../LICENSE)** - LGPL-3.0 license terms
-
-### 🗃️ Historical & Archive
-
-- **[Archive](archive/)** - Historical bug fixes and obsolete documentation
-  - Bug fix documentation (SCONS, VECTOR, LIBRARY fixes)
-  - Legacy deployment guides
-  - Superseded release documentation
-
-### 🚀 Improvements & Enhancements
-
-- **[Improvements Overview](improvements/README.md)** - Complete guide to library enhancements
-- **[OTA & Status Enhancements](improvements/OTA_STATUS_ENHANCEMENTS.md)** 📋 - Complete reference for all options
-  - ✅ Phase 1 (v1.6.x): Compressed OTA + Enhanced Status
-  - ✅ Phase 2 (v1.7.0): Broadcast OTA + MQTT Bridge
-  - 📋 Phase 3 (Future): Progressive rollout, P2P distribution, real-time telemetry
-- **[Implementation History](improvements/IMPLEMENTATION_HISTORY.md)** 🔧 - Technical details for Phases 1-2
-- **[Future Proposals](improvements/FUTURE_PROPOSALS.md)** 🚀 - Phase 3+ roadmap and specifications
-
-## Quick Links
-
-- **[GitHub Repository](https://github.com/Alteriom/painlessMesh)**
-- **[API Documentation](https://alteriom.github.io/painlessMesh/#/api/doxygen)**
-- **[Community Forum](https://groups.google.com/forum/#!forum/painlessmesh-user)**
-- **[Issue Tracker](https://github.com/Alteriom/painlessMesh/issues)**
-
-## Need Help?
-
-- Start with the [Quick Start Guide](getting-started/quickstart.md)
-- Check the [FAQ](troubleshooting/faq.md) for common questions
-- Browse [Examples](tutorials/basic-examples.md) for practical use cases
-- Join our [Community Forum](https://groups.google.com/forum/#!forum/painlessmesh-user)
-- Report bugs on the [Issue Tracker](https://github.com/Alteriom/painlessMesh/issues)
-
----
-
-This documentation is maintained by the painlessMesh community. Contributions are welcome! See our [Documentation Contributing Guide](development/documentation.md) to get started.