@alteriom/painlessmesh 1.7.7 → 1.7.9

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.

package/docs/alteriom/overview.md

@@ -498,11 +498,34 @@ public:
 3. **Validate under memory pressure**
 4. **Test with maximum expected node count**
 
+## Code Conventions
+
+### Boolean Field Naming
+
+Alteriom packages follow a consistent naming convention for boolean fields to improve code clarity:
+
+- **`*Set` suffix**: Configuration data has been provided (e.g., `deviceSecretSet`)
+- **`*Enabled` suffix**: Feature is currently active (e.g., `displayEnabled`)
+- **`is*` prefix or `*Connected`**: Current runtime state (e.g., `mqttConnected`)
+
+See [Boolean Naming Convention](../BOOLEAN_NAMING_CONVENTION.md) for complete guidelines.
+
+### Time Field Naming
+
+Time-based configuration fields follow a dual-unit convention:
+
+- **Internal storage**: Always milliseconds (e.g., `sensorReadInterval`)
+- **JSON serialization**: Both milliseconds (`_ms`) and seconds (`_s`) variants
+- **JSON deserialization**: Read from milliseconds (`_ms`) variant
+
+See package header documentation for complete details.
+
 ## Next Steps
 
 - Learn about [Sensor Packages](sensor-packages.md) in detail
 - Explore [Command System](command-system.md) implementation
 - Study [Status Monitoring](status-monitoring.md) patterns
+- Review [Boolean Naming Convention](../BOOLEAN_NAMING_CONVENTION.md) guidelines
 - See [Tutorial Examples](../tutorials/sensor-networks.md) for hands-on practice
 
 The Alteriom extensions provide a solid foundation for building robust IoT applications with painlessMesh. They demonstrate production-ready patterns while remaining flexible enough to adapt to your specific needs.

package/docs/releases/RELEASE_SUMMARY_v1.7.7.md

@@ -1,6 +1,6 @@
 # painlessMesh v1.7.7 Release Summary
 
-**Release Date:** October 23, 2025  
+**Release Date:** November 5, 2025  
 **Version:** 1.7.7  
 **Type:** Feature Release  
 **Compatibility:** 100% backward compatible with v1.7.6

package/docs/troubleshooting/ESP32_C6_COMPATIBILITY.md

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

package/docs/troubleshooting/common-issues.md

@@ -2,6 +2,34 @@
 
 This guide covers the most frequently encountered problems when working with painlessMesh and their solutions.
 
+## Platform-Specific Issues
+
+### ESP32-C6 Crashes on Startup
+
+**Symptoms:**
+- Device crashes immediately after mesh initialization
+- Endless reboot loop
+- Error message: `assert failed: tcp_alloc ... (Required to lock TCPIP core functionality!)`
+
+**Solution:**
+
+This is a known compatibility issue with ESP32-C6 and newer ESP32 variants. See the dedicated guide:
+
+📖 **[ESP32-C6 Compatibility Guide](ESP32_C6_COMPATIBILITY.md)**
+
+**Quick Fix:**
+Update your AsyncTCP library to version 3.3.0 or newer, or use the ESP32Async library which includes proper LWIP locking for Arduino ESP32 core 3.1.0+.
+
+For PlatformIO, add to your `platformio.ini`:
+```ini
+lib_deps =
+    esp32async/AsyncTCP @ ^3.4.7
+```
+
+For Arduino IDE, download and install manually from: https://github.com/ESP32Async/AsyncTCP
+
+---
+
 ## Connection Issues
 
 ### Nodes Not Connecting

package/docs/v1.7.7_MQTT_IMPROVEMENTS.md

@@ -350,9 +350,27 @@ Packages now include the `message_type` field for 90% faster message classificat
 }
 ```
 
-**Message Type Codes:**
-- **204:** MetricsPackage - SENSOR_METRICS (aligns with schema v0.7.2+)
-- **605:** HealthCheckPackage - MESH_METRICS (mesh performance health)
+**Message Type Codes (mqtt-schema v0.7.2+):**
+
+For performance optimization and standardized routing, all Alteriom packages include the `message_type` field:
+
+| Code | Constant | Message Type | Category | Description | PainlessMesh Package |
+|------|----------|--------------|----------|-------------|---------------------|
+| 200 | SENSOR_DATA | sensor_data | telemetry | Sensor telemetry readings | SensorPackage |
+| 202 | SENSOR_STATUS | sensor_status | telemetry | Sensor status change | StatusPackage |
+| 204 | SENSOR_METRICS | sensor_metrics | telemetry | Sensor health and performance metrics | MetricsPackage |
+| 400 | COMMAND | command | control | Device control command | CommandPackage |
+| 600 | MESH_NODE_LIST | mesh_node_list | mesh | Mesh node inventory | MeshNodeListPackage |
+| 601 | MESH_TOPOLOGY | mesh_topology | mesh | Mesh network topology | MeshTopologyPackage |
+| 602 | MESH_ALERT | mesh_alert | mesh | Mesh network alert | MeshAlertPackage |
+| 603 | MESH_BRIDGE | mesh_bridge | mesh | Mesh protocol bridge | MeshBridgePackage |
+| 604 | MESH_STATUS | mesh_status | mesh | Mesh network health status | EnhancedStatusPackage |
+| 605 | MESH_METRICS | mesh_metrics | mesh | Mesh network performance metrics | HealthCheckPackage |
+
+**Key Points:**
+- The `message_type` field enables 90% faster message classification compared to parsing JSON
+- All Alteriom packages align with @alteriom/mqtt-schema v0.7.2+ standards
+- Message type codes are consistent across MQTT bridge, gateway, and mesh nodes
 
 ## Implementation Guide
 

package/examples/alteriom/README.md

@@ -271,4 +271,16 @@ This validates:
 - Package type consistency
 - Field preservation
 - Edge case handling
-- Integration with painlessMesh plugin system
+- Integration with painlessMesh plugin system
+- JSON structure consistency (nested vs flat)
+
+## Documentation
+
+For developers adding new configuration fields to Alteriom packages:
+
+- **[API Design Guidelines](../../docs/API_DESIGN_GUIDELINES.md)** - Comprehensive guide on when to use nested vs flat JSON structures
+- **[Time Field Naming Convention](alteriom_sensor_package.hpp#L10-L55)** - How to handle time-based fields (ms/s variants)
+- **[Boolean Naming Convention](../../docs/BOOLEAN_NAMING_CONVENTION.md)** - Consistent patterns for boolean fields (*Set, *Enabled, is*)
+- **[JSON Structure Guidelines](alteriom_sensor_package.hpp#L57-L121)** - Quick reference for nesting patterns
+
+These guidelines ensure consistency and maintainability across all Alteriom packages.