homebridge-securitysystem 9.1.2 → 10.0.0-beta.2

package/src/handlers/trip-handler.ts

@@ -0,0 +1,219 @@
+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 { 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 { EventBusService } from '../services/event-bus-service.js';
+import { EventType } from '../types/event-type.js';
+import type { AudioService } from '../services/audio-service.js';
+import type { SensorHandler } from './sensor-handler.js';
+import type { StateHandler } from './state-handler.js';
+import { NotArmedCondition } from '../conditions/not-armed-condition.js';
+import { ArmingInProgressCondition } from '../conditions/arming-in-progress-condition.js';
+import { AlreadyTriggeredCondition } from '../conditions/already-triggered-condition.js';
+import { DoubleKnockCondition } from '../conditions/double-knock-condition.js';
+import type { ConditionContext } from '../interfaces/condition-context-interface.js';
+
+/** Handles the trip switch and trigger-delay logic, including all blocking conditions. */
+export class TripHandler {
+  private stateHandler!: StateHandler;
+
+  private readonly notArmed = new NotArmedCondition();
+  private readonly armingInProgress = new ArmingInProgressCondition();
+  private readonly alreadyTriggered = new AlreadyTriggeredCondition();
+  private readonly doubleKnock: DoubleKnockCondition;
+
+  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 audio: AudioService,
+    private readonly sensorHandler: SensorHandler,
+  ) {
+    this.doubleKnock = new DoubleKnockCondition((seconds, onExpire) => {
+      this.log.warn('Trip Switch (Knock)');
+      this.state.doubleKnockTimeout = setTimeout(() => {
+        onExpire();
+        this.log.info('Trip Switch (Reset)');
+      }, seconds * 1000);
+    });
+  }
+
+  setStateHandler(handler: StateHandler): void {
+    this.stateHandler = handler;
+  }
+
+  /**
+   * Core trip-switch logic shared by all trip/trigger paths.
+   * Returns `true` on success, `false` if blocked.
+   */
+  updateTripSwitch(value: boolean, origin: OriginType, stateChanged: boolean): boolean {
+    const ctx: ConditionContext = {
+      state: this.state,
+      services: this.services,
+      options: this.options,
+      value,
+      origin,
+    };
+
+    if (value) {
+      // Check blocking conditions in order.
+      if (this.notArmed.evaluate(ctx)) {
+        this.log.warn('Trip Switch (Not armed)');
+        return false;
+      }
+
+      if (this.armingInProgress.evaluate(ctx)) {
+        this.log.warn('Trip Switch (Still arming)');
+        return false;
+      }
+
+      if (this.doubleKnock.evaluate(ctx)) {
+        return false;
+      }
+
+      // Clear any lingering double-knock timeout once we've passed it.
+      if (this.state.doubleKnockTimeout !== null) {
+        clearTimeout(this.state.doubleKnockTimeout);
+        this.state.doubleKnockTimeout = null;
+      }
+
+      if (this.alreadyTriggered.evaluate(ctx)) {
+        this.log.warn('Security System (Already triggered)');
+        return false;
+      }
+
+      if (this.state.triggerTimeout !== null) {
+        this.log.warn('Security System (Already tripped)');
+        return false;
+      }
+
+      this.activateTrip(origin);
+    } else {
+      this.cancelTrip(origin, stateChanged);
+    }
+
+    // Sync trip switch characteristic when origin is not a direct switch press.
+    if (origin === OriginType.INTERNAL || origin === OriginType.EXTERNAL) {
+      this.services.tripSwitchService.updateCharacteristic(this.Characteristic.On, value);
+    }
+
+    return true;
+  }
+
+  /**
+   * Trip a mode-specific switch. Only triggers if the system is currently in
+   * the required mode (or the alarm is triggered and target matches).
+   */
+  triggerIfModeSet(requiredState: SecurityState, value: boolean): boolean {
+    const isTriggered = this.state.currentState === SecurityState.TRIGGERED;
+
+    if (value) {
+      const modeMatches = this.state.currentState === requiredState
+        || (isTriggered && this.state.targetState === requiredState);
+
+      if (!modeMatches) {
+        this.log.debug('Security System (Trip mode not set)');
+        return false;
+      }
+    }
+
+    return this.updateTripSwitch(value, OriginType.REGULAR_SWITCH, false);
+  }
+
+  resetTripSwitches(): void {
+    const switches: Array<[keyof ServiceRegistry, string]> = [
+      ['tripHomeSwitchService', 'Trip Home'],
+      ['tripAwaySwitchService', 'Trip Away'],
+      ['tripNightSwitchService', 'Trip Night'],
+      ['tripOverrideSwitchService', 'Trip Override'],
+    ];
+
+    for (const [key, label] of switches) {
+      const char = this.services[key].getCharacteristic(this.Characteristic.On);
+      if (char.value) {
+        char.updateValue(false);
+        this.log.debug(`${label} Switch (Off)`);
+      }
+    }
+  }
+
+  private activateTrip(origin: OriginType): void {
+    this.log.info('Security System (Tripped)');
+
+    if (this.options.trippedMotionSensor) {
+      this.sensorHandler.pulseTrippedMotionSensor();
+      this.state.trippedMotionSensorInterval = setInterval(
+        () => this.sensorHandler.pulseTrippedMotionSensor(),
+        this.options.trippedMotionSensorSeconds * 1000,
+      );
+    }
+
+    const triggerSeconds = this.resolveTriggerSeconds();
+    this.log.debug(`Trigger delay (${triggerSeconds}s)`);
+
+    this.state.triggerTimeout = setTimeout(() => {
+      this.state.triggerTimeout = null;
+      this.stateHandler.setCurrentState(SecurityState.TRIGGERED, origin);
+    }, triggerSeconds * 1000);
+
+    if (triggerSeconds > 0) {
+      this.bus.emit(EventType.WARNING, { origin, triggerSeconds });
+    }
+  }
+
+  private cancelTrip(origin: OriginType, stateChanged: boolean): void {
+    this.log.info('Security System (Cancelled)');
+    this.audio.stop();
+
+    if (this.state.currentState === SecurityState.TRIGGERED) {
+      if (!stateChanged) {
+        this.stateHandler.updateTargetState(SecurityState.OFF, OriginType.INTERNAL, 0);
+      }
+    } else {
+      this.stateHandler.resetTimers();
+    }
+
+    if (this.options.trippedMotionSensor) {
+      this.sensorHandler.resetTrippedMotionSensor();
+    }
+
+    this.state.isKnocked = false;
+  }
+
+  private resolveTriggerSeconds(): number {
+    const seconds = this.options.triggerSeconds;
+    const cur = this.state.currentState;
+
+    if (cur === SecurityState.HOME && this.options.homeTriggerSeconds !== null) {
+      return this.options.homeTriggerSeconds;
+    }
+
+    if (cur === SecurityState.AWAY) {
+      const extChar = this.services.modeAwayExtendedSwitchService
+        .getCharacteristic(this.Characteristic.On);
+
+      if (this.options.modeAwayExtendedSwitchTriggerSeconds !== null && extChar.value) {
+        return this.options.modeAwayExtendedSwitchTriggerSeconds;
+      }
+
+      if (this.options.awayTriggerSeconds !== null) {
+        return this.options.awayTriggerSeconds;
+      }
+    }
+
+    if (cur === SecurityState.NIGHT && this.options.nightTriggerSeconds !== null) {
+      return this.options.nightTriggerSeconds;
+    }
+
+    return seconds;
+  }
+}
+
+export { HK_NOT_ALLOWED_IN_CURRENT_STATE };

package/src/index.ts

@@ -0,0 +1,9 @@
+import type { API } from 'homebridge';
+import { SecuritySystem } from './security-system.js';
+
+const PLUGIN_NAME = 'homebridge-securitysystem';
+const ACCESSORY_NAME = 'security-system';
+
+export default (api: API): void => {
+  api.registerAccessory(PLUGIN_NAME, ACCESSORY_NAME, SecuritySystem);
+};

package/src/interfaces/condition-context-interface.ts

@@ -0,0 +1,14 @@
+import type { OriginType } from '../types/origin-type.js';
+import type { SecuritySystemOptions } from './options-interface.js';
+import type { ServiceRegistry } from './service-registry-interface.js';
+import type { SystemState } from './system-state-interface.js';
+
+/** Context passed to Condition.evaluate() to determine if an action is blocked. */
+export interface ConditionContext {
+  state: SystemState;
+  services: ServiceRegistry;
+  options: SecuritySystemOptions;
+  /** The value being set (true = activating, false = deactivating). */
+  value: boolean;
+  origin: OriginType;
+}

package/src/interfaces/hap-types-interface.ts

@@ -0,0 +1,11 @@
+import type { API } from 'homebridge';
+
+/**
+ * Runtime type of `api.hap.Characteristic` (the class with all static characteristic
+ * definitions). Using `API['hap']['Characteristic']` avoids the self-referential
+ * `typeof Characteristic` issue that arises with `import type { Characteristic }`.
+ */
+export type CharacteristicConstructor = API['hap']['Characteristic'];
+
+/** Runtime type of `api.hap.Service`. */
+export type ServiceConstructor = API['hap']['Service'];

package/src/interfaces/options-interface.ts

@@ -0,0 +1,120 @@
+/** Key-value pair for extra ffplay environment variables. */
+export interface AudioVariable {
+  key: string;
+  value: 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;
+  audioSwitchName: string;
+
+  // Behaviour toggles
+  logDirectory: string | null;
+  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;
+
+  // Arming lock
+  armingLockSwitch: boolean;
+  armingLockSwitches: boolean;
+
+  // Motion sensors
+  armingMotionSensor: boolean;
+  trippedMotionSensor: boolean;
+  trippedMotionSensorSeconds: number;
+  triggeredMotionSensor: boolean;
+  triggeredMotionSensorSeconds: 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;
+
+  // Audio
+  audio: boolean;
+  audioPath: string | null;
+  audioLanguage: string;
+  audioVolume: number | null;
+  audioArmingLooped: boolean;
+  audioAlertLooped: boolean;
+  audioExtraVariables: AudioVariable[];
+  audioSwitch: boolean;
+
+  // Server
+  serverPort: number | null;
+  serverCode: number | 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
+  webhookUrl: string | null;
+  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;
+}

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,37 @@
+import type { Service } from 'homebridge';
+
+/** All HomeKit services exposed by the security system accessory. */
+export interface ServiceRegistry {
+  mainService: Service;
+  accessoryInfoService: Service;
+
+  // Trip switches
+  tripSwitchService: Service;
+  tripHomeSwitchService: Service;
+  tripAwaySwitchService: Service;
+  tripNightSwitchService: Service;
+  tripOverrideSwitchService: Service;
+
+  // Arming lock switches
+  armingLockSwitchService: Service;
+  armingLockHomeSwitchService: Service;
+  armingLockAwaySwitchService: Service;
+  armingLockNightSwitchService: Service;
+
+  // Mode switches
+  modeHomeSwitchService: Service;
+  modeAwaySwitchService: Service;
+  modeNightSwitchService: Service;
+  modeOffSwitchService: Service;
+  modeAwayExtendedSwitchService: Service;
+  modePauseSwitchService: Service;
+
+  // Audio switch
+  audioSwitchService: Service;
+
+  // Motion sensors
+  armingMotionSensorService: Service;
+  trippedMotionSensorService: Service;
+  triggeredMotionSensorService: Service;
+  triggeredResetMotionSensorService: Service;
+}

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

@@ -0,0 +1,25 @@
+import type { ChildProcess } from 'child_process';
+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;
+  isKnocked: boolean;
+  invalidCodeCount: number;
+  pausedCurrentState: SecurityState | null;
+  audioProcess: ChildProcess | null;
+
+  // Active timers (null = not running)
+  armTimeout: ReturnType<typeof setTimeout> | null;
+  pauseTimeout: ReturnType<typeof setTimeout> | null;
+  triggerTimeout: ReturnType<typeof setTimeout> | null;
+  doubleKnockTimeout: ReturnType<typeof setTimeout> | null;
+  resetTimeout: ReturnType<typeof setTimeout> | null;
+  trippedMotionSensorInterval: ReturnType<typeof setInterval> | null;
+  triggeredMotionSensorInterval: ReturnType<typeof setInterval> | null;
+}