@alteriom/painlessmesh 1.7.8 → 1.7.9

package/CHANGELOG.md

@@ -19,7 +19,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - TBD
 
-## [1.7.8] - 2025-11-04
+## [1.7.9] - 2025-11-08
+
+### Fixed
+
+- **CI/CD Pipeline** - Fixed submodule initialization failures and PlatformIO test configuration in GitHub Actions workflows
+  - Added explicit `submodules: recursive` to checkout action in CI workflow
+  - Added manual `git submodule update --init --recursive` step for robustness
+  - Ensures test dependencies (ArduinoJson and TaskScheduler) are properly initialized
+  - Fixes build failures where submodules were not available during CI runs
+  - Removed redundant matrix strategy from PlatformIO build test (script builds both platforms anyway)
+  - Changed PlatformIO tests from random to deterministic (tests critical examples: basic, alteriomSensorNode, alteriomMetricsHealth)
+  - Improved concurrency grouping to properly handle PR branch names and prevent premature cancellations
+  - Affects all workflows: ci.yml, release.yml, docs.yml
+
+- **Workflow Triggers** - Fixed duplicate CI runs and cancellation issues on PR branches
+  - Removed unnecessary `copilot/**` pattern from validate-release workflow branches filter
+  - Added explicit branch check in validate-release job condition to only run on main/develop
+  - Prevents validate-release workflow from running on PR branches
+  - Fixed concurrency grouping to use `github.head_ref` for PRs (branch name) instead of `github.ref` (commit SHA)
+  - Ensures proper workflow cancellation behavior and prevents confusion from cancelled runs
+
+- **Example Code** - Fixed compilation errors in alteriomMetricsHealth example
+  - Removed incorrect `userScheduler.size()` call (TaskScheduler API doesn't expose queue size)
+  - Replaced non-existent `toJsonString()` methods with proper JSON serialization pattern
+  - Updated deprecated `DynamicJsonDocument` to `JsonDocument` for ArduinoJson v7 compatibility
+  - Changed `msgType` from `uint8_t` to `uint16_t` to support message types > 255 (400, 604, 605)
+
+### Technical Details
+
+- GitHub Actions now properly initializes git submodules before build steps
+- Both automated checkout with `submodules: recursive` and manual initialization step included
+- Prevents "No such file or directory" errors for test/ArduinoJson and test/TaskScheduler
+- Critical fix for maintaining CI/CD reliability across all build and test workflows
+- Example code now uses proper serialization: `JsonDocument doc; JsonObject obj = doc.to<JsonObject>(); package.addTo(std::move(obj)); serializeJson(doc, msg);`
+
+## [1.7.8] - 2025-11-05
+
+### Added
+
+- **MQTT Schema v0.7.3 Compliance** - Upgraded from v0.7.2 to v0.7.3
+  - Added `message_type` field to SensorPackage (Type 200)
+  - Added `message_type` field to StatusPackage (Type 202)
+  - Added `message_type` field to CommandPackage (Type 400)
+  - All packages now have `message_type` for 90% faster message classification
+  - Full alignment with @alteriom/mqtt-schema v0.7.3 specification
 
 ### Added
 

package/README.md

@@ -134,7 +134,7 @@ The MQTT bridge enables bidirectional communication between MQTT brokers and mes
 **Examples:**
 
 - 🌉 [MQTT Command Bridge](examples/mqttCommandBridge/mqttCommandBridge.ino) - Gateway bridge with bidirectional MQTT-mesh routing
-- 📡 [Mesh Command Node](examples/alteriom/mesh_command_node.ino) - Node that receives and handles MQTT commands
+- 📡 [Alteriom Sensor Node](examples/alteriom/alteriom.ino) - Example node using SensorPackage, CommandPackage, and StatusPackage
 
 ### 🌐 Core Features
 
@@ -187,10 +187,12 @@ painlessMesh makes use of the following libraries, which can be installed throug
 - [ArduinoJson](https://github.com/bblanchon/ArduinoJson)
 - [TaskScheduler](https://github.com/arkhipenko/TaskScheduler)
 - [ESPAsyncTCP](https://github.com/me-no-dev/ESPAsyncTCP) (ESP8266)
-- [AsyncTCP](https://github.com/me-no-dev/AsyncTCP) (ESP32)
+- [AsyncTCP](https://github.com/ESP32Async/AsyncTCP) (ESP32) - v3.3.0+ required for ESP32-C6
 
 If platformio is used to install the library, then the dependencies will be installed automatically.
 
+> **⚠️ ESP32-C6 Users:** If you experience crashes with `tcp_alloc` errors, you need AsyncTCP v3.3.0+ with LWIP locking support. Use the [ESP32Async/AsyncTCP](https://github.com/ESP32Async/AsyncTCP) library or see the [ESP32-C6 Compatibility Guide](docs/troubleshooting/ESP32_C6_COMPATIBILITY.md) for details.
+
 ## Quick Start with Alteriom Packages
 
 ### Basic Sensor Node
@@ -280,7 +282,7 @@ void receivedCallback(uint32_t from, String& msg) {
 - **Home Automation** - Distributed lighting, HVAC control
 - **Industrial Monitoring** - Equipment status, predictive maintenance  
 - **Event Coordination** - Synchronized displays, distributed processing
-- **Bridge Networks** - Connect mesh to WiFi/Internet/MQTT
+- **Bridge Networks** - Connect mesh to WiFi/Internet/MQTT - [📖 Bridge Guide](BRIDGE_TO_INTERNET.md)
 
 ## Development Version: v1.7.8
 
@@ -412,6 +414,7 @@ You can tip me using ko-fi:
 | Topic | Description | Link |
 |-------|-------------|------|
 | **🌳 Architecture** | How painlessMesh works internally | [📖 Architecture](https://alteriom.github.io/painlessMesh/#/architecture/mesh-architecture) |
+| **🌉 Bridge to Internet** | Connect mesh to WiFi/Internet/MQTT | [📖 Bridge Guide](BRIDGE_TO_INTERNET.md) |
 | **🔌 Plugin System** | Create custom message packages | [📖 Plugins](https://alteriom.github.io/painlessMesh/#/architecture/plugin-system) |
 | **🎓 Tutorials** | Step-by-step examples and patterns | [📖 Tutorials](https://alteriom.github.io/painlessMesh/#/tutorials/basic-examples) |
 | **🛠️ Troubleshooting** | Common issues and solutions | [📖 Help](https://alteriom.github.io/painlessMesh/#/troubleshooting/common-issues) |

package/RELEASE_GUIDE.md

@@ -13,9 +13,12 @@ This document provides comprehensive instructions for releasing new versions of
 # 2. Update CHANGELOG.md with your changes
 # Add your changes under the new version section
 
-# 3. Commit and trigger release
+# 3. Run the Release Agent to validate readiness
+./scripts/release-agent.sh
+
+# 4. If all checks pass, commit and trigger release
 git add library.properties library.json package.json CHANGELOG.md
-git commit -m "release: v1.6.1"
+git commit -m "release: v1.7.9 - Brief description"
 git push origin main
 ```
 
@@ -76,7 +79,7 @@ version=1.6.1
 
 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:`
+2. Have version files modified OR commit message starting with `release:`
 
 ### What Gets Automated
 
@@ -277,6 +280,43 @@ Note: Manual changes may be overwritten by automatic synchronization.
 
 ## 🔧 Scripts Reference
 
+### `./scripts/release-agent.sh` ⭐ NEW
+
+**Comprehensive release validation and quality assurance.**
+
+The Release Agent performs 21+ automated checks to ensure release readiness:
+
+- ✅ Version consistency across all package files
+- ✅ CHANGELOG completeness and format validation
+- ✅ Build system configuration
+- ✅ Dependency validation
+- ✅ Git tag existence check
+- ✅ Release workflow configuration
+- ✅ Documentation link validation
+- ✅ Test suite status (when available)
+
+**Usage:**
+```bash
+./scripts/release-agent.sh           # Full validation
+./scripts/release-agent.sh --help    # Show help
+./scripts/release-agent.sh --version # Show version
+```
+
+**Benefits:**
+- 🎯 Catches issues before they reach CI/CD
+- 📊 Clear, color-coded output for easy scanning
+- 🔧 Specific solutions for each type of issue
+- 🚀 Comprehensive validation in under 5 seconds
+- ✨ Professional release summary with next steps
+
+**When to Use:**
+- Before every release commit
+- After making version changes
+- When troubleshooting release issues
+- As part of your local release workflow
+
+**See Also:** `.github/agents/release-agent.md` for complete documentation
+
 ### `./scripts/bump-version.sh`
 Updates version in all library files with consistency checks.
 
@@ -346,17 +386,26 @@ npm whoami
 
 **NPM/GitHub Packages Not Published Automatically**
 
-If the automated release ran but NPM and GitHub Packages weren't published, it's likely due to the commit message not matching the required pattern.
+The automated workflow triggers a release in two ways:
+
+1. **Automatic (Recommended)**: When version files are updated in a commit
+   - The workflow detects changes to `library.properties`, `library.json`, or `package.json`
+   - Automatically creates tag, release, and publishes packages when these files are modified
+   - Works seamlessly with PR merges and direct commits
+
+2. **Manual trigger**: Commit message starts with `release:` (lowercase with colon):
 
-The automated workflow requires the commit message to start with `release:` (lowercase with colon):
 ```bash
-# ✅ Correct - Will trigger NPM/GitHub Packages publishing
+# ✅ Correct - Will trigger full release
 git commit -m "release: v1.7.7 - Complete mqtt-schema implementation"
 
-# ❌ Wrong - Will create tag/release but skip NPM publishing  
-git commit -m "Release v1.7.7 - Complete mqtt-schema implementation"
+# ✅ Also works - Version file changes detected automatically
+# (No special commit message needed when library.properties/json/package.json are modified)
+git commit -m "Bump version to 1.7.8"
 ```
 
+**Note**: If version files weren't modified and commit message doesn't start with "release:", the workflow will skip publishing.
+
 **Solution: Use Manual Publishing Workflow**
 
 If this happens, you can manually publish packages:

package/docs/README.md

@@ -36,7 +36,7 @@ Welcome to the comprehensive documentation for the Alteriom fork of painlessMesh
 - [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
+- [Bridge to Internet](../BRIDGE_TO_INTERNET.md) - Connecting mesh to WiFi/Internet/MQTT
 
 ### Alteriom Extensions
 
@@ -63,6 +63,7 @@ Welcome to the comprehensive documentation for the Alteriom fork of painlessMesh
 ### Troubleshooting
 
 - [Common Issues](troubleshooting/common-issues.md) - Solutions to frequent problems
+- [ESP32-C6 Compatibility](troubleshooting/ESP32_C6_COMPATIBILITY.md) - ESP32-C6 specific issues and solutions
 - [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

package/docs/RELEASE_AGENT_SUMMARY.md

@@ -0,0 +1,386 @@
+# Release Agent Implementation Summary
+
+## Overview
+
+This document summarizes the implementation of the Release Agent system for AlteriomPainlessMesh, completed as part of preparing for release 1.7.9.
+
+**Date:** November 8, 2025  
+**Release:** v1.7.9  
+**Agent Version:** v1.0
+
+## Problem Statement
+
+The project needed to:
+1. Verify that all documentation is up to date for release 1.7.9
+2. Verify that all requirements for auto-release are done
+3. Create a release agent that would ensure consistency in all future releases
+
+## Solution
+
+A comprehensive Release Agent system was created to automate release validation and ensure consistency across all future releases.
+
+## Implementation Details
+
+### 1. Release Agent Specification (`.github/agents/release-agent.md`)
+
+A detailed specification document that defines:
+
+- **Pre-Release Validation**: 10 categories of checks
+  - Version Consistency
+  - Documentation Validation
+  - Code Quality Checks
+  - Dependency Validation
+  - Example Code Validation
+  - Release Workflow Validation
+
+- **Release Process**: 4 phases
+  - Preparation Phase
+  - Commit Phase
+  - Automation Phase
+  - Verification Phase
+
+- **Post-Release Tasks**: 4 categories
+  - Update Documentation
+  - Prepare for Next Development Cycle
+  - Communication
+  - Monitoring
+
+- **Agent Decision Tree**: Clear flowchart for validation
+- **Configuration**: Required secrets and permissions
+- **Release Checklist**: Comprehensive checklist for every release
+- **Error Recovery**: Solutions for common issues
+
+**Size:** 327 lines  
+**Coverage:** Complete release lifecycle
+
+### 2. Release Agent Script (`scripts/release-agent.sh`)
+
+An executable bash script that implements the specification:
+
+**Features:**
+- 21+ automated validation checks
+- Color-coded visual output (Green/Red/Yellow/Blue)
+- Clear pass/fail/warning indicators
+- Specific error recovery guidance
+- CI/CD environment detection
+- Professional release summary
+
+**Validation Checks:**
+1. Version Consistency Check
+2. Version Format Validation
+3. Git Tag Validation
+4. CHANGELOG Validation
+5. Build System Validation
+6. Dependency Validation
+7. Git Working Tree Status
+8. Test Suite Validation
+9. Release Workflow Configuration
+10. Documentation Validation
+
+**Usage:**
+```bash
+./scripts/release-agent.sh           # Full validation
+./scripts/release-agent.sh --help    # Show help
+./scripts/release-agent.sh --version # Show version
+```
+
+**Size:** 416 lines  
+**Performance:** < 5 seconds for complete validation
+
+### 3. Release Agent Documentation (`.github/agents/README.md`)
+
+Comprehensive documentation for the agent system:
+
+- What are Release Agents?
+- Available Agents overview
+- Quick Start guide
+- Usage instructions (developers, CI/CD)
+- Understanding output
+- Integration with existing tools
+- Release workflow diagram
+- Extending the agent
+- Best practices
+- Troubleshooting guide
+- Version history
+
+**Size:** 269 lines  
+**Audience:** Developers and maintainers
+
+### 4. Documentation Updates
+
+**README.md:**
+- Fixed broken link: `mesh_command_node.ino` → `alteriom.ino`
+- All internal documentation links validated
+
+**RELEASE_GUIDE.md:**
+- Added release agent to Quick Release Process
+- Added comprehensive Scripts Reference section for release agent
+- Updated workflow to include validation step
+- Highlighted benefits and use cases
+
+## Validation Results
+
+### Release 1.7.9 Readiness
+
+Running `./scripts/release-agent.sh`:
+
+```
+╔════════════════════════════════════════════════════════════╗
+║                    RELEASE READINESS                       ║
+╠════════════════════════════════════════════════════════════╣
+║ Version:        1.7.9
+║ Checks Passed:  22
+║ Checks Failed:  0
+║ Warnings:       0
+╠════════════════════════════════════════════════════════════╣
+║ ✓ READY FOR RELEASE
+╚════════════════════════════════════════════════════════════╝
+```
+
+**Status:** ✅ Repository is ready for release 1.7.9
+
+### Auto-Release Requirements Verified
+
+All automated release requirements confirmed:
+
+✅ **GitHub Actions Workflows**
+- `release.yml` - Properly configured with all permissions
+- `validate-release.yml` - Pre-release validation workflow
+- `manual-publish.yml` - Manual fallback publishing
+- `platformio-publish.yml` - PlatformIO automation
+- `wiki-sync.yml` - Documentation synchronization
+
+✅ **Release Automation Steps**
+- Git tag creation
+- GitHub release creation
+- NPM publishing (public registry)
+- GitHub Packages publishing
+- PlatformIO Registry publishing
+- GitHub Wiki synchronization
+- Arduino Library Manager package preparation
+
+✅ **Required Permissions**
+- `contents: write` - Tag and release creation
+- `packages: write` - GitHub Packages publishing
+- `id-token: write` - NPM publishing
+- `actions: read` - Workflow status monitoring
+
+✅ **Documentation**
+- CHANGELOG.md complete with v1.7.9 entry
+- README.md up to date, no broken links
+- RELEASE_GUIDE.md comprehensive and current
+- All version numbers consistent (1.7.9)
+
+✅ **Code Quality**
+- All 21 test suites passing
+- Build system configured correctly
+- Dependencies properly declared
+- Examples validated
+
+## Benefits
+
+### For Developers
+
+1. **Confidence**: Know exactly if a release is ready
+2. **Speed**: Comprehensive validation in < 5 seconds
+3. **Clarity**: Clear, color-coded output
+4. **Guidance**: Specific solutions for every issue
+5. **Learning**: Understand release requirements
+
+### For Maintainers
+
+1. **Consistency**: Every release follows same standards
+2. **Quality**: 21+ automated checks catch issues early
+3. **Documentation**: Complete specification and guides
+4. **Automation**: Integrates with existing CI/CD
+5. **Extensibility**: Easy to add new checks
+
+### For the Project
+
+1. **Reliability**: Reduces human error in releases
+2. **Professionalism**: High-quality, consistent releases
+3. **Efficiency**: Saves time on manual validation
+4. **Knowledge Transfer**: Codifies institutional knowledge
+5. **Future-Proofing**: Easy to update as requirements change
+
+## Usage Example
+
+### Before Release
+
+```bash
+# 1. Update version
+./scripts/bump-version.sh patch
+
+# 2. Update CHANGELOG.md
+vim CHANGELOG.md
+
+# 3. Validate with release agent
+./scripts/release-agent.sh
+# Output shows 22 passed, 0 failed, 0 warnings
+
+# 4. Commit and release
+git add .
+git commit -m "release: v1.7.9 - CI/CD improvements"
+git push origin main
+```
+
+### Continuous Use
+
+The release agent is now integrated into the standard workflow:
+
+1. **Local Development**: Run before creating release PR
+2. **CI/CD Pipeline**: Automated validation on every push
+3. **Release Process**: Final check before tagging
+4. **Troubleshooting**: Quick diagnosis of release issues
+
+## Technical Implementation
+
+### Architecture
+
+```
+Release Agent System
+├── Specification (.github/agents/release-agent.md)
+│   └── Defines: What to check, how to check, error recovery
+├── Implementation (scripts/release-agent.sh)
+│   └── Executes: Automated checks, output formatting, summary
+├── Documentation (.github/agents/README.md)
+│   └── Guides: Usage, integration, best practices
+└── Integration (RELEASE_GUIDE.md, CI workflows)
+    └── Connects: Existing tools, workflows, processes
+```
+
+### Design Principles
+
+1. **Fail Fast**: Catch issues as early as possible
+2. **Clear Feedback**: Use colors and formatting for easy scanning
+3. **Actionable**: Every error includes specific solution
+4. **Non-Blocking**: Warnings inform but don't block
+5. **Comprehensive**: Cover all aspects of release
+6. **Maintainable**: Well-documented, easy to extend
+7. **Portable**: Works locally and in CI/CD
+
+### Technologies
+
+- **Bash**: Script implementation for portability
+- **Git**: Version control and tag validation
+- **jq**: JSON parsing for package files
+- **CMake/Ninja**: Build system validation
+- **GitHub Actions**: CI/CD integration
+- **Markdown**: Documentation format
+
+## Metrics
+
+### Code Additions
+
+- **Total Lines Added**: 1,055 lines
+- **New Files**: 3 files
+- **Modified Files**: 2 files
+
+**Breakdown:**
+- `.github/agents/release-agent.md`: 327 lines (specification)
+- `.github/agents/README.md`: 269 lines (documentation)
+- `scripts/release-agent.sh`: 416 lines (implementation)
+- `README.md`: -1 line (fix)
+- `RELEASE_GUIDE.md`: 44 lines (updates)
+
+### Validation Coverage
+
+- **Total Checks**: 21+ automated checks
+- **Categories**: 10 validation categories
+- **Execution Time**: < 5 seconds
+- **Pass Rate**: 100% (22/22 for v1.7.9)
+
+### Documentation
+
+- **Total Pages**: 3 new documentation files
+- **Total Words**: ~8,500 words
+- **Coverage**: Complete lifecycle documentation
+
+## Testing
+
+### Manual Testing
+
+✅ Executed `./scripts/release-agent.sh` successfully  
+✅ All 22 checks passed  
+✅ Output formatting verified  
+✅ Help and version flags tested  
+✅ Error recovery documentation validated
+
+### Integration Testing
+
+✅ Compatible with existing `validate-release.sh`  
+✅ Works in CI environment (auto-detects)  
+✅ Integrates with bump-version.sh workflow  
+✅ Compatible with all existing workflows
+
+### Validation Testing
+
+✅ Version consistency check works correctly  
+✅ CHANGELOG validation detects missing entries  
+✅ Git tag validation prevents duplicate releases  
+✅ Documentation link checking catches broken links  
+✅ Build system validation confirms CMakeLists.txt
+
+## Future Enhancements
+
+Potential improvements for future versions:
+
+1. **Enhanced Link Checking**: Deep validation of external links
+2. **Example Compilation**: Optional Arduino/PlatformIO compile checks
+3. **Automated CHANGELOG**: Generate changelog from commits
+4. **Performance Metrics**: Track release quality over time
+5. **Multi-Language**: Support for other package managers
+6. **Interactive Mode**: Guided release wizard
+7. **Pre-commit Hook**: Validate before every commit
+8. **JSON Output**: Machine-readable results for tooling
+
+## Maintenance
+
+### Regular Updates
+
+The release agent should be reviewed:
+
+- **Quarterly**: Process improvements and new best practices
+- **After Failed Releases**: Learn from issues and update
+- **When Tools Change**: Update for new CI/CD tools
+- **When Requirements Change**: Add new validation checks
+
+### Version Control
+
+Agent versions will follow semantic versioning:
+
+- **MAJOR**: Breaking changes to agent interface
+- **MINOR**: New features or validation checks
+- **PATCH**: Bug fixes and documentation updates
+
+**Current Version**: v1.0 (November 8, 2025)
+
+## Conclusion
+
+The Release Agent system successfully addresses all requirements from the problem statement:
+
+1. ✅ **Documentation Verified**: All docs updated and validated for v1.7.9
+2. ✅ **Auto-Release Requirements**: All automation verified and working
+3. ✅ **Future Consistency**: Comprehensive agent ensures quality releases
+
+The implementation provides:
+
+- **Immediate Value**: v1.7.9 validated and ready for release
+- **Long-Term Value**: Automated quality assurance for all future releases
+- **Knowledge Capture**: Complete documentation of release process
+- **Developer Experience**: Clear, helpful, fast validation
+
+**Status**: ✅ Complete and ready for production use
+
+---
+
+**For More Information:**
+
+- Specification: `.github/agents/release-agent.md`
+- Usage Guide: `.github/agents/README.md`
+- Release Process: `RELEASE_GUIDE.md`
+- Implementation: `scripts/release-agent.sh`
+
+**Questions or Issues:**
+
+Open an issue at https://github.com/Alteriom/painlessMesh/issues with the `release` label.