@alteriom/painlessmesh 1.8.14 → 1.9.0

package/src/painlessmesh/message_tracker.hpp

@@ -0,0 +1,311 @@
+#ifndef _PAINLESS_MESH_MESSAGE_TRACKER_HPP_
+#define _PAINLESS_MESH_MESSAGE_TRACKER_HPP_
+
+#include <map>
+#include <algorithm>
+#include "painlessmesh/configuration.hpp"
+#include "painlessmesh/logger.hpp"
+
+// External logger instance
+extern painlessmesh::logger::LogClass Log;
+
+namespace painlessmesh {
+
+/**
+ * Key for tracking messages by their unique combination of ID and origin node
+ */
+struct MessageKey {
+  uint32_t messageId;
+  uint32_t originNode;
+  
+  bool operator<(const MessageKey& other) const {
+    if (messageId != other.messageId) {
+      return messageId < other.messageId;
+    }
+    return originNode < other.originNode;
+  }
+  
+  bool operator==(const MessageKey& other) const {
+    return messageId == other.messageId && originNode == other.originNode;
+  }
+};
+
+/**
+ * Tracked message entry with timestamp and acknowledgment status
+ */
+struct TrackedMessage {
+  uint32_t timestamp;     // When the message was first processed (millis)
+  bool acknowledged;      // Whether the message has been acknowledged
+  
+  TrackedMessage() : timestamp(0), acknowledged(false) {}
+  TrackedMessage(uint32_t ts) : timestamp(ts), acknowledged(false) {}
+};
+
+/**
+ * MessageTracker - Prevents duplicate message processing and tracks acknowledgments
+ * 
+ * This class provides efficient tracking of processed messages to prevent
+ * duplicate processing in mesh networks. It supports:
+ * - Configurable maximum tracked messages (memory-efficient for ESP8266)
+ * - Automatic cleanup of expired entries
+ * - Acknowledgment tracking for reliable delivery
+ * - Thread-safe consideration for ESP32
+ * 
+ * Example usage:
+ * \code
+ * MessageTracker tracker(500, 60000);  // Max 500 messages, 60s timeout
+ * 
+ * uint32_t msgId = 12345;
+ * uint32_t originNode = 67890;
+ * 
+ * // Check if message was already processed
+ * if (!tracker.isProcessed(msgId, originNode)) {
+ *     // Process the message
+ *     processMessage(msg);
+ *     
+ *     // Mark as processed
+ *     tracker.markProcessed(msgId, originNode);
+ * }
+ * 
+ * // Later, mark as acknowledged
+ * tracker.markAcknowledged(msgId, originNode);
+ * 
+ * // Periodically cleanup old entries
+ * tracker.cleanup();
+ * \endcode
+ */
+class MessageTracker {
+public:
+  /**
+   * Constructor
+   * @param maxMessages Maximum number of messages to track (default: 500)
+   * @param timeoutMs Timeout in milliseconds for automatic cleanup (default: 60000)
+   */
+  MessageTracker(uint16_t maxMessages = 500, uint32_t timeoutMs = 60000)
+    : maxTrackedMessages(maxMessages), messageTimeoutMs(timeoutMs) {}
+  
+  /**
+   * Check if a message has already been processed
+   * @param messageId The unique message identifier
+   * @param originNode The node that originated the message
+   * @return true if the message was already processed, false otherwise
+   */
+  bool isProcessed(uint32_t messageId, uint32_t originNode) {
+    MessageKey key = {messageId, originNode};
+    auto it = trackedMessages.find(key);
+    return it != trackedMessages.end();
+  }
+  
+  /**
+   * Mark a message as processed
+   * If the tracker is at capacity, oldest entries will be removed first.
+   * Note: If maxMessages is 0, this method does nothing and returns false.
+   * @param messageId The unique message identifier
+   * @param originNode The node that originated the message
+   * @return true if message was tracked, false if capacity is 0
+   */
+  bool markProcessed(uint32_t messageId, uint32_t originNode) {
+    MessageKey key = {messageId, originNode};
+    uint32_t currentTime = millis();
+    
+    // Check if already exists
+    auto it = trackedMessages.find(key);
+    if (it != trackedMessages.end()) {
+      // Update timestamp but preserve acknowledged status
+      it->second.timestamp = currentTime;
+      Log(logger::GENERAL, "MessageTracker: Updated message %u from node %u\n",
+          messageId, originNode);
+      return true;
+    }
+    
+    // Handle capacity 0 case - don't add new entries
+    if (maxTrackedMessages == 0) {
+      Log(logger::GENERAL, "MessageTracker: Cannot track message %u (capacity=0)\n",
+          messageId);
+      return false;
+    }
+    
+    // Enforce memory limits before adding new entry
+    if (trackedMessages.size() >= maxTrackedMessages) {
+      enforceMemoryLimit();
+    }
+    
+    // Add new entry
+    trackedMessages[key] = TrackedMessage(currentTime);
+    Log(logger::GENERAL, "MessageTracker: Tracked message %u from node %u (size=%zu)\n",
+        messageId, originNode, trackedMessages.size());
+    return true;
+  }
+  
+  /**
+   * Mark a message as acknowledged
+   * @param messageId The unique message identifier
+   * @param originNode The node that originated the message
+   * @return true if the message was found and marked, false otherwise
+   */
+  bool markAcknowledged(uint32_t messageId, uint32_t originNode) {
+    MessageKey key = {messageId, originNode};
+    auto it = trackedMessages.find(key);
+    
+    if (it != trackedMessages.end()) {
+      it->second.acknowledged = true;
+      Log(logger::GENERAL, "MessageTracker: Acknowledged message %u from node %u\n",
+          messageId, originNode);
+      return true;
+    }
+    
+    Log(logger::GENERAL, "MessageTracker: Message %u from node %u not found for acknowledgment\n",
+        messageId, originNode);
+    return false;
+  }
+  
+  /**
+   * Check if a message has been acknowledged
+   * @param messageId The unique message identifier
+   * @param originNode The node that originated the message
+   * @return true if acknowledged, false if not found or not acknowledged
+   */
+  bool isAcknowledged(uint32_t messageId, uint32_t originNode) {
+    MessageKey key = {messageId, originNode};
+    auto it = trackedMessages.find(key);
+    
+    if (it != trackedMessages.end()) {
+      return it->second.acknowledged;
+    }
+    
+    return false;
+  }
+  
+  /**
+   * Cleanup expired entries based on the configured timeout
+   * @return Number of entries removed
+   */
+  uint32_t cleanup() {
+    uint32_t currentTime = millis();
+    uint32_t removedCount = 0;
+    
+    auto it = trackedMessages.begin();
+    while (it != trackedMessages.end()) {
+      // Handle millis() overflow - if currentTime < timestamp, assume overflow
+      uint32_t age;
+      if (currentTime >= it->second.timestamp) {
+        age = currentTime - it->second.timestamp;
+      } else {
+        // Overflow occurred
+        age = (0xFFFFFFFF - it->second.timestamp) + currentTime + 1;
+      }
+      
+      if (age > messageTimeoutMs) {
+        it = trackedMessages.erase(it);
+        removedCount++;
+      } else {
+        ++it;
+      }
+    }
+    
+    if (removedCount > 0) {
+      Log(logger::GENERAL, "MessageTracker: Cleaned up %u expired entries (size=%zu)\n",
+          removedCount, trackedMessages.size());
+    }
+    
+    return removedCount;
+  }
+  
+  /**
+   * Get the current number of tracked messages
+   * @return Number of entries in the tracker
+   */
+  size_t size() const {
+    return trackedMessages.size();
+  }
+  
+  /**
+   * Check if the tracker is empty
+   * @return true if no messages are being tracked
+   */
+  bool empty() const {
+    return trackedMessages.empty();
+  }
+  
+  /**
+   * Clear all tracked messages
+   */
+  void clear() {
+    trackedMessages.clear();
+    Log(logger::GENERAL, "MessageTracker: Cleared all entries\n");
+  }
+  
+  /**
+   * Get the maximum number of tracked messages
+   * @return Configured maximum
+   */
+  uint16_t getMaxMessages() const {
+    return maxTrackedMessages;
+  }
+  
+  /**
+   * Get the timeout value in milliseconds
+   * @return Configured timeout
+   */
+  uint32_t getTimeoutMs() const {
+    return messageTimeoutMs;
+  }
+  
+  /**
+   * Set a new maximum for tracked messages
+   * If current size exceeds new max, oldest entries will be removed
+   * @param maxMessages New maximum
+   */
+  void setMaxMessages(uint16_t maxMessages) {
+    maxTrackedMessages = maxMessages;
+    
+    // Enforce new limit if needed
+    while (trackedMessages.size() > maxTrackedMessages) {
+      enforceMemoryLimit();
+    }
+  }
+  
+  /**
+   * Set a new timeout value
+   * @param timeoutMs New timeout in milliseconds
+   */
+  void setTimeoutMs(uint32_t timeoutMs) {
+    messageTimeoutMs = timeoutMs;
+  }
+
+private:
+  std::map<MessageKey, TrackedMessage> trackedMessages;
+  uint16_t maxTrackedMessages;
+  uint32_t messageTimeoutMs;
+  
+  /**
+   * Enforce memory limit by removing the oldest entry
+   * @return true if an entry was removed, false if tracker was empty
+   */
+  bool enforceMemoryLimit() {
+    if (trackedMessages.empty()) {
+      return false;
+    }
+    
+    // Find the oldest entry
+    auto oldest = trackedMessages.begin();
+    uint32_t oldestTimestamp = oldest->second.timestamp;
+    
+    for (auto it = trackedMessages.begin(); it != trackedMessages.end(); ++it) {
+      if (it->second.timestamp < oldestTimestamp) {
+        oldest = it;
+        oldestTimestamp = it->second.timestamp;
+      }
+    }
+    
+    Log(logger::GENERAL, "MessageTracker: Evicting oldest entry (msg=%u, node=%u) to enforce limit\n",
+        oldest->first.messageId, oldest->first.originNode);
+    
+    trackedMessages.erase(oldest);
+    return true;
+  }
+};
+
+}  // namespace painlessmesh
+
+#endif  // _PAINLESS_MESH_MESSAGE_TRACKER_HPP_

package/src/painlessmesh/protocol.hpp

@@ -56,6 +56,12 @@ constexpr int BRIDGE_ELECTION = 611;    // Bridge election candidacy announcemen
 constexpr int BRIDGE_TAKEOVER = 612;    // Bridge takeover notification
 constexpr int BRIDGE_COORDINATION = 613; // Multi-bridge coordination (defined in plugin.hpp)
 
+// Gateway data protocol types
+// Used for routing Internet requests through the mesh network
+constexpr int GATEWAY_DATA = 620;       // Gateway data package for Internet routing
+constexpr int GATEWAY_ACK = 621;        // Gateway acknowledgment package
+constexpr int GATEWAY_HEARTBEAT = 622;  // Gateway heartbeat for health monitoring
+
 class PackageInterface {
  public:
   virtual JsonObject addTo(JsonObject&& jsonObj) const = 0;

package/DOCUMENTATION_INDEX.md

@@ -1,146 +0,0 @@
-# AlteriomPainlessMesh Documentation Index
-
-Complete guide to finding documentation in the AlteriomPainlessMesh library.
-
-## Quick Links
-
-- 🌐 **[Online Documentation](https://alteriom.github.io/painlessMesh/)** - Interactive documentation website
-- 📖 **[API Reference](https://alteriom.github.io/painlessMesh/#/api/doxygen)** - Complete API documentation
-- 🎯 **[Examples](https://alteriom.github.io/painlessMesh/#/tutorials/basic-examples)** - Code examples and tutorials
-
-## Core Documentation
-
-### Getting Started
-- **[README.md](README.md)** - Project overview, features, and quick start
-- **[docs/getting-started/quickstart.md](docs/getting-started/quickstart.md)** - Quick start guide
-- **[docs/getting-started/installation.md](docs/getting-started/installation.md)** - Installation instructions
-- **[docs/getting-started/first-mesh.md](docs/getting-started/first-mesh.md)** - Your first mesh network
-
-### Release Information
-- **[CHANGELOG.md](CHANGELOG.md)** - Complete version history
-- **[RELEASE_GUIDE.md](RELEASE_GUIDE.md)** - Release process for maintainers
-- **[RELEASE_NOTES_1.8.12.md](RELEASE_NOTES_1.8.12.md)** - Latest release notes
-- **[RELEASE_CHECKLIST_1.8.12.md](RELEASE_CHECKLIST_1.8.12.md)** - Release checklist
-
-### Contributing
-- **[CONTRIBUTING.md](CONTRIBUTING.md)** - How to contribute to the project
-- **[LICENSE](LICENSE)** - LGPL-3.0 license terms
-
-## Technical Documentation
-
-### Alteriom Extensions
-- **[docs/alteriom/overview.md](docs/alteriom/overview.md)** - Alteriom extensions overview
-- **[examples/alteriom/README.md](examples/alteriom/README.md)** - Alteriom package documentation
-- **[examples/alteriom/alteriom_sensor_package.hpp](examples/alteriom/alteriom_sensor_package.hpp)** - Package definitions with extensive inline documentation
-
-### MQTT Integration
-- **[docs/MQTT_BRIDGE_COMMANDS.md](docs/MQTT_BRIDGE_COMMANDS.md)** - MQTT command API
-- **[docs/MQTT_BRIDGE_IMPLEMENTATION_SUMMARY.md](docs/MQTT_BRIDGE_IMPLEMENTATION_SUMMARY.md)** - Implementation details
-- **[docs/MQTT_SCHEMA_COMPLIANCE.md](docs/MQTT_SCHEMA_COMPLIANCE.md)** - Schema validation
-- **[docs/OTA_COMMANDS_REFERENCE.md](docs/OTA_COMMANDS_REFERENCE.md)** - OTA update commands
-
-### Advanced Features
-- **[docs/MESH_TOPOLOGY_GUIDE.md](docs/MESH_TOPOLOGY_GUIDE.md)** - Network topology reporting
-- **[docs/BRIDGE_FAILOVER.md](docs/BRIDGE_FAILOVER.md)** - Bridge failover documentation
-- **[docs/BRIDGE_HEALTH_MONITORING.md](docs/BRIDGE_HEALTH_MONITORING.md)** - Bridge health monitoring
-- **[BRIDGE_TO_INTERNET.md](BRIDGE_TO_INTERNET.md)** - Connecting mesh to internet
-
-### Development
-- **[docs/API_DESIGN_GUIDELINES.md](docs/API_DESIGN_GUIDELINES.md)** - API design patterns
-- **[docs/VERSION_MANAGEMENT.md](docs/VERSION_MANAGEMENT.md)** - Version management guide
-- **[docs/development/DOCKER_TESTING.md](docs/development/DOCKER_TESTING.md)** - Docker testing guide
-- **[docs/development/TESTING_SUMMARY.md](docs/development/TESTING_SUMMARY.md)** - Test suite overview
-- **[docs/development/ARDUINO_COMPLIANCE_SUMMARY.md](docs/development/ARDUINO_COMPLIANCE_SUMMARY.md)** - Arduino standards
-
-### Phase Documentation
-- **[docs/PHASE1_GUIDE.md](docs/PHASE1_GUIDE.md)** - Phase 1 features (v1.6.x)
-- **[docs/PHASE2_GUIDE.md](docs/PHASE2_GUIDE.md)** - Phase 2 features (v1.7.x+)
-- **[docs/releases/FEATURE_HISTORY.md](docs/releases/FEATURE_HISTORY.md)** - Consolidated feature history
-
-## Example Code
-
-### Basic Examples
-- **[examples/basic/](examples/basic/)** - Basic mesh networking
-- **[examples/startHere/](examples/startHere/)** - Simple starting point
-
-### Alteriom Examples
-- **[examples/alteriom/](examples/alteriom/)** - Core Alteriom package examples
-- **[examples/alteriomSensorNode/](examples/alteriomSensorNode/)** - Sensor node implementation
-- **[examples/alteriomImproved/](examples/alteriomImproved/)** - Enhanced sensor node
-- **[examples/alteriomMetricsHealth/](examples/alteriomMetricsHealth/)** - Metrics and health monitoring
-- **[examples/alteriomPhase1/](examples/alteriomPhase1/)** - Phase 1 features demo
-- **[examples/alteriomPhase2/](examples/alteriomPhase2/)** - Phase 2 features demo
-
-### Bridge Examples
-- **[examples/bridge/](examples/bridge/)** - Basic bridge examples
-- **[examples/bridge_failover/](examples/bridge_failover/)** - Bridge failover implementation
-- **[examples/multi_bridge/](examples/multi_bridge/)** - Multiple bridge setup
-- **[examples/bridgeAwareSensorNode/](examples/bridgeAwareSensorNode/)** - Bridge-aware nodes
-
-### MQTT Examples
-- **[examples/mqttBridge/](examples/mqttBridge/)** - MQTT bridge
-- **[examples/mqttCommandBridge/](examples/mqttCommandBridge/)** - Command bridge
-- **[examples/mqttStatusBridge/](examples/mqttStatusBridge/)** - Status reporting bridge
-- **[examples/mqttTopologyTest/](examples/mqttTopologyTest/)** - Topology testing
-
-### Advanced Examples
-- **[examples/otaReceiver/](examples/otaReceiver/)** - OTA update receiver
-- **[examples/otaSender/](examples/otaSender/)** - OTA update sender
-- **[examples/ntpTimeSyncBridge/](examples/ntpTimeSyncBridge/)** - NTP time sync bridge
-- **[examples/ntpTimeSyncNode/](examples/ntpTimeSyncNode/)** - NTP time sync node
-- **[examples/webServer/](examples/webServer/)** - Mesh web server
-- **[examples/diagnosticsExample/](examples/diagnosticsExample/)** - Diagnostics tools
-
-## Troubleshooting
-
-- **[docs/troubleshooting/common-issues.md](docs/troubleshooting/common-issues.md)** - Common problems and solutions
-- **[docs/troubleshooting/ESP32_C6_COMPATIBILITY.md](docs/troubleshooting/ESP32_C6_COMPATIBILITY.md)** - ESP32-C6 issues
-- **[docs/troubleshooting/debugging.md](docs/troubleshooting/debugging.md)** - Debugging techniques
-- **[docs/troubleshooting/faq.md](docs/troubleshooting/faq.md)** - Frequently asked questions
-
-## Architecture Documentation
-
-- **[docs/architecture/mesh-architecture.md](docs/architecture/mesh-architecture.md)** - Mesh architecture overview
-- **[docs/architecture/plugin-system.md](docs/architecture/plugin-system.md)** - Plugin architecture
-- **[docs/architecture/routing.md](docs/architecture/routing.md)** - Message routing
-- **[docs/architecture/time-sync.md](docs/architecture/time-sync.md)** - Time synchronization
-
-## Support & Community
-
-### Getting Help
-- **GitHub Issues**: https://github.com/Alteriom/painlessMesh/issues
-- **GitHub Discussions**: https://github.com/Alteriom/painlessMesh/discussions
-
-### Package Registries
-- **NPM**: https://www.npmjs.com/package/@alteriom/painlessmesh
-- **PlatformIO**: https://registry.platformio.org/libraries/alteriom/painlessMesh
-- **Arduino Library Manager**: Search for "AlteriomPainlessMesh"
-
-## Version-Specific Documentation
-
-### Current Version (1.8.12)
-- Focus on documentation improvements and code quality
-- Added prettier configuration for consistent formatting
-- Enhanced inline documentation
-- See [RELEASE_NOTES_1.8.12.md](RELEASE_NOTES_1.8.12.md) for details
-
-### Previous Versions
-- **v1.8.11** - Bridge discovery and Windows MSVC compatibility fixes
-- **v1.8.10** - Bridge status direct messaging improvements
-- **v1.8.9** - Bridge self-registration fixes
-- **v1.8.0** - Bridge failover introduction
-- **v1.7.0** - Phase 2 features (broadcast OTA, MQTT status bridge)
-- **v1.6.0** - Phase 1 features (Alteriom packages)
-
-See [CHANGELOG.md](CHANGELOG.md) for complete version history.
-
-## Contributing to Documentation
-
-To contribute to documentation:
-1. Follow the style guide in existing documentation
-2. Update this index when adding new documentation files
-3. Ensure all links are functional
-4. Use Markdown for all documentation
-5. Include code examples where appropriate
-
-For detailed contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).