@alteriom/painlessmesh 1.7.6 → 1.7.8

package/docs/wiki/API-Reference.md

@@ -84,7 +84,7 @@ variant.printTo(message);
 mesh.sendBroadcast(message);
 ```
 
-### CommandPackage (Type 201)
+### CommandPackage (Type 400)
 
 Device control and automation commands for remote node management.
 
@@ -176,7 +176,7 @@ void receivedCallback(uint32_t from, String& msg) {
         case 200: // SensorPackage
             handleSensorData(alteriom::SensorPackage(obj), from);
             break;
-        case 201: // CommandPackage  
+        case 400: // CommandPackage  
             handleCommand(alteriom::CommandPackage(obj), from);
             break;
         case 202: // StatusPackage

package/docs/wiki/Complete-Documentation.md

@@ -77,7 +77,7 @@ For environmental sensor data collection:
 - Battery level monitoring
 - Timestamp synchronization
 
-### CommandPackage (Type 201)
+### CommandPackage (Type 400)
 For device control and automation:
 - Remote device commands
 - Parameter passing via JSON

package/examples/alteriom/README.md

@@ -15,8 +15,8 @@ Broadcast package for sharing environmental sensor data across the mesh.
 - `timestamp` - Unix timestamp of measurement
 - `batteryLevel` - Battery level percentage (0-100)
 
-### CommandPackage (Type 201)
-Single-destination package for sending commands to specific nodes.
+### CommandPackage (Type 400)
+Single-destination package for sending commands to specific nodes. Uses COMMAND code (400) per mqtt-schema v0.7.2+ for full compliance.
 
 **Fields:**
 - `command` - Command type identifier
@@ -44,6 +44,129 @@ Extended status package with comprehensive health metrics (18 fields).
 - `avgLatency`, `packetLossRate`, `throughput` - Performance metrics
 - `alertFlags`, `lastError` - Alert system
 
+### MetricsPackage (Type 204) - NEW in v1.7.7
+Comprehensive performance metrics for detailed monitoring and dashboards.
+
+**Key Fields:**
+- `cpuUsage`, `loopIterations`, `taskQueueSize` - CPU and processing metrics
+- `freeHeap`, `minFreeHeap`, `heapFragmentation`, `maxAllocHeap` - Memory metrics
+- `bytesReceived`, `bytesSent`, `packetsReceived`, `packetsSent` - Network performance
+- `avgResponseTime`, `maxResponseTime`, `avgMeshLatency` - Timing metrics
+- `connectionQuality`, `wifiRSSI` - Connection quality indicators
+- `collectionTimestamp`, `collectionInterval` - Collection metadata
+
+**Use Cases:**
+- Real-time performance dashboards
+- Capacity planning and optimization
+- Network throughput analysis
+- Latency monitoring
+
+### HealthCheckPackage (Type 605) - NEW in v1.7.7
+Proactive health monitoring with problem detection and recommendations.
+
+**Key Fields:**
+- `healthStatus` - Overall health: 0=critical, 1=warning, 2=healthy
+- `problemFlags` - Bit flags for specific problems (16 types)
+- `memoryHealth`, `networkHealth`, `performanceHealth` - Component health scores (0-100)
+- `memoryTrend` - Memory leak detection (bytes/hour)
+- `packetLossPercent`, `reconnectionCount` - Network stability
+- `missedDeadlines`, `maxLoopTime` - Performance indicators
+- `temperature`, `temperatureHealth` - Environmental monitoring
+- `estimatedTimeToFailure` - Predictive maintenance indicator
+- `recommendations` - Actionable guidance for operators
+
+**Problem Flags:**
+- 0x0001 - Low memory warning
+- 0x0002 - High CPU usage
+- 0x0004 - Connection instability
+- 0x0008 - High packet loss
+- 0x0010 - Network congestion
+- 0x0020 - Low battery
+- 0x0040 - Thermal warning
+- 0x0080 - Mesh partition detected
+- 0x0100 - OTA in progress
+- 0x0200 - Configuration error
+
+**Use Cases:**
+- Proactive problem detection
+- Predictive maintenance
+- Automated alerting
+- Memory leak detection
+
+### MeshNodeListPackage (Type 600) - NEW in v1.7.7
+List of all nodes in the mesh network with their status.
+
+**Fields:**
+- `nodes[]` - Array of node information (max 50)
+  - `nodeId` - Node identifier
+  - `status` - 0=offline, 1=online, 2=unreachable
+  - `lastSeen` - Unix timestamp of last communication
+  - `signalStrength` - RSSI in dBm
+- `nodeCount` - Total number of nodes
+- `meshId` - Mesh network identifier
+
+**Use Cases:**
+- Node discovery and monitoring
+- Network health visualization
+- Device inventory management
+
+### MeshTopologyPackage (Type 601) - NEW in v1.7.7
+Mesh network topology with all connections between nodes.
+
+**Fields:**
+- `connections[]` - Array of connections (max 100)
+  - `fromNode` - Source node ID
+  - `toNode` - Destination node ID
+  - `linkQuality` - Link quality 0.0-1.0
+  - `latencyMs` - Latency in milliseconds
+  - `hopCount` - Number of hops
+- `connectionCount` - Total number of connections
+- `rootNode` - Root/gateway node ID
+
+**Use Cases:**
+- Topology visualization
+- Network optimization
+- Path analysis
+
+### MeshAlertPackage (Type 602) - NEW in v1.7.7
+Mesh network alerts for critical events and warnings.
+
+**Fields:**
+- `alerts[]` - Array of alerts (max 20)
+  - `alertType` - Alert type (0-8: low_memory, node_offline, connection_lost, etc.)
+  - `severity` - 0=info, 1=warning, 2=critical
+  - `message` - Human-readable alert message
+  - `nodeId` - Related node ID
+  - `metricValue` - Related metric value
+  - `threshold` - Threshold that triggered alert
+  - `alertId` - Unique alert identifier
+- `alertCount` - Total number of alerts
+
+**Use Cases:**
+- Automated alerting
+- Problem notification
+- Event logging
+
+### MeshBridgePackage (Type 603) - NEW in v1.7.7
+Bridge package for encapsulating native mesh protocol messages.
+
+**Fields:**
+- `meshProtocol` - 0=painlessMesh, 1=esp-now, 2=ble-mesh, etc.
+- `fromNodeId` - Source node ID
+- `toNodeId` - Destination node ID (0=broadcast)
+- `meshType` - Mesh protocol-specific message type
+- `rawPayload` - Raw payload (hex/base64 encoded)
+- `rssi` - Signal strength in dBm
+- `hopCount` - Number of hops
+- `meshTimestamp` - Mesh protocol timestamp
+- `gatewayNodeId` - Gateway's node ID
+- `meshNetworkId` - Mesh network identifier
+
+**Use Cases:**
+- Mesh-to-MQTT bridging
+- Multi-protocol support
+- Protocol translation
+
 ## Examples
 
 ### `alteriom_sensor_node.ino`
@@ -61,6 +184,17 @@ Phase 1 OTA enhancement example demonstrating:
 - Alert system implementation
 - Usage patterns for Phase 1 features
 
+### `metrics_health_node.ino` (NEW in v1.7.7)
+Comprehensive monitoring node example demonstrating:
+- MetricsPackage (Type 204) collection and broadcasting
+- HealthCheckPackage (Type 605) proactive monitoring (MESH_METRICS)
+- CPU usage calculation and tracking
+- Memory leak detection with trend analysis
+- Network quality assessment
+- Problem flag detection and alerting
+- Predictive maintenance indicators
+- Configurable collection intervals
+
 ## Usage
 
 ```cpp
@@ -77,7 +211,7 @@ mesh.sendBroadcast(sensor.toJsonString());
 // Handle incoming commands
 void handleMessage(String& msg) {
     auto doc = parseJson(msg);
-    if (doc["type"] == 201) {
+    if (doc["type"] == 400) {
         CommandPackage cmd(doc.as<JsonObject>());
         processCommand(cmd);
     }
@@ -137,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.

package/examples/alteriom/alteriom.ino

@@ -126,7 +126,7 @@ void handleIncomingPackage(uint32_t from, String& msg) {
       // Process sensor data (store, forward, analyze, etc.)
     } break;
 
-    case 201:  // CommandPackage
+    case 400:  // CommandPackage
     {
       CommandPackage receivedCmd(obj);
       if (receivedCmd.dest == mesh.getNodeId()) {