@alteriom/mqtt-schema 0.5.0 → 0.7.0

package/README.md

@@ -33,6 +33,10 @@ Firmware emits structured MQTT payloads that must remain tightly aligned with we
 - Helpful error paths (JSON Pointer style)
 - Lightweight (Ajv peer dependency, schemas embedded)
 - Ships original schema JSON files (optional consumption)
+- **NEW in v0.7.0**: Best-in-class OTA management with security, rollback, and delta updates
+- **NEW in v0.6.0**: Enhanced location/geolocation support for asset tracking
+- **NEW in v0.6.0**: Extended sensor metadata (accuracy, calibration, operational range)
+- **NEW in v0.6.0**: Comprehensive gateway health metrics (storage, network, errors)
 
 ## Installation
 
@@ -147,9 +151,155 @@ mqttClient.subscribe(`alteriom/nodes/${command.device_id}/responses`, (message)
 - Success boolean and error codes in responses
 - Latency tracking for performance monitoring
 
-## OTA Firmware Manifest Schema (v0.3.1+)
+## Enhanced Location & Environment Tracking (v0.6.0+)
 
-The package includes OTA firmware manifest schema with both rich and minimal formats.
+Track device location and deployment context for asset management and map-based visualization:
+
+```ts
+import { validators, isSensorDataMessage } from '@alteriom/mqtt-schema';
+
+const sensorData = {
+  schema_version: 1,
+  device_id: 'SN456',
+  device_type: 'sensor',
+  timestamp: new Date().toISOString(),
+  firmware_version: 'SN 2.1.0',
+  // Standardized location for map visualization
+  location: {
+    latitude: 43.6532,
+    longitude: -79.3832,
+    altitude: 76.5,
+    accuracy_m: 10.0,
+    zone: 'warehouse_A',
+    description: 'Shelf 3, Row B'
+  },
+  // Deployment context
+  environment: {
+    deployment_type: 'indoor',
+    power_source: 'battery',
+    expected_battery_life_days: 365
+  },
+  sensors: {
+    temperature: {
+      value: 22.3,
+      unit: 'C',
+      // Enhanced sensor metadata
+      timestamp: '2025-10-19T20:59:58.000Z',
+      accuracy: 0.5,
+      last_calibration: '2025-01-15',
+      error_margin_pct: 2.0,
+      operational_range: { min: -40, max: 85 },
+      quality_score: 0.95
+    }
+  },
+  battery_level: 78,
+  signal_strength: -65
+};
+
+const result = validators.sensorData(sensorData);
+if (result.valid && isSensorDataMessage(sensorData)) {
+  // Display on map using location data
+  displayOnMap(sensorData.location.latitude, sensorData.location.longitude);
+  
+  // Show sensor health based on metadata
+  if (sensorData.sensors.temperature.accuracy) {
+    console.log(`Temperature accuracy: ±${sensorData.sensors.temperature.accuracy}${sensorData.sensors.temperature.unit}`);
+  }
+  
+  // Check calibration status
+  const lastCal = new Date(sensorData.sensors.temperature.last_calibration);
+  const daysSinceCalibration = (Date.now() - lastCal.getTime()) / (1000 * 60 * 60 * 24);
+  if (daysSinceCalibration > 365) {
+    console.warn('Sensor calibration overdue');
+  }
+}
+```
+
+**Location & Environment Features:**
+- GPS coordinates (latitude, longitude, altitude) with accuracy tracking
+- Zone-based organization (warehouses, floors, rooms)
+- Human-readable location descriptions
+- Deployment type tracking (indoor/outdoor/mobile)
+- Power source information for battery management
+- Per-sensor timestamps for async polling scenarios
+- Sensor accuracy and calibration tracking
+- Operational range validation support
+
+## Enhanced Gateway Metrics (v0.6.0+)
+
+Comprehensive system health monitoring for gateways:
+
+```ts
+import { validators, isGatewayMetricsMessage } from '@alteriom/mqtt-schema';
+
+const metrics = {
+  schema_version: 1,
+  device_id: 'GW002',
+  device_type: 'gateway',
+  timestamp: new Date().toISOString(),
+  firmware_version: 'GW 1.4.0',
+  metrics: {
+    uptime_s: 86400,
+    cpu_usage_pct: 15.3,
+    memory_usage_pct: 42.7,
+    temperature_c: 45.2,
+    // Enhanced storage metrics
+    storage_usage_pct: 45.2,
+    storage_total_mb: 512,
+    storage_free_mb: 280.5,
+    // Network bandwidth tracking
+    network_rx_kbps: 125.4,
+    network_tx_kbps: 89.3,
+    active_connections: 5,
+    // System health indicators
+    error_count_24h: 3,
+    warning_count_24h: 12,
+    restart_count: 2,
+    last_restart_reason: 'firmware_update',
+    // Mesh network metrics
+    connected_devices: 12,
+    mesh_nodes: 8,
+    packet_loss_pct: 0.5
+  }
+};
+
+const result = validators.gatewayMetrics(metrics);
+if (result.valid && isGatewayMetricsMessage(metrics)) {
+  // Storage monitoring
+  if (metrics.metrics.storage_usage_pct > 80) {
+    console.warn('Storage usage critical:', metrics.metrics.storage_usage_pct);
+  }
+  
+  // Network health
+  const totalBandwidth = metrics.metrics.network_rx_kbps + metrics.metrics.network_tx_kbps;
+  console.log(`Total bandwidth: ${totalBandwidth.toFixed(1)} kbps`);
+  
+  // Error trend analysis
+  if (metrics.metrics.error_count_24h > 10) {
+    console.error('High error rate detected:', metrics.metrics.error_count_24h);
+  }
+  
+  // Restart tracking
+  console.log(`Last restart: ${metrics.metrics.last_restart_reason}`);
+  console.log(`Total restarts: ${metrics.metrics.restart_count}`);
+}
+```
+
+**Enhanced Gateway Metrics Features:**
+- Storage usage tracking (percentage, total, free space)
+- Network bandwidth monitoring (RX/TX rates)
+- Active connection counting
+- Error and warning counters (24-hour rolling window)
+- Restart tracking with reason codes
+- All metrics are optional for gradual firmware adoption
+
+## OTA Firmware Management (v0.7.0+)
+
+Comprehensive best-in-class OTA solution based on 2024 industry standards.
+
+### OTA Manifest Schema
+
+The package includes OTA firmware manifest schema with both rich and minimal formats, enhanced with enterprise-grade features.
 
 **Preferred: Stable alias import** (v0.3.1+):
 ```ts
@@ -184,6 +334,104 @@ Supported formats:
 - **Minimal environment map**: environment → channels mapping  
 - **Chunk variants**: structured objects or SHA256 array
 
+### Enhanced OTA Features (v0.7.0+)
+
+**Security & Authenticity:**
+```ts
+const manifest = {
+  environment: "universal-sensor",
+  branch: "main",
+  manifests: {
+    prod: {
+      build_type: "prod",
+      file: "firmware-v2.0.0.bin",
+      size: 456789,
+      sha256: "a1b2c3...",
+      firmware_version: "2.0.0",
+      built: "2025-10-19T12:00:00Z",
+      ota_url: "https://firmware.example.com/v2.0.0.bin",
+      
+      // Digital signature for authenticity
+      signature: "MEUCIQDx...",
+      signature_algorithm: "ECDSA-SHA256",
+      signing_key_id: "prod-signing-key-2025",
+      
+      // Version constraints
+      min_version: "1.5.0",        // Minimum version to upgrade from
+      max_version: "1.9.99",       // Prevent downgrades
+      
+      // Release management
+      release_notes_url: "https://docs.example.com/v2.0.0",
+      criticality: "high",          // low | medium | high | critical
+      mandatory: true,              // Must be installed
+      
+      // Staged rollout
+      rollout_percentage: 25,       // Start with 25% of fleet
+      rollout_target_groups: ["beta-testers", "early-adopters"],
+      
+      // Delta updates (60-90% bandwidth reduction)
+      delta_from_version: "1.9.0",
+      delta_patch_url: "https://firmware.example.com/patches/1.9.0-to-2.0.0.patch",
+      delta_patch_size: 45678,
+      delta_patch_sha256: "c3d4e5..."
+    }
+  }
+};
+```
+
+**Firmware Update Status Tracking:**
+```ts
+import { validators, isFirmwareStatusMessage } from '@alteriom/mqtt-schema';
+
+// Enhanced status tracking
+const status = {
+  schema_version: 1,
+  device_id: "SN789",
+  device_type: "sensor",
+  timestamp: new Date().toISOString(),
+  firmware_version: "2.0.0",
+  
+  status: "downloading",           // New: rolled_back, rollback_pending, rollback_failed
+  progress_pct: 42,
+  
+  // Progress details
+  download_speed_kbps: 125.5,
+  bytes_downloaded: 196608,
+  bytes_total: 456789,
+  eta_seconds: 28,
+  
+  // Rollback support
+  rollback_available: true,
+  previous_version: "1.9.0",
+  
+  // Security verification
+  update_type: "delta",            // full | delta | patch
+  signature_verified: true,
+  checksum_verified: true,
+  
+  // Operational context
+  battery_level_pct: 85,
+  free_space_kb: 2048,
+  retry_count: 0
+};
+
+const result = validators.firmwareStatus(status);
+if (result.valid) {
+  console.log(`Download progress: ${status.progress_pct}% at ${status.download_speed_kbps} kbps`);
+  console.log(`ETA: ${status.eta_seconds} seconds`);
+}
+```
+
+**OTA Best Practices:**
+- **Security**: Always use digital signatures for production firmware
+- **Rollback**: Maintain backup partition for automatic rollback on failures
+- **Delta Updates**: Use delta patches for bandwidth-constrained deployments (60-90% reduction)
+- **Staged Rollout**: Start with 5-10% rollout, monitor, then expand gradually
+- **Version Control**: Use min_version to prevent upgrades from incompatible versions
+- **Criticality**: Mark security patches as "critical" with mandatory: true
+
+See `docs/OTA_MANIFEST.md` for comprehensive guide and best practices.
+
 ## API Surface
 
 ```ts

package/dist/cjs/generated/types.d.ts

@@ -1,9 +1,24 @@
 /**
  * Auto-generated TypeScript types for Alteriom MQTT Schema v1
  * Source: docs/mqtt_schema/*.schema.json
- * Generation Date: 2025-09-20
+ * Generation Date: 2025-10-19
  * NOTE: This file is maintained in firmware repo for UI alignment. Changes require coordinated review.
  */
+export interface LocationInfo {
+    latitude?: number;
+    longitude?: number;
+    altitude?: number;
+    accuracy_m?: number;
+    zone?: string;
+    description?: string;
+    [k: string]: unknown;
+}
+export interface EnvironmentInfo {
+    deployment_type?: 'indoor' | 'outdoor' | 'mobile' | 'mixed';
+    power_source?: 'battery' | 'mains' | 'solar' | 'mixed' | 'other';
+    expected_battery_life_days?: number;
+    [k: string]: unknown;
+}
 export interface BaseEnvelope {
     schema_version: 1;
     device_id: string;
@@ -11,6 +26,8 @@ export interface BaseEnvelope {
     timestamp: string;
     firmware_version?: string;
     hardware_version?: string;
+    location?: LocationInfo;
+    environment?: EnvironmentInfo;
     [k: string]: unknown;
 }
 export interface SensorEntry {
@@ -22,6 +39,14 @@ export interface SensorEntry {
     name?: string;
     location?: string;
     additional_data?: Record<string, unknown>;
+    timestamp?: string;
+    accuracy?: number;
+    last_calibration?: string;
+    error_margin_pct?: number;
+    operational_range?: {
+        min: number;
+        max: number;
+    };
     [k: string]: unknown;
 }
 export interface SensorDataMessage extends BaseEnvelope {
@@ -67,6 +92,16 @@ export interface GatewayMetricsMessage extends BaseEnvelope {
         mesh_nodes?: number;
         packet_loss_pct?: number;
         data_throughput_kbps?: number;
+        storage_usage_pct?: number;
+        storage_total_mb?: number;
+        storage_free_mb?: number;
+        network_rx_kbps?: number;
+        network_tx_kbps?: number;
+        active_connections?: number;
+        error_count_24h?: number;
+        warning_count_24h?: number;
+        restart_count?: number;
+        last_restart_reason?: string;
         [k: string]: unknown;
     };
 }

package/dist/cjs/generated/types.js

@@ -2,7 +2,7 @@
 /**
  * Auto-generated TypeScript types for Alteriom MQTT Schema v1
  * Source: docs/mqtt_schema/*.schema.json
- * Generation Date: 2025-09-20
+ * Generation Date: 2025-10-19
  * NOTE: This file is maintained in firmware repo for UI alignment. Changes require coordinated review.
  */
 Object.defineProperty(exports, "__esModule", { value: true });