@alteriom/painlessmesh 1.8.15 → 1.9.0

package/examples/rtcIntegration/README.md

@@ -1,294 +0,0 @@
-# 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
-
-## Time Authority
-
-painlessMesh v1.8.12+ includes **time authority** support to prevent nodes from adopting incorrect time from nodes without accurate time sources.
-
-### How It Works
-
-Nodes with time authority (RTC or Internet) are prioritized during mesh time synchronization:
-- Nodes **without** time authority will adopt time from nodes **with** time authority
-- Nodes **with** time authority will **NOT** adopt time from nodes without
-- When both nodes have same authority status, existing subnet/node ID logic applies
-
-### Setting Time Authority
-
-Time authority is automatically set when:
-- RTC is enabled via `enableRTC()` (time authority = true)
-- RTC is disabled via `disableRTC()` (time authority = false)
-
-For bridge nodes with Internet, set time authority manually:
-
-```cpp
-void bridgeStatusCallback(uint32_t bridgeNodeId, bool hasInternet) {
-  // If THIS node is the bridge, update time authority
-  if (bridgeNodeId == mesh.getNodeId()) {
-    if (hasInternet) {
-      mesh.setTimeAuthority(true);  // Internet available
-    } else if (!mesh.hasRTC()) {
-      mesh.setTimeAuthority(false); // No Internet and no RTC
-    }
-  }
-}
-```
-
-### Checking Time Authority
-
-```cpp
-if (mesh.getTimeAuthority()) {
-  Serial.println("This node has authoritative time source");
-}
-```
-
-### Use Cases
-
-**Scenario 1: Mixed RTC nodes**
-- Node A: Has RTC (time authority = true)
-- Node B: No RTC (time authority = false)
-- Result: Node B adopts time from Node A ✓
-
-**Scenario 2: Bridge with Internet**
-- Node A: Bridge with Internet (time authority = true)
-- Node B: Regular node (time authority = false)
-- Result: Node B adopts time from bridge ✓
-
-**Scenario 3: Network split**
-- Subnet A: All nodes have RTC
-- Subnet B: No nodes have RTC
-- Result: When subnets reconnect, Subnet B adopts from Subnet A ✓
-
-## 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
-6. **Set time authority** for bridge nodes when Internet is available
-7. **Use RTC on at least one node** in offline deployments for accurate timestamps
-
-## 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

@@ -1,210 +0,0 @@
-//************************************************************
-// 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 THIS node is the bridge, set time authority based on Internet availability
-  if (bridgeNodeId == mesh.getNodeId()) {
-    if (hasInternet) {
-      Serial.println("This node has Internet - setting time authority");
-      mesh.setTimeAuthority(true);
-    } else {
-      // Lost Internet - remove time authority if no RTC
-      if (!mesh.hasRTC()) {
-        Serial.println("Lost Internet and no RTC - removing time authority");
-        mesh.setTimeAuthority(false);
-      }
-    }
-  }
-  
-  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());
-}