@alteriom/painlessmesh 1.7.6 → 1.7.8

package/CHANGELOG.md

@@ -19,6 +19,183 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - TBD
 
+## [1.7.8] - 2025-11-04
+
+### 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
+
+- **MQTT Schema v0.7.2 Compliance** - Updated to @alteriom/mqtt-schema v0.7.2
+  - Added `message_type` field to all packages for 90% faster classification
+  - MetricsPackage (204) now aligns with schema SENSOR_METRICS (v0.7.2+)
+  - CommandPackage moved from type 201 → 400 (COMMAND per schema, resolves conflict with SENSOR_HEARTBEAT)
+  - HealthCheckPackage uses 605 (MESH_METRICS per mqtt-schema v0.7.2+)
+  - EnhancedStatusPackage uses 604 (MESH_STATUS per mqtt-schema v0.7.2+)
+  - Compatible with mesh bridge schema (type 603) for future integration
+  
+- **MetricsPackage (Type 204)** - Comprehensive performance metrics for real-time monitoring and dashboards
+  - CPU and processing metrics (cpuUsage, loopIterations, taskQueueSize)
+  - Memory metrics (freeHeap, minFreeHeap, heapFragmentation, maxAllocHeap)
+  - Network performance (bytesReceived, bytesSent, packetsDropped, currentThroughput)
+  - Timing and latency metrics (avgResponseTime, maxResponseTime, avgMeshLatency)
+  - Connection quality indicators (connectionQuality, wifiRSSI)
+  - Collection metadata for tracking
+  
+- **MeshNodeListPackage (Type 600)** - List of all nodes in mesh network (MESH_NODE_LIST per mqtt-schema v0.7.2+)
+  - Array of node information (nodeId, status, lastSeen, signalStrength)
+  - Total node count and mesh identifier
+  - Enables node discovery and monitoring
+
+- **MeshTopologyPackage (Type 601)** - Mesh network topology with connections (MESH_TOPOLOGY per mqtt-schema v0.7.2+)
+  - Array of connections between nodes (fromNode, toNode, linkQuality, latencyMs, hopCount)
+  - Root/gateway node identification
+  - Enables topology visualization and network analysis
+
+- **MeshAlertPackage (Type 602)** - Mesh network alerts and warnings (MESH_ALERT per mqtt-schema v0.7.2+)
+  - Array of alerts with type, severity, and message
+  - Node-specific and network-wide alerts
+  - Threshold-based alerting with metric values
+
+- **MeshBridgePackage (Type 603)** - Bridge for native mesh protocol messages (MESH_BRIDGE per mqtt-schema v0.7.2+)
+  - Encapsulates native painlessMesh protocol messages
+  - Supports multiple mesh protocols (painlessMesh, esp-now, ble-mesh, etc.)
+  - Includes RSSI, hop count, and timing information
+  - Enables mesh-to-MQTT bridging
+
+- **HealthCheckPackage (Type 605)** - Proactive health monitoring with problem detection (MESH_METRICS per mqtt-schema v0.7.2+)
+  - Overall health status (0=critical, 1=warning, 2=healthy)
+  - Problem flags for 10+ specific issue types (low memory, high CPU, network issues, etc.)
+  - Component health scores (memoryHealth, networkHealth, performanceHealth)
+  - Memory leak detection with trend analysis (bytes/hour)
+  - Predictive maintenance indicators (estimatedTimeToFailure)
+  - Actionable recommendations for operators
+  - Environmental monitoring (temperature, temperatureHealth)
+  
+- **Example Implementation** - `examples/alteriom/metrics_health_node.ino`
+  - Demonstrates complete metrics collection and health monitoring
+  - Configurable collection intervals
+  - CPU usage calculation
+  - Memory leak detection
+  - Network quality assessment
+  - Problem flag detection and alerting
+  
+- **Comprehensive Testing** - `test/catch/catch_metrics_health_packages.cpp`
+  - 64 test assertions validating both new packages
+  - Edge case handling (min/max values)
+  - Problem flag testing
+  - Health status level validation
+  - Serialization/deserialization verification
+  
+- **Documentation** - `docs/v1.7.7_MQTT_IMPROVEMENTS.md`
+  - Complete implementation guide
+  - MQTT bridge integration examples
+  - Dashboard integration (Grafana, InfluxDB, Home Assistant)
+  - Performance considerations and optimization tips
+  - Alert configuration examples
+  - Best practices and troubleshooting
+
+### Improved
+
+- **MQTT Communication Efficiency** - Optimized metric collection for large meshes
+  - Minimal network overhead (~109 bytes/sec for 10 nodes)
+  - Configurable collection intervals based on health status
+  - Selective reporting of changed metrics
+  
+- **Problem Detection** - Early warning system for common issues
+  - Memory leak detection with trend analysis
+  - Network instability detection
+  - Performance degradation alerts
+  - Thermal warnings
+  - Mesh partition detection
+  
+- **Predictive Maintenance** - Proactive failure prevention
+  - Estimated time to failure calculations
+  - Memory exhaustion prediction
+  - Automated recommendations
+  - Health-based interval adjustment
+
+### Performance
+
+- **Memory Impact**: <1KB overhead for both packages with reasonable collection intervals
+- **Network Bandwidth**: Minimal impact (~109 bytes/sec for 10 nodes with 30s/60s intervals)
+- **CPU Overhead**: <1% additional CPU usage for metric collection
+
+### Compatibility
+
+- **100% Backward Compatible** with v1.7.6
+- All existing packages (200-203) work unchanged
+- New packages (204, 604, 605) are optional additions
+- No breaking changes to existing code
+- Can be adopted incrementally
+
 ## [1.7.6] - 2025-10-19
 
 ### Fixed

package/README.md

@@ -24,12 +24,80 @@ This fork includes specialized packages for structured IoT communication:
 
 #### Custom Package Types
 
-- **`SensorPackage`** (Type 200) - Environmental data collection (temperature, humidity, pressure, battery levels)
-- **`CommandPackage`** (Type 201) - Device control and automation commands  
-- **`StatusPackage`** (Type 202) - Health monitoring and system status reporting
-- **`EnhancedStatusPackage`** (Type 203) - Detailed performance metrics and mesh statistics
-
-All packages provide type-safe serialization, automatic JSON conversion, and mesh-wide broadcasting or targeted messaging.
+**Core IoT Packages:**
+
+- **`SensorPackage`** (Type 200) - Environmental data collection
+  - Temperature, humidity, pressure monitoring
+  - Battery level tracking
+  - Sensor ID and timestamp fields
+  - Ideal for environmental monitoring and smart agriculture
+
+- **`StatusPackage`** (Type 202) - Basic health monitoring
+  - Device status flags and uptime
+  - Free memory and WiFi strength
+  - Firmware version tracking
+  - Command response capability for MQTT bridge
+
+- **`CommandPackage`** (Type 400) - Device control and automation (COMMAND per mqtt-schema v0.7.2+)
+  - Targeted command execution
+  - JSON parameter support
+  - Command tracking with unique IDs
+  - Perfect for remote device control
+
+**Advanced Monitoring Packages (Phase 2):**
+
+- **`MetricsPackage`** (Type 204) - Comprehensive performance metrics (SENSOR_METRICS per mqtt-schema v0.7.2+)
+  - CPU usage and processing metrics
+  - Memory health (heap, fragmentation, max allocation)
+  - Network throughput and packet statistics
+  - Response time and latency tracking
+  - Connection quality and WiFi RSSI
+  - Dashboard-ready data collection
+
+- **`HealthCheckPackage`** (Type 605) - Proactive problem detection (MESH_METRICS per mqtt-schema v0.7.2+)
+  - Overall health scoring (0-100 for memory, network, performance)
+  - Problem flag indicators (16-bit flags for specific issues)
+  - Memory leak detection with trend analysis
+  - Predictive maintenance (estimated time to failure)
+  - Crash tracking and reboot reason codes
+  - Actionable recommendations
+
+**Mesh Topology & Management (Phase 2):**
+
+- **`EnhancedStatusPackage`** (Type 604) - Detailed mesh status (MESH_STATUS per mqtt-schema v0.7.2+)
+  - Complete mesh statistics (node count, connections, messages)
+  - Performance metrics (latency, packet loss, throughput)
+  - Alert flags and error reporting
+  - Firmware verification with MD5 hash
+
+- **`MeshNodeListPackage`** (Type 600) - Node discovery and inventory (MESH_NODE_LIST per mqtt-schema v0.7.2+)
+  - List of all mesh nodes with status (offline/online/unreachable)
+  - Signal strength (RSSI) for each node
+  - Last seen timestamps
+  - Supports up to 50 nodes per message
+
+- **`MeshTopologyPackage`** (Type 601) - Network topology visualization (MESH_TOPOLOGY per mqtt-schema v0.7.2+)
+  - Connection graph with link quality
+  - Latency measurements per connection
+  - Hop count tracking
+  - Root/gateway node identification
+  - Supports up to 100 connections per message
+
+- **`MeshAlertPackage`** (Type 602) - Network event notifications (MESH_ALERT per mqtt-schema v0.7.2+)
+  - Configurable alert types (low memory, node offline, connection lost)
+  - Severity levels (info, warning, critical)
+  - Metric-based threshold triggering
+  - Human-readable alert messages
+  - Supports up to 20 alerts per message
+
+- **`MeshBridgePackage`** (Type 603) - Protocol bridging (MESH_BRIDGE per mqtt-schema v0.7.2+)
+  - Encapsulates native mesh protocol messages
+  - Multi-protocol support (painlessMesh, ESP-NOW, BLE-Mesh)
+  - Raw payload with signal strength
+  - Gateway node identification
+  - Enables heterogeneous mesh networks
+
+All packages provide type-safe serialization, automatic JSON conversion, and mesh-wide broadcasting or targeted messaging. They align with mqtt-schema v0.7.2+ for enterprise IoT integration.
 
 #### 🚀 Phase 2 Features (v1.7.0+)
 
@@ -177,8 +245,15 @@ 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` |
+| 603 | `MeshBridgePackage` | Mesh bridge (v1.7.7+, MESH_BRIDGE) | `meshProtocol`, `fromNodeId`, `toNodeId`, `meshType`, `rawPayload`, `rssi`, `hopCount` |
+| 604 | `EnhancedStatusPackage` | Mesh status (MESH_STATUS per schema v0.7.2+) | `nodeCount`, `connectionCount`, `messagesReceived`, `messagesSent`, `avgLatency`, `packetLossRate` |
+| 605 | `HealthCheckPackage` | Mesh metrics (v1.7.7+, MESH_METRICS per schema v0.7.2+) | `healthStatus`, `problemFlags`, `memoryHealth`, `networkHealth`, `performanceHealth`, `recommendations` |
 
 ## Key Features
 
@@ -207,16 +282,23 @@ void receivedCallback(uint32_t from, String& msg) {
 - **Event Coordination** - Synchronized displays, distributed processing
 - **Bridge Networks** - Connect mesh to WiFi/Internet/MQTT
 
-## Latest Release: v1.7.6 (October 19, 2025)
+## Development Version: v1.7.8
+
+**In Development** - Next release after v1.7.7
+
+See [CHANGELOG](CHANGELOG.md) for upcoming changes.
+
+## 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
 

package/RELEASE_GUIDE.md

@@ -344,6 +344,42 @@ npm whoami
 # Create any page to initialize, then re-run release
 ```
 
+**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 requires the commit message to start with `release:` (lowercase with colon):
+```bash
+# ✅ Correct - Will trigger NPM/GitHub Packages publishing
+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"
+```
+
+**Solution: Use Manual Publishing Workflow**
+
+If this happens, you can manually publish packages:
+
+1. Go to **Actions** → **Manual Package Publishing**
+2. Click **Run workflow**
+3. Select options:
+   - ✅ Publish to NPM Registry
+   - ✅ Publish to GitHub Packages
+4. Click **Run workflow**
+
+The manual workflow will:
+- Read the current version from `library.properties`
+- Publish to NPM (if selected)
+- Publish to GitHub Packages (if selected)
+- Show success/failure status for each
+
+Alternatively, from command line:
+```bash
+# Trigger via GitHub CLI
+gh workflow run manual-publish.yml
+```
+
 ### Manual Override
 
 If automation fails, you can manually perform any step: