@alteriom/painlessmesh 1.8.14 → 1.9.0

package/docs/VERSION_MANAGEMENT.md

@@ -1,213 +0,0 @@
-# Version Management in AlteriomPainlessMesh
-
-This document explains how versioning works in the AlteriomPainlessMesh library and clarifies common questions about version numbers in different files.
-
-## 📋 Version Number Locations
-
-The library version is maintained in multiple files across the repository:
-
-### 1. **Official Version Files** (Source of Truth)
-
-These files define the official library version:
-
-- **`library.properties`** - Arduino Library Manager version
-- **`library.json`** - PlatformIO Library Registry version  
-- **`package.json`** - NPM package version
-
-**All three files must always have the same version number.**
-
-### 2. **Header File Version Comments** (Documentation)
-
-These are **documentation comments** that indicate when the header file documentation was last updated:
-
-- **`src/painlessMesh.h`** - `@version` in header comment
-- **`src/AlteriomPainlessMesh.h`** - `ALTERIOM_PAINLESS_MESH_VERSION` defines
-
-**Important:** Version numbers in header file comments reflect the overall library version at the time the header was documented, not file-specific versioning.
-
-## ❓ Common Questions
-
-### Q: Does the version in `painlessMesh.h` mean the file hasn't changed since that version?
-
-**A: No.** The version comment in header files indicates the library version when the header documentation was last reviewed/updated, not the last time the file was modified.
-
-**Example:**
-```cpp
-/**
- * @file painlessMesh.h
- * @version 1.8.7
- * @date 2025-11-12
- */
-```
-
-This means:
-- ✅ The library version is 1.8.7
-- ✅ The header documentation is current as of version 1.8.7
-- ❌ It does NOT mean the file hasn't been modified since 1.8.7
-
-### Q: Why might header version comments be out of sync?
-
-**A:** During rapid development, header file documentation may not be updated every release. The comments are updated when:
-- Significant API changes are made
-- Documentation requires updating
-- Major version milestones are reached
-- Version consistency review is performed
-
-### Q: Which version number should I trust?
-
-**A:** Always refer to the official version files:
-1. `library.properties` - Official Arduino version
-2. `library.json` - Official PlatformIO version
-3. `package.json` - Official NPM version
-4. GitHub releases - Tagged release versions
-
-Header file comments are for documentation reference only.
-
-## 🔄 Version Update Process
-
-### When Releasing a New Version:
-
-1. **Update Official Version Files** (required)
-   ```bash
-   ./scripts/bump-version.sh patch  # or minor, major
-   ```
-   This updates: `library.properties`, `library.json`, `package.json`
-
-2. **Update CHANGELOG.md** (required)
-   - Move items from `[Unreleased]` to new version section
-   - Add release date
-
-3. **Update Header File Comments** (recommended)
-   - Update `@version` in `src/painlessMesh.h`
-   - Update version defines in `src/AlteriomPainlessMesh.h`
-
-4. **Commit and Tag** (required)
-   ```bash
-   git commit -m "release: vX.Y.Z - Brief description"
-   git push origin main
-   ```
-   GitHub Actions will automatically create the tag.
-
-## 📝 Version Comment Best Practices
-
-### In Header Files:
-
-**Good Practice:**
-```cpp
-/**
- * @file painlessMesh.h
- * @brief Main header file for Alteriom painlessMesh library
- * 
- * @version 1.8.7
- * @date 2025-11-12
- * 
- * painlessMesh is a user-friendly library for creating mesh networks...
- */
-```
-
-**What This Means:**
-- The library is at version 1.8.7
-- Header documentation was reviewed/updated on 2025-11-12
-- Always synchronized with library version during releases
-
-### In Implementation Files:
-
-Implementation files (`.cpp`, `.hpp`) typically do not need version comments. Version information in these files can be misleading and is unnecessary since:
-- Git history tracks all changes with timestamps
-- Version is centrally managed in the official version files
-- Per-file versioning creates maintenance overhead
-
-## 🎯 Version Management Workflow
-
-### Developer Workflow:
-
-1. **Check Current Version**
-   ```bash
-   grep "version=" library.properties
-   ```
-
-2. **Make Changes**
-   - Implement features/fixes
-   - Update documentation as needed
-   - Add entries to CHANGELOG.md under `[Unreleased]`
-
-3. **Prepare Release**
-   ```bash
-   ./scripts/release-agent.sh  # Validate release readiness
-   ./scripts/bump-version.sh patch  # Update version
-   ```
-
-4. **Update Documentation**
-   - Review and update header file version comments
-   - Ensure CHANGELOG.md has the new version section
-   - Verify all documentation references are current
-
-5. **Release**
-   ```bash
-   git add library.properties library.json package.json CHANGELOG.md src/*.h
-   git commit -m "release: v1.8.7 - Brief description"
-   git push origin main
-   ```
-
-### Automated Process:
-
-GitHub Actions automatically handles:
-- ✅ Git tag creation
-- ✅ GitHub release with notes
-- ✅ NPM publishing
-- ✅ PlatformIO registry update
-- ✅ Documentation deployment
-
-## 🔍 Version History Tracking
-
-### To Check File History:
-
-Use Git to see actual file modification history:
-
-```bash
-# See all commits that modified a file
-git log --oneline -- src/painlessMesh.h
-
-# See detailed changes to a file
-git log -p -- src/painlessMesh.h
-
-# See when a file was last modified
-git log -1 --format="%ai %an" -- src/painlessMesh.h
-```
-
-### To Check Version History:
-
-```bash
-# List all version tags
-git tag -l "v*"
-
-# See changes in a specific version
-git show v1.8.7
-
-# Compare two versions
-git diff v1.8.6..v1.8.7
-```
-
-## 📚 Related Documentation
-
-- **[CHANGELOG.md](../CHANGELOG.md)** - Complete version history with changes
-- **[RELEASE_GUIDE.md](../RELEASE_GUIDE.md)** - Detailed release process
-- **[GitHub Releases](https://github.com/Alteriom/painlessMesh/releases)** - Official release notes
-
-## 🎓 Summary
-
-**Key Takeaways:**
-
-1. **Official version** = `library.properties` / `library.json` / `package.json`
-2. **Header comments** = Documentation reference, not file-specific versions
-3. **Git history** = Actual source of truth for file modifications
-4. **CHANGELOG.md** = Human-readable version history
-5. **GitHub releases** = Tagged versions with release notes
-
-**When in doubt:** Check `library.properties` for the official library version, and use `git log` to see actual file modification history.
-
----
-
-**Version Management Process Owner:** @Alteriom  
-**Last Updated:** 2025-11-12  
-**Document Version:** 1.0

package/docs/archive/DOCUSAURUS_DEPLOYMENT.md

@@ -1,166 +0,0 @@
-# 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

@@ -1,337 +0,0 @@
-# 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