@alteriom/painlessmesh 1.8.2 → 1.8.3

package/examples/priority/README.md

@@ -0,0 +1,274 @@
+# Priority-Based Message Sending
+
+## Overview
+
+painlessMesh now supports priority-based message sending with 4 distinct priority levels. This ensures that critical messages (alarms, commands) are delivered before less important messages (logs, routine sensor data), even under high network load.
+
+## Priority Levels
+
+| Priority | Value | Use Case | Examples |
+|----------|-------|----------|----------|
+| **CRITICAL** | 0 | Life/safety critical messages | Fire alarms, oxygen level warnings, emergency shutdowns |
+| **HIGH** | 1 | Important commands and urgent status | Device commands, critical status requests, immediate alerts |
+| **NORMAL** | 2 | Regular operational data (default) | Sensor readings, routine updates, telemetry |
+| **LOW** | 3 | Non-essential information | Debug logs, verbose telemetry, statistics |
+
+## API Reference
+
+### Broadcast Messages with Priority
+
+```cpp
+// Send with default NORMAL priority (backward compatible)
+mesh.sendBroadcast(message);
+
+// Send with explicit priority level (0-3)
+mesh.sendBroadcast(message, priorityLevel);
+
+// Examples
+mesh.sendBroadcast(alarmData, 0);    // CRITICAL priority
+mesh.sendBroadcast(command, 1);      // HIGH priority
+mesh.sendBroadcast(sensorData, 2);   // NORMAL priority
+mesh.sendBroadcast(debugLog, 3);     // LOW priority
+```
+
+### Direct Messages with Priority
+
+```cpp
+// Send to specific node with default NORMAL priority
+mesh.sendSingle(destinationNodeId, message);
+
+// Send to specific node with explicit priority
+mesh.sendSingle(destinationNodeId, message, priorityLevel);
+
+// Examples
+mesh.sendSingle(123456, alarmMsg, 0);   // CRITICAL
+mesh.sendSingle(123456, cmdMsg, 1);     // HIGH
+mesh.sendSingle(123456, dataMsg, 2);    // NORMAL
+mesh.sendSingle(123456, logMsg, 3);     // LOW
+```
+
+## How It Works
+
+### Priority Scheduling
+
+1. **Queue Management**: Messages are queued by priority level
+2. **Send Order**: Higher priority messages (lower numbers) are sent first
+3. **TCP Push**: CRITICAL (0) and HIGH (1) messages trigger immediate TCP push for faster delivery
+4. **Fairness**: Within the same priority level, messages maintain FIFO order
+
+### Performance Characteristics
+
+- **Memory Overhead**: Minimal - adds ~8 bytes per queued message
+- **CPU Overhead**: O(n) scan to find highest priority (typically negligible with small queues)
+- **Network Impact**: 
+  - CRITICAL/HIGH messages call `client->send()` for immediate transmission
+  - NORMAL/LOW messages use standard TCP buffering
+
+## Best Practices
+
+### 1. Choose Appropriate Priority Levels
+
+```cpp
+// ✅ GOOD: Reserve CRITICAL for actual emergencies
+if (oxygenLevel < CRITICAL_THRESHOLD) {
+    mesh.sendBroadcast(alarmData, 0);  // CRITICAL
+}
+
+// ❌ BAD: Don't overuse CRITICAL priority
+mesh.sendBroadcast(routineSensorData, 0);  // Wrong!
+```
+
+### 2. Use Priority Consistently
+
+```cpp
+// Define constants for clarity
+const uint8_t PRIORITY_ALARM = 0;
+const uint8_t PRIORITY_COMMAND = 1;
+const uint8_t PRIORITY_SENSOR = 2;
+const uint8_t PRIORITY_DEBUG = 3;
+
+// Use throughout your code
+mesh.sendBroadcast(alarmMsg, PRIORITY_ALARM);
+mesh.sendBroadcast(sensorMsg, PRIORITY_SENSOR);
+```
+
+### 3. Consider Message Frequency
+
+```cpp
+// High-frequency messages should use NORMAL or LOW priority
+void loop() {
+    if (millis() - lastSensorRead > 1000) {
+        // Sensor data every second - use NORMAL
+        mesh.sendBroadcast(sensorData, 2);
+    }
+}
+
+// Low-frequency critical events use CRITICAL/HIGH
+void onAlarmDetected() {
+    // Rare but critical event
+    mesh.sendBroadcast(alarmData, 0);
+}
+```
+
+### 4. Test Under Load
+
+Always test your priority assignments under realistic network load:
+
+```cpp
+// Simulate high load
+for (int i = 0; i < 100; i++) {
+    mesh.sendBroadcast(normalData, 2);  // Many NORMAL messages
+}
+
+// Verify CRITICAL messages still get through quickly
+mesh.sendBroadcast(criticalAlarm, 0);
+```
+
+## Examples
+
+### Example 1: Safety Monitoring System
+
+```cpp
+void monitorSafety() {
+    // Read oxygen sensor
+    float oxygenLevel = readOxygenSensor();
+    
+    if (oxygenLevel < CRITICAL_LEVEL) {
+        // CRITICAL: Life-threatening situation
+        String alarm = "{\"type\":\"alarm\",\"sensor\":\"oxygen\",\"level\":" + 
+                       String(oxygenLevel) + ",\"severity\":\"critical\"}";
+        mesh.sendBroadcast(alarm, 0);
+        
+    } else if (oxygenLevel < WARNING_LEVEL) {
+        // HIGH: Concerning but not immediate danger
+        String warning = "{\"type\":\"warning\",\"sensor\":\"oxygen\",\"level\":" + 
+                        String(oxygenLevel) + "}";
+        mesh.sendBroadcast(warning, 1);
+        
+    } else {
+        // NORMAL: Regular monitoring data
+        String data = "{\"type\":\"sensor\",\"oxygen\":" + String(oxygenLevel) + "}";
+        mesh.sendBroadcast(data, 2);
+    }
+}
+```
+
+### Example 2: Industrial Control System
+
+```cpp
+void sendControlCommand(uint32_t targetNode, String command) {
+    // Control commands are HIGH priority
+    String cmdMsg = "{\"type\":\"control\",\"command\":\"" + command + "\"}";
+    mesh.sendSingle(targetNode, cmdMsg, 1);
+}
+
+void sendSensorData() {
+    // Regular sensor data is NORMAL priority
+    String data = "{\"type\":\"telemetry\",\"temp\":" + String(getTemp()) + "}";
+    mesh.sendBroadcast(data, 2);
+}
+
+void sendDebugInfo() {
+    // Debug logs are LOW priority
+    String debug = "{\"type\":\"debug\",\"heap\":" + String(ESP.getFreeHeap()) + "}";
+    mesh.sendBroadcast(debug, 3);
+}
+```
+
+### Example 3: Smart Building Automation
+
+```cpp
+void handleFireAlarm() {
+    // CRITICAL: Fire detected
+    String alarm = "{\"type\":\"fire_alarm\",\"location\":\"Building A\",\"floor\":3}";
+    mesh.sendBroadcast(alarm, 0);
+    
+    // Also send HIGH priority evacuation command to all displays
+    String evacCmd = "{\"type\":\"command\",\"action\":\"evacuate\"}";
+    mesh.sendBroadcast(evacCmd, 1);
+}
+
+void updateLighting() {
+    // NORMAL: Regular lighting adjustments
+    String lightingData = "{\"type\":\"lighting\",\"brightness\":75}";
+    mesh.sendBroadcast(lightingData, 2);
+}
+
+void logActivity() {
+    // LOW: Activity logs
+    String log = "{\"type\":\"log\",\"activity\":\"motion_detected\",\"room\":\"Conference A\"}";
+    mesh.sendBroadcast(log, 3);
+}
+```
+
+## Statistics and Monitoring
+
+The priority system tracks statistics for monitoring:
+
+```cpp
+// Note: Statistics API is internal to SentBuffer
+// Access through connection stats if needed for debugging
+```
+
+## Backward Compatibility
+
+The priority system is **100% backward compatible**:
+
+```cpp
+// Old code continues to work (uses NORMAL priority)
+mesh.sendBroadcast(message);
+mesh.sendSingle(nodeId, message);
+
+// Legacy bool priority flag still works (false=NORMAL, true=HIGH)
+mesh.sendBroadcast(message, true);  // Maps to HIGH priority
+```
+
+## Performance Considerations
+
+### Memory Usage
+
+- **Per Message**: +8 bytes (priority field + iterator overhead)
+- **Total Overhead**: Minimal, typically <1KB for 100 queued messages
+
+### ESP8266 vs ESP32
+
+Both platforms support all 4 priority levels. On ESP8266 with limited memory:
+- Monitor queue sizes
+- Use LOW priority for verbose/debug messages
+- Consider message frequency when assigning priorities
+
+### Network Load
+
+Under high load:
+- CRITICAL messages bypass most queuing
+- HIGH messages get priority scheduling
+- NORMAL messages may experience slight delays
+- LOW messages may be delayed significantly
+
+This is by design - it ensures critical messages get through when you need them most.
+
+## Troubleshooting
+
+### Issue: CRITICAL messages still delayed
+
+**Cause**: Network congestion at lower layers (WiFi, TCP)
+
+**Solution**: 
+- Reduce overall message volume
+- Increase message send intervals for LOW priority messages
+- Consider mesh topology (reduce hops)
+
+### Issue: LOW priority messages never sent
+
+**Cause**: Continuous stream of HIGH priority messages
+
+**Solution**:
+- Review HIGH priority message frequency
+- Ensure proper priority assignment
+- Implement rate limiting on HIGH priority sources
+
+## See Also
+
+- [Message Queue](../queued_alarms/README.md) - For offline message queueing
+- [Basic Example](../basic/basic.ino) - Getting started with painlessMesh
+- [Bridge Examples](../bridge/) - Internet connectivity patterns

package/examples/priority/priority_basic_example.ino

@@ -0,0 +1,115 @@
+/**
+ * Basic Priority Messaging Example for painlessMesh
+ * 
+ * Demonstrates how to send messages with different priority levels.
+ * 
+ * Priority levels:
+ * - PRIORITY_CRITICAL (0): Life/safety critical messages (alarms, emergencies)
+ * - PRIORITY_HIGH (1): Important commands and status requests
+ * - PRIORITY_NORMAL (2): Regular sensor data and routine updates (default)
+ * - PRIORITY_LOW (3): Non-essential telemetry and debug logs
+ * 
+ * Hardware: ESP32 or ESP8266
+ */
+
+#include "painlessMesh.h"
+
+#define MESH_PREFIX     "PriorityMeshDemo"
+#define MESH_PASSWORD   "somethingSneaky"
+#define MESH_PORT       5555
+
+Scheduler userScheduler;
+painlessMesh mesh;
+
+// Task to send regular sensor data (NORMAL priority)
+Task taskSensorData(5000, TASK_FOREVER, []() {
+    String sensorData = "{\"type\":\"sensor\",\"temp\":23.5,\"humidity\":45}";
+    
+    // Send with NORMAL priority (default)
+    mesh.sendBroadcast(sensorData, 2);  // Priority level 2 = NORMAL
+    
+    Serial.println("Sent sensor data (NORMAL priority)");
+});
+
+// Task to send status updates (HIGH priority)
+Task taskStatusUpdate(10000, TASK_FOREVER, []() {
+    String status = "{\"type\":\"status\",\"online\":true,\"uptime\":" + String(millis()) + "}";
+    
+    // Send with HIGH priority
+    mesh.sendBroadcast(status, 1);  // Priority level 1 = HIGH
+    
+    Serial.println("Sent status update (HIGH priority)");
+});
+
+// Task to send low-priority debug logs
+Task taskDebugLog(15000, TASK_FOREVER, []() {
+    String debug = "{\"type\":\"debug\",\"freeHeap\":" + String(ESP.getFreeHeap()) + "}";
+    
+    // Send with LOW priority
+    mesh.sendBroadcast(debug, 3);  // Priority level 3 = LOW
+    
+    Serial.println("Sent debug log (LOW priority)");
+});
+
+void receivedCallback(uint32_t from, String& msg) {
+    Serial.printf("Received from %u: %s\n", from, msg.c_str());
+}
+
+void newConnectionCallback(uint32_t nodeId) {
+    Serial.printf("New connection: %u\n", nodeId);
+}
+
+void changedConnectionCallback() {
+    Serial.printf("Connections changed\n");
+}
+
+void setup() {
+    Serial.begin(115200);
+    
+    mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+    
+    mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+    mesh.onReceive(&receivedCallback);
+    mesh.onNewConnection(&newConnectionCallback);
+    mesh.onChangedConnections(&changedConnectionCallback);
+    
+    // Add periodic tasks
+    userScheduler.addTask(taskSensorData);
+    userScheduler.addTask(taskStatusUpdate);
+    userScheduler.addTask(taskDebugLog);
+    
+    taskSensorData.enable();
+    taskStatusUpdate.enable();
+    taskDebugLog.enable();
+    
+    Serial.println("Priority messaging demo started");
+    Serial.println("Messages sent with different priorities:");
+    Serial.println("  CRITICAL (0): Emergency alarms");
+    Serial.println("  HIGH (1): Status updates");
+    Serial.println("  NORMAL (2): Sensor data");
+    Serial.println("  LOW (3): Debug logs");
+}
+
+void loop() {
+    mesh.update();
+}
+
+// Example: Sending a CRITICAL alarm message
+void sendCriticalAlarm(String alarmType, String message) {
+    String criticalMsg = "{\"type\":\"alarm\",\"alarm\":\"" + alarmType + "\",\"msg\":\"" + message + "\"}";
+    
+    // Send with CRITICAL priority - will be sent immediately, bypassing queue
+    mesh.sendBroadcast(criticalMsg, 0);  // Priority level 0 = CRITICAL
+    
+    Serial.printf("CRITICAL ALARM SENT: %s - %s\n", alarmType.c_str(), message.c_str());
+}
+
+// Example: Sending a direct message with priority
+void sendCommandToNode(uint32_t destNode, String command) {
+    String cmdMsg = "{\"type\":\"command\",\"cmd\":\"" + command + "\"}";
+    
+    // Send to specific node with HIGH priority
+    mesh.sendSingle(destNode, cmdMsg, 1);  // Priority level 1 = HIGH
+    
+    Serial.printf("Command sent to node %u with HIGH priority\n", destNode);
+}

package/examples/priority/priority_with_queue.ino

@@ -0,0 +1,249 @@
+/**
+ * Advanced Priority Example with Message Queue Integration
+ * 
+ * Demonstrates how to use priority messaging with the message queue
+ * for offline/Internet-unavailable scenarios.
+ * 
+ * This example shows:
+ * - Priority-based message sending
+ * - Message queueing when Internet is unavailable
+ * - Automatic queue flushing when Internet becomes available
+ * - Priority ordering during queue flush
+ * 
+ * Hardware: ESP32 or ESP8266
+ */
+
+#include "painlessMesh.h"
+
+#define MESH_PREFIX     "PriorityQueueMesh"
+#define MESH_PASSWORD   "somethingSneaky"
+#define MESH_PORT       5555
+
+Scheduler userScheduler;
+painlessMesh mesh;
+
+bool internetAvailable = false;
+uint32_t bridgeNodeId = 0;
+
+// Task to check bridge status
+Task taskCheckBridge(5000, TASK_FOREVER, []() {
+    bool hasInternet = mesh.hasInternetConnection();
+    
+    if (hasInternet != internetAvailable) {
+        internetAvailable = hasInternet;
+        Serial.printf("Internet status changed: %s\n", hasInternet ? "ONLINE" : "OFFLINE");
+        
+        if (hasInternet) {
+            // Internet came back online - flush queued messages by priority
+            flushQueuedMessages();
+        }
+    }
+});
+
+// Task to generate sensor data
+Task taskSensorData(10000, TASK_FOREVER, []() {
+    String sensorData = "{\"type\":\"sensor\",\"temp\":" + String(random(15, 30)) + 
+                       ",\"humidity\":" + String(random(30, 70)) + "}";
+    
+    sendMessage(sensorData, 2);  // NORMAL priority
+});
+
+// Task to generate status updates
+Task taskStatusUpdate(30000, TASK_FOREVER, []() {
+    String status = "{\"type\":\"status\",\"uptime\":" + String(millis() / 1000) + 
+                   ",\"heap\":" + String(ESP.getFreeHeap()) + "}";
+    
+    sendMessage(status, 1);  // HIGH priority
+});
+
+void setup() {
+    Serial.begin(115200);
+    
+    // Enable message queue with 500 message capacity
+    mesh.enableMessageQueue(true, 500);
+    
+    mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+    
+    mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+    mesh.onReceive(&receivedCallback);
+    mesh.onNewConnection(&newConnectionCallback);
+    mesh.onBridgeStatusChanged(&bridgeStatusChanged);
+    mesh.onQueueStateChanged(&queueStateChanged);
+    
+    // Add tasks
+    userScheduler.addTask(taskCheckBridge);
+    userScheduler.addTask(taskSensorData);
+    userScheduler.addTask(taskStatusUpdate);
+    
+    taskCheckBridge.enable();
+    taskSensorData.enable();
+    taskStatusUpdate.enable();
+    
+    Serial.println("Priority + Queue demo started");
+    Serial.println("Messages will be queued when Internet is unavailable");
+    Serial.println("Queue will be flushed by priority when Internet returns");
+}
+
+void loop() {
+    mesh.update();
+}
+
+/**
+ * Send a message with priority
+ * - If Internet available: send immediately via mesh with priority
+ * - If Internet unavailable: queue for later with priority
+ */
+void sendMessage(String message, uint8_t priority) {
+    if (internetAvailable && bridgeNodeId != 0) {
+        // Internet available - send with priority
+        mesh.sendSingle(bridgeNodeId, message, priority);
+        Serial.printf("Sent message with priority %u\n", priority);
+        
+    } else {
+        // Internet unavailable - queue with priority
+        // Map our priority levels to MessageQueue priorities
+        MessagePriority queuePriority;
+        switch(priority) {
+            case 0: queuePriority = PRIORITY_CRITICAL; break;
+            case 1: queuePriority = PRIORITY_HIGH; break;
+            case 2: queuePriority = PRIORITY_NORMAL; break;
+            case 3: queuePriority = PRIORITY_LOW; break;
+            default: queuePriority = PRIORITY_NORMAL; break;
+        }
+        
+        uint32_t msgId = mesh.queueMessage(message, "mqtt://cloud", queuePriority);
+        if (msgId > 0) {
+            Serial.printf("Queued message #%u with priority %u (offline mode)\n", msgId, priority);
+        } else {
+            Serial.println("Failed to queue message - queue full!");
+        }
+    }
+}
+
+/**
+ * Send a critical alarm - always gets through
+ */
+void sendCriticalAlarm(String alarmType, String alarmMessage) {
+    String criticalMsg = "{\"type\":\"alarm\",\"alarm\":\"" + alarmType + 
+                        "\",\"msg\":\"" + alarmMessage + "\",\"time\":" + 
+                        String(millis()) + "}";
+    
+    // CRITICAL priority - send immediately even if queued
+    sendMessage(criticalMsg, 0);
+    
+    Serial.printf("CRITICAL ALARM: %s - %s\n", alarmType.c_str(), alarmMessage.c_str());
+}
+
+/**
+ * Flush queued messages by priority when Internet returns
+ */
+void flushQueuedMessages() {
+    Serial.println("Flushing queued messages by priority...");
+    
+    // Get all queued messages (already sorted by priority in MessageQueue)
+    auto messages = mesh.flushMessageQueue();
+    
+    Serial.printf("Found %d queued messages to send\n", messages.size());
+    
+    // Send each message with its original priority
+    for (auto& msg : messages) {
+        // Convert MessagePriority back to send priority (0-3)
+        uint8_t sendPriority;
+        switch(msg.priority) {
+            case PRIORITY_CRITICAL: sendPriority = 0; break;
+            case PRIORITY_HIGH: sendPriority = 1; break;
+            case PRIORITY_NORMAL: sendPriority = 2; break;
+            case PRIORITY_LOW: sendPriority = 3; break;
+            default: sendPriority = 2; break;
+        }
+        
+        // Send with original priority
+        if (bridgeNodeId != 0) {
+            bool sent = mesh.sendSingle(bridgeNodeId, msg.payload, sendPriority);
+            
+            if (sent) {
+                // Remove from queue on success
+                mesh.removeQueuedMessage(msg.id);
+                Serial.printf("Sent queued message #%u (priority %u)\n", msg.id, sendPriority);
+            } else {
+                // Failed to send - increment attempts
+                uint32_t attempts = mesh.incrementQueuedMessageAttempts(msg.id);
+                Serial.printf("Failed to send queued message #%u (attempt %u)\n", msg.id, attempts);
+                
+                // If too many attempts, remove it
+                if (attempts > 5) {
+                    mesh.removeQueuedMessage(msg.id);
+                    Serial.printf("Dropped message #%u after 5 attempts\n", msg.id);
+                }
+            }
+        }
+        
+        // Small delay between sends to avoid overwhelming the network
+        delay(10);
+    }
+    
+    Serial.printf("Queue flush complete. Remaining: %u messages\n", 
+                 mesh.getQueuedMessageCount());
+}
+
+void receivedCallback(uint32_t from, String& msg) {
+    Serial.printf("Received from %u: %s\n", from, msg.c_str());
+}
+
+void newConnectionCallback(uint32_t nodeId) {
+    Serial.printf("New connection: %u\n", nodeId);
+}
+
+void bridgeStatusChanged(uint32_t nodeId, bool hasInternet) {
+    Serial.printf("Bridge %u status: Internet %s\n", 
+                 nodeId, hasInternet ? "ONLINE" : "OFFLINE");
+    
+    if (hasInternet) {
+        bridgeNodeId = nodeId;
+        internetAvailable = true;
+        
+        // Flush queued messages with priority
+        flushQueuedMessages();
+    } else {
+        internetAvailable = false;
+    }
+}
+
+void queueStateChanged(QueueState state, uint32_t count) {
+    switch(state) {
+        case QUEUE_EMPTY:
+            Serial.println("Queue is empty");
+            break;
+        case QUEUE_NORMAL:
+            Serial.printf("Queue normal: %u messages\n", count);
+            break;
+        case QUEUE_75_PERCENT:
+            Serial.printf("WARNING: Queue 75%% full (%u messages)\n", count);
+            break;
+        case QUEUE_FULL:
+            Serial.printf("ALERT: Queue is FULL (%u messages)\n", count);
+            break;
+    }
+}
+
+// Example: Simulate a critical event
+void simulateCriticalEvent() {
+    sendCriticalAlarm("FIRE", "Fire detected in Building A, Floor 3");
+}
+
+// Example: Monitor queue statistics
+void printQueueStats() {
+    auto stats = mesh.getQueueStats();
+    
+    Serial.println("=== Queue Statistics ===");
+    Serial.printf("Total queued: %u\n", stats.totalQueued);
+    Serial.printf("Total sent: %u\n", stats.totalSent);
+    Serial.printf("Total dropped: %u\n", stats.totalDropped);
+    Serial.printf("Current size: %u / %u\n", stats.currentSize, stats.maxSize);
+    Serial.println();
+    Serial.printf("CRITICAL queued: %u\n", stats.criticalQueued);
+    Serial.printf("HIGH queued: %u\n", stats.highQueued);
+    Serial.printf("NORMAL queued: %u\n", stats.normalQueued);
+    Serial.printf("LOW queued: %u\n", stats.lowQueued);
+    Serial.println("=======================");
+}