@alteriom/painlessmesh 1.7.2 → 1.7.4

package/docs/MQTT_SCHEMA_COMPLIANCE.md

@@ -1,285 +1,285 @@
-# Alteriom MQTT Schema Compliance
-
-## Overview
-
-The painlessMesh library is compliant with the **@alteriom/mqtt-schema** specifications for all mesh-related messages. This ensures interoperability with other Alteriom services and monitoring tools.
-
-## Schema Package
-
-- **Package:** `@alteriom/mqtt-schema` v0.5.0 (latest)
-- **Registry:** npm (https://www.npmjs.com/package/@alteriom/mqtt-schema)
-- **Documentation:** https://github.com/Alteriom/alteriom-mqtt-schema
-- **Release:** v0.5.0 includes mesh topology and event schemas!
-
----
-
-## v0.5.0 Compliance (Mesh Topology & Events)
-
-### Mesh Topology (alteriom/mesh/{mesh_id}/topology)
-
-✅ **Fully Compliant** with `mesh_topology.schema.json` v0.5.0
-
-**Implementation:** `examples/bridge/mesh_topology_reporter.hpp`
-
-**Required Fields:**
-- ✅ Envelope: `schema_version`, `device_id`, `device_type`, `timestamp`, `firmware_version`
-- ✅ Event: `mesh_topology`
-- ✅ Mesh ID: `mesh_id`, `gateway_node_id`
-- ✅ Nodes: Array with `node_id`, `role`, `status`, `last_seen`, `firmware_version`, `uptime_seconds`, `free_memory_kb`, `connection_count`
-- ✅ Connections: Array with `from_node`, `to_node`, `quality`, `latency_ms`, `rssi`, `hop_count`
-- ✅ Metrics: `total_nodes`, `online_nodes`, `network_diameter`, `avg_connection_quality`, `messages_per_second`
-- ✅ Update Type: `full` or `incremental`
-
-**Device ID Format:** `ALT-XXXXXXXXXXXX` (12 hex digits)
-
-**MQTT Topics:**
-- `alteriom/mesh/MESH-001/topology` - Full/incremental updates
-- `alteriom/mesh/MESH-001/topology/response` - Command responses with `correlation_id`
-
-**Publishing Schedule:**
-- Full topology: Every 60 seconds
-- Incremental: Every 5 seconds (if changed)
-- On-demand: Via GET_TOPOLOGY command (300)
-
-### Mesh Events (alteriom/mesh/{mesh_id}/events)
-
-✅ **Fully Compliant** with `mesh_event.schema.json` v0.5.0
-
-**Implementation:** `examples/bridge/mesh_event_publisher.hpp`
-
-**Required Fields:**
-- ✅ Envelope: `schema_version`, `device_id`, `device_type`, `timestamp`, `firmware_version`
-- ✅ Event: `mesh_event`
-- ✅ Event Type: `node_join`, `node_leave`, `connection_lost`, `connection_restored`, `network_split`, `network_merged`
-- ✅ Mesh ID: `mesh_id`
-- ✅ Affected Nodes: Array of device IDs
-- ✅ Details: Object with event-specific information
-
-**MQTT Topic:** `alteriom/mesh/MESH-001/events`
-
-**Event Types Implemented:**
-- ✅ `node_join` - New node connected
-- ✅ `node_leave` - Node disconnected
-- ✅ `connection_lost` - Direct connection failed
-- ✅ `connection_restored` - Connection recovered
-- ✅ `network_split` - Mesh partitioned (detection TBD)
-- ✅ `network_merged` - Partitions rejoined (detection TBD)
-
-### Command Integration (GET_TOPOLOGY - Command 300)
-
-✅ **Fully Compliant** with `command.schema.json` and `command_response.schema.json`
-
-**Implementation:** `examples/bridge/mqtt_command_bridge.hpp`
-
-**Command Request:**
-```json
-{
-  "command": 300,
-  "targetDevice": 0,
-  "commandId": 12345,
-  "parameters": "{}"
-}
-```
-
-**Command Response:**
-- Full mesh topology with `correlation_id` field
-- Published to: `alteriom/mesh/MESH-001/topology/response`
-- Schema-compliant mesh_topology message
-
----
-
-## v0.4.0 Compliance (Gateway Metrics & Commands)
-
-## Compliance Status
-
-### Gateway Metrics (mesh/status/metrics)
-
-✅ **Fully Compliant** with `gateway_metrics.schema.json` v1
-
-**Required Envelope Fields:**
-- `schema_version`: 1 (integer)
-- `device_id`: Mesh node ID or custom identifier
-- `device_type`: "gateway"
-- `timestamp`: ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)
-- `firmware_version`: String (configurable, default: "1.0.0")
-
-**Metrics Object:**
-- `uptime_s`: Uptime in seconds
-- `mesh_nodes`: Number of connected mesh nodes
-- `memory_usage_pct`: Memory usage percentage
-- `connected_devices`: Number of connected devices
-
-**Example Message:**
-```json
-{
-  "schema_version": 1,
-  "device_id": "123456",
-  "device_type": "gateway",
-  "timestamp": "2024-01-01T12:34:56Z",
-  "firmware_version": "1.0.0",
-  "metrics": {
-    "uptime_s": 3600,
-    "mesh_nodes": 5,
-    "memory_usage_pct": 45.2,
-    "connected_devices": 5
-  }
-}
-```
-
-### All Topics - 100% Compliant with Official v0.4.0! ✅
-
-All MQTT topics are now **100% compliant** with official @alteriom/mqtt-schema@0.4.0:
-
-- ✅ `mesh/status/metrics` - **100% compliant** with gateway_metrics.schema.json v1
-- ✅ `mesh/status/nodes` - **100% compliant** with mesh_node_list.schema.json v1 (officially included in v0.4.0!)
-- ✅ `mesh/status/topology` - **100% compliant** with mesh_topology.schema.json v1 (officially included in v0.4.0!)
-- ✅ `mesh/status/alerts` - **100% compliant** with mesh_alert.schema.json v1 (officially included in v0.4.0!)
-- ✅ `mesh/status/node/{id}` - **100% compliant** with sensor_status.schema.json v1
-
-**All proposed schemas have been officially included in @alteriom/mqtt-schema@0.4.0!**
-
-**All devices in the mesh network now report using official standardized schemas!**
-
-## Configuration
-
-### Setting Device Information
-
-```cpp
-MqttStatusBridge bridge(mesh, mqttClient);
-
-// Set device ID (defaults to mesh node ID)
-bridge.setDeviceId("gateway-001");
-
-// Set firmware version (defaults to "1.0.0")
-bridge.setFirmwareVersion("2.1.3");
-
-bridge.begin();
-```
-
-### Timestamp Generation
-
-The implementation generates timestamps in ISO 8601 format compliant with the schema requirement.
-
-**Production Recommendations:**
-- **Preferred:** Use NTP time sync via WiFi or mesh time synchronization
-- **Alternative:** Use RTC (Real-Time Clock) module for accurate timestamps
-- **Fallback:** Current implementation uses Unix epoch (1970-01-01) + millis()
-
-**Format:** `YYYY-MM-DDTHH:MM:SSZ` (ISO 8601 with Zulu time)
-
-**Example Production Implementation:**
-```cpp
-// With NTP (recommended)
-#include <WiFi.h>
-#include <time.h>
-
-String getISO8601Timestamp() {
-  struct tm timeinfo;
-  if (!getLocalTime(&timeinfo)) {
-    return "1970-01-01T00:00:00Z";  // Fallback
-  }
-  char buffer[25];
-  strftime(buffer, sizeof(buffer), "%Y-%m-%dT%H:%M:%SZ", &timeinfo);
-  return String(buffer);
-}
-
-// Configure NTP in setup()
-configTime(0, 0, "pool.ntp.org");
-```
-
-## Validation
-
-To validate messages against the schema:
-
-```javascript
-// Node.js example
-const { validators } = require('@alteriom/mqtt-schema');
-
-const message = JSON.parse(mqttPayload);
-const result = validators.gatewayMetrics(message);
-
-if (!result.valid) {
-  console.error('Validation errors:', result.errors);
-}
-```
-
-## Benefits of Compliance
-
-1. **Interoperability**: Works with other Alteriom services
-2. **Validation**: Messages can be validated against published schemas
-3. **Type Safety**: TypeScript types available from the schema package
-4. **Documentation**: Schema serves as API documentation
-5. **Evolution**: Forward-compatible with schema versioning
-
-## Dependencies
-
-Add to `package.json`:
-```json
-{
-  "devDependencies": {
-    "@alteriom/mqtt-schema": "^0.4.0",
-    "ajv": "^8.17.0",
-    "ajv-formats": "^2.1.1"
-  }
-}
-```
-
-## Migration Notes
-
-If you have existing MQTT consumers expecting the old format:
-
-**Old Format:**
-```json
-{
-  "nodeCount": 5,
-  "rootNodeId": 123456,
-  "uptime": 3600,
-  "freeHeap": 45000,
-  "timestamp": 1234567890
-}
-```
-
-**New Format (Schema v1):**
-```json
-{
-  "schema_version": 1,
-  "device_id": "123456",
-  "device_type": "gateway",
-  "timestamp": "2024-01-01T12:34:56Z",
-  "firmware_version": "1.0.0",
-  "metrics": {
-    "uptime_s": 3600,
-    "mesh_nodes": 5,
-    "memory_usage_pct": 45.2,
-    "connected_devices": 5
-  }
-}
-```
-
-**Migration Path:**
-1. Update MQTT consumers to handle both formats during transition
-2. Use `schema_version` field to detect new format
-3. Gradually migrate all publishers to new format
-4. Remove old format support once migration complete
-
-## References
-
-- Schema Package: https://www.npmjs.com/package/@alteriom/mqtt-schema
-- Schema Repository: https://github.com/Alteriom/alteriom-mqtt-schema
-- JSON Schema Spec: https://json-schema.org/
-- Phase 2 Guide: [PHASE2_GUIDE.md](PHASE2_GUIDE.md)
-- Implementation: [mqtt_status_bridge.hpp](../examples/bridge/mqtt_status_bridge.hpp)
-
-## Future Enhancements
-
-Potential schema alignment for other message types:
-- Align node list with sensor_status schema
-- Create custom mesh_topology schema
-- Standardize alert format across Alteriom ecosystem
-- Add validation helpers in the bridge class
-
----
-
-**Last Updated:** October 2024  
-**Schema Version:** v1  
-**Package Version:** @alteriom/mqtt-schema@0.4.0
+# Alteriom MQTT Schema Compliance
+
+## Overview
+
+The painlessMesh library is compliant with the **@alteriom/mqtt-schema** specifications for all mesh-related messages. This ensures interoperability with other Alteriom services and monitoring tools.
+
+## Schema Package
+
+- **Package:** `@alteriom/mqtt-schema` v0.5.0 (latest)
+- **Registry:** npm (https://www.npmjs.com/package/@alteriom/mqtt-schema)
+- **Documentation:** https://github.com/Alteriom/alteriom-mqtt-schema
+- **Release:** v0.5.0 includes mesh topology and event schemas!
+
+---
+
+## v0.5.0 Compliance (Mesh Topology & Events)
+
+### Mesh Topology (alteriom/mesh/{mesh_id}/topology)
+
+✅ **Fully Compliant** with `mesh_topology.schema.json` v0.5.0
+
+**Implementation:** `examples/bridge/mesh_topology_reporter.hpp`
+
+**Required Fields:**
+- ✅ Envelope: `schema_version`, `device_id`, `device_type`, `timestamp`, `firmware_version`
+- ✅ Event: `mesh_topology`
+- ✅ Mesh ID: `mesh_id`, `gateway_node_id`
+- ✅ Nodes: Array with `node_id`, `role`, `status`, `last_seen`, `firmware_version`, `uptime_seconds`, `free_memory_kb`, `connection_count`
+- ✅ Connections: Array with `from_node`, `to_node`, `quality`, `latency_ms`, `rssi`, `hop_count`
+- ✅ Metrics: `total_nodes`, `online_nodes`, `network_diameter`, `avg_connection_quality`, `messages_per_second`
+- ✅ Update Type: `full` or `incremental`
+
+**Device ID Format:** `ALT-XXXXXXXXXXXX` (12 hex digits)
+
+**MQTT Topics:**
+- `alteriom/mesh/MESH-001/topology` - Full/incremental updates
+- `alteriom/mesh/MESH-001/topology/response` - Command responses with `correlation_id`
+
+**Publishing Schedule:**
+- Full topology: Every 60 seconds
+- Incremental: Every 5 seconds (if changed)
+- On-demand: Via GET_TOPOLOGY command (300)
+
+### Mesh Events (alteriom/mesh/{mesh_id}/events)
+
+✅ **Fully Compliant** with `mesh_event.schema.json` v0.5.0
+
+**Implementation:** `examples/bridge/mesh_event_publisher.hpp`
+
+**Required Fields:**
+- ✅ Envelope: `schema_version`, `device_id`, `device_type`, `timestamp`, `firmware_version`
+- ✅ Event: `mesh_event`
+- ✅ Event Type: `node_join`, `node_leave`, `connection_lost`, `connection_restored`, `network_split`, `network_merged`
+- ✅ Mesh ID: `mesh_id`
+- ✅ Affected Nodes: Array of device IDs
+- ✅ Details: Object with event-specific information
+
+**MQTT Topic:** `alteriom/mesh/MESH-001/events`
+
+**Event Types Implemented:**
+- ✅ `node_join` - New node connected
+- ✅ `node_leave` - Node disconnected
+- ✅ `connection_lost` - Direct connection failed
+- ✅ `connection_restored` - Connection recovered
+- ✅ `network_split` - Mesh partitioned (detection TBD)
+- ✅ `network_merged` - Partitions rejoined (detection TBD)
+
+### Command Integration (GET_TOPOLOGY - Command 300)
+
+✅ **Fully Compliant** with `command.schema.json` and `command_response.schema.json`
+
+**Implementation:** `examples/bridge/mqtt_command_bridge.hpp`
+
+**Command Request:**
+```json
+{
+  "command": 300,
+  "targetDevice": 0,
+  "commandId": 12345,
+  "parameters": "{}"
+}
+```
+
+**Command Response:**
+- Full mesh topology with `correlation_id` field
+- Published to: `alteriom/mesh/MESH-001/topology/response`
+- Schema-compliant mesh_topology message
+
+---
+
+## v0.4.0 Compliance (Gateway Metrics & Commands)
+
+## Compliance Status
+
+### Gateway Metrics (mesh/status/metrics)
+
+✅ **Fully Compliant** with `gateway_metrics.schema.json` v1
+
+**Required Envelope Fields:**
+- `schema_version`: 1 (integer)
+- `device_id`: Mesh node ID or custom identifier
+- `device_type`: "gateway"
+- `timestamp`: ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)
+- `firmware_version`: String (configurable, default: "1.0.0")
+
+**Metrics Object:**
+- `uptime_s`: Uptime in seconds
+- `mesh_nodes`: Number of connected mesh nodes
+- `memory_usage_pct`: Memory usage percentage
+- `connected_devices`: Number of connected devices
+
+**Example Message:**
+```json
+{
+  "schema_version": 1,
+  "device_id": "123456",
+  "device_type": "gateway",
+  "timestamp": "2024-01-01T12:34:56Z",
+  "firmware_version": "1.0.0",
+  "metrics": {
+    "uptime_s": 3600,
+    "mesh_nodes": 5,
+    "memory_usage_pct": 45.2,
+    "connected_devices": 5
+  }
+}
+```
+
+### All Topics - 100% Compliant with Official v0.4.0! ✅
+
+All MQTT topics are now **100% compliant** with official @alteriom/mqtt-schema@0.4.0:
+
+- ✅ `mesh/status/metrics` - **100% compliant** with gateway_metrics.schema.json v1
+- ✅ `mesh/status/nodes` - **100% compliant** with mesh_node_list.schema.json v1 (officially included in v0.4.0!)
+- ✅ `mesh/status/topology` - **100% compliant** with mesh_topology.schema.json v1 (officially included in v0.4.0!)
+- ✅ `mesh/status/alerts` - **100% compliant** with mesh_alert.schema.json v1 (officially included in v0.4.0!)
+- ✅ `mesh/status/node/{id}` - **100% compliant** with sensor_status.schema.json v1
+
+**All proposed schemas have been officially included in @alteriom/mqtt-schema@0.4.0!**
+
+**All devices in the mesh network now report using official standardized schemas!**
+
+## Configuration
+
+### Setting Device Information
+
+```cpp
+MqttStatusBridge bridge(mesh, mqttClient);
+
+// Set device ID (defaults to mesh node ID)
+bridge.setDeviceId("gateway-001");
+
+// Set firmware version (defaults to "1.0.0")
+bridge.setFirmwareVersion("2.1.3");
+
+bridge.begin();
+```
+
+### Timestamp Generation
+
+The implementation generates timestamps in ISO 8601 format compliant with the schema requirement.
+
+**Production Recommendations:**
+- **Preferred:** Use NTP time sync via WiFi or mesh time synchronization
+- **Alternative:** Use RTC (Real-Time Clock) module for accurate timestamps
+- **Fallback:** Current implementation uses Unix epoch (1970-01-01) + millis()
+
+**Format:** `YYYY-MM-DDTHH:MM:SSZ` (ISO 8601 with Zulu time)
+
+**Example Production Implementation:**
+```cpp
+// With NTP (recommended)
+#include <WiFi.h>
+#include <time.h>
+
+String getISO8601Timestamp() {
+  struct tm timeinfo;
+  if (!getLocalTime(&timeinfo)) {
+    return "1970-01-01T00:00:00Z";  // Fallback
+  }
+  char buffer[25];
+  strftime(buffer, sizeof(buffer), "%Y-%m-%dT%H:%M:%SZ", &timeinfo);
+  return String(buffer);
+}
+
+// Configure NTP in setup()
+configTime(0, 0, "pool.ntp.org");
+```
+
+## Validation
+
+To validate messages against the schema:
+
+```javascript
+// Node.js example
+const { validators } = require('@alteriom/mqtt-schema');
+
+const message = JSON.parse(mqttPayload);
+const result = validators.gatewayMetrics(message);
+
+if (!result.valid) {
+  console.error('Validation errors:', result.errors);
+}
+```
+
+## Benefits of Compliance
+
+1. **Interoperability**: Works with other Alteriom services
+2. **Validation**: Messages can be validated against published schemas
+3. **Type Safety**: TypeScript types available from the schema package
+4. **Documentation**: Schema serves as API documentation
+5. **Evolution**: Forward-compatible with schema versioning
+
+## Dependencies
+
+Add to `package.json`:
+```json
+{
+  "devDependencies": {
+    "@alteriom/mqtt-schema": "^0.4.0",
+    "ajv": "^8.17.0",
+    "ajv-formats": "^2.1.1"
+  }
+}
+```
+
+## Migration Notes
+
+If you have existing MQTT consumers expecting the old format:
+
+**Old Format:**
+```json
+{
+  "nodeCount": 5,
+  "rootNodeId": 123456,
+  "uptime": 3600,
+  "freeHeap": 45000,
+  "timestamp": 1234567890
+}
+```
+
+**New Format (Schema v1):**
+```json
+{
+  "schema_version": 1,
+  "device_id": "123456",
+  "device_type": "gateway",
+  "timestamp": "2024-01-01T12:34:56Z",
+  "firmware_version": "1.0.0",
+  "metrics": {
+    "uptime_s": 3600,
+    "mesh_nodes": 5,
+    "memory_usage_pct": 45.2,
+    "connected_devices": 5
+  }
+}
+```
+
+**Migration Path:**
+1. Update MQTT consumers to handle both formats during transition
+2. Use `schema_version` field to detect new format
+3. Gradually migrate all publishers to new format
+4. Remove old format support once migration complete
+
+## References
+
+- Schema Package: https://www.npmjs.com/package/@alteriom/mqtt-schema
+- Schema Repository: https://github.com/Alteriom/alteriom-mqtt-schema
+- JSON Schema Spec: https://json-schema.org/
+- Phase 2 Guide: [PHASE2_GUIDE.md](PHASE2_GUIDE.md)
+- Implementation: [mqtt_status_bridge.hpp](../examples/bridge/mqtt_status_bridge.hpp)
+
+## Future Enhancements
+
+Potential schema alignment for other message types:
+- Align node list with sensor_status schema
+- Create custom mesh_topology schema
+- Standardize alert format across Alteriom ecosystem
+- Add validation helpers in the bridge class
+
+---
+
+**Last Updated:** October 2024  
+**Schema Version:** v1  
+**Package Version:** @alteriom/mqtt-schema@0.4.0