@alteriom/painlessmesh 1.8.2 → 1.8.3

package/docs/troubleshooting/ARDUINO_LIBRARY_NAME_FIX.md

@@ -0,0 +1,197 @@
+# 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/NPM_PUBLISHING_ISSUE_SUMMARY.md

@@ -0,0 +1,110 @@
+# NPM and GitHub Packages Publishing Issue - Summary
+
+## Issue Identified
+
+When PR#19 was merged to main with the commit message:
+```
+Release v1.7.7 - Complete mqtt-schema v0.7.2 implementation
+```
+
+The automated release workflow created the tag and GitHub release successfully, **but the NPM and GitHub Packages publishing jobs were skipped**.
+
+## Root Cause
+
+The automated workflow file `.github/workflows/release.yml` has a condition for NPM and GitHub Packages publishing:
+
+```yaml
+npm-publish:
+  needs: [tag-and-release]
+  runs-on: ubuntu-latest
+  if: startsWith(github.event.head_commit.message, 'release:')
+```
+
+**Problem**: The condition checks if the commit message starts with `release:` (lowercase with colon), but the merge commit was:
+-  Tag created: v1.7.7
+-  GitHub Release created
+-  NPM publish skipped (message started with "Release" not "release:")
+-  GitHub Packages publish skipped (same reason)
+
+## Solution Implemented
+
+### 1. Manual Publishing Workflow Created
+
+Created `.github/workflows/manual-publish.yml` with:
+- Manual trigger via GitHub Actions UI
+- Checkboxes to select which registries to publish to:
+  -  Publish to NPM Registry
+  -  Publish to GitHub Packages
+- Reads version from `library.properties` automatically
+- Validates authentication tokens
+- Provides clear success/failure feedback
+
+### 2. How to Use Manual Publishing
+
+**Via GitHub UI:**
+1. Go to https://github.com/Alteriom/painlessMesh/actions
+2. Select "Manual Package Publishing" workflow
+3. Click "Run workflow" button
+4. Select desired options (both checked by default)
+5. Click "Run workflow"
+
+**Via GitHub CLI:**
+```bash
+gh workflow run manual-publish.yml
+```
+
+### 3. Documentation Updated
+
+Updated `RELEASE_GUIDE.md` with:
+- Explanation of the commit message requirement
+- Troubleshooting section for this specific issue
+- Instructions for using the manual publishing workflow
+- Examples of correct vs incorrect commit messages
+
+## Immediate Action Required
+
+To publish v1.7.7 to NPM and GitHub Packages:
+
+1. Navigate to: https://github.com/Alteriom/painlessMesh/actions/workflows/manual-publish.yml
+2. Click "Run workflow"
+3. Ensure both checkboxes are selected:
+   -  Publish to NPM Registry
+   -  Publish to GitHub Packages
+4. Click "Run workflow"
+
+The workflow will:
+- Read version 1.7.7 from library.properties
+- Publish @alteriom/painlessmesh@1.7.7 to npmjs.org
+- Publish to GitHub Packages registry
+
+## Prevention for Future Releases
+
+To avoid this issue in future releases, ensure commit messages start with `release:` (lowercase with colon):
+
+** Correct:**
+```bash
+git commit -m "release: v1.7.8 - Next version description"
+```
+
+** Wrong:**
+```bash
+git commit -m "Release v1.7.8 - Next version description"
+```
+
+## Additional Notes
+
+- The tag v1.7.7 exists and is correct
+- GitHub Release exists and is correct
+- Only NPM/GitHub Packages publishing needs to be done manually this time
+- All other release channels (PlatformIO, Arduino Library Manager) are unaffected
+- This is a one-time manual fix; future releases will work automatically if commit message is correct
+
+## Files Changed
+
+1. `.github/workflows/manual-publish.yml` - New manual publishing workflow
+2. `RELEASE_GUIDE.md` - Updated documentation with troubleshooting
+
+---
+
+**Status**: Ready to manually publish v1.7.7 packages
+**Action**: Run manual-publish.yml workflow via GitHub Actions UI

package/docs/troubleshooting/station-reconnection-issues.md

@@ -0,0 +1,172 @@
+# Station Reconnection Issues in Bridge Mode
+
+## Problem Description
+
+When using `stationManual()` to create a bridge node that connects to a router while also maintaining a mesh network, users may experience issues where the station (router) connection drops during mesh initialization and fails to reconnect automatically.
+
+### Symptoms
+
+- Initial connection to router succeeds
+- Mesh network initializes successfully
+- Station connection drops with `ARDUINO_EVENT_WIFI_STA_DISCONNECTED` events
+- Station never reconnects despite reconnection logic being triggered
+- Serial output shows repeated disconnect events without successful reconnection
+
+### Example Serial Output
+
+```
+=== WiFi Connectivity Diagnostics ===
+Step 1: Connecting to router to detect channel...
+✓ Successfully connected to router!
+  Router Channel: 6 ← Auto-detected!
+  Router IP: 192.168.18.11
+
+Step 2: Initializing mesh on channel 6...
+STARTUP: init(): 1
+STARTUP: init(): Mesh channel set to 6
+STARTUP: AP tcp server established on port 5555
+STARTUP: stationManual(): Connecting to MyRouter
+STARTUP: stationManual(): Connection initiated
+✓ Mesh initialized
+
+Step 3: Waiting for station reconnection...
+CONNECTION: eventSTADisconnectedHandler: ARDUINO_EVENT_WIFI_STA_DISCONNECTED
+CONNECTION: eraseClosedConnections():
+CONNECTION: eventSTADisconnectedHandler: ARDUINO_EVENT_WIFI_STA_DISCONNECTED
+CONNECTION: eraseClosedConnections():
+⚠ Station not connected yet (may connect later)
+```
+
+## Root Cause
+
+The issue was in the `connectToAP()` method in `src/painlessMeshSTA.cpp`. When operating in manual mode (for router connections via `stationManual()`):
+
+1. Station disconnects during mesh initialization (normal behavior in AP+STA mode)
+2. Disconnect callback triggers `yieldConnectToAP()` to reconnect
+3. `connectToAP()` checks if router SSID is in the scan results
+4. Router SSID is NOT in scan results (scan only looks for mesh nodes on mesh channel)
+5. Function returns without calling `WiFi.begin()` to reconnect
+6. Station remains disconnected indefinitely
+
+### Code Analysis
+
+**Before Fix** (lines 192-195 in `painlessMeshSTA.cpp`):
+
+```cpp
+} else if (aps.empty() || !ssid.equals(aps.begin()->ssid)) {
+    task.enableDelayed(SCAN_INTERVAL);
+    return;  // ← Just delays, never attempts reconnection!
+}
+```
+
+The problem: This conditional assumes the router SSID will appear in the `aps` list from `stationScan()`. However, `stationScan()` only scans on the mesh channel for mesh nodes, not for routers which may be on the same or different channel.
+
+## Solution
+
+**After Fix** (v1.8.1+):
+
+```cpp
+} else {
+    // For manual router connections, reconnect directly using WiFi.begin()
+    // Don't rely on scan results since router may be on different channel
+    Log(CONNECTION, 
+        "connectToAP(): Manual connection - attempting to reconnect to %s\n",
+        ssid.c_str());
+    WiFi.begin(ssid.c_str(), password.c_str());
+    task.enableDelayed(SCAN_INTERVAL);
+    return;
+}
+```
+
+The fix:
+- Removes dependency on scan results for manual connections
+- Calls `WiFi.begin()` directly to reconnect to the router
+- Lets ESP hardware auto-detect the router's channel (as designed)
+- Adds clear logging to show reconnection attempts
+
+## Verification
+
+After applying the fix, the expected behavior is:
+
+```
+Step 3: Waiting for station reconnection...
+CONNECTION: eventSTADisconnectedHandler: ARDUINO_EVENT_WIFI_STA_DISCONNECTED
+CONNECTION: eraseClosedConnections():
+CONNECTION: connectToAP(): Manual connection - attempting to reconnect to MyRouter
+✓ Station reconnected successfully!
+  IP Address: 192.168.18.11
+```
+
+## Workaround (for older versions)
+
+If you're using a version before v1.8.1, you can work around this issue by implementing explicit reconnection logic:
+
+```cpp
+void setup() {
+  // ... mesh initialization ...
+  
+  // Add a task to monitor and reconnect station
+  userScheduler.addTask(Task(5000, TASK_FOREVER, [](){
+    if (WiFi.status() != WL_CONNECTED) {
+      Serial.println("Station disconnected, reconnecting...");
+      WiFi.begin(ROUTER_SSID, ROUTER_PASSWORD);
+    }
+  }));
+}
+```
+
+## Related Issues
+
+- Issue #21: Original user report from @woodlist
+- Issue #50: Bug tracking for stationManual() channel issues
+- Issue #59: Bridge-centric architecture proposal
+- PR #[number]: Fix implementation
+
+## Affected Versions
+
+- **Affected**: v1.5.0 - v1.8.0
+- **Fixed**: v1.8.1+
+
+## Platforms
+
+This issue affects all ESP platforms:
+- ESP32 (all variants including ESP32-C6, ESP32-S3)
+- ESP8266
+
+## Additional Notes
+
+### Why Does Station Disconnect During Mesh Init?
+
+When the ESP switches from pure STA mode to AP+STA mode during mesh initialization, the WiFi subsystem may briefly disconnect from the station to reconfigure. This is normal behavior and the library should automatically reconnect.
+
+### Channel Matching
+
+Remember that in AP+STA mode, both the AP (mesh) and STA (router connection) **must use the same WiFi channel**. This is a hardware limitation. The fix ensures reconnection works regardless of channel, but both interfaces will still operate on the same channel.
+
+### Best Practice
+
+For production bridge nodes, consider using the "Station First" pattern to auto-detect the router's channel before initializing the mesh:
+
+```cpp
+void setup() {
+  // Step 1: Connect to router first to detect its channel
+  WiFi.mode(WIFI_STA);
+  WiFi.begin(ROUTER_SSID, ROUTER_PASSWORD);
+  while (WiFi.status() != WL_CONNECTED) {
+    delay(500);
+  }
+  
+  uint8_t detectedChannel = WiFi.channel();
+  Serial.printf("Router channel: %d\n", detectedChannel);
+  
+  WiFi.disconnect();
+  delay(1000);
+  
+  // Step 2: Initialize mesh on the detected channel
+  mesh.init(MESH_SSID, MESH_PASSWORD, &userScheduler, MESH_PORT, 
+            WIFI_AP_STA, detectedChannel);
+  mesh.stationManual(ROUTER_SSID, ROUTER_PASSWORD);
+}
+```
+
+This approach guarantees channel compatibility and more reliable connections.