@alteriom/painlessmesh 1.7.7 → 1.7.9

package/CHANGELOG.md

@@ -19,7 +19,121 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - TBD
 
-## [1.7.7] - 2025-10-23
+## [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
+
+- **BRIDGE_TO_INTERNET.md** - Comprehensive documentation for bridging mesh networks to the Internet via WiFi router
+  - Complete code examples with AP+STA mode configuration
+  - WiFi channel matching requirements and best practices
+  - Links to working bridge examples (basic, MQTT, web server, enhanced MQTT)
+  - Architecture diagrams and forwarding patterns
+  - Troubleshooting and additional resources
+
+- **Enhanced StatusPackage** - New organization and sensor configuration fields
+  - Organization fields: `organizationId`, `organizationName`, `organizationDomain`
+  - Sensor configuration: `sensorTypes` array, `sensorConfig` JSON, `sensorInventory` array
+  - Separate JSON serialization keys for sensors data vs configuration
+  - CamelCase field naming convention for consistency
+
+- **API Design Guidelines** - `docs/API_DESIGN_GUIDELINES.md`
+  - Field naming conventions (camelCase, units in field names)
+  - Boolean naming patterns (`is`, `has`, `should`, `can`)
+  - Time field naming with units (`_ms`, `_s`, `_us` suffixes)
+  - Serialization patterns and consistency rules
+  - Comprehensive validation tests
+
+- **Manual Publishing Workflow** - `.github/workflows/manual-publish.yml`
+  - On-demand NPM and GitHub Packages publishing
+  - Fixes cases where automated release doesn't trigger package publication
+  - Configurable options for selective publishing
+
+### Changed
+
+- **Time Field Naming Convention** - Consistent unit suffixes across all packages
+  - `collectionTimestamp` → `collectionTimestamp_ms`
+  - `avgResponseTime` → `avgResponseTime_us`
+  - `estimatedTimeToFailure` → `estimatedTimeToFailure_s`
+  - All time fields now include explicit units in field names
+  - Documentation: `docs/architecture/TIME_FIELD_NAMING.md`
+
+- **StatusPackage JSON Structure** - Improved field organization
+  - Sensor data uses `sensors` key (array of readings)
+  - Sensor configuration uses separate keys (`sensorTypes`, `sensorConfig`, `sensorInventory`)
+  - No key collisions between runtime data and configuration
+  - Unconditional serialization for predictable JSON structure
+
+- **MQTT Retry Logic** - Fixed serialization to include all retry fields
+  - Proper condition for including retry configuration
+  - Epsilon comparison for floating-point backoff multiplier
+
+### Fixed
+
+- **CI Pipeline** - Made validate-release depend on CI completion
+  - Prevents release validation from running before tests complete
+  - Ensures all tests pass before release can proceed
+
+- **ArduinoJson API** - Updated deprecated API usage
+  - Fixed deprecated JsonVariant::is<JsonObject>() calls
+  - Updated to ArduinoJson 7.x compatible patterns
+  - Code formatting improvements
+
+- **ESP8266 Compatibility** - Fixed `getDeviceId()` function
+  - Added proper ESP8266 implementation in mqttTopologyTest
+  - Platform-specific device ID retrieval
+
+- **Documentation** - Multiple improvements
+  - Fixed v1.7.7 release date in documentation
+  - Added comprehensive mqtt-schema v0.7.2+ message type codes table
+  - Corrected CommandPackage type number (400, not 201)
+  - Enhanced Alteriom Extensions section in README
+  - Added GitHub Packages authentication for npm install
+
+## [1.7.7] - 2025-11-05
 
 ### 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
@@ -245,9 +247,9 @@ void receivedCallback(uint32_t from, String& msg) {
 | Type | Class | Purpose | Fields |
 |------|-------|---------|--------|
 | 200 | `SensorPackage` | Environmental data | `temperature`, `humidity`, `pressure`, `sensorId`, `timestamp`, `batteryLevel` |
-| 201 | `CommandPackage` | Device control | `command`, `targetDevice`, `parameters`, `commandId` |
 | 202 | `StatusPackage` | Health monitoring | `deviceStatus`, `uptime`, `freeMemory`, `wifiStrength`, `firmwareVersion` |
 | 204 | `MetricsPackage` | Sensor metrics (v1.7.7+, aligns with schema v0.7.2+) | `cpuUsage`, `freeHeap`, `bytesReceived`, `currentThroughput`, `connectionQuality`, `wifiRSSI` |
+| 400 | `CommandPackage` | Device control (v1.7.7+, moved from 201) | `command`, `targetDevice`, `parameters`, `commandId` |
 | 600 | `MeshNodeListPackage` | Mesh node list (v1.7.7+, MESH_NODE_LIST) | `nodes[]` (nodeId, status, lastSeen, signalStrength), `nodeCount`, `meshId` |
 | 601 | `MeshTopologyPackage` | Mesh topology (v1.7.7+, MESH_TOPOLOGY) | `connections[]` (fromNode, toNode, linkQuality, latencyMs), `rootNode` |
 | 602 | `MeshAlertPackage` | Mesh alerts (v1.7.7+, MESH_ALERT) | `alerts[]` (alertType, severity, message, nodeId), `alertCount` |
@@ -280,18 +282,25 @@ 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
+
+**In Development** - Next release after v1.7.7
+
+See [CHANGELOG](CHANGELOG.md) for upcoming changes.
 
-## Latest Release: v1.7.6 (October 19, 2025)
+## Latest Release: v1.7.7 (November 5, 2025)
 
-**Critical emergency fix** for compilation failures in v1.7.4 and v1.7.5:
+**MQTT Schema v0.7.2 Compliance with Enhanced Monitoring**:
 
-- ✅ **Compilation Fixed** - Resolved "_task_request_t was not declared" error
-- ✅ **ESP32 & ESP8266** - All platforms now compile successfully  
-- ✅ **FreeRTOS Stability** - Maintained ~85% crash reduction on ESP32
-- 🚨 **v1.7.4/v1.7.5 Users** - Upgrade immediately (those versions don't compile)
+- ✅ **MetricsPackage (Type 204)** - Comprehensive performance metrics for real-time monitoring
+- ✅ **HealthCheckPackage (Type 605)** - Proactive health monitoring with problem detection
+- ✅ **Mesh Topology Packages** - Complete network visualization (Types 600-603)
+- ✅ **Enhanced MQTT Bridge** - On-demand metrics, health checks, and aggregated statistics
+- ✅ **100% Backward Compatible** - All existing code continues to work
 
-**[📋 Full Release Notes](docs/releases/RELEASE_SUMMARY_v1.7.6.md)** | **[🔖 CHANGELOG](CHANGELOG.md)**
+**[📋 Full Release Notes](docs/releases/RELEASE_SUMMARY_v1.7.7.md)** | **[🔖 CHANGELOG](CHANGELOG.md)**
 
 ## Getting Help
 
@@ -405,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: