@alteriom/painlessmesh 1.6.1 → 1.7.2

package/docs/getting-started/quickstart.md

@@ -1,158 +1,158 @@
-# Quick Start Guide
-
-Get your first painlessMesh network running in just a few minutes! This guide will walk you through creating a simple mesh network with two ESP8266 or ESP32 devices.
-
-## What You'll Need
-
-- 2 or more ESP8266 or ESP32 development boards
-- Arduino IDE or PlatformIO
-- USB cables for programming
-
-## Step 1: Install painlessMesh
-
-### Arduino IDE
-1. Open Arduino IDE
-2. Go to **Sketch → Include Library → Manage Libraries**
-3. Search for "painlessMesh"
-4. Install the latest version by "Coopdis"
-
-### PlatformIO
-Add to your `platformio.ini`:
-```ini
-lib_deps = 
-    painlessMesh
-```
-
-## Step 2: Basic Mesh Example
-
-Copy this code to your Arduino IDE or create a new PlatformIO project:
-
-```cpp
-#include "painlessMesh.h"
-
-#define   MESH_PREFIX     "MyMeshNetwork"
-#define   MESH_PASSWORD   "somethingSneaky"
-#define   MESH_PORT       5555
-
-Scheduler userScheduler; // to control your personal task
-painlessMesh  mesh;
-
-// User stub
-void sendMessage(); // Prototype so PlatformIO doesn't complain
-
-Task taskSendMessage(TASK_SECOND * 1, TASK_FOREVER, &sendMessage);
-
-void sendMessage() {
-  String msg = "Hello from node ";
-  msg += mesh.getNodeId();
-  mesh.sendBroadcast(msg);
-  taskSendMessage.setInterval(random(TASK_SECOND * 1, TASK_SECOND * 5));
-}
-
-// Needed for painless library
-void receivedCallback(uint32_t from, String &msg) {
-  Serial.printf("startHere: Received from %u msg=%s\n", from, msg.c_str());
-}
-
-void newConnectionCallback(uint32_t nodeId) {
-    Serial.printf("--> startHere: New Connection, nodeId = %u\n", nodeId);
-}
-
-void changedConnectionCallback() {
-  Serial.printf("Changed connections\n");
-}
-
-void nodeTimeAdjustedCallback(int32_t offset) {
-    Serial.printf("Adjusted time %u. Offset = %d\n", mesh.getNodeTime(),offset);
-}
-
-void setup() {
-  Serial.begin(115200);
-
-  // Set debug messages before init()
-  mesh.setDebugMsgTypes(ERROR | STARTUP);
-
-  // Initialize mesh
-  mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
-  mesh.onReceive(&receivedCallback);
-  mesh.onNewConnection(&newConnectionCallback);
-  mesh.onChangedConnections(&changedConnectionCallback);
-  mesh.onNodeTimeAdjusted(&nodeTimeAdjustedCallback);
-
-  // Add task to scheduler
-  userScheduler.addTask(taskSendMessage);
-  taskSendMessage.enable();
-}
-
-void loop() {
-  // it will run the user scheduler as well
-  mesh.update();
-}
-```
-
-## Step 3: Upload and Test
-
-1. **Upload the code** to your first ESP8266/ESP32 device
-2. **Open Serial Monitor** (115200 baud) to see debug messages
-3. **Upload the same code** to your second device
-4. Watch them automatically discover each other and start exchanging messages!
-
-## What You Should See
-
-In the Serial Monitor, you'll see output like:
-```
-startHere: New Connection, nodeId = 123456789
-startHere: Received from 123456789 msg=Hello from node 123456789
-Changed connections
-Adjusted time 1234567. Offset = 12
-```
-
-## Key Concepts
-
-- **Mesh Network**: All nodes automatically discover and connect to each other
-- **Broadcasting**: Messages sent to all nodes in the network
-- **Node ID**: Each device gets a unique identifier
-- **Time Sync**: All nodes automatically synchronize their clocks
-- **Self-Healing**: If nodes disconnect, the mesh automatically reorganizes
-
-## Next Steps
-
-Now that you have a basic mesh working:
-
-1. **Add more nodes** - Upload the same code to additional devices
-2. **Try different message types** - See [Custom Packages Tutorial](../tutorials/custom-packages.md)
-3. **Add sensors** - Check out the [Sensor Networks Tutorial](../tutorials/sensor-networks.md)
-4. **Explore Alteriom features** - Learn about [Alteriom Extensions](../alteriom/overview.md)
-
-## Troubleshooting
-
-**Nodes not connecting?**
-- Make sure MESH_PREFIX and MESH_PASSWORD are identical on all devices
-- Check that devices are within WiFi range
-- Verify MESH_PORT is the same on all devices
-
-**Serial output not showing?**
-- Check baud rate is set to 115200
-- Ensure USB cable supports data transfer
-- Try pressing the reset button after upload
-
-For more help, see our [Troubleshooting Guide](../troubleshooting/common-issues.md).
-
-## Configuration Options
-
-You can customize your mesh network by changing these parameters:
-
-```cpp
-// Network credentials
-#define MESH_PREFIX     "YourNetworkName"    // Network name (SSID)
-#define MESH_PASSWORD   "YourPassword"       // Network password
-#define MESH_PORT       5555                 // TCP port for mesh communication
-
-// Debug levels - combine with | operator
-mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
-
-// Available debug types:
-// ERROR, STARTUP, CONNECTION, SYNC, COMMUNICATION, GENERAL, MSG_TYPES, REMOTE
-```
-
+# Quick Start Guide
+
+Get your first painlessMesh network running in just a few minutes! This guide will walk you through creating a simple mesh network with two ESP8266 or ESP32 devices.
+
+## What You'll Need
+
+- 2 or more ESP8266 or ESP32 development boards
+- Arduino IDE or PlatformIO
+- USB cables for programming
+
+## Step 1: Install painlessMesh
+
+### Arduino IDE
+1. Open Arduino IDE
+2. Go to **Sketch → Include Library → Manage Libraries**
+3. Search for "painlessMesh"
+4. Install the latest version by "Coopdis"
+
+### PlatformIO
+Add to your `platformio.ini`:
+```ini
+lib_deps = 
+    painlessMesh
+```
+
+## Step 2: Basic Mesh Example
+
+Copy this code to your Arduino IDE or create a new PlatformIO project:
+
+```cpp
+#include "painlessMesh.h"
+
+#define   MESH_PREFIX     "MyMeshNetwork"
+#define   MESH_PASSWORD   "somethingSneaky"
+#define   MESH_PORT       5555
+
+Scheduler userScheduler; // to control your personal task
+painlessMesh  mesh;
+
+// User stub
+void sendMessage(); // Prototype so PlatformIO doesn't complain
+
+Task taskSendMessage(TASK_SECOND * 1, TASK_FOREVER, &sendMessage);
+
+void sendMessage() {
+  String msg = "Hello from node ";
+  msg += mesh.getNodeId();
+  mesh.sendBroadcast(msg);
+  taskSendMessage.setInterval(random(TASK_SECOND * 1, TASK_SECOND * 5));
+}
+
+// Needed for painless library
+void receivedCallback(uint32_t from, String &msg) {
+  Serial.printf("startHere: Received from %u msg=%s\n", from, msg.c_str());
+}
+
+void newConnectionCallback(uint32_t nodeId) {
+    Serial.printf("--> startHere: New Connection, nodeId = %u\n", nodeId);
+}
+
+void changedConnectionCallback() {
+  Serial.printf("Changed connections\n");
+}
+
+void nodeTimeAdjustedCallback(int32_t offset) {
+    Serial.printf("Adjusted time %u. Offset = %d\n", mesh.getNodeTime(),offset);
+}
+
+void setup() {
+  Serial.begin(115200);
+
+  // Set debug messages before init()
+  mesh.setDebugMsgTypes(ERROR | STARTUP);
+
+  // Initialize mesh
+  mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+  mesh.onReceive(&receivedCallback);
+  mesh.onNewConnection(&newConnectionCallback);
+  mesh.onChangedConnections(&changedConnectionCallback);
+  mesh.onNodeTimeAdjusted(&nodeTimeAdjustedCallback);
+
+  // Add task to scheduler
+  userScheduler.addTask(taskSendMessage);
+  taskSendMessage.enable();
+}
+
+void loop() {
+  // it will run the user scheduler as well
+  mesh.update();
+}
+```
+
+## Step 3: Upload and Test
+
+1. **Upload the code** to your first ESP8266/ESP32 device
+2. **Open Serial Monitor** (115200 baud) to see debug messages
+3. **Upload the same code** to your second device
+4. Watch them automatically discover each other and start exchanging messages!
+
+## What You Should See
+
+In the Serial Monitor, you'll see output like:
+```
+startHere: New Connection, nodeId = 123456789
+startHere: Received from 123456789 msg=Hello from node 123456789
+Changed connections
+Adjusted time 1234567. Offset = 12
+```
+
+## Key Concepts
+
+- **Mesh Network**: All nodes automatically discover and connect to each other
+- **Broadcasting**: Messages sent to all nodes in the network
+- **Node ID**: Each device gets a unique identifier
+- **Time Sync**: All nodes automatically synchronize their clocks
+- **Self-Healing**: If nodes disconnect, the mesh automatically reorganizes
+
+## Next Steps
+
+Now that you have a basic mesh working:
+
+1. **Add more nodes** - Upload the same code to additional devices
+2. **Try different message types** - See [Custom Packages Tutorial](../tutorials/custom-packages.md)
+3. **Add sensors** - Check out the [Sensor Networks Tutorial](../tutorials/sensor-networks.md)
+4. **Explore Alteriom features** - Learn about [Alteriom Extensions](../alteriom/overview.md)
+
+## Troubleshooting
+
+**Nodes not connecting?**
+- Make sure MESH_PREFIX and MESH_PASSWORD are identical on all devices
+- Check that devices are within WiFi range
+- Verify MESH_PORT is the same on all devices
+
+**Serial output not showing?**
+- Check baud rate is set to 115200
+- Ensure USB cable supports data transfer
+- Try pressing the reset button after upload
+
+For more help, see our [Troubleshooting Guide](../troubleshooting/common-issues.md).
+
+## Configuration Options
+
+You can customize your mesh network by changing these parameters:
+
+```cpp
+// Network credentials
+#define MESH_PREFIX     "YourNetworkName"    // Network name (SSID)
+#define MESH_PASSWORD   "YourPassword"       // Network password
+#define MESH_PORT       5555                 // TCP port for mesh communication
+
+// Debug levels - combine with | operator
+mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+
+// Available debug types:
+// ERROR, STARTUP, CONNECTION, SYNC, COMMUNICATION, GENERAL, MSG_TYPES, REMOTE
+```
+
 Ready to dive deeper? Check out our [Installation Guide](installation.md) for more advanced setup options!

package/docs/improvements/FEATURE_PROPOSALS.md

@@ -0,0 +1,337 @@
+# Feature Proposals: OTA and Status Enhancements
+
+**Status:** 📋 Proposal - Awaiting Review  
+**Type:** Enhancement  
+**Impact:** High  
+**Effort:** Medium-High
+
+---
+
+## 🎯 Overview
+
+This proposal explores comprehensive enhancements to painlessMesh for production IoT deployments, focusing on two critical areas:
+
+1. **Enhanced OTA Distribution** - More efficient, reliable, and scalable firmware updates across mesh networks
+2. **Mesh Network Status Monitoring** - Comprehensive health monitoring and diagnostic capabilities
+
+---
+
+## 📚 Documentation Index
+
+### Quick Start
+- **[Quick Reference Guide](ota-status-quick-reference.md)** ⚡ - Start here for TL;DR with decision matrices
+- **[Architecture Diagrams](ota-status-architecture-diagrams.md)** 📊 - Visual understanding of each option
+
+### Complete Analysis
+- **[Full Proposal](ota-and-status-enhancements.md)** 📖 - Comprehensive 50+ page analysis with:
+  - Detailed examination of current implementation
+  - 5 OTA enhancement options with pros/cons
+  - 5 status monitoring options with pros/cons
+  - Implementation details and code examples
+  - Risk assessment and mitigation strategies
+  - Phased rollout recommendations
+
+---
+
+## 🚀 At a Glance
+
+### OTA Enhancement Options
+
+| Option | Description | Speed | Memory | Best For |
+|--------|-------------|-------|--------|----------|
+| **1E: Compression** ⭐⭐⭐⭐⭐ | Gzip firmware transfers | ⭐⭐⭐⭐ | +4-8KB | Everyone (start here) |
+| **1A: Broadcast** ⭐⭐⭐⭐ | Mesh-wide simultaneous distribution | ⭐⭐⭐⭐⭐ | +2-5KB | Medium-large meshes |
+| **1B: Progressive** ⭐⭐⭐⭐ | Phased rollout with safety checks | ⭐⭐ | +3-7KB | Production safety |
+| 1C: Peer-to-Peer | Viral propagation via updated nodes | ⭐⭐⭐⭐⭐ | +200KB | Very large meshes |
+| 1D: MQTT Bridge | Cloud-managed OTA via MQTT | ⭐⭐⭐ | +5-10KB | MQTT infrastructure |
+
+### Status Monitoring Options
+
+| Option | Description | Real-time | Overhead | Best For |
+|--------|-------------|-----------|----------|----------|
+| **2A: Enhanced Package** ⭐⭐⭐⭐⭐ | Extended Alteriom StatusPackage | ⭐⭐⭐ | Low | Simple integration |
+| **2E: MQTT Bridge** ⭐⭐⭐⭐⭐ | Publish status to MQTT topics | ⭐⭐⭐ | Low | Cloud integration |
+| **2B: Status Service** ⭐⭐⭐⭐ | Query-based status collection | ⭐⭐⭐ | Medium | Centralized control |
+| 2C: Telemetry Stream | Continuous low-bandwidth updates | ⭐⭐⭐⭐⭐ | Very Low | Real-time critical |
+| 2D: Health Dashboard | Complete web-based monitoring | ⭐⭐⭐⭐⭐ | Medium | User-facing apps |
+
+---
+
+## 🎯 Recommended Path
+
+### ✅ Phase 1: Quick Wins (Weeks 3-4)
+**Implement:** Options 1E + 2A  
+**Effort:** 3-4 weeks  
+**Value:** Immediate 40-60% OTA speed improvement + standardized status
+
+```cpp
+// Compressed OTA
+mesh.offerOTA("sensor", "ESP32", md5, parts, false, false, true);
+
+// Enhanced Status
+alteriom::EnhancedStatusPackage status;
+status.uptime = millis() / 1000;
+status.freeMemory = ESP.getFreeHeap() / 1024;
+mesh.sendBroadcast(status.toJsonString());
+```
+
+**Benefits:**
+- ✅ Faster OTA distribution
+- ✅ Lower network bandwidth usage
+- ✅ Standardized status reporting
+- ✅ Minimal risk, high reward
+
+---
+
+### ✅ Phase 2: Production Ready (Weeks 6-8)
+**Implement:** Options 1A + 2E  
+**Effort:** 6-8 weeks  
+**Value:** Scalable OTA + professional monitoring
+
+```cpp
+// Broadcast OTA
+mesh.offerOTA("sensor", "ESP32", md5, parts, false, true);
+
+// MQTT Status
+MqttStatusBridge bridge(mesh, mqttClient);
+bridge.setPublishInterval(30000);
+bridge.begin();
+```
+
+**Benefits:**
+- ✅ Scales to large meshes (50+ nodes)
+- ✅ Cloud integration via MQTT
+- ✅ Professional monitoring tools (Grafana, InfluxDB)
+- ✅ Enterprise-ready features
+
+---
+
+### ✅ Phase 3: Advanced (Months 3-4)
+**Implement:** Options 1B + 2C  
+**Effort:** 3-4 months  
+**Value:** Production-safe updates + real-time monitoring
+
+```cpp
+// Progressive Rollout
+ProgressiveOTA ota(mesh);
+ota.setPhases({0.05, 0.20, 1.0});  // 5%, 20%, 100%
+ota.setHealthCheck(checkNodeHealth);
+ota.begin("sensor", "ESP32", md5);
+
+// Telemetry Stream
+TelemetryStream telemetry(mesh);
+telemetry.setInterval(60000);  // 60s
+telemetry.begin();
+```
+
+**Benefits:**
+- ✅ Zero-downtime updates
+- ✅ Early failure detection
+- ✅ Real-time anomaly detection
+- ✅ Proactive alerting
+
+---
+
+## 📊 Expected Results
+
+### OTA Improvements
+
+**Current State:**
+- Update time: 60-120s for 10 nodes
+- Network usage: N × Firmware_Size
+- Success rate: ~85%
+
+**After Phase 1 (Compression):**
+- Update time: 35-70s (40% faster)
+- Network usage: 0.5 × N × Firmware_Size
+- Success rate: ~90%
+
+**After Phase 2 (Broadcast + Compression):**
+- Update time: 15-30s (75% faster)
+- Network usage: 1 × Firmware_Size (regardless of node count)
+- Success rate: ~95%
+
+### Status Monitoring
+
+**Current State:**
+- Manual status collection
+- No standardization
+- Application-specific implementation
+
+**After Phase 1 (Enhanced Package):**
+- Standardized status format
+- Integration with metrics system
+- 500 bytes overhead per update
+
+**After Phase 2 (MQTT Bridge):**
+- Cloud integration
+- Integration with standard tools
+- Historical data tracking
+- Alert management
+
+---
+
+## 🎓 Decision Guide
+
+### "Which OTA option should I choose?"
+
+**Start with:** 1E (Compression)  
+- Universal benefit (40-60% faster)
+- Low complexity
+- Works with existing infrastructure
+
+**Add 1A (Broadcast) if:**
+- Mesh has 10+ nodes
+- Frequent OTA updates
+- Network congestion is an issue
+
+**Add 1B (Progressive) if:**
+- Production deployment
+- Cannot afford downtime
+- Need safety guarantees
+
+**Consider 1C (P2P) if:**
+- Very large mesh (50+ nodes)
+- Nodes have sufficient flash (ESP32)
+- Need fastest possible distribution
+
+**Use 1D (MQTT) if:**
+- Already using MQTT infrastructure
+- Need cloud-based management
+- External OTA tools required
+
+### "Which status option should I choose?"
+
+**Start with:** 2A (Enhanced StatusPackage)  
+- Easiest integration
+- Builds on existing Alteriom packages
+- Minimal changes required
+
+**Add 2E (MQTT Bridge) if:**
+- Need cloud monitoring
+- Using monitoring tools (Grafana, etc.)
+- Want historical data
+
+**Use 2B (Status Service) if:**
+- Need centralized aggregation
+- On-demand queries preferred
+- RESTful API required
+
+**Use 2C (Telemetry) if:**
+- Real-time monitoring critical
+- Large-scale deployment (50+ nodes)
+- Proactive alerting needed
+
+**Use 2D (Dashboard) if:**
+- User-facing application
+- Need visual interface
+- Web-based monitoring required
+
+---
+
+## ⚠️ Important Notes
+
+### For OTA Implementation
+
+**Always remember:**
+- ✅ Include OTA support in updated firmware (prevents bricking)
+- ✅ Test on single node before mesh-wide deployment
+- ✅ Implement rollback mechanism for failures
+- ✅ Use MD5 validation for firmware integrity
+- ✅ Consider progressive rollout for production
+
+**Common pitfalls:**
+- ❌ Updating all nodes simultaneously without testing
+- ❌ Forgetting OTA support in new firmware
+- ❌ Skipping MD5 validation
+- ❌ No rollback plan
+
+### For Status Monitoring
+
+**Always remember:**
+- ✅ Choose appropriate update intervals (30-60s typical)
+- ✅ Implement timeout handling for non-responsive nodes
+- ✅ Monitor memory usage to prevent exhaustion
+- ✅ Set up alerts for critical conditions
+
+**Common pitfalls:**
+- ❌ Polling status too frequently (causes congestion)
+- ❌ Ignoring memory warnings (causes crashes)
+- ❌ Assuming all nodes respond (timeouts happen)
+- ❌ No historical data retention
+
+---
+
+## 🔄 Current Status
+
+### Completed
+- ✅ Analysis of current implementation
+- ✅ Research of enhancement options
+- ✅ Detailed proposal documentation
+- ✅ Architecture diagrams
+- ✅ Quick reference guide
+
+### Next Steps
+1. ⏳ Review proposal with team
+2. ⏳ Approve Phase 1 features
+3. ⏳ Create detailed design documents
+4. ⏳ Set up test infrastructure
+5. ⏳ Begin Phase 1 implementation
+
+### Timeline
+- **Weeks 1-2:** Review and approval
+- **Weeks 3-6:** Phase 1 implementation
+- **Weeks 7-12:** Phase 2 implementation
+- **Months 4-6:** Phase 3 implementation
+
+---
+
+## 🤝 Contributing
+
+Interested in implementing these features?
+
+1. Read the full proposal: [ota-and-status-enhancements.md](ota-and-status-enhancements.md)
+2. Review architecture: [ota-status-architecture-diagrams.md](ota-status-architecture-diagrams.md)
+3. Check quick reference: [ota-status-quick-reference.md](ota-status-quick-reference.md)
+4. Open a GitHub issue to discuss
+5. Submit a pull request with implementation
+
+---
+
+## 📖 Related Resources
+
+### In This Repository
+- [Library Improvements Overview](README.md)
+- [Metrics System](../../src/painlessmesh/metrics.hpp)
+- [Alteriom Packages](../../examples/alteriom/alteriom_sensor_package.hpp)
+- [OTA Sender Example](../../examples/otaSender/otaSender.ino)
+- [OTA Receiver Example](../../examples/otaReceiver/otaReceiver.ino)
+- [MQTT Bridge Example](../../examples/mqttBridge/mqttBridge.ino)
+
+### Documentation
+- [painlessMesh Architecture](../architecture/mesh-architecture.md)
+- [Plugin System](../architecture/plugin-system.md)
+- [API Reference](../api/core-api.md)
+- [Troubleshooting](../troubleshooting/common-issues.md)
+
+### External References
+- ESP-IDF OTA Documentation
+- ArduinoOTA Library
+- MQTT Protocol Specification
+- InfluxDB/Grafana Integration
+
+---
+
+## 📞 Contact
+
+Questions or feedback?
+
+- **GitHub Issues:** https://github.com/Alteriom/painlessMesh/issues
+- **Discussions:** https://github.com/Alteriom/painlessMesh/discussions
+- **Email:** See CONTRIBUTING.md
+
+---
+
+**Last Updated:** December 2024  
+**Proposal Version:** 1.0  
+**Status:** Ready for Review