homebridge-securitysystem 0.0.1-matter

package/dist/utils/state-util.js

@@ -0,0 +1,29 @@
+import { SecurityState } from '../types/security-state-type.js';
+/** Converts a SecurityState value to its human-readable mode string. */
+export function stateToMode(state) {
+    switch (state) {
+        case SecurityState.TRIGGERED: return 'triggered';
+        case SecurityState.HOME: return 'home';
+        case SecurityState.AWAY: return 'away';
+        case SecurityState.NIGHT: return 'night';
+        case SecurityState.OFF: return 'off';
+        case 'lock': return 'lock';
+        case 'warning': return 'warning';
+        default: return 'unknown';
+    }
+}
+/** Converts a mode string to its corresponding SecurityState value (-1 if unknown). */
+export function modeToState(mode) {
+    switch (mode) {
+        case 'home': return SecurityState.HOME;
+        case 'away': return SecurityState.AWAY;
+        case 'night': return SecurityState.NIGHT;
+        case 'off': return SecurityState.OFF;
+        default: return -1;
+    }
+}
+/** Capitalises the first letter of a string. */
+export function capitalise(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+//# sourceMappingURL=state-util.js.map

package/dist/utils/state-util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-util.js","sourceRoot":"","sources":["../../src/utils/state-util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAGhE,wEAAwE;AACxE,MAAM,UAAU,WAAW,CAAC,KAA6B;IACvD,QAAQ,KAAK,EAAE,CAAC;QAChB,KAAK,aAAa,CAAC,SAAS,EAAE,OAAO,WAAW,CAAC;QACjD,KAAK,aAAa,CAAC,IAAI,EAAE,OAAO,MAAM,CAAC;QACvC,KAAK,aAAa,CAAC,IAAI,EAAE,OAAO,MAAM,CAAC;QACvC,KAAK,aAAa,CAAC,KAAK,EAAE,OAAO,OAAO,CAAC;QACzC,KAAK,aAAa,CAAC,GAAG,EAAE,OAAO,KAAK,CAAC;QACrC,KAAK,MAAM,EAAE,OAAO,MAAM,CAAC;QAC3B,KAAK,SAAS,EAAE,OAAO,SAAS,CAAC;QACjC,SAAS,OAAO,SAAS,CAAC;IAC1B,CAAC;AACH,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,QAAQ,IAAI,EAAE,CAAC;QACf,KAAK,MAAM,EAAE,OAAO,aAAa,CAAC,IAAI,CAAC;QACvC,KAAK,MAAM,EAAE,OAAO,aAAa,CAAC,IAAI,CAAC;QACvC,KAAK,OAAO,EAAE,OAAO,aAAa,CAAC,KAAK,CAAC;QACzC,KAAK,KAAK,EAAE,OAAO,aAAa,CAAC,GAAG,CAAC;QACrC,SAAS,OAAO,CAAC,CAAkB,CAAC;IACpC,CAAC;AACH,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC"}

package/docs/MQTT.md

@@ -0,0 +1,50 @@
+# MQTT
+
+Publish real-time security system state updates to an MQTT broker.
+
+## Configuration
+
+Add these fields to your plugin config (or configure via the Homebridge UI):
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `mqtt_broker` | `string` | — | Broker URL, e.g. `mqtt://localhost:1883` or `mqtts://broker.example.com:8883` |
+| `mqtt_username` | `string` | — | Optional username for authentication |
+| `mqtt_password` | `string` | — | Optional password for authentication |
+| `mqtt_topic` | `string` | `security-system/state` | Topic to publish status payloads to |
+| `mqtt_client_id` | `string` | — | Optional client ID (auto-generated if omitted) |
+
+MQTT is **optional** — omit `mqtt_broker` to disable it.
+
+## Payload
+
+Published as a retained JSON message on every state change:
+
+```json
+{
+  "arming": false,
+  "current_mode": "home",
+  "target_mode": "home",
+  "tripped": true
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `arming` | `boolean` | Whether the system is counting down an arming delay |
+| `current_mode` | `string` | Current active mode: `off`, `home`, `away`, `night`, `triggered` |
+| `target_mode` | `string` | Target mode being transitioned to |
+| `tripped` | `boolean` | Whether a trip switch is active (trigger delay counting down) |
+
+## Events
+
+Publishes are triggered by these state machine changes:
+
+- Current mode changes (`CURRENT_CHANGED`)
+- Target mode changes (`TARGET_CHANGED`)
+- Arming delay start (`ARMING`)
+- Warning state (`WARNING`)
+
+## Proxy Mode
+
+If `proxy_mode` is enabled, publishes originating from external sources (e.g. HTTP API) are suppressed.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "homebridge-securitysystem",
+  "displayName": "Homebridge Security System",
+  "type": "module",
+  "version": "0.0.1-matter",
+  "description": "Homebridge plugin that creates a security system accessory that can be triggered by HomeKit sensors.",
+  "author": "MiguelRipoll23",
+  "license": "MIT",
+  "homepage": "https://github.com/MiguelRipoll23/homebridge-securitysystem#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MiguelRipoll23/homebridge-securitysystem.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MiguelRipoll23/homebridge-securitysystem/issues"
+  },
+  "keywords": [
+    "homebridge-plugin",
+    "homebridge",
+    "homekit",
+    "security system",
+    "alarm",
+    "category-security",
+    "supports-hap",
+    "supports-matter"
+  ],
+  "main": "dist/index.js",
+  "engines": {
+    "node": "^22 || ^24",
+    "homebridge": "^1.8.0 || ^2.0.0"
+  },
+  "dependencies": {
+    "@hono/node-server": "^2.1.1",
+    "@hono/zod-openapi": "^1.6.0",
+    "@scalar/hono-api-reference": "^0.11.14",
+    "hono": "^4.13.2",
+    "mqtt": "^5.15.2",
+    "node-persist": "^4.0.4",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "@types/node-persist": "^3.1.8",
+    "homebridge": "^2.3.1",
+    "nodemon": "^3.1.14",
+    "oxlint": "^1.78.0",
+    "rimraf": "^6.1.3",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/MiguelRipoll23"
+    }
+  ],
+  "scripts": {
+    "build": "rimraf ./dist && tsc",
+    "lint": "oxlint",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "watch": "pnpm run build && pnpm link && nodemon"
+  }
+}

package/src/@types/homebridge-lib.d.ts

@@ -0,0 +1,11 @@
+declare module 'homebridge-lib/EveHomeKitTypes' {
+  export class EveHomeKitTypes {
+    constructor(homebridge: any);
+
+    Characteristics: Record<string, any>;
+    Services: Record<string, any>;
+  }
+}
+
+declare module 'homebridge-lib' {
+}

package/src/conditions/already-triggered-condition.ts

@@ -0,0 +1,24 @@
+import { SecurityState } from '../types/security-state-type.js';
+import type { ConditionContext } from '../interfaces/condition-context-interface.js';
+import { Condition } from './condition.js';
+
+/**
+ * Blocks a new trip activation when the alarm has already been triggered.
+ * Prevents stacking multiple trigger events on an active alarm.
+ */
+export class AlreadyTriggeredCondition extends Condition {
+  readonly name = 'already-triggered';
+
+  evaluate({ state, value, log }: ConditionContext): boolean {
+    this.clearFailureReason();
+    if (!value) {
+      return false;
+    }
+    const blocked = state.currentState === SecurityState.TRIGGERED;
+    if (blocked) {
+      this._failureReason = 'Security System (Already triggered): alarm is already active';
+      log.warn(this._failureReason);
+    }
+    return blocked;
+  }
+}

package/src/conditions/arming-in-progress-condition.ts

@@ -0,0 +1,23 @@
+import type { ConditionContext } from '../interfaces/condition-context-interface.js';
+import { Condition } from './condition.js';
+
+/**
+ * Blocks a trip action while the arm delay countdown is still running.
+ * Prevents an intruder from tripping the system before it has fully armed.
+ */
+export class ArmingInProgressCondition extends Condition {
+  readonly name = 'arming-in-progress';
+
+  evaluate({ state, value, log }: ConditionContext): boolean {
+    this.clearFailureReason();
+    if (!value) {
+      return false;
+    }
+    if (state.isArming) {
+      this._failureReason = 'Trip Switch (Still arming): arm delay countdown is still in progress';
+      log.warn(this._failureReason);
+      return true;
+    }
+    return false;
+  }
+}

package/src/conditions/arming-lock-condition.ts

@@ -0,0 +1,50 @@
+import { SecurityState } from '../types/security-state-type.js';
+import type { ConditionContext } from '../interfaces/condition-context-interface.js';
+import { Condition } from './condition.js';
+
+/**
+ * Blocks arming when an arming-lock switch (global or mode-specific) is active.
+ * Does NOT block disarming.
+ */
+export class ArmingLockCondition extends Condition {
+  readonly name = 'arming-lock';
+
+  evaluate({ state, options }: ConditionContext): boolean {
+    this.clearFailureReason();
+    const hasLockFeature = options.armingLockSwitch || options.armingLockSwitches;
+    if (!hasLockFeature) {
+      return false;
+    }
+
+    const targetState = state.targetState;
+    if (targetState === SecurityState.OFF) {
+      return false;
+    }
+
+    // Check global arming-lock switch.
+    if (state.armingLocks.global) {
+      this._failureReason = 'arming is blocked by the global arming lock switch';
+      return true;
+    }
+
+    // Check mode-specific arming-lock switch.
+    let blocked = false;
+    switch (targetState) {
+    case SecurityState.HOME:
+      blocked = state.armingLocks.home;
+      break;
+    case SecurityState.AWAY:
+      blocked = state.armingLocks.away;
+      break;
+    case SecurityState.NIGHT:
+      blocked = state.armingLocks.night;
+      break;
+    }
+
+    if (blocked) {
+      this._failureReason = 'arming is blocked by a mode-specific arming lock switch';
+    }
+
+    return blocked;
+  }
+}

package/src/conditions/condition.ts

@@ -0,0 +1,31 @@
+import type { ConditionContext } from '../interfaces/condition-context-interface.js';
+
+/**
+ * Base class for all conditions that can block a trip/trigger action.
+ *
+ * Extend this class and implement `evaluate()` to return `true` when the
+ * condition should prevent the action from proceeding. Set `_failureReason`
+ * before returning `true` so callers can retrieve it via `failureReason`.
+ */
+export abstract class Condition {
+  abstract readonly name: string;
+
+  protected _failureReason: string | undefined;
+
+  /** Returns the reason the condition blocked the last evaluated action, if any. */
+  get failureReason(): string | undefined {
+    return this._failureReason;
+  }
+
+  /** Must be called at the top of every evaluate() implementation to clear any stale reason. */
+  protected clearFailureReason(): void {
+    this._failureReason = undefined;
+  }
+
+  /**
+   * Returns `true` if this condition blocks the action described by `context`.
+   * When `true` is returned the caller must reject the HomeKit request.
+   * Implementations must call `this.clearFailureReason()` before any allow/deny logic.
+   */
+  abstract evaluate(context: ConditionContext): boolean;
+}

package/src/conditions/double-knock-condition.ts

@@ -0,0 +1,84 @@
+import { SecurityState } from '../types/security-state-type.js';
+import { OriginType } from '../types/origin-type.js';
+import type { ConditionContext } from '../interfaces/condition-context-interface.js';
+import { modeToState } from '../utils/state-util.js';
+import { Condition } from './condition.js';
+
+/**
+ * Implements the double-knock pattern: the first activation within a mode that
+ * has double-knock enabled sets a "knocked" flag and rejects the trip. Only the
+ * second activation within the configured window proceeds.
+ *
+ * The caller is responsible for managing `state.isKnocked` and the timeout
+ * via the `onFirstKnock` callback injected at construction.
+ */
+export class DoubleKnockCondition extends Condition {
+  readonly name = 'double-knock';
+
+  /**
+   * @param onFirstKnock Called when the first knock is detected.
+   *   The callback receives the window duration in seconds and a reset function
+   *   to invoke when the window expires.
+   * @param onCancelTimer Called on the second knock to cancel the running window timer.
+   */
+  constructor(
+    private readonly onFirstKnock: (seconds: number, onExpire: () => void) => void,
+    private readonly onCancelTimer: () => void,
+  ) {
+    super();
+  }
+
+  evaluate({ state, options, value, origin, log }: ConditionContext): boolean {
+    this.clearFailureReason();
+    if (!value || !options.doubleKnock) {
+      return false;
+    }
+    if (origin === OriginType.OVERRIDE_SWITCH) {
+      return false;
+    }
+    if (state.isArming) {
+      return false;
+    }
+
+    const knockableStates = options.doubleKnockModes.map(m => modeToState(m.toLowerCase()));
+    if (!knockableStates.includes(state.currentState)) {
+      return false;
+    }
+
+    if (state.isKnocked) {
+      // Second knock — clear the flag and cancel the window timer, then allow through.
+      state.isKnocked = false;
+      this.onCancelTimer();
+      return false;
+    }
+
+    // First knock — block and schedule expiry.
+    state.isKnocked = true;
+    const seconds = this.resolveWindow(state.currentState, options);
+
+    this.onFirstKnock(seconds, () => {
+      state.isKnocked = false;
+      log.info('Trip Switch (Reset): double-knock window expired without second activation');
+    });
+
+    this._failureReason = 'Trip Switch (Knock): double-knock is required, waiting for second activation';
+    log.warn(this._failureReason);
+    return true;
+  }
+
+  private resolveWindow(
+    currentState: SecurityState,
+    options: ConditionContext['options'],
+  ): number {
+    if (currentState === SecurityState.HOME && options.homeDoubleKnockSeconds !== null) {
+      return options.homeDoubleKnockSeconds;
+    }
+    if (currentState === SecurityState.AWAY && options.awayDoubleKnockSeconds !== null) {
+      return options.awayDoubleKnockSeconds;
+    }
+    if (currentState === SecurityState.NIGHT && options.nightDoubleKnockSeconds !== null) {
+      return options.nightDoubleKnockSeconds;
+    }
+    return options.doubleKnockSeconds;
+  }
+}

package/src/conditions/not-armed-condition.ts

@@ -0,0 +1,30 @@
+import { SecurityState } from '../types/security-state-type.js';
+import { OriginType } from '../types/origin-type.js';
+import type { ConditionContext } from '../interfaces/condition-context-interface.js';
+import { Condition } from './condition.js';
+
+/**
+ * Blocks a trip action when the system is disarmed and neither
+ * `override_off` nor the override switch is in use.
+ */
+export class NotArmedCondition extends Condition {
+  readonly name = 'not-armed';
+
+  evaluate({ state, options, value, origin, log }: ConditionContext): boolean {
+    this.clearFailureReason();
+    if (!value) {
+      return false;
+    }
+
+    const isDisarmed = state.currentState === SecurityState.OFF;
+    const isNotOverridingOff = !options.overrideOff;
+    const isNotOverrideSwitch = origin !== OriginType.OVERRIDE_SWITCH;
+
+    const blocked = isDisarmed && isNotOverridingOff && isNotOverrideSwitch;
+    if (blocked) {
+      this._failureReason = 'Trip Switch (Not armed): system is disarmed and override is not enabled';
+      log.warn(this._failureReason);
+    }
+    return blocked;
+  }
+}

package/src/conditions/trigger-already-running-condition.ts

@@ -0,0 +1,23 @@
+import type { ConditionContext } from '../interfaces/condition-context-interface.js';
+import { Condition } from './condition.js';
+
+/**
+ * Blocks a trip activation when the trigger-delay countdown is already running.
+ * Prevents stacking multiple trigger events during the pre-alarm window.
+ */
+export class TriggerAlreadyRunningCondition extends Condition {
+  readonly name = 'trigger-already-running';
+
+  evaluate({ state, value, log }: ConditionContext): boolean {
+    this.clearFailureReason();
+    if (!value) {
+      return false;
+    }
+    if (state.isTripping) {
+      this._failureReason = 'Security System (Already tripped): trigger delay countdown is already running';
+      log.warn(this._failureReason);
+      return true;
+    }
+    return false;
+  }
+}

package/src/constants/default-constant.ts

@@ -0,0 +1,28 @@
+/** Default configuration values applied when a config property is not set. */
+export const DEFAULTS = {
+  NAME: 'Security System',
+  SERIAL_NUMBER: 'S3CUR1TYSYST3M',
+  DEFAULT_MODE: 'off',
+  ARM_SECONDS: 0,
+  TRIGGER_SECONDS: 0,
+  RESET_MINUTES: 10,
+  DOUBLE_KNOCK_SECONDS: 90,
+  TRIPPED_SENSOR_SECONDS: 5,
+  PAUSE_MINUTES: 0,
+
+  // Switch display names
+  TRIP_SWITCH_NAME: 'Trip',
+  TRIP_HOME_SWITCH_NAME: 'Trip Home',
+  TRIP_AWAY_SWITCH_NAME: 'Trip Away',
+  TRIP_NIGHT_SWITCH_NAME: 'Trip Night',
+  TRIP_OVERRIDE_SWITCH_NAME: 'Trip Override',
+  MODE_HOME_SWITCH_NAME: 'Mode Home',
+  MODE_AWAY_SWITCH_NAME: 'Mode Away',
+  MODE_NIGHT_SWITCH_NAME: 'Mode Night',
+  MODE_OFF_SWITCH_NAME: 'Mode Off',
+  MODE_AWAY_EXTENDED_SWITCH_NAME: 'Mode Away Extended',
+  MODE_PAUSE_SWITCH_NAME: 'Mode Pause',
+
+  // MQTT
+  MQTT_TOPIC: 'security-system/state',
+} as const;

package/src/constants/homekit-constant.ts

@@ -0,0 +1,2 @@
+/** Pulse duration in ms used by motion sensors to emit a brief motion event. */
+export const SENSOR_PULSE_MS = 750;

package/src/constants/matter-constant.ts

@@ -0,0 +1,69 @@
+import type { FixedMatterSwitchKey, MatterAccessoryKey } from '../types/matter-accessory-key-type.js';
+import type { SensorKind } from '../types/sensor-kind-type.js';
+
+/**
+ * Stable device-type-indexed identity for every fixed switch, following the
+ * Matter convention of `<device-type>-<index>` (e.g. `motion-sensor-1`).
+ * The index comes from the fixed slot, so disabling an accessory never
+ * renumbers the others.
+ */
+export const MATTER_SWITCH_IDENTITIES: Record<FixedMatterSwitchKey, string> = {
+  // Trip switches
+  trip: 'switch-1',
+  'trip-home': 'switch-2',
+  'trip-away': 'switch-3',
+  'trip-night': 'switch-4',
+  'trip-override': 'switch-5',
+  // Mode switches
+  'mode-home': 'switch-6',
+  'mode-away': 'switch-7',
+  'mode-night': 'switch-8',
+  'mode-off': 'switch-9',
+  'mode-away-extended': 'switch-10',
+  'mode-pause': 'switch-11',
+  // Arming lock switches
+  'arming-lock': 'switch-12',
+  'arming-lock-home': 'switch-13',
+  'arming-lock-away': 'switch-14',
+  'arming-lock-night': 'switch-15',
+};
+
+/** The first index available for custom trip switches. */
+export const MATTER_CUSTOM_TRIP_START_INDEX = 16;
+
+/** Stable device-type-indexed identity for each motion sensor. */
+export const MATTER_SENSOR_IDENTITIES: Record<SensorKind, string> = {
+  arming: 'motion-sensor-1',
+  tripped: 'motion-sensor-2',
+  reset: 'motion-sensor-3',
+};
+
+/** All mode-switch keys, used to push their displayed state to Matter. */
+export const MATTER_MODE_SWITCH_KEYS = [
+  'mode-home',
+  'mode-away',
+  'mode-night',
+  'mode-off',
+  'mode-away-extended',
+  'mode-pause',
+] as const satisfies readonly MatterAccessoryKey[];
+
+/** All trip-switch keys, used to push their displayed state to Matter. */
+export const MATTER_TRIP_SWITCH_KEYS = [
+  'trip',
+  'trip-home',
+  'trip-away',
+  'trip-night',
+  'trip-override',
+] as const satisfies readonly MatterAccessoryKey[];
+
+/** All arming-lock switch keys, used to push their displayed state to Matter. */
+export const MATTER_ARMING_LOCK_SWITCH_KEYS = [
+  'arming-lock',
+  'arming-lock-home',
+  'arming-lock-away',
+  'arming-lock-night',
+] as const satisfies readonly MatterAccessoryKey[];
+
+export const MATTER_MANUFACTURER = 'MiguelRipoll23';
+export const MATTER_MODEL = 'Security System (Matter)';

package/src/handlers/sensor-handler.ts

@@ -0,0 +1,78 @@
+import type { Logging } from 'homebridge';
+import { SENSOR_PULSE_MS } from '../constants/homekit-constant.js';
+import type { EventBusService } from '../services/event-bus-service.js';
+import { EventType } from '../types/event-type.js';
+import type { SensorKind } from '../types/sensor-kind-type.js';
+
+/**
+ * Owns the current state of every motion sensor and publishes changes over the
+ * bus (SENSOR_STATE_CHANGED), which MatterService pushes to Matter. Sensors are
+ * Matter-only, so no HomeKit characteristics are touched here.
+ */
+export class SensorHandler {
+  private readonly currentValueByKind: Record<SensorKind, boolean> = {
+    arming: false,
+    tripped: false,
+    reset: false,
+  };
+
+  constructor(
+    private readonly log: Logging,
+    private readonly bus: EventBusService,
+  ) {}
+
+  // ── Arming sensor ──────────────────────────────────────────────────────────
+
+  updateArmingMotionSensor(value: boolean): void {
+    this.setSensorValue('arming', value);
+  }
+
+  resetArmingMotionSensor(): void {
+    if (this.currentValueByKind.arming) {
+      this.setSensorValue('arming', false);
+    }
+  }
+
+  // ── Tripped sensor ─────────────────────────────────────────────────────────
+
+  pulseTrippedMotionSensor(): void {
+    this.setTrippedMotionSensor(true);
+    this.scheduleReset('tripped');
+  }
+
+  setTrippedMotionSensor(value: boolean): void {
+    this.setSensorValue('tripped', value);
+  }
+
+  resetTrippedMotionSensor(): void {
+    if (this.currentValueByKind.tripped) {
+      this.setSensorValue('tripped', false);
+    }
+  }
+
+  // ── Reset sensor ───────────────────────────────────────────────────────────
+
+  pulseResetMotionSensor(): void {
+    this.setSensorValue('reset', true);
+    this.scheduleReset('reset');
+    this.log.debug('Reset sensor (Triggered)');
+  }
+
+  /** Returns the current value of the given sensor, for Matter startup sync. */
+  getMotionState(kind: SensorKind): boolean {
+    return this.currentValueByKind[kind];
+  }
+
+  // ── Private helpers ────────────────────────────────────────────────────────
+
+  private setSensorValue(kind: SensorKind, value: boolean): void {
+    this.currentValueByKind[kind] = value;
+    this.bus.emit(EventType.SENSOR_STATE_CHANGED, { sensor: kind, value });
+  }
+
+  private scheduleReset(kind: SensorKind): void {
+    setTimeout(() => {
+      this.setSensorValue(kind, false);
+    }, SENSOR_PULSE_MS);
+  }
+}