@alteriom/painlessmesh 1.8.0 → 1.8.2

package/examples/queued_alarms/README.md

@@ -0,0 +1,390 @@
+# Queued Alarms Example
+
+## Overview
+
+This example demonstrates **priority-based message queueing** for critical IoT systems that cannot afford to lose data during Internet outages. It's designed for the fish farm dissolved oxygen (O2) monitoring use case described in [Issue #66](https://github.com/Alteriom/painlessMesh/issues/66).
+
+## Problem Statement
+
+In production IoT systems like fish farm monitoring, **critical alarms must never be lost**. When the bridge node loses Internet connectivity:
+
+- ❌ **Without queueing**: Critical O2 alarms are lost → fish die
+- ✅ **With queueing**: Alarms are queued and delivered when connection restored → supervisor notified, fish saved
+
+## Features
+
+### ✅ Priority-Based Queueing
+
+- **CRITICAL** (Priority 0): Life-safety alarms - never dropped
+- **HIGH** (Priority 1): Important warnings - preserved up to 80% capacity
+- **NORMAL** (Priority 2): Regular data - preserved up to 60% capacity  
+- **LOW** (Priority 3): Telemetry - dropped first when queue full
+
+### ✅ Automatic Queue Management
+
+- Queues messages when Internet unavailable
+- Flushes queue when Internet restored
+- Prunes old messages (configurable age)
+- Monitors queue health with callbacks
+
+### ✅ Production Ready
+
+- Survives Internet outages (queuing)
+- Handles queue overflow intelligently
+- Provides queue statistics
+- Retry logic with attempt tracking
+
+## Hardware Requirements
+
+- **ESP32** or **ESP8266** 
+- At least 2 nodes (1 bridge + 1 sensor node)
+- Bridge node needs WiFi router access
+
+## Configuration
+
+### 1. Mesh Network Settings
+
+```cpp
+#define MESH_PREFIX     "FishFarmMesh"
+#define MESH_PASSWORD   "somethingSneaky"
+#define MESH_PORT       5555
+```
+
+### 2. Router Credentials (Bridge Node)
+
+```cpp
+#define ROUTER_SSID     "YourWiFiSSID"
+#define ROUTER_PASSWORD "YourWiFiPassword"
+```
+
+Enable in setup for bridge node:
+```cpp
+mesh.stationManual(ROUTER_SSID, ROUTER_PASSWORD);
+```
+
+### 3. Sensor Thresholds
+
+Adjust for your sensors (dissolved oxygen in mg/L):
+
+```cpp
+#define CRITICAL_O2_THRESHOLD  3.0  // Life-critical
+#define WARNING_O2_THRESHOLD   5.0  // Warning level
+```
+
+### 4. Queue Configuration
+
+```cpp
+#define MAX_QUEUE_SIZE  500  // Max messages
+#define QUEUE_PRUNE_AGE (24 * 60 * 60 * 1000)  // 24 hours
+```
+
+## How It Works
+
+### Normal Operation (Internet Available)
+
+```
+Sensor → Mesh → Bridge → Internet → Cloud/MQTT
+```
+
+Messages sent immediately, no queueing.
+
+### Offline Mode (No Internet)
+
+```
+Sensor → Mesh → Bridge → Queue (Priority-based)
+                         ↓
+                    [CRITICAL never dropped]
+                    [LOW dropped first]
+```
+
+Messages queued with priority, delivered when Internet restored.
+
+### Internet Restored
+
+```
+Queue → Flush → MQTT/HTTP → Cloud
+  ↓
+Remove on success
+Retry on failure (max 3 attempts)
+```
+
+## Usage
+
+### 1. Flash Bridge Node
+
+1. Uncomment these lines in `setup()`:
+   ```cpp
+   mesh.stationManual(ROUTER_SSID, ROUTER_PASSWORD);
+   mesh.setHostname("FishFarmBridge");
+   ```
+2. Upload to ESP32/ESP8266 with router access
+3. Bridge connects to router and provides Internet to mesh
+
+### 2. Flash Sensor Nodes
+
+1. Leave router lines commented
+2. Upload to sensor node ESP32/ESP8266
+3. Node joins mesh and monitors sensors
+
+### 3. Monitor Serial Output
+
+**Normal operation:**
+```
+✅ ONLINE MODE - Internet restored
+📊 Telemetry: 7.32 mg/L
+📊 Telemetry: 6.85 mg/L
+```
+
+**Internet lost:**
+```
+⚠️  OFFLINE MODE ACTIVATED
+  Queue size: 0 messages
+📊 Telemetry: 6.42 mg/L - queued #1
+  [Queue: 1 messages]
+```
+
+**Critical alarm (offline):**
+```
+🚨 CRITICAL O2 ALARM: 2.87 mg/L - QUEUED #5
+  [Queue: 5 messages (1 CRITICAL)]
+```
+
+**Internet restored:**
+```
+✅ ONLINE MODE - Internet restored
+  Flushing 5 queued messages...
+  Sending queued message #1 (priority=3, attempts=0)
+  Sending queued message #5 (priority=0, attempts=0)
+  ✅ Queue flushed (5 messages sent)
+```
+
+## Queue States
+
+The example monitors queue health:
+
+- **EMPTY**: No messages queued
+- **NORMAL**: Queue has space available
+- **75% FULL**: Warning - queue reaching capacity
+- **FULL**: Queue full - dropping LOW priority messages
+
+Example output:
+```
+⚠️  Queue 75% full (375 messages)
+🚨 Queue FULL (500 messages) - dropping LOW priority
+```
+
+## Testing Without Hardware
+
+### Simulate Internet Loss
+
+In real deployment, Internet loss is automatic. For testing, you can:
+
+1. **Disconnect router**: Physically disconnect Ethernet/WAN
+2. **Block MAC address**: Router settings → Block bridge MAC
+3. **Power cycle router**: Turn off router
+4. **Modify code**: Add test button to toggle `offlineMode`
+
+### Verify Queue Behavior
+
+1. Start with Internet connected
+2. Cause Internet loss (any method above)
+3. Wait for critical alarms to queue
+4. Restore Internet
+5. Verify messages are flushed
+
+Expected sequence:
+```
+✅ Online → ⚠️ Offline (queueing) → ✅ Online (flush queue)
+```
+
+## Integration with Cloud Services
+
+### MQTT Example
+
+Replace simulated sending with MQTT:
+
+```cpp
+#include <PubSubClient.h>
+
+WiFiClient wifiClient;
+PubSubClient mqttClient(wifiClient);
+
+// In setup()
+mqttClient.setServer("mqtt.example.com", 1883);
+
+// In bridgeStatusCallback()
+for (auto& msg : messages) {
+  bool sent = mqttClient.publish(
+    msg.destination.c_str(),  // Topic from queueMessage()
+    msg.payload.c_str()
+  );
+  
+  if (sent) {
+    mesh.removeQueuedMessage(msg.id);
+  } else {
+    mesh.incrementQueuedMessageAttempts(msg.id);
+  }
+}
+```
+
+### HTTP Example
+
+Replace simulated sending with HTTP POST:
+
+```cpp
+#include <HTTPClient.h>
+
+HTTPClient http;
+
+for (auto& msg : messages) {
+  http.begin(msg.destination);  // URL from queueMessage()
+  http.addHeader("Content-Type", "application/json");
+  
+  int httpCode = http.POST(msg.payload);
+  bool sent = (httpCode == 200 || httpCode == 201);
+  
+  if (sent) {
+    mesh.removeQueuedMessage(msg.id);
+  } else {
+    mesh.incrementQueuedMessageAttempts(msg.id);
+  }
+  
+  http.end();
+}
+```
+
+## Message Format
+
+Example JSON message structure:
+
+### Critical Alarm
+```json
+{
+  "type": "CRITICAL_ALARM",
+  "sensor": "O2",
+  "value": 2.87,
+  "threshold": 3.0,
+  "tankId": "TANK_A",
+  "nodeId": 123456789,
+  "timestamp": 1234567890
+}
+```
+
+### Warning
+```json
+{
+  "type": "WARNING",
+  "sensor": "O2",
+  "value": 4.5,
+  "threshold": 5.0,
+  "nodeId": 123456789
+}
+```
+
+### Telemetry
+```json
+{
+  "sensor": "O2",
+  "value": 7.32,
+  "nodeId": 123456789
+}
+```
+
+## API Reference
+
+### Enable Queue
+
+```cpp
+mesh.enableMessageQueue(true, MAX_QUEUE_SIZE);
+```
+
+### Queue Message
+
+```cpp
+uint32_t msgId = mesh.queueMessage(
+  payload,              // Message content
+  destination,          // Cloud endpoint/topic
+  PRIORITY_CRITICAL     // Priority level
+);
+```
+
+### Flush Queue
+
+```cpp
+auto messages = mesh.flushMessageQueue();
+for (auto& msg : messages) {
+  if (sendToCloud(msg)) {
+    mesh.removeQueuedMessage(msg.id);
+  }
+}
+```
+
+### Query Queue
+
+```cpp
+uint32_t total = mesh.getQueuedMessageCount();
+uint32_t critical = mesh.getQueuedMessageCount(PRIORITY_CRITICAL);
+```
+
+### Callbacks
+
+```cpp
+mesh.onBridgeStatusChanged([](uint32_t bridgeId, bool hasInternet) {
+  // Handle Internet connectivity change
+});
+
+mesh.onQueueStateChanged([](QueueState state, uint32_t count) {
+  // Handle queue state change (EMPTY, NORMAL, 75%, FULL)
+});
+```
+
+## Troubleshooting
+
+### Queue Always Full
+
+- Increase `MAX_QUEUE_SIZE`
+- Decrease message frequency
+- Lower message priorities
+- Reduce `QUEUE_PRUNE_AGE`
+
+### Messages Not Flushing
+
+- Check `bridgeStatusCallback()` is called
+- Verify Internet connectivity with `mesh.hasInternetConnection()`
+- Check MQTT/HTTP sending code
+- Monitor serial for errors
+
+### High Memory Usage
+
+- Reduce `MAX_QUEUE_SIZE`
+- Enable aggressive pruning
+- Use shorter message payloads
+- Monitor with `ESP.getFreeHeap()`
+
+## Performance
+
+### Memory Usage
+
+| Queue Size | RAM Usage (approx) |
+|------------|-------------------|
+| 100        | ~20 KB            |
+| 500        | ~100 KB           |
+| 1000       | ~200 KB           |
+
+**ESP32**: Can handle 1000+ messages  
+**ESP8266**: Recommend ≤500 messages
+
+### Throughput
+
+- **Queue**: ~1000 msg/sec
+- **Flush**: Limited by MQTT/HTTP send rate (~10-50 msg/sec)
+
+## Related Documentation
+
+- [Issue #66: Message Queueing Feature](https://github.com/Alteriom/painlessMesh/issues/66)
+- [Issue #63: Bridge Status Broadcast](https://github.com/Alteriom/painlessMesh/issues/63)
+- [painlessMesh Documentation](https://gitlab.com/painlessMesh/painlessMesh)
+
+## License
+
+MIT License - See repository LICENSE file

package/examples/queued_alarms/queued_alarms.ino

@@ -0,0 +1,265 @@
+//************************************************************
+// Queued Alarms Example - Message Queueing for Offline Mode
+//
+// Demonstrates priority-based message queueing for critical alarms
+// when Internet connection is unavailable. Perfect for IoT systems
+// that cannot afford to lose critical data.
+//
+// Use Case: Fish farm dissolved oxygen monitoring
+// - CRITICAL alarms (low O2) must never be lost
+// - Queue messages during Internet outages
+// - Automatic delivery when connection restored
+//
+// Hardware: ESP32 or ESP8266
+//************************************************************
+
+#include "painlessMesh.h"
+
+// Mesh configuration
+#define   MESH_PREFIX     "FishFarmMesh"
+#define   MESH_PASSWORD   "somethingSneaky"
+#define   MESH_PORT       5555
+
+// Router credentials for bridge node
+#define   ROUTER_SSID     "YourWiFiSSID"
+#define   ROUTER_PASSWORD "YourWiFiPassword"
+
+// Sensor thresholds (mg/L for dissolved oxygen)
+#define   CRITICAL_O2_THRESHOLD  3.0
+#define   WARNING_O2_THRESHOLD   5.0
+
+// Queue configuration
+#define   MAX_QUEUE_SIZE  500
+#define   QUEUE_PRUNE_AGE (24 * 60 * 60 * 1000)  // 24 hours in ms
+
+Scheduler userScheduler;
+painlessMesh mesh;
+
+bool offlineMode = false;
+uint32_t lastO2Check = 0;
+uint32_t lastQueuePrune = 0;
+
+// Simulated sensor reading (replace with actual sensor code)
+float readDissolvedOxygenSensor() {
+  // In real application, read from actual sensor
+  // For demo, simulate varying O2 levels
+  static float o2Level = 7.0;
+  o2Level += random(-20, 20) / 10.0;  // +/- 2.0 mg/L variation
+  o2Level = constrain(o2Level, 2.0, 10.0);
+  return o2Level;
+}
+
+// Send critical O2 alarm
+void sendCriticalAlarm(float o2Level) {
+  // Create alarm message (in real app, use JSON)
+  String payload = String("{\"type\":\"CRITICAL_ALARM\",\"sensor\":\"O2\",\"value\":") 
+                   + String(o2Level, 2) + ",\"threshold\":" 
+                   + String(CRITICAL_O2_THRESHOLD, 2) + ",\"tankId\":\"TANK_A\",\"nodeId\":" 
+                   + mesh.getNodeId() + ",\"timestamp\":" + mesh.getNodeTime() + "}";
+  
+  if (offlineMode || !mesh.hasInternetConnection()) {
+    // CRITICAL: Queue for guaranteed delivery
+    uint32_t msgId = mesh.queueMessage(
+      payload,
+      "mqtt://cloud.farm.com/alarms/critical",
+      PRIORITY_CRITICAL
+    );
+    
+    if (msgId) {
+      Serial.printf("🚨 CRITICAL O2 ALARM: %.2f mg/L - QUEUED #%u\n", o2Level, msgId);
+    } else {
+      Serial.printf("🚨 CRITICAL O2 ALARM: %.2f mg/L - QUEUE FAILED!\n", o2Level);
+    }
+  } else {
+    // Send immediately via bridge (in real app, use MQTT client)
+    Serial.printf("🚨 CRITICAL O2 ALARM: %.2f mg/L - SENT IMMEDIATELY\n", o2Level);
+    // mqttClient.publish("alarms/critical", payload.c_str());
+  }
+}
+
+// Send warning alarm
+void sendWarningAlarm(float o2Level) {
+  String payload = String("{\"type\":\"WARNING\",\"sensor\":\"O2\",\"value\":") 
+                   + String(o2Level, 2) + ",\"threshold\":" 
+                   + String(WARNING_O2_THRESHOLD, 2) + ",\"nodeId\":" 
+                   + mesh.getNodeId() + "}";
+  
+  if (offlineMode) {
+    uint32_t msgId = mesh.queueMessage(
+      payload,
+      "mqtt://cloud.farm.com/alarms/warning",
+      PRIORITY_HIGH
+    );
+    
+    if (msgId) {
+      Serial.printf("⚠️  WARNING O2: %.2f mg/L - QUEUED #%u\n", o2Level, msgId);
+    } else {
+      Serial.printf("⚠️  WARNING O2: %.2f mg/L - QUEUE FULL\n", o2Level);
+    }
+  } else {
+    Serial.printf("⚠️  WARNING O2: %.2f mg/L - SENT\n", o2Level);
+  }
+}
+
+// Send normal telemetry
+void sendNormalTelemetry(float o2Level) {
+  String payload = String("{\"sensor\":\"O2\",\"value\":") + String(o2Level, 2) 
+                   + ",\"nodeId\":" + mesh.getNodeId() + "}";
+  
+  if (offlineMode) {
+    // Low priority - queue only if space available
+    uint32_t msgId = mesh.queueMessage(
+      payload,
+      "mqtt://cloud.farm.com/telemetry",
+      PRIORITY_LOW
+    );
+    
+    if (msgId) {
+      Serial.printf("📊 Telemetry: %.2f mg/L - queued #%u\n", o2Level, msgId);
+    } else {
+      Serial.printf("📊 Telemetry: %.2f mg/L - dropped (queue full)\n", o2Level);
+    }
+  } else {
+    Serial.printf("📊 Telemetry: %.2f mg/L\n", o2Level);
+  }
+}
+
+// Check O2 sensor and send appropriate message
+void checkO2Sensor() {
+  float o2Level = readDissolvedOxygenSensor();
+  
+  if (o2Level < CRITICAL_O2_THRESHOLD) {
+    sendCriticalAlarm(o2Level);
+  } else if (o2Level < WARNING_O2_THRESHOLD) {
+    sendWarningAlarm(o2Level);
+  } else {
+    sendNormalTelemetry(o2Level);
+  }
+}
+
+// Bridge status callback - Internet connectivity changed
+void bridgeStatusCallback(uint32_t bridgeNodeId, bool hasInternet) {
+  if (!hasInternet) {
+    offlineMode = true;
+    Serial.println("\n⚠️  OFFLINE MODE ACTIVATED");
+    Serial.printf("  Bridge node %u lost Internet\n", bridgeNodeId);
+    Serial.printf("  Queue size: %u messages\n", mesh.getQueuedMessageCount());
+    
+    uint32_t critical = mesh.getQueuedMessageCount(PRIORITY_CRITICAL);
+    if (critical > 0) {
+      Serial.printf("  ⚠️  %u CRITICAL messages queued!\n", critical);
+    }
+  } else {
+    offlineMode = false;
+    Serial.println("\n✅ ONLINE MODE - Internet restored");
+    Serial.printf("  Bridge node %u has Internet\n", bridgeNodeId);
+    
+    // Flush queued messages
+    uint32_t queuedCount = mesh.getQueuedMessageCount();
+    if (queuedCount > 0) {
+      Serial.printf("  Flushing %u queued messages...\n", queuedCount);
+      
+      auto messages = mesh.flushMessageQueue();
+      for (auto& msg : messages) {
+        // In real application, send via MQTT or HTTP
+        Serial.printf("  Sending queued message #%u (priority=%d, attempts=%u)\n",
+                     msg.id, msg.priority, msg.attempts);
+        
+        // Simulate sending (in real app, check if send succeeded)
+        bool sent = true;  // Replace with: mqttClient.publish(...)
+        
+        if (sent) {
+          mesh.removeQueuedMessage(msg.id);
+        } else {
+          // Increment attempt counter
+          mesh.incrementQueuedMessageAttempts(msg.id);
+          
+          // Remove if too many attempts
+          if (msg.attempts >= 3) {
+            Serial.printf("  ❌ Message #%u failed after 3 attempts, removing\n", msg.id);
+            mesh.removeQueuedMessage(msg.id);
+          }
+        }
+      }
+      
+      Serial.printf("  ✅ Queue flushed (%u messages sent)\n", queuedCount);
+    }
+  }
+}
+
+// Queue state callback - Monitor queue health
+void queueStateCallback(QueueState state, uint32_t messageCount) {
+  switch (state) {
+    case QUEUE_EMPTY:
+      Serial.println("ℹ️  Queue empty");
+      break;
+    case QUEUE_NORMAL:
+      Serial.printf("ℹ️  Queue normal (%u messages)\n", messageCount);
+      break;
+    case QUEUE_75_PERCENT:
+      Serial.printf("⚠️  Queue 75%% full (%u messages)\n", messageCount);
+      break;
+    case QUEUE_FULL:
+      Serial.printf("🚨 Queue FULL (%u messages) - dropping LOW priority\n", messageCount);
+      break;
+  }
+}
+
+void setup() {
+  Serial.begin(115200);
+  Serial.println("\n\n=== Fish Farm O2 Monitoring with Message Queue ===\n");
+  
+  // Initialize mesh
+  mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+  mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+  
+  // For bridge node: set router credentials
+  // Uncomment if this is the bridge node
+  // mesh.stationManual(ROUTER_SSID, ROUTER_PASSWORD);
+  // mesh.setHostname("FishFarmBridge");
+  
+  // Enable message queue
+  mesh.enableMessageQueue(true, MAX_QUEUE_SIZE);
+  Serial.printf("Message queue enabled (capacity: %u)\n", MAX_QUEUE_SIZE);
+  
+  // Set callbacks
+  mesh.onBridgeStatusChanged(&bridgeStatusCallback);
+  mesh.onQueueStateChanged(&queueStateCallback);
+  
+  Serial.println("Setup complete. Monitoring O2 levels...\n");
+  
+  // Initialize random for sensor simulation
+  randomSeed(analogRead(0));
+}
+
+void loop() {
+  mesh.update();
+  
+  // Check O2 sensor every 10 seconds
+  if (millis() - lastO2Check > 10000) {
+    lastO2Check = millis();
+    checkO2Sensor();
+    
+    // Print queue status
+    uint32_t queueSize = mesh.getQueuedMessageCount();
+    if (queueSize > 0) {
+      Serial.printf("  [Queue: %u messages", queueSize);
+      
+      uint32_t critical = mesh.getQueuedMessageCount(PRIORITY_CRITICAL);
+      if (critical > 0) {
+        Serial.printf(" (%u CRITICAL)", critical);
+      }
+      
+      Serial.println("]");
+    }
+  }
+  
+  // Prune old messages every hour
+  if (millis() - lastQueuePrune > 3600000) {
+    lastQueuePrune = millis();
+    uint32_t pruned = mesh.pruneQueue(QUEUE_PRUNE_AGE);
+    if (pruned > 0) {
+      Serial.printf("ℹ️  Pruned %u old messages from queue\n", pruned);
+    }
+  }
+}

package/library.json

@@ -6,7 +6,7 @@
     "type": "git",
     "url": "https://github.com/Alteriom/painlessMesh"
   },
-  "version": "1.8.0",
+  "version": "1.8.2",
   "frameworks": [
     "arduino"
   ],
@@ -78,17 +78,36 @@
   ],
   "examples": [
     "examples/alteriom/alteriom.ino",
-    "examples/alteriom/alteriom_sensor_node.ino",
-    "examples/alteriom/improved_sensor_node.ino",
+    "examples/alteriomSensorNode/alteriom_sensor_node.ino",
+    "examples/alteriomImproved/improved_sensor_node.ino",
+    "examples/alteriomMetricsHealth/metrics_health_node.ino",
+    "examples/alteriomPhase1/phase1_features.ino",
+    "examples/alteriomPhase2/phase2_features.ino",
     "examples/basic/basic.ino",
     "examples/bridge/bridge.ino",
+    "examples/bridge/bridge_health_monitoring_example.ino",
+    "examples/bridge/enhanced_mqtt_bridge_example.ino",
+    "examples/bridgeAwareSensorNode/bridgeAwareSensorNode.ino",
+    "examples/bridge_failover/bridge_failover.ino",
+    "examples/diagnosticsExample/diagnosticsExample.ino",
     "examples/echoNode/echoNode.ino",
     "examples/logClient/logClient.ino",
     "examples/logServer/logServer.ino",
+    "examples/meshCommandNode/meshCommandNode.ino",
     "examples/mqttBridge/mqttBridge.ino",
+    "examples/mqttCommandBridge/mqttCommandBridge.ino",
+    "examples/mqttStatusBridge/mqttStatusBridge.ino",
+    "examples/mqttTopologyTest/mqttTopologyTest.ino",
+    "examples/multi_bridge/primary_bridge.ino",
+    "examples/multi_bridge/secondary_bridge.ino",
+    "examples/multi_bridge/regular_node.ino",
     "examples/namedMesh/namedMesh.ino",
+    "examples/ntpTimeSyncBridge/ntpTimeSyncBridge.ino",
+    "examples/ntpTimeSyncNode/ntpTimeSyncNode.ino",
     "examples/otaReceiver/otaReceiver.ino",
     "examples/otaSender/otaSender.ino",
+    "examples/queued_alarms/queued_alarms.ino",
+    "examples/rtcIntegration/rtcIntegration.ino",
     "examples/startHere/startHere.ino",
     "examples/webServer/webServer.ino"
   ]

package/library.properties

@@ -1,5 +1,5 @@
 name=AlteriomPainlessMesh
-version=1.8.0
+version=1.8.2
 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