@alteriom/painlessmesh 1.8.14 → 1.9.0

package/docs/troubleshooting/ARDUINO_IDE_VERSION_FIX_SUMMARY.md

@@ -1,229 +0,0 @@
-# Arduino IDE Version Detection Issue - Resolution Summary
-
-## Issue Summary **[RESOLVED]**
-
-**Problem**: Arduino IDE does not detect the current library version (1.8.2), shows old version (1.6.1).
-
-**Root Cause**: The library name in `library.properties` was changed from `Alteriom PainlessMesh` (v1.6.1) to `AlteriomPainlessMesh` (v1.7.0+). Arduino Library Manager requires consistent library names and stopped indexing new releases when the name changed.
-
-**Impact**: Users could only see and install version 1.6.1 via Arduino IDE Library Manager.
-
-**Solution**: Reverted library name in `library.properties` back to original format with space: `Alteriom PainlessMesh`
-
-## Solution Overview
-
-This issue has been **RESOLVED**. The library name has been corrected and Arduino Library Manager will resume indexing new releases.
-
-### What Has Been Done ✅
-
-1. **Identified Root Cause**: Library name changed from `Alteriom PainlessMesh` to `AlteriomPainlessMesh`
-2. **Verified Registration**: Confirmed library is already in arduino/library-registry
-3. **Fixed Library Name**: Reverted `library.properties` to use original name with space
-4. **Verified Compliance**: All Arduino Library Manager requirements are met
-5. **Updated Documentation**: Comprehensive explanation and validation tools
-6. **No Manual Action Required**: Arduino will automatically index new releases
-
-## What Happens Next (Automatic)
-
-**Arduino Library Manager will automatically index the next release:**
-
-### Step-by-Step Submission Process
-
-1. **Open Browser** → https://github.com/arduino/library-registry
-2. **Click "Issues"** → "New Issue"
-3. **Copy Template** from `.github/ARDUINO_LIBRARY_REGISTRY_SUBMISSION.md`
-4. **Paste and Submit** the issue
-5. **Wait for Review** (1-2 weeks typical)
-6. **Verify Registration** in Arduino IDE
-
-### Quick Submission
-
-Use this command to view the submission template:
-
-```bash
-cat .github/ARDUINO_LIBRARY_REGISTRY_SUBMISSION.md
-```
-
-Then copy the entire content and create an issue at https://github.com/arduino/library-registry
-
-## What Happens After Submission
-
-### Immediate (Upon Approval)
-- ✅ Library appears in Arduino IDE Library Manager
-- ✅ Users can search for "AlteriomPainlessMesh"
-- ✅ One-click installation available
-- ✅ Version 1.8.2 (and all future releases) automatically indexed
-
-### Future Releases
-- **Automatic**: Arduino Library Manager checks for updates every 24-48 hours
-- **No Manual Work**: Just create GitHub releases with proper version tags
-- **Seamless Updates**: Users see "Update" button in Library Manager
-
-## Files Created
-
-### Documentation
-1. **`docs/ARDUINO_LIBRARY_MANAGER_SUBMISSION.md`** (10KB)
-   - Complete submission guide
-   - Pre-submission checklist
-   - Testing procedures
-   - Troubleshooting guide
-   - Post-registration maintenance
-
-2. **`.github/ARDUINO_LIBRARY_REGISTRY_SUBMISSION.md`** (5KB)
-   - Ready-to-use submission template
-   - Includes all library features
-   - Highlights compliance status
-   - Lists all dependencies
-
-### Tools
-3. **`scripts/validate-arduino-compliance.sh`**
-   - Automated compliance checker
-   - Validates all requirements
-   - Checks version consistency
-   - Verifies file structure
-   - **Current Status**: ✅ All checks passing
-
-### Updated Documentation
-4. **`RELEASE_GUIDE.md`**
-   - Added Arduino Library Manager section
-   - Prominent registration warning
-   - Detailed submission instructions
-
-5. **`README.md`**
-   - Updated installation section
-   - Added registration status
-   - Provided temporary workarounds
-
-## Current Workarounds for Users
-
-Until registration is complete, users can install the library via:
-
-### Option 1: PlatformIO (Recommended)
-```ini
-[env:esp32dev]
-lib_deps = alteriom/AlteriomPainlessMesh@^1.8.2
-```
-
-### Option 2: Manual ZIP Installation
-1. Download from https://github.com/Alteriom/painlessMesh/releases/latest
-2. Arduino IDE → Sketch → Include Library → Add .ZIP Library
-3. Select downloaded ZIP file
-
-### Option 3: Git Clone
-```bash
-cd ~/Arduino/libraries/
-git clone https://github.com/Alteriom/painlessMesh.git AlteriomPainlessMesh
-```
-
-### Option 4: NPM (for Node.js projects)
-```bash
-npm install @alteriom/painlessmesh
-```
-
-## Validation Results
-
-All Arduino Library Manager requirements verified:
-
-```
-✓ library.properties exists and is properly formatted
-✓ Version field set to 1.8.2
-✓ src/ directory with header files
-✓ examples/ directory with 29 examples
-✓ LICENSE file (LGPL-3.0)
-✓ README.md with comprehensive documentation
-✓ Git tags properly formatted (v1.8.2)
-✓ Version consistency across all files
-✓ Dependencies properly declared
-✓ keywords.txt present
-```
-
-Run validation: `./scripts/validate-arduino-compliance.sh`
-
-## Expected Timeline
-
-| Phase | Duration | Status |
-|-------|----------|--------|
-| Documentation & Validation | Complete | ✅ Done |
-| Submission Creation | 5 minutes | ⏳ Pending |
-| Arduino Team Review | 1-2 weeks | ⏳ Awaiting submission |
-| Indexing & Availability | 24-48 hours | ⏳ After approval |
-
-## Benefits of Registration
-
-### For Users
-- ✅ One-click installation via Arduino IDE
-- ✅ Automatic update notifications
-- ✅ Version selection in Library Manager
-- ✅ Integration with Arduino's ecosystem
-
-### For Maintainers
-- ✅ Wider user reach
-- ✅ Automatic version indexing
-- ✅ Reduced support burden
-- ✅ Professional credibility
-
-## Support Resources
-
-### Documentation Files
-- **Submission Guide**: `docs/ARDUINO_LIBRARY_MANAGER_SUBMISSION.md`
-- **Submission Template**: `.github/ARDUINO_LIBRARY_REGISTRY_SUBMISSION.md`
-- **Release Guide**: `RELEASE_GUIDE.md`
-- **Validation Script**: `scripts/validate-arduino-compliance.sh`
-
-### External Resources
-- **Arduino Library Registry**: https://github.com/arduino/library-registry
-- **Submission Guidelines**: https://support.arduino.cc/hc/en-us/articles/360012175419
-- **Library Specification**: https://arduino.github.io/arduino-cli/latest/library-specification/
-
-### Getting Help
-- **Issues**: https://github.com/Alteriom/painlessMesh/issues
-- **Discussions**: https://github.com/Alteriom/painlessMesh/discussions
-- **Arduino Forum**: https://forum.arduino.cc/c/using-arduino/libraries/67
-
-## Frequently Asked Questions
-
-### Q: Why isn't this automatic?
-**A**: Arduino Library Manager requires one-time manual submission to their registry repository. After approval, all future releases are automatically indexed.
-
-### Q: How long does approval take?
-**A**: Typically 1-2 weeks, but can vary depending on the Arduino team's review queue.
-
-### Q: Will this break existing users?
-**A**: No. Users already using PlatformIO, manual installation, or NPM will continue working. This only adds Arduino IDE support.
-
-### Q: What if the submission is rejected?
-**A**: Unlikely, as all requirements are met. If issues are found, the Arduino team will provide feedback to address them.
-
-### Q: Do we need to update library.properties?
-**A**: No. The current library.properties is compliant and ready for submission.
-
-## Next Steps Summary
-
-**For Repository Maintainer:**
-1. Review `.github/ARDUINO_LIBRARY_REGISTRY_SUBMISSION.md`
-2. Create issue at https://github.com/arduino/library-registry
-3. Monitor issue for Arduino team feedback
-4. Verify library appears in Arduino IDE after approval
-
-**For Users (Current):**
-- Use PlatformIO, manual ZIP, or git clone installation
-- All features and updates available via these methods
-- Arduino IDE support coming after registration
-
-**For Future:**
-- After registration, Arduino IDE installation works automatically
-- No additional work needed for future releases
-- Semantic version tags automatically indexed
-
----
-
-## Summary
-
-✅ **Problem Identified**: Library not in Arduino Library Manager registry  
-✅ **Solution Prepared**: Documentation and submission template ready  
-✅ **Requirements Met**: All compliance checks passing  
-✅ **Action Required**: One-time manual submission by maintainer  
-✅ **Workarounds Available**: PlatformIO, ZIP, git clone all functional  
-✅ **Future Automatic**: After registration, all releases auto-indexed  
-
-**Estimated Resolution**: 1-3 weeks after submission

package/docs/troubleshooting/ARDUINO_LIBRARY_NAME_FIX.md

@@ -1,197 +0,0 @@
-# Arduino Library Manager - Library Name Fix
-
-## Issue Resolution Summary
-
-**Date**: November 11, 2025  
-**Issue**: Arduino IDE showing version 1.6.1 instead of current version 1.8.2  
-**Status**: ✅ **RESOLVED**
-
-## Problem Analysis
-
-### Initial Diagnosis (Incorrect)
-Initially believed the library was not registered in Arduino Library Manager.
-
-### Actual Root Cause (Correct)
-The library IS registered, but the library name changed between releases:
-
-| Version | Library Name | Arduino Indexing |
-|---------|-------------|------------------|
-| v1.6.1 (Sept 2025) | `Alteriom PainlessMesh` | ✅ Indexed |
-| v1.7.0 - v1.8.2 | `AlteriomPainlessMesh` | ❌ Not indexed |
-
-**Arduino Library Manager Requirement**: Library names must remain consistent after registration.
-
-When the name changed from `Alteriom PainlessMesh` (with space) to `AlteriomPainlessMesh` (no space), the Arduino indexer stopped recognizing new releases as updates to the registered library.
-
-## Solution Applied
-
-### Change Made
-Restored the library name in `library.properties` to match the original registration:
-
-```diff
-- name=AlteriomPainlessMesh
-+ name=Alteriom PainlessMesh
-```
-
-### Verification
-```bash
-# v1.6.1 (last indexed version)
-name=Alteriom PainlessMesh
-
-# Current (fixed)
-name=Alteriom PainlessMesh
-
-# Result: ✓ Names match
-```
-
-## Impact & Timeline
-
-### Immediate
-- ✅ Library name corrected in repository
-- ✅ Validation script updated to detect this issue
-- ✅ Documentation updated with correct information
-
-### Next 24-48 Hours
-- Arduino Library Manager will detect next release (v1.8.3 or v1.9.0)
-- New version will appear in Arduino IDE Library Manager
-- Users will see update notification
-
-### Going Forward
-- All future releases will be automatically indexed
-- No manual intervention required
-- Library Manager will show latest versions within 24-48 hours of each GitHub release
-
-## Technical Details
-
-### Arduino Library Registry Status
-- **Registered**: ✅ Yes
-- **Repository URL**: https://github.com/Alteriom/painlessMesh
-- **Registry Entry**: https://github.com/arduino/library-registry (repositories.txt)
-- **Original Registration Name**: `Alteriom PainlessMesh`
-
-### How Arduino Library Manager Works
-1. Library is registered once in arduino/library-registry
-2. Arduino indexer checks registered repositories for new releases every 24-48 hours
-3. For each new release tag, indexer reads `library.properties`
-4. **Critical**: Library name in `library.properties` must match original registration
-5. If name matches, new version is added to index
-6. If name doesn't match, release is ignored
-
-### Why Name Changed
-Between v1.6.1 and v1.7.0, the library name was changed (likely to remove the space for URL compatibility). However, this broke Arduino Library Manager indexing.
-
-### Versions Affected
-**Not Indexed** (due to name mismatch):
-- v1.7.0, v1.7.1, v1.7.2, v1.7.3, v1.7.4, v1.7.5, v1.7.6, v1.7.7, v1.7.8, v1.7.9
-- v1.8.0, v1.8.1, v1.8.2
-
-**Will Be Indexed** (after fix):
-- v1.8.3+ (any future releases with corrected name)
-
-## What Users Will See
-
-### Before Fix
-```
-Arduino IDE Library Manager:
-┌─────────────────────────────────┐
-│ Alteriom PainlessMesh           │
-│ Version: 1.6.1                  │
-│ [Installed]                     │
-└─────────────────────────────────┘
-```
-
-### After Fix (24-48 hours after v1.8.3 release)
-```
-Arduino IDE Library Manager:
-┌─────────────────────────────────┐
-│ Alteriom PainlessMesh           │
-│ Version: 1.8.3 (Update available)│
-│ [Update]                        │
-└─────────────────────────────────┘
-```
-
-## Validation
-
-### Automated Check
-Run the validation script to confirm library name is correct:
-
-```bash
-./scripts/validate-arduino-compliance.sh
-```
-
-Expected output:
-```
-Checking library name format... ✓ CORRECT (name='Alteriom PainlessMesh')
-```
-
-### Manual Verification
-Compare current name with v1.6.1:
-
-```bash
-# Current
-grep "^name=" library.properties
-# Output: name=Alteriom PainlessMesh
-
-# v1.6.1 (last indexed)
-curl -s "https://raw.githubusercontent.com/Alteriom/painlessMesh/v1.6.1/library.properties" | grep "^name="
-# Output: name=Alteriom PainlessMesh
-
-# They should match ✓
-```
-
-## Lessons Learned
-
-### For Library Maintainers
-1. **Never change library name** after Arduino Library Manager registration
-2. Library name must remain exactly the same (including spaces, capitalization)
-3. Use validation scripts to catch name changes before release
-4. Check Arduino Library Manager indexing after each release
-
-### For This Repository
-1. Added library name validation to compliance script
-2. Documented the requirement clearly in release guide
-3. This issue is now prevented by automated checks
-
-## Related Files
-
-### Modified Files (Commit 5065fa5)
-- `library.properties` - Restored correct library name
-- `docs/ARDUINO_LIBRARY_MANAGER_SUBMISSION.md` - Updated with resolution
-- `README.md` - Fixed status and explanation
-- `RELEASE_GUIDE.md` - Corrected registration information
-- `ARDUINO_IDE_VERSION_FIX_SUMMARY.md` - Updated resolution details
-- `scripts/validate-arduino-compliance.sh` - Added name consistency check
-
-### Documentation
-- `docs/ARDUINO_LIBRARY_MANAGER_SUBMISSION.md` - Complete guide
-- `ARDUINO_IDE_VERSION_FIX_SUMMARY.md` - Issue summary
-- This file - Detailed resolution documentation
-
-## References
-
-### Arduino Documentation
-- [Arduino Library Manager FAQ](https://github.com/arduino/library-registry/blob/main/FAQ.md)
-- [Library Specification](https://arduino.github.io/arduino-cli/latest/library-specification/)
-- [Why libraries aren't updated](https://github.com/arduino/library-registry/issues/1002)
-
-### Repository Links
-- [Arduino Library Registry](https://github.com/arduino/library-registry)
-- [Library Registry repositories.txt](https://github.com/arduino/library-registry/blob/main/repositories.txt)
-- [This Repository](https://github.com/Alteriom/painlessMesh)
-
-## Credits
-
-**Issue Identified By**: @sparck75  
-**Resolution**: GitHub Copilot  
-**Date**: November 11, 2025  
-**Commit**: 5065fa5
-
----
-
-## Summary
-
-✅ **Issue**: Library name changed, breaking Arduino indexing  
-✅ **Fix**: Restored original name with space  
-✅ **Result**: Automatic indexing will resume with next release  
-✅ **Timeline**: 24-48 hours after v1.8.3+ release  
-✅ **Prevention**: Validation script now checks library name  

package/docs/troubleshooting/CRASH_QUICK_REF.md

@@ -1,93 +0,0 @@
-# 🚨 MESH CONNECTION CRASH - QUICK REFERENCE
-
-**Issue:** `assert failed: vTaskPriorityDisinheritAfterTimeout`  
-**When:** Sensor nodes connect to mesh  
-**Platform:** ESP32 only  
-**Cause:** painlessMesh library (NOT Build 8015)
-
----
-
-## ⚡ FASTEST FIX (5 min)
-
-**File:** `src/painlessmesh/mesh.hpp` **Line 544**
-
-```cpp
-// CHANGE THIS:
-return xSemaphoreTake(xSemaphore, (TickType_t)10) == pdTRUE;
-
-// TO THIS:
-return xSemaphoreTake(xSemaphore, (TickType_t)100) == pdTRUE;
-```
-
-**Then:** `pio run -t upload`
-
----
-
-## 🛡️ PRODUCTION FIX (10 min)
-
-**1. Create:** `src/painlessTaskOptions.h`
-```cpp
-#ifndef _PAINLESS_TASK_OPTIONS_H_
-#define _PAINLESS_TASK_OPTIONS_H_
-
-#ifdef ESP32
-#define _TASK_THREAD_SAFE
-#define _TASK_PRIORITY
-#endif
-
-#endif
-```
-
-**2. In your sketch BEFORE** `#include <painlessMesh.h>`:
-```cpp
-#include "painlessTaskOptions.h"
-```
-
-**3. Rebuild:** `pio run -t upload`
-
----
-
-## 📊 MONITORING CODE
-
-Add to `setup()`:
-```cpp
-mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
-
-mesh.onNewConnection([](uint32_t nodeId) {
-    Serial.printf("Node %u: Heap=%d Stack=%d\n", 
-                 nodeId, ESP.getFreeHeap(), 
-                 uxTaskGetStackHighWaterMark(NULL));
-});
-```
-
----
-
-## ✅ TEST CHECKLIST
-
-- [ ] Single node connects without crash
-- [ ] 5 nodes connect simultaneously
-- [ ] Rapid connect/disconnect cycles (10x)
-- [ ] 1+ hour sustained operation
-- [ ] Heap remains stable (check every 30 sec)
-
----
-
-## 📚 FULL DOCS
-
-- `docs/troubleshooting/SENSOR_NODE_CONNECTION_CRASH.md` - Action plan
-- `docs/troubleshooting/QUICK_FIX_FREERTOS.md` - Emergency fixes
-- `docs/troubleshooting/FREERTOS_ASSERTION_FAILURE.md` - Technical details
-
----
-
-## 🎯 KEY POINTS
-
-✅ **Apply fix BEFORE testing Build 8015**  
-✅ **This is separate from Phase 2 changes**  
-✅ **Known library issue - not your code**  
-✅ **Choose Option A for speed, Option B for production**
-
----
-
-**Last Updated:** 2025-10-19  
-**Status:** 🟡 Workaround available, library fix pending

package/docs/troubleshooting/ESP32_C6_COMPATIBILITY.md

@@ -1,157 +0,0 @@
-# ESP32-C6 Compatibility Guide
-
-## Overview
-
-ESP32-C6 is a newer ESP32 variant that requires updated dependencies to work correctly with painlessMesh. This guide addresses common issues and solutions for using painlessMesh on ESP32-C6.
-
-## Known Issue: TCP Allocation Crash
-
-### Symptom
-
-The device crashes on startup or during mesh initialization with the following error:
-
-```
-assert failed: tcp_alloc /IDF/components/lwip/lwip/src/core/tcp.c:1854 (Required to lock TCPIP core functionality!)
-```
-
-The device enters an endless reboot loop, preventing normal mesh operation.
-
-### Root Cause
-
-This issue is caused by incompatibility between:
-- ESP32-C6 hardware
-- Arduino ESP32 core v3.1.0 or later
-- Older versions of the AsyncTCP library
-
-The newer ESP32 Arduino core enforces stricter LWIP (Lightweight IP) thread safety requirements. Operations that modify TCP/IP data structures must now be protected with proper mutex locking. Older AsyncTCP versions (< v3.3.0) do not implement this locking, causing runtime assertions and crashes.
-
-### Solution
-
-#### Option 1: Update AsyncTCP Library (Recommended)
-
-Use the latest version of AsyncTCP that includes proper LWIP locking:
-
-**For PlatformIO:**
-
-Update your `platformio.ini`:
-
-```ini
-[env:esp32c6]
-platform = espressif32
-board = esp32-c6-devkitc-1  ; or your specific board
-framework = arduino
-
-lib_deps =
-    https://github.com/Alteriom/painlessMesh.git
-    esp32async/AsyncTCP @ ^3.4.7  ; Use latest version with LWIP locking
-    bblanchon/ArduinoJson @ ^7.4.2
-    arkhipenko/TaskScheduler @ ^4.0.0
-```
-
-**For Arduino IDE:**
-
-1. Remove any existing AsyncTCP library installation
-2. Download the latest AsyncTCP from: https://github.com/ESP32Async/AsyncTCP
-3. Install using "Sketch" → "Include Library" → "Add .ZIP Library"
-4. **Important:** Do not use the Arduino Library Manager for AsyncTCP, as it may install an outdated version
-
-#### Option 2: Downgrade Arduino Core (Temporary Workaround)
-
-If you need an immediate solution and cannot update AsyncTCP:
-
-1. In Arduino IDE: Tools → Board Manager → ESP32 by Espressif Systems
-2. Install version **3.0.7** instead of 3.1.0+
-3. This is not recommended long-term as you'll miss security updates and new features
-
-#### Option 3: Use Recommended Build Flags
-
-Add these configuration options to improve stability (PlatformIO):
-
-```ini
-build_flags =
-    -D CONFIG_ASYNC_TCP_MAX_ACK_TIME=5000
-    -D CONFIG_ASYNC_TCP_PRIORITY=10
-    -D CONFIG_ASYNC_TCP_QUEUE_SIZE=64
-    -D CONFIG_ASYNC_TCP_RUNNING_CORE=1
-    -D CONFIG_ASYNC_TCP_STACK_SIZE=4096
-```
-
-These flags help maintain proper task scheduling and LWIP event handling.
-
-## Verification
-
-After applying the fix, verify your setup:
-
-1. Upload a simple bridge example
-2. Monitor serial output for clean startup
-3. Check for successful mesh initialization without crashes
-4. Verify mesh connectivity with other nodes
-
-Example verification output:
-```
-setLogLevel: ERROR | STARTUP | CONNECTION |
-STARTUP: init(): 1
-STARTUP: stationManual() Starting WiFi connection
-STARTUP: Connection established
-STARTUP: IP address: 192.168.1.100
-```
-
-## Additional ESP32-C6 Considerations
-
-### Hardware-Specific Notes
-
-- ESP32-C6 uses RISC-V architecture (not Xtensa like older ESP32)
-- Built-in WiFi 6 (802.11ax) support - but mesh uses 802.11n
-- Lower power consumption compared to ESP32
-- Different GPIO pinout - verify your pin assignments
-
-### Memory Constraints
-
-ESP32-C6 typically has:
-- 320 KB SRAM
-- 4 MB Flash (typical configuration)
-
-This is adequate for painlessMesh, but be mindful of:
-- Maximum node count in mesh (recommend < 20 nodes)
-- Message queue sizes
-- JSON message complexity
-
-### Performance Optimization
-
-For best results on ESP32-C6:
-
-1. **WiFi Channel Selection**: Use channels 1, 6, or 11 for best performance
-2. **Mesh Size**: Keep mesh networks under 15-20 nodes
-3. **Message Frequency**: Avoid sending messages more than once per second per node
-4. **Power Management**: Consider WiFi power save modes for battery operation
-
-## Troubleshooting Checklist
-
-If you're still experiencing issues:
-
-- [ ] Confirmed AsyncTCP version is 3.3.0 or newer
-- [ ] Removed all old AsyncTCP library installations
-- [ ] Arduino ESP32 core is 3.0.7 or 3.1.0+ with updated AsyncTCP
-- [ ] Verified board definition matches your hardware
-- [ ] Checked serial monitor for actual error messages
-- [ ] Tested with minimal example (examples/basic/basic.ino)
-- [ ] Verified WiFi credentials are correct
-- [ ] Confirmed router and mesh use same WiFi channel (for bridge mode)
-
-## References
-
-- [AsyncTCP Library (ESP32Async)](https://github.com/ESP32Async/AsyncTCP)
-- [ESP32 Arduino Core Release Notes](https://github.com/espressif/arduino-esp32/releases)
-- [painlessMesh GitHub Issues](https://github.com/Alteriom/painlessMesh/issues)
-
-## Related Documentation
-
-- [Common Issues](common-issues.md)
-- [FAQ](faq.md)
-- [Bridge to Internet Guide](../../BRIDGE_TO_INTERNET.md)
-- [Debugging Guide](debugging.md)
-
----
-
-**Last Updated:** 2025-11-05  
-**Applies to:** painlessMesh v1.7.8+, ESP32-C6, Arduino ESP32 Core 3.0+