homebridge-qolsys-panel

Qolsys IQ Panel bridge for Homebridge. Pairs as a virtual IQ Remote over local mTLS/MQTT, inspired by the public behavior and integration model used by ha-qolsys-panel / QolsysController for Home Assistant. No AppDaemon, no separate MQTT broker: this plugin talks to the panel directly.

Requirements

• A Qolsys panel that supports IQ Remote pairing (IQ Panel 2+/4, IQ Panel 4, IQ Hub, IQ Pro, etc.)
• Homebridge and the panel on the same network subnet (mDNS pairing doesn't route across subnets)
• The panel's installer or dealer code, to authorize pairing on the panel itself

What it exposes

• Security System — one per partition. Arm Stay/Away/Night and Disarm, mapped to the panel's real state machine (including the exit-delay window and the panel's own alarm-triggered state).
• Sensors — contact (door/window), motion, smoke, carbon monoxide, and leak sensors, one accessory per zone. Panel-internal zones (keypads, panel modules, etc.) are intentionally not exposed — they aren't real intrusion sensors.
• Garage Door Opener — for Alarm.com/ADC-bridged devices (e.g. a MyQ garage door integrated through the panel). Any other "virtual device" type (locks, lights) isn't mapped yet; see Limitations below.

Installation and pairing

1. Install the plugin.
2. Open its settings page in Homebridge Config UI and click Pair with Panel. On the panel, go to Settings → Advanced Settings → Installation → Devices → Wi-Fi Devices → IQ Remote Devices and pair — this needs the installer/dealer code. Pairing can take a couple of minutes; the settings page shows live progress.
3. Once paired, the page shows the panel's IP address it detected automatically — confirm or correct it, then Apply Changes and Save.
4. Restart Homebridge. Accessories appear automatically based on what the panel reports.

If you'd rather pair from a terminal (e.g. testing before deploying), npm run pair -- --dir <pki-dir> in this package runs the same pairing flow standalone.

Re-pairing

Pairing again with Pair with Panel generates a fresh identity — it doesn't reuse or invalidate the previous one on the panel side. If you re-pair, remove the old entry from the panel's IQ Remote Devices list once you've confirmed the new one works.

If a re-pair attempt doesn't seem to save on the panel side (the new device never shows up under IQ Remote Devices), the most common cause is a stale entry from a previous identity still sitting in that list — some panel firmware silently ignores a new pairing once its IQ Remote slot limit is reached, rather than erroring. Remove the old entry on the panel first, then use Forget next to the old identity on the plugin's settings page (or npm run pair -- --dir <pki-dir> --id <identity> --clear from a terminal) to delete its local keys, and pair again.

Configuration reference

| Field | Required | Description | |---|---|---| | panelIp | yes | Static local IP of the panel. | | pkiDir | yes | Directory containing the paired identity (the settings page manages this for you). | | identity | no | Only needed if pkiDir contains more than one paired identity. | | pluginIp | no | Override auto-detected local IP, if needed. | | armUserId / disarmUserId | no | Numeric userID of a dedicated panel user, for attribution in the panel's own history log. The panel's PIN hash is never transmitted or verified by this plugin — pairing (the mTLS client cert) is the actual security boundary, not an app-level code check. Defaults to 0 (arm) / 1 (disarm), matching an unauthenticated IQ Remote. |

Known limitations

• Only one partition's worth of testing has been done (a single-partition system). Multi-partition systems should work — each partition becomes its own Security System accessory — but haven't been verified against real hardware.
• Freeze, heat, glass-break, tilt, and shock sensor types have no clean HomeKit equivalent and aren't exposed.
• Virtual devices other than a binary open/close actuator (e.g. ADC-bridged locks or lights) aren't mapped to HomeKit yet.
• If Homebridge restarts without a graceful shutdown (a crash, kill -9, power loss), the panel may take a few minutes to notice the dropped session before accepting a new one from the same identity — a normal docker restart or Homebridge restart is unaffected (this plugin sends a clean disconnect on shutdown).

Credits

Compatibility approach inspired by EHylands/QolsysController and ha-qolsys-panel (MIT). This plugin is an independent implementation in TypeScript, not a port of that code.