@alteriom/painlessmesh 1.6.1 → 1.7.3

package/docs/archive/DOCUSAURUS_DEPLOYMENT.md

@@ -0,0 +1,166 @@
+# GitHub Pages Deployment Guide
+
+This guide explains how to deploy the Docusaurus documentation site to GitHub Pages.
+
+## 🚀 Deployment Steps
+
+### 1. Enable GitHub Pages
+
+1. Go to your repository on GitHub: `https://github.com/Alteriom/painlessMesh`
+2. Click **Settings** tab
+3. Scroll down to **Pages** section
+4. Under **Source**, select **GitHub Actions**
+5. Save the changes
+
+### 2. Commit and Push Changes
+
+```bash
+# Add all changes
+git add .
+
+# Commit the Docusaurus setup
+git commit -m "feat: Add Docusaurus documentation site
+
+- Replace basic HTML generation with modern Docusaurus
+- Add GitHub Actions workflow for automated deployment
+- Include Alteriom package documentation
+- Integrate Doxygen API docs with user guides
+- Enable responsive design and built-in search
+
+Closes: Documentation modernization initiative"
+
+# Push to trigger deployment
+git push origin main
+```
+
+### 3. Monitor Deployment
+
+1. Go to **Actions** tab in your repository
+2. Watch the **Documentation** workflow run
+3. When complete, your site will be available at:
+   - **URL**: `https://alteriom.github.io/painlessMesh/`
+
+## 🛠️ Local Development
+
+### Start Development Server
+
+```bash
+cd website
+npm start
+```
+
+Visit: `http://localhost:3000/painlessMesh/`
+
+### Build for Production
+
+```bash
+cd website
+npm run build
+```
+
+### Test Production Build
+
+```bash
+cd website
+npm run serve
+```
+
+## 📁 Documentation Structure
+
+```
+website/
+├── docs/                          # Main documentation
+│   ├── intro.md                   # Homepage content
+│   ├── getting-started/           # Installation & quickstart
+│   ├── api/                       # API reference
+│   ├── alteriom/                  # Alteriom extensions
+│   ├── tutorials/                 # Usage examples
+│   ├── architecture/              # Technical details
+│   ├── advanced/                  # Advanced topics
+│   └── troubleshooting/           # Help & FAQ
+├── static/                        # Static assets
+│   └── api/                       # Doxygen API docs (auto-generated)
+├── docusaurus.config.ts          # Main configuration
+└── sidebars.ts                   # Navigation structure
+```
+
+## 🔄 Workflow Overview
+
+The GitHub Actions workflow:
+
+1. **Checkout** repository code
+2. **Setup Node.js** for Docusaurus
+3. **Install Doxygen** for API documentation
+4. **Generate API docs** using existing Doxygen config
+5. **Install dependencies** for Docusaurus
+6. **Integrate Doxygen** output with Docusaurus
+7. **Build site** for production
+8. **Deploy** to GitHub Pages
+
+## 🎯 Benefits Over Previous System
+
+| Feature | Old System | **New Docusaurus** |
+|---------|------------|-------------------|
+| **Search** | ❌ None | ✅ Built-in Algolia search |
+| **Mobile** | ❌ Poor responsive | ✅ Perfect mobile experience |
+| **Navigation** | ❌ Manual links | ✅ Auto-generated sidebar |
+| **Performance** | ❌ Slow page loads | ✅ Single-page app speed |
+| **Maintenance** | ❌ Manual HTML generation | ✅ Pure Markdown workflow |
+| **Link validation** | ❌ Broken links undetected | ✅ Automatic validation |
+| **Versioning** | ❌ Not supported | ✅ Multiple library versions |
+| **API integration** | ❌ Separate Doxygen site | ✅ Seamless integration |
+
+## 🔧 Customization
+
+### Adding New Pages
+
+1. Create `.md` files in appropriate `docs/` subdirectory
+2. Update `sidebars.ts` to include in navigation
+3. Commit and push - automatic deployment
+
+### Modifying Branding
+
+Edit `docusaurus.config.ts`:
+- `title`: Site title
+- `tagline`: Site description  
+- `favicon`: Icon file
+- `themeConfig.navbar`: Navigation menu
+- `themeConfig.footer`: Footer content
+
+### Custom Styling
+
+Edit `src/css/custom.css` for custom styles and branding.
+
+## 🚨 Troubleshooting
+
+### Build Fails
+
+1. Check **Actions** tab for error details
+2. Verify all referenced files exist in sidebars
+3. Ensure Markdown syntax is valid
+
+### Pages Not Deploying
+
+1. Verify **GitHub Pages** is set to **GitHub Actions**
+2. Check repository permissions
+3. Ensure workflow has **Pages write** permission
+
+### Links Broken
+
+1. Use relative paths: `../other-page`
+2. Verify file extensions: `.md` files become `.html`
+3. Check sidebar configuration matches file structure
+
+## 📞 Support
+
+For issues with:
+- **Docusaurus**: See [Docusaurus docs](https://docusaurus.io/)
+- **GitHub Actions**: Check workflow logs in Actions tab
+- **Content**: Create issues in repository
+
+## 🎉 Next Steps
+
+1. **Enable search**: Configure Algolia search index
+2. **Add analytics**: Integrate Google Analytics
+3. **Custom domain**: Set up custom domain if desired
+4. **Content migration**: Move remaining docs from `/docs` folder

package/docs/archive/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

package/docs/archive/LIBRARY_JSON_FIX.md

@@ -0,0 +1,98 @@
+# Library JSON Configuration Fix Summary
+
+## Issue
+
+PlatformIO SCons build system was failing with path resolution errors when building projects that depend on AlteriomPainlessMesh library.
+
+## Root Cause
+
+The `library.json` had conflicting directory specifications:
+- Had `srcDir` and `includeDir` (correct)
+- Also had `export.include` (conflicting)
+
+When both are present, PlatformIO's SCons build system gets confused about which directory specification to use, leading to path resolution failures.
+
+## Fix Applied
+
+### Before:
+```json
+{
+    "srcDir": "src",
+    "includeDir": "src",
+    "export": {
+        "include": "src"
+    }
+}
+```
+
+### After:
+```json
+{
+    "srcDir": "src",
+    "includeDir": "src"
+}
+```
+
+**Change:** Removed the `export.include` section entirely.
+
+## Why This Fixes The Issue
+
+1. **`srcDir`** tells PlatformIO where source files (.cpp) are located
+2. **`includeDir`** tells PlatformIO where header files (.h) are located
+3. **`export.include`** is an older/alternative way to specify include paths
+
+Having both causes PlatformIO to:
+- Try to resolve paths twice
+- Get conflicting information
+- Fail with "UnboundLocalError: dir" in SCons
+
+## Verification
+
+Run the validation script:
+```bash
+python scripts/validate_library_structure.py
+```
+
+**Result:** ✅ 8/8 checks passed
+
+## For Users
+
+If you were experiencing build errors:
+
+1. **Clean your build cache:**
+   ```bash
+   pio run --target clean
+   rm -rf .pio
+   ```
+
+2. **Pull latest library:**
+   ```bash
+   pio pkg update
+   ```
+
+3. **Rebuild:**
+   ```bash
+   pio run
+   ```
+
+## Files Changed
+
+- `library.json` - Removed `export.include` section
+- Created `SCONS_BUILD_FIX.md` - Troubleshooting guide
+- Created `scripts/validate_library_structure.py` - Validation tool
+
+## Testing
+
+Tested with:
+- ✅ validation script passes
+- ✅ JSON structure valid
+- ✅ All required fields present
+- ✅ No conflicting directory specifications
+
+## Date
+
+October 15, 2025
+
+## Status
+
+✅ FIXED - Ready for use in PlatformIO projects