@blueharford/scrypted-spatial-awareness 0.1.0

package/src/main.ts

@@ -0,0 +1,690 @@
+import sdk, {
+  DeviceProvider,
+  DeviceCreator,
+  DeviceCreatorSettings,
+  Settings,
+  Setting,
+  SettingValue,
+  ScryptedDeviceBase,
+  ScryptedDeviceType,
+  ScryptedInterface,
+  ScryptedNativeId,
+  HttpRequestHandler,
+  HttpRequest,
+  HttpResponse,
+  Readme,
+} from '@scrypted/sdk';
+import { StorageSettings } from '@scrypted/sdk/storage-settings';
+import { CameraTopology, createEmptyTopology } from './models/topology';
+import { TrackedObject } from './models/tracked-object';
+import { Alert, AlertRule, createDefaultRules } from './models/alert';
+import { TrackingState } from './state/tracking-state';
+import { TrackingEngine, TrackingEngineConfig } from './core/tracking-engine';
+import { AlertManager } from './alerts/alert-manager';
+import { GlobalTrackerSensor } from './devices/global-tracker-sensor';
+import { TrackingZone } from './devices/tracking-zone';
+import { MqttPublisher, MqttConfig } from './integrations/mqtt-publisher';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const { deviceManager, systemManager } = sdk;
+
+const TRACKING_ZONE_PREFIX = 'tracking-zone:';
+const GLOBAL_TRACKER_ID = 'global-tracker';
+
+export class SpatialAwarenessPlugin extends ScryptedDeviceBase
+  implements DeviceProvider, DeviceCreator, Settings, HttpRequestHandler, Readme {
+
+  private trackingEngine: TrackingEngine | null = null;
+  private trackingState: TrackingState;
+  private alertManager: AlertManager;
+  private mqttPublisher: MqttPublisher | null = null;
+  private devices: Map<string, any> = new Map();
+
+  storageSettings = new StorageSettings(this, {
+    // Topology Configuration (stored as JSON)
+    topology: {
+      title: 'Camera Topology',
+      type: 'string',
+      description: 'JSON configuration of camera relationships',
+      hide: true,
+    },
+
+    // Floor plan image (stored as base64)
+    floorPlanImage: {
+      title: 'Floor Plan Image',
+      type: 'string',
+      hide: true,
+    },
+
+    // Correlation Settings
+    correlationWindow: {
+      title: 'Correlation Window (seconds)',
+      type: 'number',
+      defaultValue: 30,
+      description: 'Maximum time to wait for an object to appear on connected camera',
+      group: 'Tracking',
+    },
+    correlationThreshold: {
+      title: 'Correlation Confidence Threshold',
+      type: 'number',
+      defaultValue: 0.6,
+      description: 'Minimum confidence (0-1) for automatic object correlation',
+      group: 'Tracking',
+    },
+    lostTimeout: {
+      title: 'Lost Object Timeout (seconds)',
+      type: 'number',
+      defaultValue: 300,
+      description: 'Time before marking a tracked object as lost',
+      group: 'Tracking',
+    },
+    useVisualMatching: {
+      title: 'Use Visual Matching',
+      type: 'boolean',
+      defaultValue: true,
+      description: 'Use visual embeddings for object correlation (requires compatible detectors)',
+      group: 'Tracking',
+    },
+
+    // MQTT Settings
+    enableMqtt: {
+      title: 'Enable MQTT',
+      type: 'boolean',
+      defaultValue: false,
+      group: 'MQTT Integration',
+    },
+    mqttBroker: {
+      title: 'MQTT Broker URL',
+      type: 'string',
+      placeholder: 'mqtt://localhost:1883',
+      group: 'MQTT Integration',
+    },
+    mqttUsername: {
+      title: 'MQTT Username',
+      type: 'string',
+      group: 'MQTT Integration',
+    },
+    mqttPassword: {
+      title: 'MQTT Password',
+      type: 'password',
+      group: 'MQTT Integration',
+    },
+    mqttBaseTopic: {
+      title: 'MQTT Base Topic',
+      type: 'string',
+      defaultValue: 'scrypted/spatial-awareness',
+      group: 'MQTT Integration',
+    },
+
+    // Alert Settings
+    enableAlerts: {
+      title: 'Enable Alerts',
+      type: 'boolean',
+      defaultValue: true,
+      group: 'Alerts',
+    },
+    defaultNotifier: {
+      title: 'Default Notifier',
+      type: 'device',
+      deviceFilter: `interfaces.includes('${ScryptedInterface.Notifier}')`,
+      group: 'Alerts',
+    },
+
+    // Tracked Cameras
+    trackedCameras: {
+      title: 'Cameras to Track',
+      type: 'device',
+      multiple: true,
+      deviceFilter: `interfaces.includes('${ScryptedInterface.ObjectDetector}')`,
+      group: 'Cameras',
+      description: 'Select cameras with object detection to track',
+    },
+
+    // Alert Rules (stored as JSON)
+    alertRules: {
+      title: 'Alert Rules',
+      type: 'string',
+      hide: true,
+    },
+  });
+
+  constructor(nativeId?: ScryptedNativeId) {
+    super(nativeId);
+
+    this.trackingState = new TrackingState(this.storage, this.console);
+    this.alertManager = new AlertManager(this.console, this.storage);
+
+    // Initialize on next tick to allow Scrypted to fully load
+    process.nextTick(() => this.initialize());
+  }
+
+  private async initialize(): Promise<void> {
+    this.console.log('Initializing Spatial Awareness Plugin');
+
+    // Discover the global tracker device
+    await deviceManager.onDeviceDiscovered({
+      nativeId: GLOBAL_TRACKER_ID,
+      name: 'Global Object Tracker',
+      type: ScryptedDeviceType.Sensor,
+      interfaces: [
+        ScryptedInterface.OccupancySensor,
+        ScryptedInterface.Settings,
+        ScryptedInterface.Readme,
+      ],
+    });
+
+    // Load topology if it exists
+    const topologyJson = this.storage.getItem('topology');
+    if (topologyJson) {
+      try {
+        const topology = JSON.parse(topologyJson) as CameraTopology;
+        await this.startTrackingEngine(topology);
+      } catch (e) {
+        this.console.error('Failed to parse topology:', e);
+      }
+    }
+
+    // Load alert rules
+    const rulesJson = this.storage.getItem('alertRules');
+    if (rulesJson) {
+      try {
+        const rules = JSON.parse(rulesJson) as AlertRule[];
+        this.alertManager.setRules(rules);
+      } catch (e) {
+        this.console.error('Failed to parse alert rules:', e);
+        this.alertManager.setRules(createDefaultRules());
+      }
+    } else {
+      this.alertManager.setRules(createDefaultRules());
+    }
+
+    // Initialize MQTT if enabled
+    if (this.storageSettings.values.enableMqtt) {
+      await this.initializeMqtt();
+    }
+
+    this.console.log('Spatial Awareness Plugin initialized');
+  }
+
+  private async initializeMqtt(): Promise<void> {
+    const broker = this.storageSettings.values.mqttBroker as string;
+    if (!broker) {
+      this.console.warn('MQTT enabled but no broker URL configured');
+      return;
+    }
+
+    const config: MqttConfig = {
+      broker,
+      username: this.storageSettings.values.mqttUsername as string,
+      password: this.storageSettings.values.mqttPassword as string,
+      baseTopic: this.storageSettings.values.mqttBaseTopic as string || 'scrypted/spatial-awareness',
+    };
+
+    this.mqttPublisher = new MqttPublisher(config, this.console);
+    await this.mqttPublisher.connect();
+
+    // Subscribe to state changes
+    this.trackingState.onStateChange((objects) => {
+      this.mqttPublisher?.publishState(objects);
+    });
+
+    this.console.log('MQTT publisher initialized');
+  }
+
+  private async startTrackingEngine(topology: CameraTopology): Promise<void> {
+    // Stop existing engine if running
+    if (this.trackingEngine) {
+      await this.trackingEngine.stopTracking();
+    }
+
+    const config: TrackingEngineConfig = {
+      correlationWindow: (this.storageSettings.values.correlationWindow as number || 30) * 1000,
+      correlationThreshold: this.storageSettings.values.correlationThreshold as number || 0.6,
+      lostTimeout: (this.storageSettings.values.lostTimeout as number || 300) * 1000,
+      useVisualMatching: this.storageSettings.values.useVisualMatching as boolean ?? true,
+    };
+
+    this.trackingEngine = new TrackingEngine(
+      topology,
+      this.trackingState,
+      this.alertManager,
+      config,
+      this.console
+    );
+
+    await this.trackingEngine.startTracking();
+    this.console.log('Tracking engine started');
+  }
+
+  // ==================== DeviceProvider Implementation ====================
+
+  async getDevice(nativeId: string): Promise<any> {
+    let device = this.devices.get(nativeId);
+
+    if (!device) {
+      if (nativeId === GLOBAL_TRACKER_ID) {
+        device = new GlobalTrackerSensor(this, nativeId, this.trackingState);
+      } else if (nativeId.startsWith(TRACKING_ZONE_PREFIX)) {
+        device = new TrackingZone(this, nativeId, this.trackingState);
+      }
+
+      if (device) {
+        this.devices.set(nativeId, device);
+      }
+    }
+
+    return device;
+  }
+
+  async releaseDevice(id: string, nativeId: string): Promise<void> {
+    this.devices.delete(nativeId);
+  }
+
+  // ==================== DeviceCreator Implementation ====================
+
+  async getCreateDeviceSettings(): Promise<Setting[]> {
+    return [
+      {
+        key: 'name',
+        title: 'Zone Name',
+        description: 'Name for this tracking zone',
+        type: 'string',
+      },
+      {
+        key: 'type',
+        title: 'Zone Type',
+        type: 'string',
+        choices: ['entry', 'exit', 'dwell', 'restricted'],
+        value: 'entry',
+      },
+      {
+        key: 'cameras',
+        title: 'Cameras',
+        type: 'device',
+        multiple: true,
+        deviceFilter: `interfaces.includes('${ScryptedInterface.ObjectDetector}')`,
+      },
+    ];
+  }
+
+  async createDevice(settings: DeviceCreatorSettings): Promise<string> {
+    const nativeId = TRACKING_ZONE_PREFIX + Date.now().toString();
+
+    await deviceManager.onDeviceDiscovered({
+      nativeId,
+      name: (settings.name as string) || 'Tracking Zone',
+      type: ScryptedDeviceType.Sensor,
+      interfaces: [
+        ScryptedInterface.OccupancySensor,
+        ScryptedInterface.MotionSensor,
+        ScryptedInterface.Settings,
+      ],
+    });
+
+    // Store zone configuration
+    this.storage.setItem(`zone:${nativeId}`, JSON.stringify({
+      type: settings.type,
+      cameras: settings.cameras,
+    }));
+
+    return nativeId;
+  }
+
+  // ==================== Settings Implementation ====================
+
+  async getSettings(): Promise<Setting[]> {
+    const settings = await this.storageSettings.getSettings();
+
+    // Add topology editor button
+    settings.push({
+      key: 'openTopologyEditor',
+      title: 'Open Topology Editor',
+      type: 'button',
+      description: 'Configure camera relationships and transit paths with visual floor plan',
+      group: 'Cameras',
+    });
+
+    // Add status display
+    const activeCount = this.trackingState.getActiveCount();
+    settings.push({
+      key: 'status',
+      title: 'Tracking Status',
+      type: 'string',
+      readonly: true,
+      value: this.trackingEngine
+        ? `Active: Tracking ${activeCount} object${activeCount !== 1 ? 's' : ''}`
+        : 'Not configured - add cameras and configure topology',
+      group: 'Status',
+    });
+
+    // Add recent alerts summary
+    const recentAlerts = this.alertManager.getRecentAlerts(5);
+    if (recentAlerts.length > 0) {
+      settings.push({
+        key: 'recentAlerts',
+        title: 'Recent Alerts',
+        type: 'string',
+        readonly: true,
+        value: recentAlerts.map(a => `${a.type}: ${a.message}`).join('\n'),
+        group: 'Status',
+      });
+    }
+
+    return settings;
+  }
+
+  async putSetting(key: string, value: SettingValue): Promise<void> {
+    if (key === 'openTopologyEditor') {
+      // The UI will handle opening the editor via HTTP
+      this.console.log('Topology editor requested - access via plugin HTTP endpoint');
+      return;
+    }
+
+    await this.storageSettings.putSetting(key, value);
+
+    // Handle setting changes that require engine restart
+    if (
+      key === 'trackedCameras' ||
+      key === 'correlationWindow' ||
+      key === 'correlationThreshold' ||
+      key === 'lostTimeout' ||
+      key === 'useVisualMatching'
+    ) {
+      const topologyJson = this.storage.getItem('topology');
+      if (topologyJson) {
+        try {
+          const topology = JSON.parse(topologyJson) as CameraTopology;
+          await this.startTrackingEngine(topology);
+        } catch (e) {
+          this.console.error('Failed to restart tracking engine:', e);
+        }
+      }
+    }
+
+    // Handle MQTT setting changes
+    if (key === 'enableMqtt' || key === 'mqttBroker' || key === 'mqttUsername' ||
+        key === 'mqttPassword' || key === 'mqttBaseTopic') {
+      if (this.mqttPublisher) {
+        this.mqttPublisher.disconnect();
+        this.mqttPublisher = null;
+      }
+      if (this.storageSettings.values.enableMqtt) {
+        await this.initializeMqtt();
+      }
+    }
+  }
+
+  // ==================== HttpRequestHandler Implementation ====================
+
+  async onRequest(request: HttpRequest, response: HttpResponse): Promise<void> {
+    const url = new URL(request.url!, 'http://localhost');
+    const path = url.pathname;
+
+    try {
+      // API Routes
+      if (path.endsWith('/api/tracked-objects')) {
+        return this.handleTrackedObjectsRequest(request, response);
+      }
+
+      if (path.match(/\/api\/journey\/[\w-]+$/)) {
+        const globalId = path.split('/').pop()!;
+        return this.handleJourneyRequest(globalId, response);
+      }
+
+      if (path.endsWith('/api/topology')) {
+        return this.handleTopologyRequest(request, response);
+      }
+
+      if (path.endsWith('/api/alerts')) {
+        return this.handleAlertsRequest(request, response);
+      }
+
+      if (path.endsWith('/api/floor-plan')) {
+        return this.handleFloorPlanRequest(request, response);
+      }
+
+      // UI Routes
+      if (path.endsWith('/ui/editor') || path.endsWith('/ui/editor/')) {
+        return this.serveEditorUI(response);
+      }
+
+      if (path.includes('/ui/')) {
+        return this.serveStaticFile(path, response);
+      }
+
+      // Default: return info page
+      response.send(JSON.stringify({
+        name: 'Spatial Awareness Plugin',
+        version: '0.1.0',
+        endpoints: {
+          api: {
+            trackedObjects: '/api/tracked-objects',
+            journey: '/api/journey/{globalId}',
+            topology: '/api/topology',
+            alerts: '/api/alerts',
+            floorPlan: '/api/floor-plan',
+          },
+          ui: {
+            editor: '/ui/editor',
+          },
+        },
+      }), {
+        headers: { 'Content-Type': 'application/json' },
+      });
+    } catch (e) {
+      this.console.error('HTTP request error:', e);
+      response.send(JSON.stringify({ error: (e as Error).message }), {
+        code: 500,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+  }
+
+  private handleTrackedObjectsRequest(request: HttpRequest, response: HttpResponse): void {
+    const objects = this.trackingState.getAllObjects();
+    response.send(JSON.stringify(objects), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  private handleJourneyRequest(globalId: string, response: HttpResponse): void {
+    const tracked = this.trackingState.getObject(globalId);
+    if (tracked) {
+      response.send(JSON.stringify({
+        globalId: tracked.globalId,
+        className: tracked.className,
+        label: tracked.label,
+        journey: tracked.journey,
+        sightings: tracked.sightings.map(s => ({
+          cameraId: s.cameraId,
+          cameraName: s.cameraName,
+          timestamp: s.timestamp,
+        })),
+        firstSeen: tracked.firstSeen,
+        lastSeen: tracked.lastSeen,
+        state: tracked.state,
+      }), {
+        headers: { 'Content-Type': 'application/json' },
+      });
+    } else {
+      response.send(JSON.stringify({ error: 'Object not found' }), {
+        code: 404,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+  }
+
+  private handleTopologyRequest(request: HttpRequest, response: HttpResponse): void {
+    if (request.method === 'GET') {
+      const topologyJson = this.storage.getItem('topology');
+      const topology = topologyJson ? JSON.parse(topologyJson) : createEmptyTopology();
+      response.send(JSON.stringify(topology), {
+        headers: { 'Content-Type': 'application/json' },
+      });
+    } else if (request.method === 'PUT' || request.method === 'POST') {
+      try {
+        const topology = JSON.parse(request.body!) as CameraTopology;
+        this.storage.setItem('topology', JSON.stringify(topology));
+        this.startTrackingEngine(topology);
+        response.send(JSON.stringify({ success: true }), {
+          headers: { 'Content-Type': 'application/json' },
+        });
+      } catch (e) {
+        response.send(JSON.stringify({ error: 'Invalid topology JSON' }), {
+          code: 400,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+    }
+  }
+
+  private handleAlertsRequest(request: HttpRequest, response: HttpResponse): void {
+    const alerts = this.alertManager.getRecentAlerts();
+    response.send(JSON.stringify(alerts), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  private handleFloorPlanRequest(request: HttpRequest, response: HttpResponse): void {
+    if (request.method === 'GET') {
+      const imageData = this.storage.getItem('floorPlanImage');
+      if (imageData) {
+        response.send(JSON.stringify({ imageData }), {
+          headers: { 'Content-Type': 'application/json' },
+        });
+      } else {
+        response.send(JSON.stringify({ imageData: null }), {
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+    } else if (request.method === 'POST') {
+      try {
+        const body = JSON.parse(request.body!);
+        this.storage.setItem('floorPlanImage', body.imageData);
+        response.send(JSON.stringify({ success: true }), {
+          headers: { 'Content-Type': 'application/json' },
+        });
+      } catch (e) {
+        response.send(JSON.stringify({ error: 'Invalid request body' }), {
+          code: 400,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+    }
+  }
+
+  private serveEditorUI(response: HttpResponse): void {
+    // Try to read the editor HTML from the bundled file
+    try {
+      const editorPath = path.join(__dirname, 'ui', 'editor.html');
+      const html = fs.readFileSync(editorPath, 'utf-8');
+      response.send(html, {
+        headers: { 'Content-Type': 'text/html' },
+      });
+    } catch (e) {
+      this.console.error('Failed to load editor UI:', e);
+      // Fallback to basic UI
+      const html = `
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Spatial Awareness - Topology Editor</title>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; margin: 0; padding: 20px; background: #1a1a1a; color: #fff; }
+    h1 { margin-top: 0; }
+    .container { max-width: 1200px; margin: 0 auto; }
+    .btn { background: #0066cc; color: #fff; border: none; padding: 10px 20px; border-radius: 4px; cursor: pointer; font-size: 14px; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>Spatial Awareness - Topology Editor</h1>
+    <p>Error loading visual editor. Configure topology via REST API: <code>PUT /api/topology</code></p>
+    <h3>Current Topology</h3>
+    <pre id="topology-json" style="background: #2a2a2a; padding: 15px; border-radius: 4px; overflow: auto;"></pre>
+  </div>
+  <script>
+    fetch('api/topology').then(r => r.json()).then(data => {
+      document.getElementById('topology-json').textContent = JSON.stringify(data, null, 2);
+    });
+  </script>
+</body>
+</html>`;
+      response.send(html, {
+        headers: { 'Content-Type': 'text/html' },
+      });
+    }
+  }
+
+  private serveStaticFile(path: string, response: HttpResponse): void {
+    // Serve static files for the UI
+    response.send('Not found', { code: 404 });
+  }
+
+  // ==================== Readme Implementation ====================
+
+  async getReadmeMarkdown(): Promise<string> {
+    return `
+# Spatial Awareness Plugin
+
+This plugin enables cross-camera object tracking across your entire NVR system.
+
+## Features
+
+- **Cross-Camera Tracking**: Correlate objects as they move between cameras
+- **Journey History**: Complete path history for each tracked object
+- **Entry/Exit Detection**: Know when objects enter or leave your property
+- **Visual Floor Plan**: Configure camera topology with a visual editor
+- **MQTT Integration**: Export tracking data to Home Assistant
+- **REST API**: Query tracked objects and journeys programmatically
+- **Smart Alerts**: Get notified about property entry/exit, unusual paths, and more
+
+## Setup
+
+1. **Add Cameras**: Select cameras with object detection in the plugin settings
+2. **Configure Topology**: Define camera relationships and transit times
+3. **Enable Integrations**: Optionally enable MQTT for Home Assistant
+4. **Create Zones**: Add tracking zones for specific area monitoring
+
+## API Endpoints
+
+- \`GET /api/tracked-objects\` - List all tracked objects
+- \`GET /api/journey/{id}\` - Get journey for specific object
+- \`GET /api/topology\` - Get camera topology
+- \`PUT /api/topology\` - Update camera topology
+- \`GET /api/alerts\` - Get recent alerts
+
+## Visual Editor
+
+Access the visual topology editor at \`/ui/editor\` to configure camera relationships using a floor plan.
+
+## Alert Types
+
+- **Property Entry**: Object entered the property
+- **Property Exit**: Object exited the property
+- **Unusual Path**: Object took an unexpected route
+- **Dwell Time**: Object lingered too long in an area
+- **Restricted Zone**: Object entered a restricted area
+`;
+  }
+
+  // ==================== Public Methods for Child Devices ====================
+
+  getTrackingState(): TrackingState {
+    return this.trackingState;
+  }
+
+  getAlertManager(): AlertManager {
+    return this.alertManager;
+  }
+
+  getTopology(): CameraTopology | null {
+    const topologyJson = this.storage.getItem('topology');
+    return topologyJson ? JSON.parse(topologyJson) : null;
+  }
+}
+
+export default SpatialAwarenessPlugin;