@alteriom/painlessmesh 1.8.15 → 1.9.0

package/docs/CHANNEL_SYNCHRONIZATION.md

@@ -1,209 +0,0 @@
-# Channel Synchronization in painlessMesh
-
-## Problem Statement
-
-When a mesh network operates on one channel and a node promotes to bridge via election, it may connect to a router operating on a different channel. This creates a channel mismatch where:
-
-1. Bridge node switches to router's channel (e.g., channel 6)
-2. Other mesh nodes remain on original channel (e.g., channel 1)
-3. Bridge takeover announcements sent on new channel are not heard by nodes on old channel
-4. Nodes cannot find the mesh network and become isolated
-
-## Solution Overview
-
-The solution has two complementary parts:
-
-### Part 1: Automatic Channel Re-detection
-
-Nodes automatically detect when they can't find the mesh on their current channel and trigger a full channel scan to locate it.
-
-**Implementation:** `src/painlessMeshSTA.cpp` and `src/painlessMeshSTA.h`
-
-**Key Components:**
-- `consecutiveEmptyScans` counter tracks scans with no mesh nodes found
-- `EMPTY_SCAN_THRESHOLD` constant (6 scans) determines when to trigger re-scan
-- Full channel scan using `scanForMeshChannel()` when threshold reached
-- Automatic channel update and AP restart when mesh found on different channel
-
-**Flow:**
-```
-1. Node scans on current channel (e.g., channel 1)
-2. Finds no mesh nodes → increment consecutiveEmptyScans
-3. Repeat for EMPTY_SCAN_THRESHOLD scans (~30 seconds with fast scanning)
-4. Trigger scanForMeshChannel() to scan ALL channels (1-13)
-5. If mesh found on different channel:
-   a. Update mesh->_meshChannel to detected channel
-   b. Restart AP on new channel
-   c. Reset consecutiveEmptyScans counter
-6. Continue normal scanning on new channel
-```
-
-**Safeguards:**
-- Only triggers when WiFi.status() != WL_CONNECTED (not when stably connected)
-- Only triggers when channel > 0 (channel 0 already means auto-detect)
-- Resets counter when mesh nodes are found (prevents false triggers)
-
-### Part 2: Dual-Channel Takeover Announcements
-
-Bridge promotion sends takeover announcements on both the old and new channels to ensure all nodes are notified.
-
-**Implementation:** `src/arduino/wifi.hpp` in `promoteToBridge()` method
-
-**Flow:**
-```
-1. Node wins bridge election
-2. Send takeover announcement on CURRENT channel (e.g., channel 1)
-   → Nodes still on channel 1 receive this announcement
-3. Wait 1 second for announcement to propagate
-4. Stop mesh and reinitialize as bridge via initAsBridge()
-   → Connects to router, detects router's channel (e.g., channel 6)
-   → Initializes mesh on channel 6
-5. Schedule follow-up takeover announcement on NEW channel (channel 6)
-   → Sent 3 seconds after initialization
-   → Nodes that switched to channel 6 receive this announcement
-```
-
-**Benefits:**
-- Early announcement notifies nodes on old channel before bridge switches
-- Delayed announcement notifies nodes that switched early or quickly found new channel
-- Ensures complete mesh awareness regardless of node timing
-
-## Expected Behavior
-
-### Scenario: Bridge Promotion with Channel Change
-
-**Setup:**
-- Node1: Regular mesh node on channel 1
-- Node2: Regular mesh node on channel 1 (weak router signal)
-- Router: Operating on channel 6
-
-**Sequence:**
-1. Node2 starts mesh on channel 1 (default, no router connection)
-2. Node1 joins mesh on channel 1
-3. Node1 wins bridge election (better router signal)
-4. Node1 sends "Becoming bridge" announcement on channel 1
-5. Node2 receives announcement
-6. Node1 connects to router on channel 6, initializes mesh on channel 6
-7. Node1 sends follow-up "I'm the bridge" announcement on channel 6
-8. Node2 can't find mesh on channel 1 for 6 consecutive scans
-9. Node2 triggers full channel scan, finds mesh on channel 6
-10. Node2 updates to channel 6, restarts AP on channel 6
-11. Node2 reconnects to Node1 on channel 6
-12. Mesh network is now unified on channel 6
-
-**Timeline:**
-- T+0s: Node1 wins election, sends announcement on channel 1
-- T+1s: Node1 stops mesh on channel 1
-- T+2s: Node1 initializes mesh on channel 6
-- T+5s: Node1 sends follow-up announcement on channel 6
-- T+30s: Node2 can't find mesh on channel 1 (fast scanning)
-- T+30s: Node2 triggers channel re-scan
-- T+31s: Node2 finds mesh on channel 6
-- T+32s: Node2 restarts AP on channel 6
-- T+35s: Node2 reconnects to mesh on channel 6
-
-## Configuration
-
-### Adjusting Re-scan Threshold
-
-The `EMPTY_SCAN_THRESHOLD` is defined in `src/painlessMeshSTA.h`:
-
-```cpp
-static const uint16_t EMPTY_SCAN_THRESHOLD = 6; // ~30 seconds at default SCAN_INTERVAL
-```
-
-**Trade-offs:**
-- **Lower value** (e.g., 3): Faster channel detection, but more susceptible to false triggers
-- **Higher value** (e.g., 10): More stable, but slower response to channel changes
-
-### Scan Timing
-
-Default scan intervals defined in `src/painlessmesh/configuration.hpp`:
-
-```cpp
-#define SCAN_INTERVAL 30 * TASK_SECOND  // AP scan period in ms
-```
-
-When no mesh nodes found, scanning switches to fast mode:
-```cpp
-task.setInterval(0.5 * SCAN_INTERVAL);  // 15 seconds
-```
-
-With EMPTY_SCAN_THRESHOLD=6 and fast scanning:
-- Time to trigger re-scan: 6 × 15s = 90 seconds (~1.5 minutes)
-
-## Debugging
-
-### Log Messages
-
-**Channel Re-detection:**
-```
-CONNECTION: connectToAP(): No mesh nodes found for 6 scans, triggering channel re-detection
-CONNECTION: scanForMeshChannel(): Scanning all channels for mesh 'YourMesh'...
-CONNECTION: scanForMeshChannel(): Found mesh on channel 6 (RSSI: -45)
-CONNECTION: connectToAP(): Mesh found on different channel 6 (was 1), updating...
-CONNECTION: connectToAP(): Restarting AP from channel 1 to channel 6
-CONNECTION: connectToAP(): AP restarted on channel 6
-```
-
-**Bridge Promotion:**
-```
-STARTUP: === Becoming Bridge Node ===
-STARTUP: Sending takeover announcement on current channel before switching...
-STARTUP: ✓ Takeover announcement sent on channel 1
-STARTUP: Step 1: Connecting to router YourRouter...
-STARTUP: ✓ Router connected on channel 6
-STARTUP: Step 2: Initializing mesh on channel 6...
-STARTUP: ✓ Bridge promotion complete on channel 6
-STARTUP: Sending follow-up takeover announcement on new channel 6
-STARTUP: ✓ Follow-up takeover announcement sent
-```
-
-### Common Issues
-
-**Issue:** Nodes don't switch channels
-- **Check:** Ensure `channel=0` in init() for auto-detection
-- **Check:** Verify nodes are not connected via stationManual() to router
-- **Check:** Increase log level to see scanning activity
-
-**Issue:** Channel switching takes too long
-- **Solution:** Reduce EMPTY_SCAN_THRESHOLD in painlessMeshSTA.h
-- **Trade-off:** May increase false triggers during temporary network instability
-
-**Issue:** Bridge promotion doesn't work
-- **Check:** Verify router credentials are configured
-- **Check:** Ensure router has good signal strength (> -80 dBm)
-- **Check:** Confirm router is on a valid channel (1-13 for 2.4GHz)
-
-## Testing
-
-### Manual Testing Procedure
-
-1. Setup two ESP32/ESP8266 nodes with painlessMesh
-2. Configure router on channel 6
-3. Start both nodes without router credentials (will use channel 1)
-4. Configure one node with router credentials and trigger election
-5. Monitor serial output for channel switching messages
-6. Verify both nodes eventually operate on channel 6
-7. Verify mesh connectivity is maintained
-
-### Expected Results
-
-- Bridge node switches to router channel within 5 seconds
-- Non-bridge nodes detect channel change within 90 seconds
-- All nodes reconnect on new channel
-- No loss of mesh connectivity (except during transition)
-
-## Related Files
-
-- `src/painlessMeshSTA.h` - StationScan class definition with channel re-detection
-- `src/painlessMeshSTA.cpp` - Channel re-detection implementation
-- `src/arduino/wifi.hpp` - Bridge promotion with dual announcements
-- `test/catch/catch_channel_resync.cpp` - Unit tests for channel synchronization
-- `BRIDGE_TO_INTERNET.md` - Bridge setup documentation
-
-## References
-
-- Issue #137: Bridge takeover announcements not heard across channels
-- WiFi channels: 1-13 for 2.4GHz (channels 12-13 restricted in some regions)
-- ESP32/ESP8266 can only operate on one channel at a time in AP+STA mode

package/docs/CREATE_MISSING_RELEASES.md

@@ -1,321 +0,0 @@
-# Creating Missing GitHub Releases for v1.7.8 and v1.7.9
-
-## Problem
-
-Versions 1.7.8 and 1.7.9 have:
-- ✅ CHANGELOG.md entries (complete release notes)
-- ✅ Release summary documentation (docs/releases/RELEASE_SUMMARY_v1.7.x.md)
-- ✅ Version numbers in library files (library.properties, library.json, package.json)
-- ❌ **Missing GitHub Releases** (no tags, no release pages)
-
-This means:
-- Users cannot download these specific versions from GitHub
-- Release automation may not have run properly
-- NPM/GitHub Packages may not have been published
-
-## Solution: Create GitHub Releases Retroactively
-
-### Option 1: Automated Script (Recommended)
-
-We've created a script to automate the process:
-
-```bash
-./scripts/create-missing-releases.sh
-```
-
-**What it does:**
-1. Extracts release notes from CHANGELOG.md
-2. Creates git tags (v1.7.8, v1.7.9)
-3. Pushes tags to GitHub
-4. Creates GitHub releases with proper release notes
-5. Provides links to verify releases
-
-**Requirements:**
-- GitHub CLI (`gh`) installed: https://cli.github.com/
-- Authenticated with GitHub: `gh auth login`
-- Write access to the repository
-
-**Running the script:**
-
-```bash
-# Navigate to repository root
-cd /path/to/painlessMesh
-
-# Run the script
-./scripts/create-missing-releases.sh
-
-# Follow the prompts
-# - Confirm you want to proceed
-# - If releases exist, choose whether to recreate them
-```
-
-### Option 2: Manual Process
-
-If you prefer to create releases manually or the script doesn't work:
-
-#### Step 1: Extract Release Notes
-
-```bash
-# Extract v1.7.8 notes
-awk '/^## \[1\.7\.8\]/ {flag=1; next} /^## \[/ {flag=0} flag' CHANGELOG.md > release_notes_1.7.8.txt
-
-# Extract v1.7.9 notes  
-awk '/^## \[1\.7\.9\]/ {flag=1; next} /^## \[/ {flag=0} flag' CHANGELOG.md > release_notes_1.7.9.txt
-```
-
-#### Step 2: Create Tags and Releases via GitHub CLI
-
-**For v1.7.8:**
-```bash
-# Create and push tag
-git tag -a v1.7.8 -m "painlessMesh v1.7.8"
-git push origin v1.7.8
-
-# Create GitHub release
-gh release create v1.7.8 \
-  --repo Alteriom/painlessMesh \
-  --title "painlessMesh v1.7.8" \
-  --notes-file release_notes_1.7.8.txt
-```
-
-**For v1.7.9:**
-```bash
-# Create and push tag
-git tag -a v1.7.9 -m "painlessMesh v1.7.9"
-git push origin v1.7.9
-
-# Create GitHub release
-gh release create v1.7.9 \
-  --repo Alteriom/painlessMesh \
-  --title "painlessMesh v1.7.9" \
-  --notes-file release_notes_1.7.9.txt
-```
-
-#### Step 3: Create Releases via GitHub Web UI
-
-If you don't have GitHub CLI:
-
-1. **Go to**: https://github.com/Alteriom/painlessMesh/releases/new
-2. **For v1.7.8**:
-   - Tag: `v1.7.8`
-   - Release title: `painlessMesh v1.7.8`
-   - Description: Copy content from `CHANGELOG.md` section `[1.7.8]`
-   - Click "Publish release"
-3. **For v1.7.9**:
-   - Tag: `v1.7.9`
-   - Release title: `painlessMesh v1.7.9`
-   - Description: Copy content from `CHANGELOG.md` section `[1.7.9]`
-   - Click "Publish release"
-
-## Verification
-
-After creating the releases, verify:
-
-### 1. Check GitHub Releases Page
-```bash
-# View releases via CLI
-gh release list --repo Alteriom/painlessMesh
-
-# Or visit in browser
-# https://github.com/Alteriom/painlessMesh/releases
-```
-
-**Expected output:**
-```
-v1.7.9  painlessMesh v1.7.9  Latest  2025-11-08
-v1.7.8  painlessMesh v1.7.8          2025-11-05
-```
-
-### 2. Check Tags
-```bash
-git fetch --tags
-git tag -l | grep -E "v1.7.[89]"
-```
-
-**Expected output:**
-```
-v1.7.8
-v1.7.9
-```
-
-### 3. Verify Release Notes
-Visit each release page and confirm:
-- ✅ Release notes match CHANGELOG.md content
-- ✅ Date is correct (v1.7.8: Nov 5, 2025; v1.7.9: Nov 8, 2025)
-- ✅ Release is marked as "Latest" for v1.7.9
-
-## Publishing Packages
-
-After creating the GitHub releases, you may want to publish packages to NPM and GitHub Packages.
-
-### Check if Already Published
-
-```bash
-# Check NPM
-npm view @alteriom/painlessmesh versions
-
-# Check if 1.7.8 and 1.7.9 are listed
-```
-
-### Publish if Missing
-
-If versions are not published:
-
-```bash
-# Option 1: Trigger manual publish workflow
-gh workflow run manual-publish.yml --repo Alteriom/painlessMesh
-
-# Option 2: Manual NPM publish (requires NPM token)
-npm publish --access public
-```
-
-## Why This Happened
-
-The releases were likely missed because:
-
-1. **Commits didn't trigger release workflow** - The release workflow triggers on:
-   - Commits to `main` branch
-   - Changes to version files OR commit message starting with `release:`
-   - If neither condition was met, no release was created
-
-2. **Version was bumped without triggering release** - The version files were updated but:
-   - Commit message didn't start with `release:`
-   - Or changes were pushed to a different branch first
-
-3. **Workflow may have failed** - Check GitHub Actions history for failed workflows
-
-## Preventing Future Issues
-
-### Ensure Releases Trigger Properly
-
-The release workflow (`.github/workflows/release.yml`) triggers when:
-
-1. **Automatic trigger** (recommended):
-   - Modify `library.properties`, `library.json`, or `package.json`
-   - Commit changes to `main` branch
-   - Workflow automatically detects version bump and creates release
-
-2. **Manual trigger**:
-   - Commit message starts with `release:`
-   - Example: `git commit -m "release: v1.8.0 - New features"`
-
-### Best Practices for Future Releases
-
-1. **Use the bump-version script:**
-   ```bash
-   ./scripts/bump-version.sh patch  # or minor, major
-   ```
-
-2. **Update CHANGELOG.md** with release notes
-
-3. **Use release agent to validate:**
-   ```bash
-   ./scripts/release-agent.sh
-   ```
-
-4. **Commit with proper message:**
-   ```bash
-   git add library.properties library.json package.json CHANGELOG.md
-   git commit -m "release: v1.8.0 - Brief description"
-   git push origin main
-   ```
-
-5. **Verify workflow runs:**
-   - Go to: https://github.com/Alteriom/painlessMesh/actions
-   - Watch the "Automated Release" workflow
-   - Confirm it completes successfully
-
-6. **Check release was created:**
-   ```bash
-   gh release list --repo Alteriom/painlessMesh
-   ```
-
-### Monitoring Release Success
-
-After pushing a release commit, verify:
-
-- ✅ GitHub Actions workflow runs successfully
-- ✅ Git tag is created and pushed
-- ✅ GitHub release is created with notes
-- ✅ NPM package is published
-- ✅ GitHub Packages is updated
-- ✅ Wiki is synchronized (if enabled)
-
-View the workflow run:
-```bash
-gh run list --workflow=release.yml --repo Alteriom/painlessMesh
-```
-
-## Troubleshooting
-
-### "Tag already exists" Error
-
-If tags exist but releases don't:
-```bash
-# Delete existing tags (careful!)
-git tag -d v1.7.8
-git push origin :refs/tags/v1.7.8
-
-# Then recreate using the script
-./scripts/create-missing-releases.sh
-```
-
-### "Permission denied" Error
-
-You need write access to the repository:
-- Verify you're authenticated: `gh auth status`
-- Check your permissions on the repository
-- Contact repository owner for access
-
-### Script Fails
-
-If the automated script fails:
-1. Check error messages
-2. Verify GitHub CLI is installed: `gh --version`
-3. Verify you're authenticated: `gh auth login`
-4. Try manual process (Option 2 above)
-
-### Release Notes Are Empty
-
-If release notes extraction fails:
-1. Verify CHANGELOG.md format matches expected pattern
-2. Check that version sections exist: `## [1.7.8]` and `## [1.7.9]`
-3. Manually copy content from CHANGELOG.md
-
-## Additional Resources
-
-- **Release Guide**: See `RELEASE_GUIDE.md` for complete release process
-- **GitHub Releases**: https://github.com/Alteriom/painlessMesh/releases
-- **GitHub CLI Docs**: https://cli.github.com/manual/
-- **Release Workflow**: `.github/workflows/release.yml`
-
-## Summary
-
-**To create missing releases:**
-
-```bash
-# Quick method (automated)
-./scripts/create-missing-releases.sh
-
-# Verify
-gh release list --repo Alteriom/painlessMesh
-
-# Publish packages if needed
-gh workflow run manual-publish.yml --repo Alteriom/painlessMesh
-```
-
-**To prevent future issues:**
-
-```bash
-# Always use this workflow for releases:
-./scripts/bump-version.sh patch
-# Update CHANGELOG.md
-./scripts/release-agent.sh  # Validate
-git add . && git commit -m "release: vX.Y.Z - Description"
-git push origin main
-# Watch GitHub Actions to confirm success
-```
-
----
-
-**Questions?** Open an issue with the `ci/cd` label.

package/docs/DOCUMENTATION_MIGRATION_PLAN.md

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