@alteriom/painlessmesh 1.7.9 → 1.8.0

package/examples/ntpTimeSyncNode/ntpTimeSyncNode.ino

@@ -0,0 +1,109 @@
+/**
+ * @file ntpTimeSyncNode.ino
+ * @brief Example: Regular mesh node receiving NTP time from bridge
+ * 
+ * This example demonstrates a regular mesh node that:
+ * 1. Connects to the mesh network
+ * 2. Listens for NTP time broadcasts from bridge nodes
+ * 3. Updates local time when NTP sync is received
+ * 4. Optionally syncs RTC module if available
+ * 
+ * No Internet connection needed - time is received from bridge!
+ */
+
+#include "painlessMesh.h"
+#include "examples/alteriom/alteriom_sensor_package.hpp"
+
+// Mesh configuration
+#define MESH_PREFIX     "AlteriomMesh"
+#define MESH_PASSWORD   "your_mesh_password"
+#define MESH_PORT       5555
+
+Scheduler userScheduler;
+painlessMesh mesh;
+
+using namespace alteriom;
+
+// Track last time sync
+uint32_t lastNTPSync = 0;
+uint32_t ntpSyncCount = 0;
+
+// Received callback - handle incoming messages
+void receivedCallback(uint32_t from, String& msg) {
+  // Parse JSON message
+  DynamicJsonDocument doc(1024);
+  DeserializationError error = deserializeJson(doc, msg);
+  
+  if (error) {
+    Serial.printf("JSON parse error: %s\n", error.c_str());
+    return;
+  }
+  
+  JsonObject obj = doc.as<JsonObject>();
+  uint16_t msgType = obj["type"];
+  
+  // Check if this is an NTP time sync message
+  if (msgType == 614) {
+    // Deserialize NTP time sync package
+    auto pkg = NTPTimeSyncPackage(obj);
+    
+    Serial.printf("\n=== NTP Time Sync Received ===\n");
+    Serial.printf("From: %u\n", from);
+    Serial.printf("NTP Time: %u\n", pkg.ntpTime);
+    Serial.printf("Accuracy: %ums\n", pkg.accuracy);
+    Serial.printf("Source: %s\n", pkg.source.c_str());
+    Serial.printf("Timestamp: %u\n", pkg.timestamp);
+    Serial.println("=============================\n");
+    
+    // Update mesh time (this is application-specific)
+    // In a real implementation, you would:
+    // 1. Verify the sender is a bridge node
+    // 2. Apply the time with mesh.setTimeFromNTP(pkg.ntpTime)
+    // 3. Update RTC if available
+    
+    lastNTPSync = millis();
+    ntpSyncCount++;
+    
+    Serial.printf("Time sync applied! Total syncs: %u\n", ntpSyncCount);
+  }
+}
+
+// Status task - periodic status updates
+Task taskStatus(30000, TASK_FOREVER, [](){
+  uint32_t timeSinceSync = (millis() - lastNTPSync) / 1000;
+  
+  Serial.printf("\n--- Node Status ---\n");
+  Serial.printf("Node ID: %u\n", mesh.getNodeId());
+  Serial.printf("Connections: %d\n", mesh.getNodeList().size());
+  Serial.printf("NTP Syncs: %u\n", ntpSyncCount);
+  
+  if (ntpSyncCount > 0) {
+    Serial.printf("Last sync: %u seconds ago\n", timeSinceSync);
+  } else {
+    Serial.println("Waiting for first NTP sync...");
+  }
+  
+  Serial.println("------------------\n");
+});
+
+void setup() {
+  Serial.begin(115200);
+  
+  // Initialize mesh
+  mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+  mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+  
+  // Set callbacks
+  mesh.onReceive(&receivedCallback);
+  
+  // Add status task
+  userScheduler.addTask(taskStatus);
+  taskStatus.enable();
+  
+  Serial.println("Regular mesh node initialized");
+  Serial.println("Listening for NTP time broadcasts...");
+}
+
+void loop() {
+  mesh.update();
+}

package/examples/rtcIntegration/README.md

@@ -0,0 +1,235 @@
+# RTC Integration Example
+
+This example demonstrates how to integrate Real-Time Clock (RTC) modules with painlessMesh for accurate offline timekeeping.
+
+## Problem Statement
+
+When Internet or bridge connectivity is unavailable, mesh nodes lose access to accurate time synchronization. This is problematic for applications that require valid timestamps, such as:
+
+- Fish farm alarm systems (regulatory compliance)
+- Environmental monitoring with offline data logging
+- Industrial IoT with intermittent connectivity
+- Remote sensor networks
+
+## Solution
+
+painlessMesh RTC integration provides:
+
+✅ **Accurate timestamps during offline periods**  
+✅ **Automatic NTP sync when Internet available**  
+✅ **Graceful fallback to mesh time**  
+✅ **Support for common RTC modules**
+
+## Supported RTC Modules
+
+- **DS3231** - High accuracy I2C RTC with temperature compensation
+- **DS1307** - Basic I2C RTC
+- **PCF8523** - Low power I2C RTC
+- **PCF8563** - Ultra-low power I2C RTC
+- **ESP32 Internal RTC** - Built-in ESP32 RTC (requires external battery backup)
+
+## Hardware Requirements
+
+### For DS3231 (used in this example)
+- ESP32 or ESP8266 board
+- DS3231 RTC module
+- Connections:
+  - SDA → GPIO 21 (ESP32) or GPIO 4 (ESP8266)
+  - SCL → GPIO 22 (ESP32) or GPIO 5 (ESP8266)
+  - VCC → 3.3V
+  - GND → GND
+
+### Library Requirements
+```
+painlessMesh
+RTClib (Adafruit)
+```
+
+Install via Arduino Library Manager:
+- Tools → Manage Libraries
+- Search for "RTClib" by Adafruit
+- Click Install
+
+## How It Works
+
+### 1. RTC Interface Implementation
+
+You implement the `RTCInterface` for your specific RTC hardware:
+
+```cpp
+class DS3231Interface : public painlessmesh::rtc::RTCInterface {
+  // Implement begin(), isAvailable(), getUnixTime(), setUnixTime(), getType()
+};
+```
+
+### 2. Enable RTC
+
+```cpp
+DS3231Interface rtcInterface(&rtc);
+mesh.enableRTC(&rtcInterface);
+```
+
+### 3. Automatic Time Management
+
+```cpp
+mesh.onBridgeStatusChanged([](uint32_t bridgeNodeId, bool hasInternet) {
+  if (hasInternet) {
+    // Sync RTC from NTP when Internet available
+    uint32_t ntpTime = getNTPTime();
+    mesh.syncRTCFromNTP(ntpTime);
+  }
+  // Offline: RTC maintains accurate time
+});
+```
+
+### 4. Get Accurate Time
+
+```cpp
+// Prefers RTC, falls back to mesh time
+uint32_t timestamp = mesh.getAccurateTime();
+```
+
+## API Reference
+
+### Mesh Methods
+
+#### `bool enableRTC(rtc::RTCInterface* rtcInterface)`
+Enable RTC integration with a user-provided interface.
+
+**Returns:** `true` if RTC initialized successfully, `false` otherwise
+
+#### `void disableRTC()`
+Disable RTC integration.
+
+#### `bool syncRTCFromNTP(uint32_t ntpTimestamp)`
+Sync RTC from NTP/Internet time source.
+
+**Parameters:**
+- `ntpTimestamp` - Unix timestamp from NTP
+
+**Returns:** `true` if sync successful, `false` otherwise
+
+#### `uint32_t getAccurateTime()`
+Get accurate time with RTC fallback.
+
+**Returns:** Unix timestamp (seconds) from RTC, or mesh time (microseconds) if RTC unavailable
+
+#### `bool hasRTC()`
+Check if RTC is enabled and available.
+
+**Returns:** `true` if RTC can be used, `false` otherwise
+
+#### `rtc::RTCType getRTCType()`
+Get RTC module type.
+
+**Returns:** `RTCType` enum value
+
+#### `uint32_t getTimeSinceRTCSync()`
+Get time since last RTC sync.
+
+**Returns:** Milliseconds since last sync, or 0 if never synced
+
+#### `void onRTCSyncComplete(rtcSyncCompleteCallback_t callback)`
+Set callback for RTC sync completion.
+
+### RTC Types
+
+```cpp
+enum RTCType {
+  RTC_NONE = 0,
+  RTC_DS3231 = 1,
+  RTC_DS1307 = 2,
+  RTC_PCF8523 = 3,
+  RTC_PCF8563 = 4,
+  RTC_ESP32_INTERNAL = 5
+};
+```
+
+## Usage Example
+
+```cpp
+#include "painlessMesh.h"
+#include <RTClib.h>
+
+painlessMesh mesh;
+RTC_DS3231 rtc;
+DS3231Interface rtcInterface(&rtc);
+
+void setup() {
+  mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+  mesh.onBridgeStatusChanged(&bridgeStatusCallback);
+  mesh.onRTCSyncComplete(&rtcSyncCompleteCallback);
+  
+  if (mesh.enableRTC(&rtcInterface)) {
+    Serial.println("RTC enabled!");
+  }
+}
+
+void bridgeStatusCallback(uint32_t bridgeNodeId, bool hasInternet) {
+  if (hasInternet && mesh.hasRTC()) {
+    uint32_t ntpTime = getNTPTime();  // Your implementation
+    mesh.syncRTCFromNTP(ntpTime);
+  }
+}
+
+void rtcSyncCompleteCallback(uint32_t timestamp) {
+  Serial.printf("RTC synced to: %u\n", timestamp);
+}
+```
+
+## Testing
+
+### Verify RTC Time Persistence
+1. Upload sketch to node
+2. Disconnect Internet/bridge
+3. Power cycle the node
+4. Verify timestamps remain accurate (±2 seconds)
+
+### Verify NTP Sync
+1. Connect bridge to Internet
+2. Monitor serial output for sync messages
+3. Verify RTC time updated correctly
+
+### Verify Offline Operation
+1. Disconnect Internet
+2. Wait several hours
+3. Verify timestamps continue to increment accurately
+
+## Troubleshooting
+
+### "Couldn't find RTC"
+- Check I2C connections (SDA/SCL)
+- Verify RTC module has power
+- Try I2C scanner sketch to detect device
+
+### "RTC lost power"
+- RTC battery needs replacement
+- Time will be synced from NTP when available
+
+### Time Not Syncing
+- Verify bridge has Internet connectivity
+- Check NTP server is accessible
+- Ensure `syncRTCFromNTP()` called with valid timestamp
+
+## Best Practices
+
+1. **Always check RTC availability** before relying on timestamps
+2. **Sync regularly** when Internet available (recommended: every 24 hours)
+3. **Monitor battery** on RTC modules for continuous operation
+4. **Implement fallback** to mesh time if RTC fails
+5. **Log sync events** for debugging and maintenance
+
+## Regulatory Compliance
+
+For systems requiring timestamp accuracy (e.g., fish farm alarms):
+
+- RTC provides ±2 second accuracy during offline periods
+- Timestamps remain valid for alarm reporting
+- Sync logs provide audit trail
+- Battery backup ensures continuous operation
+
+## See Also
+
+- [Bridge Status Feature](../../BRIDGE_STATUS_FEATURE.md) - Internet connectivity detection
+- [Bridge Architecture](../../BRIDGE_ARCHITECTURE_IMPLEMENTATION.md) - Mesh bridge setup
+- [painlessMesh Documentation](https://gitlab.com/painlessMesh/painlessMesh) - Main library docs

package/examples/rtcIntegration/rtcIntegration.ino

@@ -0,0 +1,196 @@
+//************************************************************
+// RTC Integration Example
+//
+// This example demonstrates how to use RTC (Real-Time Clock)
+// modules with painlessMesh for accurate offline timekeeping.
+//
+// When Internet/bridge is unavailable, nodes can still maintain
+// accurate timestamps using a local RTC module.
+//
+// Supported RTC modules:
+// - DS3231, DS1307 (I2C)
+// - PCF8523, PCF8563 (I2C)
+// - ESP32 internal RTC
+//
+// This example uses DS3231 with the RTClib library.
+// Install: https://github.com/adafruit/RTClib
+//************************************************************
+
+#include "painlessMesh.h"
+#include <RTClib.h>  // Adafruit RTClib for DS3231
+
+#define MESH_PREFIX     "AlteriomMesh"
+#define MESH_PASSWORD   "somethingSneaky"
+#define MESH_PORT       5555
+
+Scheduler userScheduler;
+painlessMesh mesh;
+
+// DS3231 RTC instance
+RTC_DS3231 rtc;
+
+// RTC Interface implementation for DS3231
+class DS3231Interface : public painlessmesh::rtc::RTCInterface {
+private:
+  RTC_DS3231* rtcDevice;
+  
+public:
+  DS3231Interface(RTC_DS3231* device) : rtcDevice(device) {}
+  
+  bool begin() override {
+    if (!rtcDevice->begin()) {
+      Serial.println("Couldn't find RTC");
+      return false;
+    }
+    
+    // Check if RTC lost power and needs time set
+    if (rtcDevice->lostPower()) {
+      Serial.println("RTC lost power, time needs to be set!");
+      // Note: Time will be set via NTP when Internet available
+    }
+    
+    return true;
+  }
+  
+  bool isAvailable() override {
+    return !rtcDevice->lostPower();
+  }
+  
+  uint32_t getUnixTime() override {
+    DateTime now = rtcDevice->now();
+    return now.unixtime();
+  }
+  
+  bool setUnixTime(uint32_t timestamp) override {
+    rtcDevice->adjust(DateTime(timestamp));
+    Serial.printf("RTC time set to: %u\n", timestamp);
+    return true;
+  }
+  
+  painlessmesh::rtc::RTCType getType() override {
+    return painlessmesh::rtc::RTC_DS3231;
+  }
+};
+
+// Create RTC interface instance
+DS3231Interface rtcInterface(&rtc);
+
+// Task to send timestamped sensor data
+void sendSensorData();
+Task taskSendData(30000, TASK_FOREVER, &sendSensorData);
+
+// Flag to track if we need NTP sync
+bool needsNTPSync = true;
+
+void setup() {
+  Serial.begin(115200);
+  
+  // Initialize mesh
+  mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+  mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+  
+  // Set up mesh callbacks
+  mesh.onReceive(&receivedCallback);
+  mesh.onNewConnection(&newConnectionCallback);
+  mesh.onChangedConnections(&changedConnectionCallback);
+  mesh.onBridgeStatusChanged(&bridgeStatusCallback);
+  mesh.onRTCSyncComplete(&rtcSyncCompleteCallback);
+  
+  // Enable RTC
+  if (mesh.enableRTC(&rtcInterface)) {
+    Serial.println("RTC enabled successfully!");
+    Serial.printf("RTC Type: %d\n", mesh.getRTCType());
+    
+    // Print current RTC time
+    uint32_t rtcTime = mesh.getAccurateTime();
+    Serial.printf("Current RTC time: %u\n", rtcTime);
+  } else {
+    Serial.println("Failed to enable RTC - will use mesh time only");
+  }
+  
+  // Add sensor data task
+  userScheduler.addTask(taskSendData);
+  taskSendData.enable();
+  
+  Serial.println("Setup complete");
+}
+
+void loop() {
+  mesh.update();
+}
+
+void sendSensorData() {
+  // Get accurate timestamp (RTC if available, mesh time otherwise)
+  uint32_t timestamp = mesh.getAccurateTime();
+  
+  // Simulate sensor reading
+  float temperature = 25.5 + random(-50, 50) / 10.0;
+  float humidity = 60.0 + random(-100, 100) / 10.0;
+  
+  // Create message with timestamp
+  String msg = "{\"type\":\"sensor\",";
+  msg += "\"nodeId\":" + String(mesh.getNodeId()) + ",";
+  msg += "\"timestamp\":" + String(timestamp) + ",";
+  msg += "\"temperature\":" + String(temperature, 1) + ",";
+  msg += "\"humidity\":" + String(humidity, 1) + ",";
+  msg += "\"hasRTC\":" + String(mesh.hasRTC() ? "true" : "false") + ",";
+  msg += "\"rtcType\":" + String(mesh.getRTCType());
+  msg += "}";
+  
+  mesh.sendBroadcast(msg);
+  
+  Serial.printf("Sent sensor data with timestamp: %u\n", timestamp);
+  Serial.printf("Time since last RTC sync: %u ms\n", mesh.getTimeSinceRTCSync());
+}
+
+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("Changed connections\n");
+}
+
+void bridgeStatusCallback(uint32_t bridgeNodeId, bool hasInternet) {
+  Serial.printf("Bridge %u - Internet: %s\n", 
+                bridgeNodeId, 
+                hasInternet ? "Connected" : "Disconnected");
+  
+  if (hasInternet && needsNTPSync && mesh.hasRTC()) {
+    // Internet is available and we need to sync RTC
+    // In a real application, you would get NTP time here
+    // For this example, we'll use a placeholder
+    Serial.println("Internet available - would sync RTC from NTP now");
+    
+    // Example: Get NTP time (you need to implement this)
+    // uint32_t ntpTime = getNTPTime();
+    // if (mesh.syncRTCFromNTP(ntpTime)) {
+    //   Serial.println("RTC synced successfully!");
+    //   needsNTPSync = false;
+    // }
+    
+    // For demonstration purposes, let's sync to a known time
+    uint32_t demoTime = 1704067200; // 2024-01-01 00:00:00 UTC
+    if (mesh.syncRTCFromNTP(demoTime)) {
+      Serial.println("RTC synced to demo time!");
+      needsNTPSync = false;
+    }
+  } else if (!hasInternet) {
+    // Internet lost - RTC will keep accurate time offline
+    Serial.println("Internet offline - using RTC for timestamps");
+  }
+}
+
+void rtcSyncCompleteCallback(uint32_t timestamp) {
+  Serial.printf("RTC sync completed! New time: %u\n", timestamp);
+  
+  // Convert timestamp to human-readable format
+  DateTime dt(timestamp);
+  Serial.printf("Synced to: %d-%02d-%02d %02d:%02d:%02d\n",
+                dt.year(), dt.month(), dt.day(),
+                dt.hour(), dt.minute(), dt.second());
+}

package/library.json

@@ -6,7 +6,7 @@
     "type": "git",
     "url": "https://github.com/Alteriom/painlessMesh"
   },
-  "version": "1.7.9",
+  "version": "1.8.0",
   "frameworks": [
     "arduino"
   ],

package/library.properties

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alteriom/painlessmesh",
-  "version": "1.7.9",
+  "version": "1.8.0",
   "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",