@alteriom/painlessmesh 1.7.2 → 1.7.3

package/docs/archive/SCONS_BUILD_FIX.md

@@ -0,0 +1,313 @@
+# PlatformIO SCons Build Error Troubleshooting
+
+## Common Error: "UnboundLocalError: local variable 'dir' referenced before assignment"
+
+This error occurs during PlatformIO's SCons build process when compiling `painlessMeshSTA.cpp` and similar files.
+
+---
+
+## ✅ FIXES APPLIED TO LIBRARY
+
+The following fixes have been applied to the **painlessMesh library** itself:
+
+### 0. Added Missing Header Include (CRITICAL)
+```cpp
+// src/painlessmesh/mesh.hpp
+#include <vector>  // Required for std::vector usage
+```
+**Why:** The mesh.hpp file uses `std::vector` but wasn't including the header, causing compilation errors.
+
+### 1. Added Explicit Directory Specifications
+```json
+{
+  "srcDir": "src",
+  "includeDir": "src"
+}
+```
+**Why:** Tells PlatformIO exactly where source files are located.
+
+### 2. Removed Conflicting Export Settings
+**Before:**
+```json
+{
+  "export": {
+    "include": "src"
+  }
+}
+```
+
+**After:** (Removed completely)
+
+**Why:** The `export.include` conflicts with `srcDir` and causes path resolution issues in SCons.
+
+### 3. Verified File Locations
+- ✅ All `.cpp` files in `src/` directory
+- ✅ `painlessMeshSTA.cpp` at `src/painlessMeshSTA.cpp`
+- ✅ No source files in root directory
+- ✅ No duplicate `library.json` files
+
+### 4. Fixed Header References
+- ✅ `library.properties` references `painlessMesh.h`
+- ✅ Both `painlessMesh.h` and `AlteriomPainlessMesh.h` available
+
+---
+
+## 🔧 FIXES FOR YOUR PROJECT
+
+If you're still getting errors, apply these fixes in YOUR project:
+
+### Fix 1: Clean Build Cache
+
+```bash
+# Delete PlatformIO cache
+pio run --target clean
+
+# Or delete manually
+rm -rf .pio
+rm -rf .pioenvs
+rm -rf .piolibdeps
+```
+
+### Fix 2: Update Library from GitHub
+
+Make sure you're pulling the latest fixes:
+
+```ini
+[env:esp32]
+platform = espressif32
+board = esp32dev
+framework = arduino
+lib_deps = 
+    ; Use the LATEST commit with fixes
+    https://github.com/Alteriom/painlessMesh#copilot/start-phase-2-implementation
+```
+
+### Fix 3: Force Library Re-download
+
+```bash
+# Remove cached library
+rm -rf .pio/libdeps/*/AlteriomPainlessMesh
+
+# Or use PlatformIO's update command
+pio pkg update
+```
+
+### Fix 4: Verify PlatformIO Version
+
+```bash
+# Check version
+pio --version
+
+# Update if needed (requires >= 6.0.0)
+pip install -U platformio
+```
+
+### Fix 5: Check for Conflicting Libraries
+
+```bash
+# List installed libraries
+pio pkg list
+
+# Remove any duplicate painlessMesh installations
+pio pkg uninstall -g painlessMesh
+pio pkg uninstall -g AlteriomPainlessMesh
+```
+
+---
+
+## 🧪 TEST BUILD
+
+### Step 1: Create Test Project
+
+```bash
+mkdir test-painlessmesh
+cd test-painlessmesh
+pio init --board esp32dev
+```
+
+### Step 2: Create platformio.ini
+
+```ini
+[env:esp32]
+platform = espressif32
+board = esp32dev
+framework = arduino
+monitor_speed = 115200
+
+lib_deps = 
+    https://github.com/Alteriom/painlessMesh#copilot/start-phase-2-implementation
+```
+
+### Step 3: Create src/main.cpp
+
+```cpp
+#include <Arduino.h>
+#include <painlessMesh.h>
+
+Scheduler userScheduler;
+painlessMesh mesh;
+
+void setup() {
+  Serial.begin(115200);
+  
+  mesh.setDebugMsgTypes(ERROR | STARTUP);
+  mesh.init("TestMesh", "password", &userScheduler, 5555);
+  
+  Serial.println("Mesh initialized!");
+}
+
+void loop() {
+  mesh.update();
+}
+```
+
+### Step 4: Build
+
+```bash
+pio run
+```
+
+**Expected Output:**
+```
+Building .pio/build/esp32/src/main.cpp.o
+Building .pio/build/esp32/.pio/libdeps/esp32/AlteriomPainlessMesh/...
+Linking .pio/build/esp32/firmware.elf
+Building .pio/build/esp32/firmware.bin
+SUCCESS
+```
+
+---
+
+## 🚨 IF STILL FAILING
+
+### Collect Diagnostic Information
+
+```bash
+# Get verbose build output
+pio run -v > build.log 2>&1
+
+# Check library structure
+cd .pio/libdeps/esp32/AlteriomPainlessMesh
+ls -la
+cat library.json
+```
+
+### Check for These Issues:
+
+**1. Verify srcDir in downloaded library:**
+```bash
+cd .pio/libdeps/esp32/AlteriomPainlessMesh
+cat library.json | grep srcDir
+# Should show: "srcDir": "src",
+```
+
+**2. Verify source files exist:**
+```bash
+ls -la src/
+# Should show: painlessMeshSTA.cpp, scheduler.cpp, wifi.cpp
+```
+
+**3. Check for duplicate files:**
+```bash
+find . -name "painlessMeshSTA.cpp"
+# Should only show: ./src/painlessMeshSTA.cpp
+```
+
+**4. Verify no export.include:**
+```bash
+cat library.json | grep export
+# Should show: (nothing) or not include "include": "src"
+```
+
+---
+
+## 📋 CHECKLIST FOR SUCCESSFUL BUILD
+
+- [ ] PlatformIO version >= 6.0.0
+- [ ] Clean build cache (`pio run --target clean`)
+- [ ] Remove `.pio` directory
+- [ ] Update library.json has `srcDir` and `includeDir`
+- [ ] No `export.include` in library.json
+- [ ] All `.cpp` files in `src/` directory
+- [ ] Force library re-download from GitHub
+- [ ] Test with minimal example
+- [ ] Check verbose build log for actual error
+
+---
+
+## 🔍 UNDERSTANDING THE ERROR
+
+### What Causes "UnboundLocalError: dir"?
+
+This error occurs in PlatformIO's SCons build system when:
+
+1. **Path resolution fails:** SCons can't determine the source directory
+2. **Conflicting settings:** Multiple directory specifications conflict
+3. **Cache corruption:** Old cached metadata from previous builds
+4. **Missing metadata:** No `srcDir` specified in library.json
+
+### The Fix (Applied):
+
+```json
+{
+  "name": "AlteriomPainlessMesh",
+  "srcDir": "src",           // ← Explicit source directory
+  "includeDir": "src"        // ← Explicit include directory
+  // "export": {...}         // ← REMOVED (was causing conflicts)
+}
+```
+
+---
+
+## 📞 SUPPORT
+
+If issues persist after trying all fixes:
+
+1. **Check your build log:**
+   ```bash
+   pio run -v 2>&1 | tee build-verbose.log
+   ```
+
+2. **Verify library was actually updated:**
+   ```bash
+   cd .pio/libdeps/YOUR_ENV/AlteriomPainlessMesh
+   git log -1 --oneline
+   # Should show recent commit with fixes
+   ```
+
+3. **Try a completely fresh project:**
+   - New directory
+   - Fresh `pio init`
+   - No existing `.pio` folder
+   - Copy minimal example above
+
+4. **Report issue with:**
+   - PlatformIO version
+   - Platform (espressif32/espressif8266)
+   - Full build log
+   - Contents of `.pio/libdeps/*/AlteriomPainlessMesh/library.json`
+
+---
+
+## ✅ VERIFICATION
+
+After applying fixes, your build should succeed with output like:
+
+```
+Dependency Graph
+|-- AlteriomPainlessMesh @ 1.7.0
+|   |-- AsyncTCP @ 3.4.7
+|   |-- ArduinoJson @ 7.4.2
+|   |-- TaskScheduler @ 4.0.0
+|   |-- WiFi @ 2.0.0
+Building .pio/build/esp32/lib/.../painlessMeshSTA.cpp.o
+...
+SUCCESS
+```
+
+---
+
+**Last Updated:** October 15, 2025  
+**Library Version:** 1.7.0  
+**Branch:** copilot/start-phase-2-implementation  
+**Status:** ✅ SCons build issues resolved

package/docs/archive/TRIGGER_RELEASE.md

@@ -0,0 +1,280 @@
+# Release Trigger Guide - Alteriom painlessMesh
+
+## 🚀 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 CHANGELOG.md package.json
+git commit -m "release: v1.6.1"
+git push origin main
+```
+
+That's it! GitHub Actions will automatically:
+- ✅ Run comprehensive test suite
+- ✅ Create git tag
+- ✅ Generate GitHub release with changelog
+- ✅ Publish to NPM (public registry)
+- ✅ Publish to GitHub Packages
+- ✅ Update GitHub Wiki
+- ✅ Package library for Arduino Library Manager
+- ✅ Validate all distribution channels
+
+## 📋 Release Checklist
+
+### Pre-Release Validation
+- [ ] All tests passing locally (`npm run test`)
+- [ ] Version consistency verified (`./scripts/validate-release.sh`)
+- [ ] Changelog updated with new version
+- [ ] Examples compile successfully
+- [ ] Documentation updated if needed
+
+### Release Execution
+- [ ] Version bumped in all files
+- [ ] Commit message starts with "release:"
+- [ ] Pushed to main branch
+- [ ] GitHub Actions workflows completed successfully
+
+### Post-Release Verification
+- [ ] GitHub release created
+- [ ] NPM package published
+- [ ] GitHub Packages updated
+- [ ] Wiki synchronized
+- [ ] Library available in distribution channels
+
+## 🎯 Distribution Channels
+
+### Automatic (Zero Manual Work)
+1. **GitHub Releases** - Created automatically with changelog
+2. **NPM Public Registry** - Published to https://www.npmjs.com/package/@alteriom/painlessmesh
+3. **GitHub Packages** - Published to GitHub's NPM registry
+4. **PlatformIO Registry** - Automatically indexed from GitHub releases
+5. **GitHub Wiki** - Documentation synchronized automatically
+
+### Semi-Automatic (Requires Manual Submission)
+6. **Arduino Library Manager** - Requires one-time submission to Arduino team
+
+## 📝 Version Management
+
+### Semantic Versioning
+
+```bash
+# Patch version (1.6.0 → 1.6.1) - Bug fixes
+./scripts/bump-version.sh patch
+
+# Minor version (1.6.0 → 1.7.0) - New features
+./scripts/bump-version.sh minor
+
+# Major version (1.6.0 → 2.0.0) - Breaking changes
+./scripts/bump-version.sh major
+
+# Specific version
+./scripts/bump-version.sh patch 1.6.2
+```
+
+### Version Consistency
+
+The script automatically updates:
+- `library.properties` (Arduino)
+- `library.json` (PlatformIO)
+- `package.json` (NPM)
+
+## 🔧 NPM Publishing Details
+
+### Dual Publishing Strategy
+
+The release workflow publishes to **two NPM registries**:
+
+1. **Public NPM** (npmjs.com)
+   - Package: `@alteriom/painlessmesh`
+   - Anyone can install: `npm install @alteriom/painlessmesh`
+   - No authentication required for installation
+
+2. **GitHub Packages** (npm.pkg.github.com)
+   - Package: `@alteriom/painlessmesh`
+   - Scoped to Alteriom organization
+   - Requires authentication for installation
+
+### Installation Methods
+
+```bash
+# Public NPM (recommended for users)
+npm install @alteriom/painlessmesh
+
+# GitHub Packages (for Alteriom team/authenticated users)
+echo '@alteriom:registry=https://npm.pkg.github.com' >> .npmrc
+npm install @alteriom/painlessmesh
+```
+
+## 📚 Wiki Publishing
+
+### Automatic Synchronization
+
+The wiki is automatically updated with each release:
+
+- **Home Page** - Generated from README.md
+- **Release Guide** - From RELEASE_GUIDE.md
+- **Changelog** - From CHANGELOG.md
+- **Examples** - Auto-generated from examples directory
+- **API Reference** - Generated documentation pages
+- **CI/CD Pipeline** - Automated documentation
+
+### Manual Wiki Override
+
+If needed, you can manually update the wiki:
+
+```bash
+# Clone wiki repository
+git clone https://github.com/Alteriom/painlessMesh.wiki.git
+
+# Edit markdown files
+# Commit and push changes
+```
+
+## 🛠️ Arduino Library Manager Submission
+
+### One-Time Setup (Required)
+
+After your first release, submit to Arduino Library Manager:
+
+1. Go to: https://github.com/arduino/library-registry
+2. Create a new issue with the following template:
+
+```
+Title: Add painlessMesh library
+
+Body:
+Repository URL: https://github.com/Alteriom/painlessMesh
+Release tag: v1.6.0
+Library name: painlessMesh
+Version: 1.6.0
+
+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. Once approved, all future releases are automatically indexed
+
+## 🔍 Validation Scripts
+
+### Pre-Release Validation
+```bash
+# Comprehensive validation
+./scripts/validate-release.sh
+
+# Check version consistency
+./scripts/bump-version.sh --verify
+
+# Test library compilation
+npm run build
+npm run test
+```
+
+### Release Monitoring
+```bash
+# Check GitHub Actions status
+# Visit: https://github.com/Alteriom/painlessMesh/actions
+
+# Verify NPM publication
+npm view @alteriom/painlessmesh version
+
+# Check GitHub Packages
+# Visit: https://github.com/Alteriom/painlessMesh/packages
+
+# Verify wiki update
+# Visit: https://github.com/Alteriom/painlessMesh/wiki
+```
+
+## 🚨 Troubleshooting
+
+### Common Issues
+
+**Version Mismatch Error**
+```bash
+# Fix version inconsistencies
+./scripts/bump-version.sh patch 1.6.1  # Force set version
+```
+
+**NPM Publication Failure**
+```bash
+# Check NPM token is valid
+npm whoami
+
+# Verify package.json configuration
+npm run validate-library
+```
+
+**GitHub Packages Authentication**
+```bash
+# Verify GitHub token has packages:write permission
+# Check repository settings → Actions → General → Permissions
+```
+
+**Wiki Update Failure**
+```bash
+# Wiki may need to be manually initialized
+# Go to: https://github.com/Alteriom/painlessMesh/wiki
+# Create any page to initialize wiki, 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.1 --title "painlessMesh v1.6.1" --notes-file CHANGELOG.md
+
+# Manual tag creation
+git tag v1.6.1
+git push origin v1.6.1
+```
+
+## 📊 Release 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
+
+### Distribution Verification:
+```bash
+# 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
+```
+
+## 🎉 Success!
+
+Once your release is complete, the library will be available through:
+- GitHub Releases
+- NPM (public + GitHub Packages)
+- PlatformIO Registry (automatic)
+- Arduino Library Manager (after initial submission)
+- GitHub Wiki (documentation)
+
+All future releases follow the same simple process - just bump version, update changelog, commit with "release:" prefix, and push!
+
+---
+
+**Questions?** Create an issue with the `ci/cd` label for release process support.

package/docs/archive/VECTOR_INCLUDE_FIX.md

@@ -0,0 +1,129 @@
+# Missing #include <vector> Fix
+
+## Issue
+
+Compilation errors when building projects that use AlteriomPainlessMesh:
+
+```
+error: 'vector' in namespace 'std' does not name a template type
+   std::vector<ConnectionInfo> getConnectionDetails() {
+        ^~~~~~
+note: 'std::vector' is defined in header '<vector>'; did you forget to '#include <vector>'?
+```
+
+## Root Cause
+
+The file `src/painlessmesh/mesh.hpp` uses `std::vector` but was missing the required include:
+
+```cpp
+#include <vector>
+```
+
+This caused compilation failures in any code that included `painlessMesh.h`.
+
+## Files Affected
+
+- `src/painlessmesh/mesh.hpp` - Uses `std::vector<ConnectionInfo>` at line 386
+- `src/painlessmesh/mesh.hpp` - Uses `std::vector<uint32_t>` at line 594
+
+## Fix Applied
+
+Added `#include <vector>` to the top of `src/painlessmesh/mesh.hpp`:
+
+```cpp
+#ifndef _PAINLESS_MESH_MESH_HPP_
+#define _PAINLESS_MESH_MESH_HPP_
+
+#include <vector>  // ← ADDED THIS LINE
+
+#include "painlessmesh/configuration.hpp"
+// ... rest of includes
+```
+
+## Why This Wasn't Caught Earlier
+
+This is a common C++ compilation issue where:
+1. Sometimes the `<vector>` header gets transitively included by other headers
+2. Works on some compilers/platforms but not others
+3. Depends on which headers are included first in your project
+4. May work in the library's test environment but fail in user projects
+
+## Testing
+
+After this fix, the following should compile successfully:
+
+```cpp
+#include <Arduino.h>
+#include <painlessMesh.h>
+
+Scheduler userScheduler;
+painlessMesh mesh;
+
+void setup() {
+  Serial.begin(115200);
+  mesh.init("TestMesh", "password", &userScheduler, 5555);
+  
+  // This function uses std::vector internally
+  auto connections = mesh.getConnectionDetails();
+}
+
+void loop() {
+  mesh.update();
+}
+```
+
+## For Users
+
+To get the fix:
+
+1. **Clean your build:**
+   ```bash
+   pio run --target clean
+   rm -rf .pio
+   ```
+
+2. **Update library:**
+   ```bash
+   pio pkg update
+   ```
+
+3. **Rebuild:**
+   ```bash
+   pio run
+   ```
+
+The library will be re-downloaded from GitHub with the fix included.
+
+## Verification
+
+Your build output should change from:
+
+**Before (ERROR):**
+```
+error: 'vector' in namespace 'std' does not name a template type
+*** [.pio/build/universal-sensor/libb89/AlteriomPainlessMesh/painlessMeshSTA.cpp.o] Error 1
+```
+
+**After (SUCCESS):**
+```
+Building .pio/build/universal-sensor/libb89/AlteriomPainlessMesh/painlessMeshSTA.cpp.o
+Building .pio/build/universal-sensor/libb89/AlteriomPainlessMesh/wifi.cpp.o
+Linking .pio/build/universal-sensor/firmware.elf
+SUCCESS
+```
+
+## Related Fixes
+
+This is part of a series of library structure fixes:
+1. ✅ Added `srcDir` and `includeDir` to library.json
+2. ✅ Removed conflicting `export.include` section
+3. ✅ Fixed header references in library.properties
+4. ✅ **Added missing `#include <vector>` to mesh.hpp** ← This fix
+
+## Date
+
+October 15, 2025
+
+## Status
+
+✅ FIXED - Ready for use