homebridge-securitysystem 0.0.1-matter

package/src/interfaces/options-interface.ts

@@ -0,0 +1,116 @@
+/** A single custom trip switch entry with a user-defined label. */
+export interface TripModeSwitch {
+  label: string;
+}
+
+/** Fully-parsed, strongly-typed configuration options for the security system. */
+export interface SecuritySystemOptions {
+  name: string;
+  serialNumber: string;
+  defaultMode: string;
+  armSeconds: number;
+  triggerSeconds: number;
+  resetMinutes: number;
+  saveState: boolean;
+  proxyMode: boolean;
+  testMode: boolean;
+
+  // Switch display names
+  tripSwitchName: string;
+  tripHomeSwitchName: string;
+  tripAwaySwitchName: string;
+  tripNightSwitchName: string;
+  tripOverrideSwitchName: string;
+  modeHomeSwitchName: string;
+  modeAwaySwitchName: string;
+  modeNightSwitchName: string;
+  modeOffSwitchName: string;
+  modeAwayExtendedSwitchName: string;
+  modePauseSwitchName: string;
+
+  // Behaviour toggles
+  overrideOff: boolean;
+  resetOffFlow: boolean;
+  disabledModes: string[];
+
+  // Per-mode arm delays (null = use global armSeconds)
+  homeArmSeconds: number | null;
+  awayArmSeconds: number | null;
+  nightArmSeconds: number | null;
+
+  // Per-mode trigger delays (null = use global triggerSeconds)
+  homeTriggerSeconds: number | null;
+  awayTriggerSeconds: number | null;
+  nightTriggerSeconds: number | null;
+
+  // Trip switches
+  tripSwitch: boolean;
+  tripOverrideSwitch: boolean;
+  tripModeSwitches: boolean;
+
+  // Custom trip mode switches
+  tripHomeSwitches: TripModeSwitch[];
+  tripAwaySwitches: TripModeSwitch[];
+  tripNightSwitches: TripModeSwitch[];
+
+  // Arming lock
+  armingLockSwitch: boolean;
+  armingLockSwitches: boolean;
+
+  // Motion sensors
+  armingMotionSensor: boolean;
+  trippedMotionSensor: boolean;
+  trippedMotionSensorSeconds: number;
+  resetSensor: boolean;
+
+  // Mode switches
+  modeSwitches: boolean;
+  modeOffSwitch: boolean;
+  modePauseSwitch: boolean;
+  pauseMinutes: number;
+  modeAwayExtendedSwitch: boolean;
+  modeAwayExtendedSwitchTriggerSeconds: number | null;
+
+  // Double-knock
+  doubleKnock: boolean;
+  doubleKnockSeconds: number;
+  doubleKnockModes: string[];
+  homeDoubleKnockSeconds: number | null;
+  awayDoubleKnockSeconds: number | null;
+  nightDoubleKnockSeconds: number | null;
+
+  // Server
+  serverPort: number | null;
+  serverApiKey: string | null;
+
+  // Shell commands
+  commandTargetHome: string | null;
+  commandTargetAway: string | null;
+  commandTargetNight: string | null;
+  commandTargetOff: string | null;
+  commandCurrentHome: string | null;
+  commandCurrentAway: string | null;
+  commandCurrentNight: string | null;
+  commandCurrentOff: string | null;
+  commandCurrentWarning: string | null;
+  commandCurrentTriggered: string | null;
+
+  // Webhooks
+  webhookTargetHome: string | null;
+  webhookTargetAway: string | null;
+  webhookTargetNight: string | null;
+  webhookTargetOff: string | null;
+  webhookCurrentHome: string | null;
+  webhookCurrentAway: string | null;
+  webhookCurrentNight: string | null;
+  webhookCurrentOff: string | null;
+  webhookCurrentWarning: string | null;
+  webhookCurrentTriggered: string | null;
+
+  // MQTT
+  mqttBroker: string | null;
+  mqttUsername: string | null;
+  mqttPassword: string | null;
+  mqttTopic: string;
+  mqttClientId: string | null;
+}

package/src/interfaces/persisted-state-interface.ts

@@ -0,0 +1,7 @@
+import type { SecurityState } from '../types/security-state-type.js';
+
+/** Subset of SystemState that is persisted across Homebridge restarts. */
+export interface PersistedState {
+  currentState: SecurityState;
+  targetState: SecurityState;
+}

package/src/interfaces/service-registry-interface.ts

@@ -0,0 +1,11 @@
+import type { Service } from 'homebridge';
+
+/**
+ * HomeKit services exposed by the security system accessory.
+ * Switches and motion sensors are published over Matter only, so the HomeKit
+ * accessory carries just the security system itself.
+ */
+export interface ServiceRegistry {
+  mainService: Service;
+  accessoryInfoService: Service;
+}

package/src/interfaces/system-state-interface.ts

@@ -0,0 +1,25 @@
+import type { SecurityState } from '../types/security-state-type.js';
+
+/** Mutable runtime state shared across all handlers. */
+export interface SystemState {
+  currentState: SecurityState;
+  targetState: SecurityState;
+  defaultState: SecurityState;
+  availableTargetStates: SecurityState[];
+
+  isArming: boolean;
+  isTripping: boolean;
+  isKnocked: boolean;
+  serverAuthenticationAttempts: number;
+  pausedCurrentState: SecurityState | null;
+
+  /** Arming-lock switch state. Switches are Matter-only, so the lock state lives here (was held by HAP characteristics). */
+  armingLocks: {
+    global: boolean;
+    home: boolean;
+    away: boolean;
+    night: boolean;
+  };
+  /** True while armed away via the away-extended switch; resets on any target state change. */
+  modeAwayExtended: boolean;
+}

package/src/schemas/arming-lock-schema.ts

@@ -0,0 +1,12 @@
+import { z } from '@hono/zod-openapi';
+
+export const ArmingLockRequestSchema = z
+  .object({
+    mode: z
+      .enum(['global', 'home', 'away', 'night'])
+      .openapi({ example: 'home', description: 'Arming lock mode to update' }),
+    value: z
+      .boolean()
+      .openapi({ example: true, description: 'True to enable the arming lock, false to disable it' }),
+  })
+  .openapi('ArmingLockRequest');

package/src/schemas/error-schema.ts

@@ -0,0 +1,7 @@
+import { z } from '@hono/zod-openapi';
+
+export const ErrorSchema = z
+  .object({
+    reason: z.string().openapi({ example: 'API key invalid' }),
+  })
+  .openapi('Error');

package/src/schemas/mode-request-schema.ts

@@ -0,0 +1,18 @@
+import { z } from '@hono/zod-openapi';
+
+export const ModeRequestSchema = z
+  .object({
+    mode: z
+      .enum(['home', 'away', 'night', 'off'])
+      .openapi({ example: 'home', description: 'Target mode to activate (home, away, night, or off)' }),
+    delay: z
+      .number()
+      .int()
+      .nonnegative()
+      .optional()
+      .openapi({
+        example: 5,
+        description: 'Optional delay in seconds before applying the mode change',
+      }),
+  })
+  .openapi('ModeRequest');

package/src/schemas/status-response-schema.ts

@@ -0,0 +1,10 @@
+import { z } from '@hono/zod-openapi';
+
+export const StatusResponseSchema = z
+  .object({
+    arming: z.boolean().openapi({ example: false, description: 'Whether the system is currently arming' }),
+    current_mode: z.string().openapi({ example: 'off', description: 'The current active mode' }),
+    target_mode: z.string().openapi({ example: 'home', description: 'The target mode being transitioned to' }),
+    tripped: z.boolean().openapi({ example: false, description: 'Whether a trip switch is active' }),
+  })
+  .openapi('StatusResponse');

package/src/schemas/trip-mode-request-schema.ts

@@ -0,0 +1,24 @@
+import { z } from '@hono/zod-openapi';
+
+export const TripModeRequestSchema = z
+  .object({
+    mode: z
+      .enum(['home', 'away', 'night'])
+      .nullable()
+      .optional()
+      .openapi({
+        example: 'home',
+        description: 'Mode to trip. If omitted or null, the action applies to all modes.',
+      }),
+    delay: z
+      .number()
+      .int()
+      .nonnegative()
+      .nullable()
+      .optional()
+      .openapi({
+        example: 5,
+        description: 'Delay in seconds before activating the alarm.',
+      }),
+  })
+  .openapi('TripModeRequest');

package/src/security-system-platform.ts

@@ -0,0 +1,68 @@
+import type { API, DynamicPlatformPlugin, Logging, MatterAccessory, PlatformAccessory, PlatformConfig } from 'homebridge';
+import { SecuritySystem } from './security-system.js';
+
+const PLUGIN_NAME = 'homebridge-securitysystem';
+const PLATFORM_NAME = 'security-system';
+
+/**
+ * Homebridge dynamic platform that exposes the security system as a
+ * platform accessory. The accessory UUID is stable so the same HomeKit
+ * accessory is restored across restarts via homebridge's accessory cache.
+ * Optional switch/sensor accessories are additionally published over Matter
+ * when Matter is enabled on the bridge.
+ */
+export class SecuritySystemPlatform implements DynamicPlatformPlugin {
+  private readonly cachedAccessories = new Map<string, PlatformAccessory>();
+  private readonly cachedMatterAccessories = new Map<string, MatterAccessory>();
+
+  constructor(
+    private readonly log: Logging,
+    private readonly config: PlatformConfig,
+    private readonly api: API,
+  ) {
+    this.api.on('didFinishLaunching', () => this.setupAccessories());
+  }
+
+  configureAccessory(accessory: PlatformAccessory): void {
+    this.cachedAccessories.set(accessory.UUID, accessory);
+  }
+
+  configureMatterAccessory(accessory: MatterAccessory): void {
+    this.cachedMatterAccessories.set(accessory.UUID, accessory);
+  }
+
+  private setupAccessories(): void {
+    const uuid = this.api.hap.uuid.generate(PLATFORM_NAME);
+
+    const cached = this.cachedAccessories.get(uuid);
+    let system: SecuritySystem;
+
+    if (cached) {
+      this.cachedAccessories.delete(uuid);
+      this.log.info('Restoring cached accessory:', cached.displayName);
+      system = new SecuritySystem(this.log, this.config, this.api, cached);
+      this.api.updatePlatformAccessories([cached]);
+    } else {
+      const accessory = new this.api.platformAccessory(
+        'Security System',
+        uuid,
+        this.api.hap.Categories.SECURITY_SYSTEM,
+      );
+      system = new SecuritySystem(this.log, this.config, this.api, accessory);
+      this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory]);
+
+      // Remove any cached accessories that are no longer configured.
+      for (const stale of this.cachedAccessories.values()) {
+        this.log.info('Removing unconfigured accessory:', stale.displayName);
+        this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [stale]);
+      }
+    }
+
+    // Publish the configured Matter accessories (no-op when Matter is disabled).
+    system.setupMatterAccessories(this.cachedMatterAccessories).catch((error: unknown) => {
+      this.log.error('Failed to register Matter accessories.');
+      this.log.error(String(error));
+    });
+  }
+}
+

package/src/security-system.ts

@@ -0,0 +1,199 @@
+import type { API, Logging, MatterAccessory, PlatformAccessory, Service } from 'homebridge';
+import type { CharacteristicConstructor } from './interfaces/hap-types-interface.js';
+import { SecurityState } from './types/security-state-type.js';
+import { OriginType } from './types/origin-type.js';
+import { ConfigurationService } from './services/configuration-service.js';
+import { stateToMode, modeToState } from './utils/state-util.js';
+import type { SecuritySystemOptions } from './interfaces/options-interface.js';
+import type { SystemState } from './interfaces/system-state-interface.js';
+import type { ServiceRegistry } from './interfaces/service-registry-interface.js';
+import { EventBusService } from './services/event-bus-service.js';
+import { EventType } from './types/event-type.js';
+import { StorageService } from './services/storage-service.js';
+import { WebhookService } from './services/webhook-service.js';
+import { CommandService } from './services/command-service.js';
+import { MqttService } from './services/mqtt-service.js';
+import { MatterService } from './services/matter-service.js';
+import { ServerService } from './services/server-service.js';
+import { StateHandler } from './handlers/state-handler.js';
+import { TripHandler } from './handlers/trip-handler.js';
+import { SwitchHandler } from './handlers/switch-handler.js';
+import { SensorHandler } from './handlers/sensor-handler.js';
+import { buildServiceRegistry, buildServiceList } from './homekit/service-factory.js';
+import { HomeKitRegistrar } from './homekit/homekit-registrar.js';
+import { TimerManager } from './timers/timer-manager.js';
+
+export class SecuritySystem {
+  private readonly options: SecuritySystemOptions;
+  private readonly state: SystemState;
+  private readonly svcs: ServiceRegistry;
+  private readonly serviceList: Service[];
+
+  private readonly bus: EventBusService;
+  private readonly stateHandler: StateHandler;
+  private readonly tripHandler: TripHandler;
+  private readonly switchHandler: SwitchHandler;
+  private readonly sensorHandler: SensorHandler;
+  private readonly storageService: StorageService;
+  private readonly matterService: MatterService;
+
+  constructor(
+    private readonly log: Logging,
+    config: Record<string, unknown>,
+    private readonly api: API,
+    private readonly accessory: PlatformAccessory,
+  ) {
+    const Char = api.hap.Characteristic as CharacteristicConstructor;
+    const Svc = api.hap.Service as typeof Service;
+
+    this.options = new ConfigurationService(log, config).options;
+
+    const defaultState = modeToState(this.options.defaultMode);
+    this.state = this.buildState(defaultState === (-1 as SecurityState) ? SecurityState.OFF : defaultState);
+
+    this.svcs = buildServiceRegistry(Svc, Char, this.options);
+    this.state.availableTargetStates = this.calcAvailableTargetStates();
+
+    // Sync main service initial values.
+    this.svcs.mainService.getCharacteristic(Char.SecuritySystemTargetState).value = this.state.targetState;
+    this.svcs.mainService.getCharacteristic(Char.SecuritySystemCurrentState).value = this.state.currentState;
+    this.svcs.mainService
+      .setCharacteristic(Char.ConfiguredName, this.options.name)
+      .getCharacteristic(Char.SecuritySystemTargetState)
+      .setProps({ validValues: this.state.availableTargetStates });
+
+    // Services.
+    this.bus = new EventBusService();
+    this.storageService = new StorageService(log, this.options, api.user.storagePath());
+    const timerManager = new TimerManager(log);
+
+    // Handlers — construction order matters: sensorHandler first (leaf), then stateHandler,
+    // then switchHandler (depends on stateHandler), then tripHandler.
+    this.sensorHandler = new SensorHandler(log, this.bus);
+    this.stateHandler = new StateHandler(
+      this.svcs, this.state, this.options, Char, log, this.bus, this.storageService, timerManager, this.sensorHandler,
+    );
+    this.switchHandler = new SwitchHandler(this.state, this.options, log, timerManager, this.stateHandler);
+    this.tripHandler = new TripHandler(
+      this.state, this.options, log, this.bus, this.sensorHandler, timerManager,
+    );
+
+    // Wire bus listeners for cross-handler coordination (no more circular constructor deps).
+    this.bus.on(EventType.TRIGGER_FIRED, ({ origin }) => {
+      this.stateHandler.setCurrentState(SecurityState.TRIGGERED, origin);
+    });
+    this.bus.on(EventType.TRIP_CANCELLED, ({ stateChanged }) => {
+      if (this.state.currentState === SecurityState.TRIGGERED && !stateChanged) {
+        this.stateHandler.updateTargetState(SecurityState.OFF, OriginType.INTERNAL, 0);
+      } else {
+        this.stateHandler.resetTimers();
+      }
+    });
+
+    // Attach side-effect listeners.
+    const webhookSvc = new WebhookService(log, this.options, this.state);
+    const commandSvc = new CommandService(log, this.options, this.state);
+    webhookSvc.attachToBus(this.bus);
+    commandSvc.attachToBus(this.bus);
+    const mqttSvc = new MqttService(log, this.options, this.state);
+    mqttSvc.attachToBus(this.bus);
+    this.api.on('shutdown', () => mqttSvc.disconnect());
+
+    // Publish the optional switch/sensor accessories over Matter (HAP keeps the
+    // main SecuritySystem service and the motion sensors). Registration happens
+    // on the platform after didFinishLaunching, via setupMatterAccessories().
+    this.matterService = new MatterService(log, this.options, api, this.state, this.switchHandler, this.tripHandler, this.sensorHandler);
+    this.matterService.attachToBus(this.bus);
+
+    // Register HomeKit characteristic handlers.
+    new HomeKitRegistrar(this.svcs, this.state, this.stateHandler)
+      .register(Char);
+
+    // Build the exposed service list and host it on the platform accessory.
+    this.serviceList = buildServiceList(this.svcs);
+    this.populateAccessory(Svc);
+    this.accessory.on('identify', () => this.log.info('Identify'));
+
+    // Startup tasks.
+    this.logStartup();
+
+    const syncModeSwitches = (): void => {
+      this.bus.emit(EventType.RESET_MODE_SWITCHES, {});
+      this.bus.emit(EventType.UPDATE_MODE_SWITCHES, {});
+    };
+
+    if (this.options.saveState) {
+      this.storageService.init().then(() => this.storageService.load(this.state).then(() => {
+        this.svcs.mainService.updateCharacteristic(Char.SecuritySystemTargetState, this.state.targetState);
+        this.svcs.mainService.updateCharacteristic(Char.SecuritySystemCurrentState, this.state.currentState);
+        this.stateHandler.logMode('Current', this.state.currentState);
+        syncModeSwitches();
+      }));
+    } else {
+      syncModeSwitches();
+    }
+
+    if (this.options.serverPort !== null) {
+      new ServerService(log, this.options, this.state, this.stateHandler, this.tripHandler, this.switchHandler).start();
+    }
+  }
+
+  // ── Public API ─────────────────────────────────────────────────────────────
+
+  /**
+   * Registers all configured switch/sensor accessories over Matter.
+   * No-op when Matter is disabled on the bridge.
+   */
+  setupMatterAccessories(cachedAccessories: Map<string, MatterAccessory>): Promise<void> {
+    return this.matterService.registerAccessories(cachedAccessories);
+  }
+
+  // ── Private helpers ────────────────────────────────────────────────────────
+
+  /** Replaces the accessory's auto-created information service and adds all exposed services. */
+  private populateAccessory(Svc: typeof Service): void {
+    const existingInfoService = this.accessory.getService(Svc.AccessoryInformation);
+    if (existingInfoService) {
+      this.accessory.removeService(existingInfoService);
+    }
+    this.accessory.updateDisplayName(this.options.name);
+    for (const service of this.serviceList) {
+      this.accessory.addService(service);
+    }
+  }
+
+  private buildState(defaultState: SecurityState): SystemState {
+    return {
+      currentState: defaultState,
+      targetState: defaultState,
+      defaultState,
+      availableTargetStates: [],
+      isArming: false,
+      isTripping: false,
+      isKnocked: false,
+      serverAuthenticationAttempts: 0,
+      pausedCurrentState: null,
+      armingLocks: { global: false, home: false, away: false, night: false },
+      modeAwayExtended: false,
+    };
+  }
+
+  private calcAvailableTargetStates(): SecurityState[] {
+    const all = [SecurityState.HOME, SecurityState.AWAY, SecurityState.NIGHT, SecurityState.OFF];
+    const disabled = this.options.disabledModes.map(m => modeToState(m.toLowerCase()));
+    return all.filter(s => !disabled.includes(s));
+  }
+
+  private logStartup(): void {
+    if (this.options.testMode) {
+      this.log.warn('Test Mode');
+    }
+    stateToMode(this.state.defaultState);
+    this.stateHandler.logMode('Default', this.state.defaultState);
+    this.log.info(`Arm delay (${this.options.armSeconds}s)`);
+    this.log.info(`Trigger delay (${this.options.triggerSeconds}s)`);
+    if (this.options.proxyMode) {
+      this.log.info('Proxy mode (Enabled)');
+    }
+  }
+}

package/src/services/command-service.ts

@@ -0,0 +1,76 @@
+import { spawn } from 'child_process';
+import type { Logging } from 'homebridge';
+import { SecurityState } from '../types/security-state-type.js';
+import { OriginType } from '../types/origin-type.js';
+import { stateToMode } from '../utils/state-util.js';
+import type { SecuritySystemOptions } from '../interfaces/options-interface.js';
+import type { SystemState } from '../interfaces/system-state-interface.js';
+import type { EventBusService } from './event-bus-service.js';
+import { EventType } from '../types/event-type.js';
+
+/** Spawns shell commands in response to state-machine events. */
+export class CommandService {
+  constructor(
+    private readonly log: Logging,
+    private readonly options: SecuritySystemOptions,
+    private readonly state: SystemState,
+  ) {}
+
+  attachToBus(bus: EventBusService): void {
+    bus.on(EventType.TARGET_CHANGED, ({ state, origin }) => {
+      this.execute('target', state, origin);
+    });
+    bus.on(EventType.CURRENT_CHANGED, ({ state, origin }) => {
+      this.execute('current', state, origin);
+    });
+    bus.on(EventType.WARNING, ({ origin }) => {
+      this.execute('current', 'warning' as unknown as SecurityState, origin);
+    });
+  }
+
+  execute(type: string, stateOrMode: SecurityState | string, origin: OriginType): void {
+    if (this.options.proxyMode && origin === OriginType.EXTERNAL) {
+      this.log.debug('Command bypassed (proxy mode).');
+      return;
+    }
+
+    let command = this.resolveCommand(type, stateOrMode);
+    if (!command) {
+      this.log.debug(`Command for ${type}/${stateOrMode} not set.`);
+      return;
+    }
+
+    const currentMode = stateToMode(this.state.currentState);
+    command = command.replace('${currentMode}', currentMode);
+
+    const proc = spawn(command, { shell: true });
+
+    proc.stdout.on('data', (data: Buffer) => {
+      this.log.info(`Command output: ${data.toString().trim()}`);
+    });
+
+    proc.stderr.on('data', (data: Buffer) => {
+      this.log.error(`Command failed (${command})\n${data.toString().trim()}`);
+    });
+  }
+
+  private resolveCommand(type: string, stateOrMode: SecurityState | string): string | null {
+    const s = stateOrMode;
+    const o = this.options;
+
+    if (s === 'warning') {
+      return o.commandCurrentWarning; 
+    }
+
+    switch (s as SecurityState) {
+    case SecurityState.TRIGGERED: return o.commandCurrentTriggered;
+    case SecurityState.HOME: return type === 'current' ? o.commandCurrentHome : o.commandTargetHome;
+    case SecurityState.AWAY: return type === 'current' ? o.commandCurrentAway : o.commandTargetAway;
+    case SecurityState.NIGHT: return type === 'current' ? o.commandCurrentNight : o.commandTargetNight;
+    case SecurityState.OFF: return type === 'current' ? o.commandCurrentOff : o.commandTargetOff;
+    default:
+      this.log.error(`Unknown command state (${s})`);
+      return null;
+    }
+  }
+}