@alteriom/painlessmesh 1.8.14 → 1.9.0

package/docs/MQTT_SCHEMA_COMPLIANCE.md

@@ -1,340 +0,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.7.2 (latest)
-- **Registry:** npm (https://www.npmjs.com/package/@alteriom/mqtt-schema)
-- **Documentation:** https://github.com/Alteriom/alteriom-mqtt-schema
-- **Release:** v0.7.2 includes sensor metrics and enhanced message types!
-
-## v0.7.2 Schema Alignment
-
-### Message Type Codes (Faster Classification)
-
-The schema now includes standardized message type codes for 90% faster message classification:
-
-**Standard Schema Codes:**
-- **200:** SENSOR_DATA - Sensor telemetry readings
-- **201:** SENSOR_HEARTBEAT - Sensor presence/health
-- **202:** SENSOR_STATUS - Sensor status change
-- **203:** SENSOR_INFO - Sensor identification and capabilities (v0.7.2+)
-- **204:** SENSOR_METRICS - Sensor health and performance metrics (v0.7.2+)
-- **300:** GATEWAY_INFO - Gateway identification
-- **301:** GATEWAY_METRICS - Gateway health metrics
-- **302:** GATEWAY_DATA - Gateway telemetry (v0.7.2+)
-- **303:** GATEWAY_HEARTBEAT - Gateway presence (v0.7.2+)
-- **304:** GATEWAY_STATUS - Gateway status (v0.7.2+)
-- **400:** COMMAND - Device control command
-- **401:** COMMAND_RESPONSE - Command execution result
-- **500:** FIRMWARE_STATUS - Firmware update status
-- **600:** MESH_NODE_LIST - Mesh node inventory
-- **601:** MESH_TOPOLOGY - Mesh network topology
-- **602:** MESH_ALERT - Mesh network alert
-- **603:** MESH_BRIDGE - Mesh protocol bridge (v0.7.1+)
-- **604:** MESH_STATUS - Mesh status (v0.7.2+)
-- **605:** MESH_METRICS - Mesh-level metrics (v0.7.2+)
-- **700:** DEVICE_CONFIG - Device configuration management
-
-**painlessMesh Mesh-Specific Codes (600+ range):**
-- **600:** MeshNodeListPackage → MESH_NODE_LIST (v1.7.7+)
-- **601:** MeshTopologyPackage → MESH_TOPOLOGY (v1.7.7+)
-- **602:** MeshAlertPackage → MESH_ALERT (v1.7.7+)
-- **603:** MeshBridgePackage → MESH_BRIDGE (v1.7.7+)
-- **604:** EnhancedStatusPackage → MESH_STATUS (v1.7.7+)
-- **605:** HealthCheckPackage → MESH_METRICS (v1.7.7+)
-
-**painlessMesh Schema-Aligned Codes:**
-- **200:** SensorPackage → SENSOR_DATA ✓
-- **202:** StatusPackage → SENSOR_STATUS ✓
-- **204:** MetricsPackage → SENSOR_METRICS ✓ (aligns with v0.7.2+)
-- **400:** CommandPackage → COMMAND ✓ (moved from 201 in v1.7.7 for full schema compliance)
-
-All painlessMesh packages now include the optional `message_type` field for optimal performance.
-
-### Mesh Bridge Schema (Type 603)
-
-New schema for bridging painlessMesh protocol to MQTT, enabling standardized mesh protocol integration.
-
-**Key Features:**
-- Native painlessMesh message encapsulation
-- Support for SINGLE, BROADCAST, and other mesh message types
-- RSSI, hop count, and timing information
-- Optional payload decoding for MQTT v1 messages
-- Multiple mesh protocol support (painlessMesh, ESP-NOW, BLE Mesh, etc.)
-
----
-
-## 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