@alteriom/painlessmesh 1.6.1

package/RELEASE_GUIDE.md

@@ -0,0 +1,419 @@
+# painlessMesh Release Guide
+
+This document provides comprehensive instructions for releasing new versions of the Alteriom painlessMesh library across all distribution channels.
+
+## 🚀 Quick Release Process
+
+### Standard Release (Recommended)
+
+```bash
+# 1. Update version using the bump script
+./scripts/bump-version.sh patch  # or minor, major
+
+# 2. Update CHANGELOG.md with your changes
+# Add your changes under the new version section
+
+# 3. Commit and trigger release
+git add library.properties library.json package.json CHANGELOG.md
+git commit -m "release: v1.6.1"
+git push origin main
+```
+
+**That's it!** GitHub Actions will automatically handle:
+- ✅ Comprehensive testing across platforms
+- ✅ Git tag creation and GitHub release
+- ✅ NPM publishing (public + GitHub Packages)
+- ✅ GitHub Wiki synchronization
+- ✅ Arduino Library Manager package preparation
+- ✅ Release notes generation from changelog
+
+## 📋 Distribution Channels
+
+### Automatic (Zero Manual Work Required)
+1. **GitHub Releases** - Created with changelog and downloadable packages
+2. **NPM Public Registry** - Published to https://www.npmjs.com/package/@alteriom/painlessmesh
+3. **GitHub Packages** - Published to GitHub's NPM registry (@alteriom/painlessmesh)
+4. **PlatformIO Registry** - Automatically indexed from GitHub releases
+5. **GitHub Wiki** - Documentation synchronized from repository
+
+### Semi-Automatic (One-Time Manual Submission)
+6. **Arduino Library Manager** - Submit once, then automatically indexed
+
+## 🎯 Detailed Process
+
+### Version Management
+
+**File Consistency**: All three files must have matching versions:
+
+```properties
+# library.properties
+version=1.6.1
+```
+
+```json
+// library.json  
+{
+  "version": "1.6.1"
+}
+```
+
+```json
+// package.json
+{
+  "version": "1.6.1"
+}
+```
+
+**Semantic Versioning**: Follow [semver.org](https://semver.org/):
+- **MAJOR**: Breaking changes (e.g., 1.6.0 → 2.0.0)
+- **MINOR**: New features, backward compatible (e.g., 1.6.0 → 1.7.0)  
+- **PATCH**: Bug fixes, backward compatible (e.g., 1.6.0 → 1.6.1)
+
+### Automation Triggers
+
+The release workflow triggers on commits to `main` that:
+1. Modify `library.properties`, `library.json`, `package.json`, or `CHANGELOG.md`
+2. Have a commit message starting with `release:`
+
+### What Gets Automated
+
+#### Testing Pipeline
+- **Desktop builds**: gcc & clang with strict warnings
+- **Arduino CLI**: ESP32 & ESP8266 compilation
+- **PlatformIO**: Cross-platform build validation
+- **Code quality**: Formatting and lint checks
+
+#### Release Artifacts
+- **Git tag**: `v1.6.1` format
+- **GitHub Release**: With changelog excerpt
+- **Library package**: `painlessMesh-v1.6.1.zip`
+- **Documentation**: Auto-deployed to GitHub Pages
+
+#### NPM Publishing
+- **Public NPM**: Available to anyone via `npm install @alteriom/painlessmesh`
+- **GitHub Packages**: Scoped package for authenticated users
+- **Version consistency**: Verified across all package files
+
+#### Wiki Updates
+- **Home Page**: Generated from README.md
+- **API Reference**: Auto-generated documentation
+- **Examples**: Links to repository examples
+- **Installation Guide**: Multi-platform instructions
+
+## 📦 NPM Publishing Details
+
+### Dual Publishing Strategy
+
+Each release publishes to **two NPM registries**:
+
+1. **Public NPM** (npmjs.com)
+   - Package: `@alteriom/painlessmesh`
+   - Installation: `npm install @alteriom/painlessmesh`
+   - No authentication required
+
+2. **GitHub Packages** (npm.pkg.github.com)
+   - Package: `@alteriom/painlessmesh`
+   - Installation: Requires `.npmrc` configuration
+   - Authentication required for installation
+
+### NPM Package Contents
+
+The NPM package includes:
+- `src/` - Complete library source code
+- `examples/` - All Arduino examples
+- `docs/` - Documentation files
+- `library.properties` - Arduino metadata
+- `library.json` - PlatformIO metadata
+- Core documentation files (README, LICENSE, CHANGELOG)
+
+Excluded from NPM package:
+- Development files (`.github/`, `test/`, `scripts/`)
+- Build artifacts (`bin/`, `build/`)
+- IDE files and OS-specific files
+
+## 🛠️ Arduino Library Manager
+
+### One-Time Submission Process
+
+After your first release, submit to Arduino Library Manager:
+
+1. **Go to**: https://github.com/arduino/library-registry
+2. **Create issue** with this template:
+
+```
+Title: Add painlessMesh library
+
+Repository URL: https://github.com/Alteriom/painlessMesh
+Release tag: v1.6.1
+Library name: painlessMesh
+Version: 1.6.1
+
+This is the Alteriom fork of the painlessMesh library with enhanced 
+CI/CD, automated releases, and improved Arduino Library Manager compatibility.
+Includes SensorPackage, CommandPackage, and StatusPackage extensions.
+```
+
+3. **Monitor** the issue for Arduino team approval
+4. **Future releases** are automatically indexed
+
+### Arduino Library Compliance
+
+The library meets all Arduino Library Manager requirements:
+- ✅ Correct directory structure
+- ✅ Valid `library.properties` file
+- ✅ Source files in `src/` directory
+- ✅ Examples compile successfully
+- ✅ Consistent version numbering
+- ✅ Open source license (LGPL-3.0)
+
+## 📚 GitHub Wiki Management
+
+### Automatic Synchronization
+
+Wiki pages are automatically updated on each release:
+
+- **Home** - From README.md
+- **Release-Guide** - From RELEASE_GUIDE.md  
+- **Changelog** - From CHANGELOG.md
+- **API-Reference** - Generated documentation
+- **Examples** - Auto-generated from examples directory
+- **Installation** - Multi-platform installation guide
+- **Contributing** - From CONTRIBUTING.md
+
+### Manual Wiki Updates
+
+If you need to update the wiki manually:
+
+```bash
+# Clone wiki repository
+git clone https://github.com/Alteriom/painlessMesh.wiki.git
+
+# Edit markdown files directly
+# Commit and push changes
+```
+
+Note: Manual changes may be overwritten by automatic synchronization.
+
+## 🔧 Scripts Reference
+
+### `./scripts/bump-version.sh`
+Updates version in all library files with consistency checks.
+
+**Usage:**
+```bash
+./scripts/bump-version.sh patch        # Increment patch version
+./scripts/bump-version.sh minor        # Increment minor version  
+./scripts/bump-version.sh major        # Increment major version
+./scripts/bump-version.sh patch 1.6.2  # Set specific version
+```
+
+### `./scripts/validate-release.sh`
+Comprehensive pre-release validation.
+
+**Checks:**
+- Version consistency between all files
+- Changelog entries for current version
+- Git working tree status
+- Tag existence validation
+- Dependency declarations
+- Build file presence
+- Quick compilation test
+
+## 🚨 Troubleshooting
+
+### Common Issues
+
+**Version Mismatch Error**
+```bash
+# Fix version inconsistencies
+./scripts/bump-version.sh patch 1.6.2  # Force set version
+```
+
+**Missing Changelog Entry**
+```bash
+# Add changelog entry for current version
+vim CHANGELOG.md
+# Add section: ## [1.6.2] - YYYY-MM-DD
+```
+
+**Build Failures**
+```bash
+# Test locally before release
+npm run build
+npm run test
+```
+
+**NPM Token Invalid**
+```bash
+# Verify NPM authentication
+npm whoami
+# If not logged in: npm login
+```
+
+**GitHub Packages Authentication**
+```bash
+# Check if GITHUB_TOKEN has packages:write permission
+# Repository Settings → Actions → General → Permissions
+```
+
+**Wiki Update Failure**
+```bash
+# Wiki may need manual initialization
+# Go to: https://github.com/Alteriom/painlessMesh/wiki
+# Create any page to initialize, then re-run release
+```
+
+### Manual Override
+
+If automation fails, you can manually perform any step:
+
+```bash
+# Manual NPM publish
+npm publish --access public
+
+# Manual GitHub release  
+gh release create v1.6.2 --title "painlessMesh v1.6.2" --notes-file CHANGELOG.md
+
+# Manual tag creation
+git tag v1.6.2
+git push origin v1.6.2
+```
+
+## 🔍 Validation Commands
+
+### Pre-Release Checks
+```bash
+# Comprehensive validation
+./scripts/validate-release.sh
+
+# Version consistency check
+./scripts/bump-version.sh --verify || echo "Use proper arguments"
+
+# NPM package validation
+npm run validate-library
+
+# Build test
+npm run build && npm run test
+```
+
+### Post-Release Verification
+```bash
+# Check NPM publication
+npm view @alteriom/painlessmesh
+
+# Check GitHub Packages
+npm view @alteriom/painlessmesh --registry=https://npm.pkg.github.com
+
+# Verify GitHub release
+gh release view
+
+# Check wiki update
+curl -s https://github.com/Alteriom/painlessMesh/wiki | grep -q "v1.6.2"
+```
+
+## 🎉 Success Indicators
+
+### Successful Release Shows:
+- ✅ GitHub release created with changelog
+- ✅ Git tag pushed to repository  
+- ✅ NPM package published (check npmjs.com)
+- ✅ GitHub Packages updated
+- ✅ Wiki pages synchronized
+- ✅ All GitHub Actions workflows completed successfully
+
+### Distribution Verification:
+```bash
+# Public NPM
+npm view @alteriom/painlessmesh
+
+# GitHub Packages
+npm view @alteriom/painlessmesh --registry=https://npm.pkg.github.com
+
+# PlatformIO (updated within 24 hours)
+# Check: https://registry.platformio.org/libraries/alteriom/painlessMesh
+
+# Arduino Library Manager (after manual submission)
+# Search in Arduino IDE Library Manager
+```
+
+## 🌟 Advanced Topics
+
+### Custom Release Notes
+
+To customize release notes beyond the changelog:
+
+1. Edit the generated `release_notes.txt` in the workflow
+2. Or create a custom release notes file in `.github/release-template.md`
+
+### Environment-Specific Releases
+
+For testing releases:
+
+```bash
+# Use pre-release tags
+git tag v1.6.2-beta
+git push origin v1.6.2-beta
+
+# This creates a pre-release without full publication
+```
+
+### Rollback Procedure
+
+If a release has issues:
+
+```bash
+# Delete remote tag
+git push origin :refs/tags/v1.6.2
+
+# Delete local tag  
+git tag -d v1.6.2
+
+# Delete GitHub release
+gh release delete v1.6.2
+
+# Unpublish NPM package (contact npm support)
+# GitHub Packages: Delete from package settings
+```
+
+## 📊 Release Metrics
+
+Monitor your releases:
+- **GitHub**: https://github.com/Alteriom/painlessMesh/releases
+- **NPM**: https://www.npmjs.com/package/@alteriom/painlessmesh
+- **PlatformIO**: https://registry.platformio.org/libraries/alteriom/painlessMesh
+- **Wiki**: https://github.com/Alteriom/painlessMesh/wiki
+
+## 🤝 Security & Permissions
+
+### Required GitHub Secrets
+- `GITHUB_TOKEN`: Automatically provided by GitHub Actions
+- `NPM_TOKEN`: Required for NPM publishing (add in repository secrets)
+
+### Repository Settings
+- **Actions**: Enabled with write permissions
+- **Packages**: Enabled for GitHub Packages publication
+- **Wiki**: Enabled for documentation deployment
+- **Releases**: Public releases enabled
+
+---
+
+## Quick Reference
+
+**Release a patch version:**
+```bash
+./scripts/bump-version.sh patch
+# Edit CHANGELOG.md
+git add . && git commit -m "release: v1.6.2" && git push
+```
+
+**Check release status:**
+```bash
+./scripts/validate-release.sh
+```
+
+**Monitor release:**
+- GitHub Actions: https://github.com/Alteriom/painlessMesh/actions
+- Releases: https://github.com/Alteriom/painlessMesh/releases
+- Documentation: https://github.com/Alteriom/painlessMesh/wiki
+
+For questions or issues with the release process, create an issue with the `ci/cd` label.

package/docs/DOCUMENTATION_MIGRATION_PLAN.md

@@ -0,0 +1,176 @@
+# painlessMesh Documentation - Docusaurus Migration
+
+## Overview
+
+This document outlines the migration from the current custom documentation approach to **Docusaurus 3** for better user experience and maintainability.
+
+## Current Issues
+
+### Broken Links Found
+- `docs/tutorials/custom-packages.md` - Missing
+- `docs/tutorials/sensor-networks.md` - Missing  
+- `docs/advanced/performance.md` - Missing
+- `docs/architecture/routing.md` - Missing
+
+### Problems with Current Approach
+1. **Raw Markdown** - No processing, links break in GitHub Pages
+2. **Manual HTML generation** - Basic and unmaintainable
+3. **Doxygen isolation** - Separate from user documentation
+4. **No link validation** - Broken links undetected
+5. **No search functionality** - Poor discoverability
+6. **Poor mobile experience** - Not responsive
+
+## Proposed Solution: Docusaurus 3
+
+### Why Docusaurus?
+- ✅ **Modern React-based** - Fast, responsive, beautiful
+- ✅ **Built-in search** - Algolia integration
+- ✅ **API docs integration** - Seamless with Doxygen
+- ✅ **Link validation** - Automatic broken link detection
+- ✅ **Versioning support** - Multiple library versions
+- ✅ **GitHub Pages deployment** - Automated CI/CD
+- ✅ **SEO optimized** - Better search engine ranking
+
+### Implementation Plan
+
+#### Phase 1: Setup Docusaurus
+```bash
+# Initialize Docusaurus
+npx create-docusaurus@latest website classic
+
+# Configure for painlessMesh
+cd website
+npm install --save @docusaurus/plugin-client-redirects
+npm install --save @docusaurus/theme-mermaid
+```
+
+#### Phase 2: Content Migration
+1. **Migrate existing docs** to `docs/` folder
+2. **Create missing pages** identified in review
+3. **Fix all broken links** 
+4. **Integrate Doxygen** output
+5. **Add interactive examples**
+
+#### Phase 3: Enhanced Features
+1. **Search integration** with Algolia
+2. **API documentation** with auto-generated content
+3. **Interactive code examples** 
+4. **Version management** for releases
+5. **Analytics integration**
+
+## File Structure (Proposed)
+
+```
+website/
+├── docs/                          # Main documentation
+│   ├── getting-started/
+│   │   ├── installation.md
+│   │   ├── quickstart.md
+│   │   └── first-mesh.md
+│   ├── api/
+│   │   ├── core-api.md
+│   │   └── alteriom-packages.md
+│   ├── tutorials/
+│   │   ├── basic-examples.md
+│   │   ├── custom-packages.md     # NEW - Currently missing
+│   │   └── sensor-networks.md     # NEW - Currently missing
+│   ├── architecture/
+│   │   ├── mesh-architecture.md
+│   │   ├── plugin-system.md
+│   │   └── routing.md             # NEW - Currently missing
+│   ├── advanced/
+│   │   └── performance.md         # NEW - Currently missing
+│   └── troubleshooting/
+│       ├── faq.md
+│       └── common-issues.md
+├── src/
+│   ├── components/                # React components
+│   └── pages/                     # Custom pages
+├── static/                        # Static assets
+├── docusaurus.config.js          # Main configuration
+└── sidebars.js                   # Navigation structure
+```
+
+## Benefits
+
+### For Users
+- 🚀 **Faster navigation** - Single-page app performance
+- 🔍 **Powerful search** - Find anything instantly
+- 📱 **Mobile-friendly** - Responsive design
+- 🎯 **Better organization** - Clear navigation
+- 💡 **Interactive examples** - Live code demos
+
+### For Maintainers  
+- 🔗 **Link validation** - Automatic broken link detection
+- 📝 **Easy content management** - Simple Markdown workflow
+- 🚀 **Automated deployment** - GitHub Actions integration
+- 📊 **Analytics** - Usage insights
+- 🔄 **Version control** - Git-based workflow
+
+## Migration Timeline
+
+### Week 1: Setup & Configuration
+- [ ] Initialize Docusaurus project
+- [ ] Configure for painlessMesh branding
+- [ ] Set up build pipeline
+
+### Week 2: Content Migration
+- [ ] Migrate existing documentation
+- [ ] Create missing pages
+- [ ] Fix all broken links
+- [ ] Integrate Doxygen output
+
+### Week 3: Enhancement & Testing
+- [ ] Add search functionality
+- [ ] Create interactive examples
+- [ ] Mobile testing
+- [ ] Performance optimization
+
+### Week 4: Deployment & Cleanup
+- [ ] Deploy to GitHub Pages
+- [ ] Update all repository links
+- [ ] Archive old documentation
+- [ ] Team training
+
+## Implementation Commands
+
+```bash
+# 1. Create Docusaurus site
+npx create-docusaurus@latest docs-website classic
+cd docs-website
+
+# 2. Install additional plugins
+npm install --save @docusaurus/plugin-client-redirects
+npm install --save @docusaurus/theme-mermaid
+npm install --save @docusaurus/plugin-google-analytics
+
+# 3. Configure build for GitHub Pages
+npm run build
+
+# 4. Deploy
+npm run deploy
+```
+
+## Cost-Benefit Analysis
+
+### Current Approach Costs
+- ❌ **Developer time** - Manual HTML maintenance
+- ❌ **User frustration** - Broken links, poor UX
+- ❌ **SEO penalty** - Poor search ranking
+- ❌ **Mobile users** - Bad mobile experience
+
+### Docusaurus Benefits
+- ✅ **Time savings** - Automated builds
+- ✅ **Better UX** - Professional documentation
+- ✅ **SEO boost** - Optimized for search engines
+- ✅ **Future-proof** - Modern, maintained framework
+
+## Recommendation
+
+**Immediate Action**: Implement Docusaurus 3 migration
+
+**Priority**: High - Current documentation has critical usability issues
+
+**Timeline**: 2-4 weeks for full migration
+
+**ROI**: High - Significantly better user experience with minimal ongoing maintenance

package/docs/README.md

@@ -0,0 +1,71 @@
+# painlessMesh Documentation
+
+Welcome to the comprehensive documentation for painlessMesh - a user-friendly ESP8266/ESP32 mesh networking library that automatically handles routing and network management.
+
+## Documentation Structure
+
+### Getting Started
+- [Quick Start Guide](getting-started/quickstart.md) - Get up and running in minutes
+- [Installation](getting-started/installation.md) - Detailed installation instructions
+- [First Mesh Network](getting-started/first-mesh.md) - Your first working mesh
+
+### Architecture & Design  
+- [Mesh Architecture](architecture/mesh-architecture.md) - How painlessMesh works internally
+- [Plugin System](architecture/plugin-system.md) - Understanding the plugin architecture
+- [Message Routing](architecture/routing.md) - Message routing algorithms and strategies
+- [Time Synchronization](architecture/time-sync.md) - Mesh-wide time synchronization
+
+### API Reference
+- [Core API](api/core-api.md) - Main painlessMesh class methods
+- [Plugin API](api/plugin-api.md) - Creating custom packages and plugins
+- [Configuration](api/configuration.md) - Configuration options and constants
+- [Callbacks](api/callbacks.md) - Event handling and callbacks
+
+### Tutorials & Examples
+- [Basic Examples](tutorials/basic-examples.md) - Simple mesh networking examples
+- [Custom Packages](tutorials/custom-packages.md) - Creating your own message types
+- [Sensor Networks](tutorials/sensor-networks.md) - Building IoT sensor networks
+- [Bridge Applications](tutorials/bridge-apps.md) - Connecting mesh to external networks
+
+### Alteriom Extensions
+- [Alteriom Overview](alteriom/overview.md) - Alteriom-specific functionality
+- [Sensor Packages](alteriom/sensor-packages.md) - Environmental sensor data handling
+- [Command System](alteriom/command-system.md) - Device command and control
+- [Status Monitoring](alteriom/status-monitoring.md) - Device health and diagnostics
+
+### Advanced Topics
+- [Performance Optimization](advanced/performance.md) - Optimizing mesh performance
+- [Memory Management](advanced/memory.md) - Managing ESP8266/ESP32 memory constraints
+- [Security Considerations](advanced/security.md) - Securing your mesh network
+- [OTA Updates](advanced/ota.md) - Over-the-air firmware updates in mesh
+
+### Troubleshooting
+- [Common Issues](troubleshooting/common-issues.md) - Solutions to frequent problems
+- [Debugging Guide](troubleshooting/debugging.md) - Tools and techniques for debugging
+- [FAQ](troubleshooting/faq.md) - Frequently asked questions
+- [Network Issues](troubleshooting/network-issues.md) - Connectivity and mesh topology problems
+
+### Development
+- [Contributing](development/contributing.md) - How to contribute to painlessMesh
+- [Building & Testing](development/building.md) - Development environment setup
+- [Documentation](development/documentation.md) - Contributing to documentation
+- [Release Process](development/releases.md) - Understanding releases and versioning
+
+## Quick Links
+
+- **[GitHub Repository](https://github.com/Alteriom/painlessMesh)**
+- **[API Documentation](http://painlessmesh.gitlab.io/painlessMesh/index.html)**
+- **[Community Forum](https://groups.google.com/forum/#!forum/painlessmesh-user)**
+- **[Issue Tracker](https://github.com/Alteriom/painlessMesh/issues)**
+
+## Need Help?
+
+- Start with the [Quick Start Guide](getting-started/quickstart.md)
+- Check the [FAQ](troubleshooting/faq.md) for common questions
+- Browse [Examples](tutorials/basic-examples.md) for practical use cases
+- Join our [Community Forum](https://groups.google.com/forum/#!forum/painlessmesh-user)
+- Report bugs on the [Issue Tracker](https://github.com/Alteriom/painlessMesh/issues)
+
+---
+
+This documentation is maintained by the painlessMesh community. Contributions are welcome! See our [Documentation Contributing Guide](development/documentation.md) to get started.