homebridge-securitysystem 9.1.2 → 10.0.0-beta.2

package/src/handlers/sensor-handler.ts

@@ -0,0 +1,81 @@
+import type { Logging } from 'homebridge';
+import { SENSOR_PULSE_MS } from '../constants/homekit-constant.js';
+import type { ServiceRegistry } from '../interfaces/service-registry-interface.js';
+import type { CharacteristicConstructor } from '../interfaces/hap-types-interface.js';
+
+/** Manages all motion sensor characteristic updates. */
+export class SensorHandler {
+  constructor(
+    private readonly services: ServiceRegistry,
+    private readonly Characteristic: CharacteristicConstructor,
+    private readonly log: Logging,
+  ) {}
+
+  // ── Arming sensor ──────────────────────────────────────────────────────────
+
+  updateArmingMotionSensor(value: boolean): void {
+    this.services.armingMotionSensorService.updateCharacteristic(
+      this.Characteristic.MotionDetected,
+      value,
+    );
+  }
+
+  resetArmingMotionSensor(): void {
+    const current = this.services.armingMotionSensorService
+      .getCharacteristic(this.Characteristic.MotionDetected).value;
+
+    if (current) {
+      this.services.armingMotionSensorService.updateCharacteristic(
+        this.Characteristic.MotionDetected,
+        false,
+      );
+    }
+  }
+
+  // ── Tripped sensor ─────────────────────────────────────────────────────────
+
+  pulseTrippedMotionSensor(): void {
+    this.services.trippedMotionSensorService.updateCharacteristic(
+      this.Characteristic.MotionDetected,
+      true,
+    );
+    this.scheduleReset(this.services.trippedMotionSensorService);
+  }
+
+  resetTrippedMotionSensor(): void {
+    const char = this.services.trippedMotionSensorService
+      .getCharacteristic(this.Characteristic.MotionDetected);
+    if (char.value) {
+      char.updateValue(false);
+    }
+  }
+
+  // ── Triggered sensor ───────────────────────────────────────────────────────
+
+  pulseTriggeredMotionSensor(): void {
+    this.services.triggeredMotionSensorService.updateCharacteristic(
+      this.Characteristic.MotionDetected,
+      true,
+    );
+    this.scheduleReset(this.services.triggeredMotionSensorService);
+  }
+
+  // ── Reset sensor ───────────────────────────────────────────────────────────
+
+  pulseResetMotionSensor(): void {
+    this.services.triggeredResetMotionSensorService.updateCharacteristic(
+      this.Characteristic.MotionDetected,
+      true,
+    );
+    this.scheduleReset(this.services.triggeredResetMotionSensorService);
+    this.log.debug('Reset sensor (Triggered)');
+  }
+
+  // ── Private helpers ────────────────────────────────────────────────────────
+
+  private scheduleReset(service: ServiceRegistry[keyof ServiceRegistry]): void {
+    setTimeout(() => {
+      service.updateCharacteristic(this.Characteristic.MotionDetected, false);
+    }, SENSOR_PULSE_MS);
+  }
+}

package/src/handlers/state-handler.ts

@@ -0,0 +1,268 @@
+import type { Logging } 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 { stateToMode, capitalise } from '../utils/state-util.js';
+import { modeToState } from '../utils/state-util.js';
+import type { ServiceRegistry } from '../interfaces/service-registry-interface.js';
+import type { SystemState } from '../interfaces/system-state-interface.js';
+import type { SecuritySystemOptions } from '../interfaces/options-interface.js';
+import type { EventBusService } from '../services/event-bus-service.js';
+import { EventType } from '../types/event-type.js';
+import type { StorageService } from '../services/storage-service.js';
+import type { AudioService } from '../services/audio-service.js';
+import type { TripHandler } from './trip-handler.js';
+import type { SwitchHandler } from './switch-handler.js';
+import type { SensorHandler } from './sensor-handler.js';
+
+/** Manages the core security-system state machine: arming, triggering, and resetting. */
+export class StateHandler {
+  private tripHandler!: TripHandler;
+  private switchHandler!: SwitchHandler;
+  private sensorHandler!: SensorHandler;
+
+  constructor(
+    private readonly services: ServiceRegistry,
+    private readonly state: SystemState,
+    private readonly options: SecuritySystemOptions,
+    private readonly Characteristic: CharacteristicConstructor,
+    private readonly log: Logging,
+    private readonly bus: EventBusService,
+    private readonly storageService: StorageService,
+    private readonly audio: AudioService,
+  ) {}
+
+  setHandlers(trip: TripHandler, sw: SwitchHandler, sensor: SensorHandler): void {
+    this.tripHandler = trip;
+    this.switchHandler = sw;
+    this.sensorHandler = sensor;
+  }
+
+  // ── Public API ─────────────────────────────────────────────────────────────
+
+  setCurrentState(state: SecurityState, origin: OriginType): void {
+    this.sensorHandler.resetArmingMotionSensor();
+    this.audio.play('current', state);
+
+    if (this.state.currentState === state) {
+      this.log.warn('Current mode (Already set)');
+      return;
+    }
+
+    this.state.currentState = state;
+    this.services.mainService.setCharacteristic(
+      this.Characteristic.SecuritySystemCurrentState,
+      state,
+    );
+    this.logMode('Current', state);
+
+    this.handleCurrentStateChange(origin);
+    this.storageService.save(this.state);
+  }
+
+  updateTargetState(state: SecurityState, origin: OriginType, delay: number): boolean {
+    if (this.isBadTargetState(state)) {
+      return false; 
+    }
+
+    this.state.targetState = state;
+    this.logMode('Target', state);
+
+    if (origin === OriginType.INTERNAL || origin === OriginType.EXTERNAL) {
+      this.services.mainService.updateCharacteristic(
+        this.Characteristic.SecuritySystemTargetState,
+        state,
+      );
+    }
+
+    this.handleTargetStateChange(origin);
+
+    if (state === this.state.currentState) {
+      this.setCurrentState(state, origin);
+      return false;
+    }
+
+    const armSeconds = delay > 0 ? delay : 0;
+
+    if (armSeconds === 0) {
+      this.setCurrentState(state, origin);
+      return false;
+    }
+
+    this.state.isArming = true;
+    this.handleArmingState();
+    this.log.info(`Arm delay (${armSeconds}s)`);
+
+    this.state.armTimeout = setTimeout(() => {
+      this.state.armTimeout = null;
+      this.state.isArming = false;
+      this.setCurrentState(state, origin);
+    }, armSeconds * 1000);
+
+    return true;
+  }
+
+  getArmingSeconds(state: SecurityState): number {
+    const isTriggered = this.state.currentState === SecurityState.TRIGGERED;
+    const isOff = state === SecurityState.OFF;
+
+    if (isTriggered || isOff) {
+      return 0; 
+    }
+
+    if (state === SecurityState.HOME && this.options.homeArmSeconds !== null) {
+      return this.options.homeArmSeconds;
+    }
+    if (state === SecurityState.AWAY && this.options.awayArmSeconds !== null) {
+      return this.options.awayArmSeconds;
+    }
+    if (state === SecurityState.NIGHT && this.options.nightArmSeconds !== null) {
+      return this.options.nightArmSeconds;
+    }
+
+    return this.options.armSeconds;
+  }
+
+  resetTimers(): void {
+    if (this.state.triggerTimeout) {
+      clearTimeout(this.state.triggerTimeout);
+      this.state.triggerTimeout = null;
+      this.log.debug('Trigger timeout (Cleared)');
+    }
+    if (this.state.armTimeout) {
+      clearTimeout(this.state.armTimeout);
+      this.state.armTimeout = null;
+      this.log.debug('Arming timeout (Cleared)');
+    }
+    if (this.state.triggeredMotionSensorInterval) {
+      clearInterval(this.state.triggeredMotionSensorInterval);
+      this.state.triggeredMotionSensorInterval = null;
+      this.log.debug('Triggered interval (Cleared)');
+    }
+    if (this.state.trippedMotionSensorInterval) {
+      clearInterval(this.state.trippedMotionSensorInterval);
+      this.state.trippedMotionSensorInterval = null;
+      this.log.debug('Tripped interval (Cleared)');
+    }
+    if (this.state.doubleKnockTimeout) {
+      clearTimeout(this.state.doubleKnockTimeout);
+      this.state.doubleKnockTimeout = null;
+      this.log.debug('Double-knock timeout (Cleared)');
+    }
+    if (this.state.pauseTimeout) {
+      clearTimeout(this.state.pauseTimeout);
+      this.state.pauseTimeout = null;
+      this.log.debug('Pause timeout (Cleared)');
+    }
+    if (this.state.resetTimeout) {
+      clearTimeout(this.state.resetTimeout);
+      this.state.resetTimeout = null;
+      this.log.debug('Reset timeout (Cleared)');
+    }
+  }
+
+  getAvailableTargetStates(): 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));
+  }
+
+  logMode(type: string, state: SecurityState | string): void {
+    const mode = capitalise(stateToMode(state as SecurityState));
+    this.log.info(`${type} mode (${mode})`);
+  }
+
+  // ── Private helpers ────────────────────────────────────────────────────────
+
+  private isBadTargetState(state: SecurityState): boolean {
+    const isTriggered = this.state.currentState === SecurityState.TRIGGERED;
+    const alreadySet = this.state.targetState === state;
+
+    if (alreadySet && !isTriggered) {
+      this.log.warn('Target mode (Already set)');
+      return true;
+    }
+
+    if (!this.state.availableTargetStates.includes(state)) {
+      this.log.warn('Target mode (Disabled)');
+      return true;
+    }
+
+    const hasLock = this.options.armingLockSwitch || this.options.armingLockSwitches;
+    if (state !== SecurityState.OFF && hasLock && this.switchHandler.isArmingLocked(state)) {
+      this.log.warn('Arming lock (Not allowed)');
+      return true;
+    }
+
+    return false;
+  }
+
+  private handleTargetStateChange(origin: OriginType): void {
+    this.resetTimers();
+    this.tripHandler.resetTripSwitches();
+    this.sensorHandler.resetTrippedMotionSensor();
+    this.switchHandler.resetModeSwitches();
+    this.switchHandler.updateModeSwitches();
+
+    this.bus.emit(EventType.TARGET_CHANGED, { state: this.state.targetState, origin });
+
+    if (this.state.currentState === SecurityState.TRIGGERED) {
+      this.sensorHandler.pulseResetMotionSensor();
+    }
+
+    this.state.isKnocked = false;
+  }
+
+  private handleCurrentStateChange(origin: OriginType): void {
+    if (this.state.currentState === SecurityState.TRIGGERED) {
+      this.handleTriggeredState();
+
+      if (this.options.testMode) {
+        return; 
+      }
+    }
+
+    this.tripHandler.resetTripSwitches();
+    this.bus.emit(EventType.CURRENT_CHANGED, { state: this.state.currentState, origin });
+  }
+
+  private handleTriggeredState(): void {
+    if (this.state.trippedMotionSensorInterval) {
+      clearInterval(this.state.trippedMotionSensorInterval);
+      this.state.trippedMotionSensorInterval = null;
+    }
+
+    if (this.options.triggeredMotionSensor) {
+      this.state.triggeredMotionSensorInterval = setInterval(
+        () => this.sensorHandler.pulseTriggeredMotionSensor(),
+        this.options.triggeredMotionSensorSeconds * 1000,
+      );
+    }
+
+    this.state.resetTimeout = setTimeout(() => {
+      this.state.resetTimeout = null;
+      this.log.info('Reset (Finished)');
+      this.sensorHandler.pulseResetMotionSensor();
+
+      if (this.options.resetOffFlow) {
+        this.resetViaOffMode();
+      } else {
+        this.setCurrentState(this.state.targetState, OriginType.EXTERNAL);
+      }
+    }, this.options.resetMinutes * 60 * 1000);
+  }
+
+  private handleArmingState(): void {
+    this.sensorHandler.updateArmingMotionSensor(true);
+    this.bus.emit(EventType.ARMING, { state: this.state.targetState });
+  }
+
+  private resetViaOffMode(): void {
+    const original = this.state.targetState;
+    this.updateTargetState(SecurityState.OFF, OriginType.INTERNAL, 0);
+
+    setTimeout(() => {
+      this.updateTargetState(original, OriginType.INTERNAL, this.getArmingSeconds(original));
+    }, 100);
+  }
+}

package/src/handlers/switch-handler.ts

@@ -0,0 +1,166 @@
+import type { Logging } from 'homebridge';
+import type { CharacteristicConstructor } from '../interfaces/hap-types-interface.js';
+import { SecurityState } from '../types/security-state-type.js';
+import { HK_NOT_ALLOWED_IN_CURRENT_STATE } from '../constants/homekit-constant.js';
+import type { ServiceRegistry } from '../interfaces/service-registry-interface.js';
+import type { SystemState } from '../interfaces/system-state-interface.js';
+import type { SecuritySystemOptions } from '../interfaces/options-interface.js';
+import type { StateHandler } from './state-handler.js';
+import { OriginType } from '../types/origin-type.js';
+import { capitalise } from '../utils/state-util.js';
+
+/** Handles all mode switches, arming-lock switches, and the pause/extended switches. */
+export class SwitchHandler {
+  private stateHandler!: StateHandler;
+
+  constructor(
+    private readonly services: ServiceRegistry,
+    private readonly state: SystemState,
+    private readonly options: SecuritySystemOptions,
+    private readonly Characteristic: CharacteristicConstructor,
+    private readonly log: Logging,
+  ) {}
+
+  setStateHandler(handler: StateHandler): void {
+    this.stateHandler = handler;
+  }
+
+  // ── Mode switches ──────────────────────────────────────────────────────────
+
+  setModeSwitch(mode: SecurityState, value: boolean): number | null {
+    if (!value) {
+      return HK_NOT_ALLOWED_IN_CURRENT_STATE; 
+    }
+    const delay = this.stateHandler.getArmingSeconds(mode);
+    this.stateHandler.updateTargetState(mode, OriginType.INTERNAL, delay);
+    return null;
+  }
+
+  setModeOffSwitch(value: boolean): number | null {
+    if (!value) {
+      return HK_NOT_ALLOWED_IN_CURRENT_STATE; 
+    }
+    this.stateHandler.updateTargetState(SecurityState.OFF, OriginType.INTERNAL, 0);
+    return null;
+  }
+
+  setModeAwayExtendedSwitch(value: boolean): number | null {
+    if (!value) {
+      return HK_NOT_ALLOWED_IN_CURRENT_STATE; 
+    }
+    const delay = this.stateHandler.getArmingSeconds(SecurityState.AWAY);
+    this.stateHandler.updateTargetState(SecurityState.AWAY, OriginType.INTERNAL, delay);
+    return null;
+  }
+
+  setModePauseSwitch(value: boolean): number | null {
+    if (this.state.currentState === SecurityState.TRIGGERED) {
+      this.log.warn('Mode pause (Alarm is triggered)');
+      return HK_NOT_ALLOWED_IN_CURRENT_STATE;
+    }
+
+    if (value) {
+      if (this.state.currentState === SecurityState.OFF) {
+        this.log.warn('Mode pause (Not armed)');
+        return HK_NOT_ALLOWED_IN_CURRENT_STATE;
+      }
+
+      this.log.info('Mode pause (Started)');
+      this.state.pausedCurrentState = this.state.currentState;
+      this.stateHandler.updateTargetState(SecurityState.OFF, OriginType.INTERNAL, 0);
+
+      if (this.options.pauseMinutes !== 0) {
+        this.state.pauseTimeout = setTimeout(() => {
+          this.log.info('Mode pause (Finished)');
+          const prev = this.state.pausedCurrentState ?? this.state.defaultState;
+          this.stateHandler.updateTargetState(prev, OriginType.INTERNAL, this.stateHandler.getArmingSeconds(prev));
+        }, this.options.pauseMinutes * 60 * 1000);
+      }
+    } else {
+      this.log.info('Mode pause (Cancelled)');
+
+      if (this.state.pauseTimeout !== null) {
+        clearTimeout(this.state.pauseTimeout);
+        this.state.pauseTimeout = null;
+      }
+
+      const prev = this.state.pausedCurrentState ?? this.state.defaultState;
+      this.stateHandler.updateTargetState(prev, OriginType.INTERNAL, this.stateHandler.getArmingSeconds(prev));
+    }
+
+    return null;
+  }
+
+  // ── Arming lock switches ───────────────────────────────────────────────────
+
+  updateArmingLock(mode: string, value: boolean): boolean {
+    this.logArmingLock(mode, value);
+
+    const map: Record<string, keyof ServiceRegistry> = {
+      global: 'armingLockSwitchService',
+      home: 'armingLockHomeSwitchService',
+      away: 'armingLockAwaySwitchService',
+      night: 'armingLockNightSwitchService',
+    };
+
+    const key = map[mode];
+    if (!key) {
+      this.log.debug(`Unknown arming lock mode (${mode})`);
+      return false;
+    }
+
+    this.services[key].getCharacteristic(this.Characteristic.On).updateValue(value);
+    return true;
+  }
+
+  isArmingLocked(targetState: SecurityState): boolean {
+    if (this.services.armingLockSwitchService.getCharacteristic(this.Characteristic.On).value) {
+      return true;
+    }
+
+    const modeMap: Record<number, keyof ServiceRegistry> = {
+      [SecurityState.HOME]: 'armingLockHomeSwitchService',
+      [SecurityState.AWAY]: 'armingLockAwaySwitchService',
+      [SecurityState.NIGHT]: 'armingLockNightSwitchService',
+    };
+
+    const svcKey = modeMap[targetState];
+    return svcKey ? Boolean(this.services[svcKey].getCharacteristic(this.Characteristic.On).value) : false;
+  }
+
+  // ── Mode switch display ────────────────────────────────────────────────────
+
+  resetModeSwitches(): void {
+    const switches: Array<keyof ServiceRegistry> = [
+      'modeHomeSwitchService', 'modeAwaySwitchService', 'modeNightSwitchService',
+      'modeOffSwitchService', 'modeAwayExtendedSwitchService', 'modePauseSwitchService',
+    ];
+
+    for (const key of switches) {
+      const char = this.services[key].getCharacteristic(this.Characteristic.On);
+      if (char.value) {
+        char.updateValue(false);
+        this.log.debug(`${key} (Off)`);
+      }
+    }
+  }
+
+  updateModeSwitches(): void {
+    const modeMap: Partial<Record<SecurityState, keyof ServiceRegistry>> = {
+      [SecurityState.HOME]: 'modeHomeSwitchService',
+      [SecurityState.AWAY]: 'modeAwaySwitchService',
+      [SecurityState.NIGHT]: 'modeNightSwitchService',
+      [SecurityState.OFF]: 'modeOffSwitchService',
+    };
+
+    const key = modeMap[this.state.targetState];
+    if (key) {
+      this.services[key].updateCharacteristic(this.Characteristic.On, true);
+      this.log.debug(`${key} (On)`);
+    }
+  }
+
+  private logArmingLock(mode: string, value: boolean): void {
+    this.log.info(`Arming lock [${capitalise(mode)}] (${value ? 'On' : 'Off'})`);
+  }
+}