@alteriom/painlessmesh 1.8.0 → 1.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alteriom/painlessmesh",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "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/arduino/wifi.hpp

@@ -18,6 +18,13 @@ namespace painlessmesh {
 namespace wifi {
 class Mesh : public painlessmesh::Mesh<Connection> {
  public:
+  // Multi-bridge selection strategy enum (must be declared early)
+  enum BridgeSelectionStrategy {
+    PRIORITY_BASED = 0,  // Use highest priority bridge (default)
+    ROUND_ROBIN = 1,     // Distribute load evenly
+    BEST_SIGNAL = 2      // Use bridge with best RSSI
+  };
+
   /** Initialize the mesh network
    *
    * Add this to your setup() function. This routine does the following things:
@@ -279,6 +286,51 @@ class Mesh : public painlessmesh::Mesh<Connection> {
     Log(STARTUP, "  Port: %d\n", port);
   }
 
+  /**
+   * Initialize mesh as a bridge node with priority (for multi-bridge mode)
+   * 
+   * This overload adds bridge priority configuration for multi-bridge deployments.
+   * Priority determines which bridge is preferred when multiple bridges are available.
+   * 
+   * @param meshSSID The name of your mesh network
+   * @param meshPassword WiFi password for the mesh
+   * @param routerSSID SSID of the router to connect to
+   * @param routerPassword Password for the router
+   * @param baseScheduler Task scheduler for mesh operations
+   * @param port TCP port for mesh communication (default: 5555)
+   * @param priority Bridge priority: 10=highest (primary), 5=medium (secondary), 1=lowest (default: 5)
+   */
+  void initAsBridge(TSTRING meshSSID, TSTRING meshPassword,
+                    TSTRING routerSSID, TSTRING routerPassword,
+                    Scheduler *baseScheduler, uint16_t port, uint8_t priority) {
+    using namespace logger;
+    
+    // Validate and store priority
+    if (priority < 1) priority = 1;
+    if (priority > 10) priority = 10;
+    bridgePriority = priority;
+    
+    // Store role based on priority
+    if (priority >= 8) {
+      bridgeRole = "primary";
+    } else if (priority >= 5) {
+      bridgeRole = "secondary";
+    } else {
+      bridgeRole = "standby";
+    }
+    
+    Log(STARTUP, "=== Bridge Mode Initialization (Priority: %d, Role: %s) ===\n", 
+        priority, bridgeRole.c_str());
+    
+    // Call the base initAsBridge method
+    initAsBridge(meshSSID, meshPassword, routerSSID, routerPassword, baseScheduler, port);
+    
+    // Setup multi-bridge coordination if enabled
+    if (multiBridgeEnabled) {
+      initBridgeCoordination();
+    }
+  }
+
   /**
    * Connect (as a station) to a specified network and ip
    *
@@ -418,6 +470,148 @@ class Mesh : public painlessmesh::Mesh<Connection> {
     bridgeRoleChangedCallback = callback;
   }
 
+  /**
+   * Enable or disable multi-bridge coordination mode
+   * 
+   * When enabled, multiple bridges can operate simultaneously for:
+   * - Load balancing across multiple Internet connections
+   * - Geographic distribution
+   * - Hot standby redundancy without failover delays
+   * 
+   * @param enabled true to enable multi-bridge mode, false for single-bridge (default)
+   */
+  void enableMultiBridge(bool enabled) {
+    multiBridgeEnabled = enabled;
+    if (enabled) {
+      Log(logger::GENERAL, "enableMultiBridge(): Multi-bridge coordination enabled\n");
+    }
+  }
+
+  /**
+   * Set bridge selection strategy for multi-bridge mode
+   * 
+   * @param strategy Selection strategy:
+   *   - PRIORITY_BASED: Always use highest priority bridge (default)
+   *   - ROUND_ROBIN: Distribute load evenly across bridges
+   *   - BEST_SIGNAL: Always use bridge with best RSSI
+   */
+  void setBridgeSelectionStrategy(BridgeSelectionStrategy strategy) {
+    bridgeSelectionStrategy = strategy;
+    Log(logger::GENERAL, "setBridgeSelectionStrategy(): Strategy set to %d\n", (int)strategy);
+  }
+
+  /**
+   * Set maximum number of concurrent bridges in multi-bridge mode
+   * 
+   * @param maxBridges Maximum bridges to track (default: 2, max: 5)
+   */
+  void setMaxBridges(uint8_t maxBridges) {
+    if (maxBridges < 1) maxBridges = 1;
+    if (maxBridges > 5) maxBridges = 5;
+    maxConcurrentBridges = maxBridges;
+    Log(logger::GENERAL, "setMaxBridges(): Max concurrent bridges set to %d\n", maxBridges);
+  }
+
+  /**
+   * Get list of all active bridges (with Internet connection)
+   * 
+   * @return vector of node IDs for active bridges
+   */
+  std::vector<uint32_t> getActiveBridges() {
+    std::vector<uint32_t> activeBridges;
+    auto bridges = this->getBridges();
+    
+    for (const auto& bridge : bridges) {
+      if (bridge.internetConnected && bridge.isHealthy()) {
+        activeBridges.push_back(bridge.nodeId);
+      }
+    }
+    
+    return activeBridges;
+  }
+
+  /**
+   * Get recommended bridge for message transmission
+   * 
+   * Uses the configured bridge selection strategy to pick the best bridge.
+   * Returns 0 if no suitable bridge is available.
+   * 
+   * @return node ID of recommended bridge, or 0 if none available
+   */
+  uint32_t getRecommendedBridge() {
+    auto activeBridges = getActiveBridges();
+    
+    if (activeBridges.empty()) {
+      return 0;
+    }
+    
+    // Single bridge - return it
+    if (activeBridges.size() == 1) {
+      return activeBridges[0];
+    }
+    
+    // Multi-bridge mode: apply selection strategy
+    switch (bridgeSelectionStrategy) {
+      case ROUND_ROBIN: {
+        // Simple round-robin: cycle through bridges
+        lastSelectedBridgeIndex = (lastSelectedBridgeIndex + 1) % activeBridges.size();
+        return activeBridges[lastSelectedBridgeIndex];
+      }
+      
+      case BEST_SIGNAL: {
+        // Find bridge with best RSSI
+        uint32_t bestBridge = 0;
+        int8_t bestRSSI = -127;
+        
+        for (const auto& bridge : this->getBridges()) {
+          if (bridge.internetConnected && bridge.isHealthy() && bridge.routerRSSI > bestRSSI) {
+            bestRSSI = bridge.routerRSSI;
+            bestBridge = bridge.nodeId;
+          }
+        }
+        return bestBridge;
+      }
+      
+      case PRIORITY_BASED:
+      default: {
+        // Use highest priority bridge (stored in bridgePriorities map)
+        uint32_t bestBridge = 0;
+        uint8_t highestPriority = 0;
+        
+        for (uint32_t bridgeId : activeBridges) {
+          uint8_t priority = bridgePriorities[bridgeId];
+          if (priority > highestPriority) {
+            highestPriority = priority;
+            bestBridge = bridgeId;
+          }
+        }
+        
+        // If no priority info, use first active bridge
+        return bestBridge ? bestBridge : activeBridges[0];
+      }
+    }
+  }
+
+  /**
+   * Select a specific bridge for next transmission
+   * 
+   * This overrides the automatic bridge selection for one message.
+   * 
+   * @param bridgeNodeId Node ID of bridge to use
+   */
+  void selectBridge(uint32_t bridgeNodeId) {
+    selectedBridgeOverride = bridgeNodeId;
+  }
+
+  /**
+   * Check if multi-bridge mode is enabled
+   * 
+   * @return true if multi-bridge coordination is enabled
+   */
+  bool isMultiBridgeEnabled() const {
+    return multiBridgeEnabled;
+  }
+
   void stop() {
     // remove all WiFi events
 #ifdef ESP32
@@ -498,6 +692,115 @@ class Mesh : public painlessmesh::Mesh<Connection> {
         this->bridgeStatusIntervalMs);
   }
 
+  /**
+   * Initialize bridge coordination broadcasting
+   * Sets up periodic coordination messages between bridges
+   */
+  void initBridgeCoordination() {
+    using namespace logger;
+    
+    if (!this->isBridge() || !multiBridgeEnabled) {
+      return;
+    }
+    
+    Log(STARTUP, "initBridgeCoordination(): Setting up multi-bridge coordination\n");
+    
+    // Register handler for incoming coordination messages (Type 613)
+    this->callbackList.onPackage(
+        613,  // BRIDGE_COORDINATION type
+        [this](protocol::Variant& variant, std::shared_ptr<Connection>, uint32_t) {
+          JsonDocument doc;
+          TSTRING str;
+          variant.printTo(str);
+          deserializeJson(doc, str);
+          JsonObject obj = doc.as<JsonObject>();
+          
+          if (obj["priority"].is<unsigned int>()) {
+            uint32_t fromNode = obj["from"];
+            uint8_t priority = obj["priority"];
+            TSTRING role = obj["role"].as<TSTRING>();
+            uint8_t load = obj["load"] | 0;
+            
+            // Store bridge priority for selection decisions
+            bridgePriorities[fromNode] = priority;
+            
+            // Update peer bridges list
+            if (obj["peerBridges"].is<JsonArray>()) {
+              JsonArray peers = obj["peerBridges"];
+              for (JsonVariant peer : peers) {
+                uint32_t peerId = peer.as<uint32_t>();
+                if (peerId != this->nodeId && 
+                    std::find(knownBridgePeers.begin(), knownBridgePeers.end(), peerId) == knownBridgePeers.end()) {
+                  knownBridgePeers.push_back(peerId);
+                }
+              }
+            }
+            
+            Log(CONNECTION, "Bridge coordination from %u: priority=%d, role=%s, load=%d%%\n",
+                fromNode, priority, role.c_str(), load);
+          }
+          return false;  // Don't consume the package
+        });
+    
+    // Create periodic task to send coordination messages
+    bridgeCoordinationTask = this->addTask(
+      30000,  // 30 seconds interval
+      TASK_FOREVER,
+      [this]() {
+        this->sendBridgeCoordination();
+      }
+    );
+    
+    Log(STARTUP, "Bridge coordination enabled (priority: %d, role: %s)\n", 
+        bridgePriority, bridgeRole.c_str());
+  }
+
+  /**
+   * Send bridge coordination message to other bridges
+   * Called periodically in multi-bridge mode
+   */
+  void sendBridgeCoordination() {
+    using namespace logger;
+    
+    if (!this->isBridge() || !multiBridgeEnabled) {
+      return;
+    }
+    
+    // Calculate current load (simplified: based on node count)
+    uint8_t currentLoad = 0;
+    auto nodeCount = this->getNodeList(false).size();
+    if (nodeCount > 0) {
+      currentLoad = (nodeCount * 100) / MAX_CONN;
+      if (currentLoad > 100) currentLoad = 100;
+    }
+    
+    // Create coordination message
+    JsonDocument doc;
+    JsonObject obj = doc.to<JsonObject>();
+    
+    obj["type"] = 613;  // BRIDGE_COORDINATION
+    obj["from"] = this->nodeId;
+    obj["routing"] = 2;  // BROADCAST
+    obj["priority"] = bridgePriority;
+    obj["role"] = bridgeRole;
+    obj["load"] = currentLoad;
+    obj["timestamp"] = this->getNodeTime();
+    obj["message_type"] = 613;
+    
+    // Add peer bridges list
+    JsonArray peers = obj["peerBridges"].to<JsonArray>();
+    for (uint32_t peerId : knownBridgePeers) {
+      peers.add(peerId);
+    }
+    
+    String msg;
+    serializeJson(doc, msg);
+    this->sendBroadcast(msg);
+    
+    Log(CONNECTION, "Bridge coordination sent: priority=%d, role=%s, load=%d%%\n",
+        bridgePriority, bridgeRole.c_str(), currentLoad);
+  }
+
   /**
    * Scan for router and return its signal strength
    * 
@@ -578,7 +881,7 @@ class Mesh : public painlessmesh::Mesh<Connection> {
     electionCandidates.push_back(selfCandidate);
     
     // Broadcast candidacy using JSON directly (avoiding dependency on alteriom package)
-    DynamicJsonDocument doc(256);
+    JsonDocument doc;
     JsonObject obj = doc.to<JsonObject>();
     obj["type"] = 611;  // BRIDGE_ELECTION
     obj["from"] = this->nodeId;
@@ -721,7 +1024,7 @@ class Mesh : public painlessmesh::Mesh<Connection> {
     }
     
     // Broadcast takeover announcement
-    DynamicJsonDocument doc(256);
+    JsonDocument doc;
     JsonObject obj = doc.to<JsonObject>();
     obj["type"] = 612;  // BRIDGE_TAKEOVER
     obj["from"] = this->nodeId;
@@ -789,7 +1092,7 @@ class Mesh : public painlessmesh::Mesh<Connection> {
     // Create bridge status package
     // We need to include the package header here since we're in wifi namespace
     // The package will be sent as a JSON string
-    DynamicJsonDocument doc(256);
+    JsonDocument doc;
     JsonObject obj = doc.to<JsonObject>();
     
     obj["type"] = 610;  // BRIDGE_STATUS type
@@ -937,6 +1240,19 @@ class Mesh : public painlessmesh::Mesh<Connection> {
   uint32_t electionDeadline = 0;
   std::vector<BridgeCandidate> electionCandidates;
   std::function<void(bool isBridge, TSTRING reason)> bridgeRoleChangedCallback;
+
+  // Multi-bridge coordination state and configuration
+ protected:
+  bool multiBridgeEnabled = false;
+  BridgeSelectionStrategy bridgeSelectionStrategy = PRIORITY_BASED;
+  uint8_t maxConcurrentBridges = 2;
+  uint8_t bridgePriority = 5;  // Default medium priority
+  TSTRING bridgeRole = "secondary";  // Default role
+  std::shared_ptr<Task> bridgeCoordinationTask;
+  std::map<uint32_t, uint8_t> bridgePriorities;  // nodeId -> priority mapping
+  std::vector<uint32_t> knownBridgePeers;  // List of peer bridge node IDs
+  uint32_t selectedBridgeOverride = 0;  // Manual bridge selection override
+  size_t lastSelectedBridgeIndex = 0;  // For round-robin selection
 };
 }  // namespace wifi
 };  // namespace painlessmesh

package/src/painlessmesh/mesh.hpp

@@ -7,6 +7,7 @@
 
 #include "painlessmesh/connection.hpp"
 #include "painlessmesh/logger.hpp"
+#include "painlessmesh/message_queue.hpp"
 #include "painlessmesh/ntp.hpp"
 #include "painlessmesh/plugin.hpp"
 #include "painlessmesh/protocol.hpp"
@@ -810,6 +811,200 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
     rtcSyncCompleteCallback = onRTCSyncComplete;
   }
 
+  //
+  // Message Queue API
+  //
+  
+  /**
+   * Enable or disable message queueing for offline mode
+   * 
+   * When enabled, messages can be queued when Internet is unavailable
+   * and automatically flushed when connection is restored.
+   * 
+   * @param enabled True to enable queueing, false to disable
+   * @param maxSize Maximum number of messages in queue (default 1000)
+   * 
+   * \code
+   * mesh.enableMessageQueue(true, 500);  // Enable with 500 message capacity
+   * \endcode
+   */
+  void enableMessageQueue(bool enabled, uint32_t maxSize = 1000) {
+    if (enabled && !messageQueue) {
+      messageQueue = new MessageQueue(maxSize);
+      Log(logger::GENERAL, "enableMessageQueue(): Queue enabled with capacity %u\n", maxSize);
+    } else if (!enabled && messageQueue) {
+      delete messageQueue;
+      messageQueue = nullptr;
+      Log(logger::GENERAL, "enableMessageQueue(): Queue disabled\n");
+    }
+  }
+  
+  /**
+   * Queue a message with priority for later delivery
+   * 
+   * Use this to queue critical messages when Internet is unavailable.
+   * Messages are automatically delivered when connection is restored.
+   * 
+   * @param payload Message content to queue
+   * @param destination Optional destination metadata (e.g., MQTT topic, HTTP endpoint)
+   * @param priority Message priority (default: PRIORITY_NORMAL)
+   * @return Message ID if successfully queued, 0 if failed
+   * 
+   * \code
+   * // Queue critical alarm
+   * uint32_t msgId = mesh.queueMessage(
+   *   alarmData.toJSON(),
+   *   "mqtt://cloud.example.com/alarms",
+   *   PRIORITY_CRITICAL
+   * );
+   * \endcode
+   */
+  uint32_t queueMessage(const TSTRING& payload, 
+                       const TSTRING& destination = "",
+                       MessagePriority priority = PRIORITY_NORMAL) {
+    if (!messageQueue) {
+      Log(logger::ERROR, "queueMessage(): Message queue not enabled\n");
+      return 0;
+    }
+    
+    return messageQueue->enqueue(priority, payload, destination);
+  }
+  
+  /**
+   * Flush all queued messages
+   * 
+   * Attempts to send all queued messages. This is typically called
+   * automatically when Internet connection is restored, but can be
+   * called manually.
+   * 
+   * Note: This returns the messages for the application to send.
+   * The application is responsible for actually transmitting them
+   * and calling removeQueuedMessage() when successful.
+   * 
+   * @return Vector of queued messages to send
+   * 
+   * \code
+   * auto messages = mesh.flushMessageQueue();
+   * for (auto& msg : messages) {
+   *   if (sendToCloud(msg.payload, msg.destination)) {
+   *     mesh.removeQueuedMessage(msg.id);
+   *   }
+   * }
+   * \endcode
+   */
+  std::vector<QueuedMessage> flushMessageQueue() {
+    if (!messageQueue) {
+      return std::vector<QueuedMessage>();
+    }
+    
+    return messageQueue->getMessages();
+  }
+  
+  /**
+   * Remove a successfully sent message from the queue
+   * 
+   * @param messageId ID of message to remove
+   * @return true if message was found and removed
+   */
+  bool removeQueuedMessage(uint32_t messageId) {
+    if (!messageQueue) {
+      return false;
+    }
+    
+    return messageQueue->remove(messageId);
+  }
+  
+  /**
+   * Increment send attempt counter for a message
+   * 
+   * @param messageId ID of message
+   * @return New attempt count, or 0 if message not found
+   */
+  uint32_t incrementQueuedMessageAttempts(uint32_t messageId) {
+    if (!messageQueue) {
+      return 0;
+    }
+    
+    return messageQueue->incrementAttempts(messageId);
+  }
+  
+  /**
+   * Get number of queued messages
+   * 
+   * @param priority Optional priority level to count (counts all if not specified)
+   * @return Number of queued messages
+   */
+  uint32_t getQueuedMessageCount(MessagePriority priority) {
+    if (!messageQueue) {
+      return 0;
+    }
+    
+    return messageQueue->size(priority);
+  }
+  
+  uint32_t getQueuedMessageCount() {
+    if (!messageQueue) {
+      return 0;
+    }
+    
+    return messageQueue->size();
+  }
+  
+  /**
+   * Get queue statistics
+   * 
+   * @return QueueStats structure with detailed statistics
+   */
+  QueueStats getQueueStats() {
+    if (!messageQueue) {
+      return QueueStats();
+    }
+    
+    return messageQueue->getStats();
+  }
+  
+  /**
+   * Set callback for queue state changes
+   * 
+   * Fires when queue state changes (EMPTY, NORMAL, 75%, FULL)
+   * 
+   * \code
+   * mesh.onQueueStateChanged([](QueueState state, uint32_t count) {
+   *   if (state == QUEUE_75_PERCENT) {
+   *     Serial.printf("Warning: Queue 75%% full (%u messages)\n", count);
+   *   }
+   * });
+   * \endcode
+   */
+  void onQueueStateChanged(queueStateChangedCallback_t callback) {
+    if (messageQueue) {
+      messageQueue->onStateChanged(callback);
+    }
+  }
+  
+  /**
+   * Prune old messages from the queue
+   * 
+   * @param maxAgeMs Maximum age in milliseconds
+   * @return Number of messages removed
+   */
+  uint32_t pruneQueue(uint32_t maxAgeMs) {
+    if (!messageQueue) {
+      return 0;
+    }
+    
+    return messageQueue->pruneOldMessages(maxAgeMs);
+  }
+  
+  /**
+   * Clear all messages from the queue
+   */
+  void clearQueue() {
+    if (messageQueue) {
+      messageQueue->clear();
+    }
+  }
+
   /**
    * Are we connected/know a route to the given node?
    *
@@ -1568,6 +1763,7 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
   ~Mesh() {
     this->stop();
     if (!isExternalScheduler) delete mScheduler;
+    if (messageQueue) delete messageQueue;
   }
 
  protected:
@@ -1621,6 +1817,10 @@ class Mesh : public ntp::MeshTime, public plugin::PackageHandler<T> {
   nodeDelayCallback_t nodeDelayReceivedCallback;
   bridgeStatusChangedCallback_t bridgeStatusChangedCallback;
   rtcSyncCompleteCallback_t rtcSyncCompleteCallback;
+  
+  // Message queue for offline mode
+  MessageQueue* messageQueue = nullptr;
+  
 #ifdef ESP32
   SemaphoreHandle_t xSemaphore = NULL;
 #endif