homebridge-scout

A Homebridge plugin that enables HomeKit integration for the Scout security system.

Usage no npm install needed!

<script type="module">
  import homebridgeScout from 'https://cdn.skypack.dev/homebridge-scout';
</script>

README

homebridge-scout

A Homebridge plug-in that enables HomeKit integration for the Scout security system.

demo

verified-by-homebridge build status test coverage npm version npm downloads license

Table of Contents

Installation

  1. Install Homebridge.

  2. Install this plug-in: npm install -g homebridge-scout

  3. Update your Homebridge configuration file (~/.homebridge/config.json). See configuration options below.

Configuration

Options

Required

All of the following configuration options are required. If any are missing or invalid, Homebridge will log an error message describing the problem.

  • "platform": Must be "ScoutAlarm".

  • "auth": Your Scout login credentials. Use a member account, not an admin account.

    • "email": Your Scout email.

    • "password": Your Scout password. Don't forget to backslash-escape any double-quotes (e.g. pwd"23 should be "pwd\"123").

Optional

The following configuration options are optional and change the default behavior.

  • "modes": If modes are defined, your Scout system will be added as a HomeKit security system. These map the HomeKit modes to your Scout modes. Your Scout mode names can be found in the Scout app or dashboard. Each HomeKit can be mapped to zero or more† Scout mode(s) (e.g., [], ["Mode A"] or ["Mode A", "Mode B"]). If a HomeKit mode is empty or not provided, it will not be shown in Apple’s Home app.

    • "stay": Possibly ["Home"].
    • "away": Possibly ["Away"].
    • "night": Possibly ["Night"].

    † There are caveats to mapping a HomeKit mode to multiple Scout modes. Let's assume you have four Scout modes (Home, Away, Vacation, and Night) and have mapped the Away HomeKit mode to your Away and Vacation Scout modes. If you arm either the Away or Vacation Scout modes from the Scout app, HomeKit will report the mode as Away with no way to differentiate between the two. Additionally, if you arm the Away HomeKit mode via HomeKit, the plug-in will arm whichever Scout mode is listed first. There would be no way to arm your Vacation mode via HomeKit. This limitation is due to HomeKit's strict 3-mode design.

  • "location": The name of the Scout location you want to integrate. If you only have a single location (most common), this option is unnecessary. If you have multiple locations, you need to choose which one to use. You can find your location names in the sidebar of the Scout app or dashboard.

  • "triggerAlarmImmediately": By default, HomeKit will not consider the alarm triggered until the (optional) alarm delay has expired. Enabling this option causes HomeKit to consider the alarm triggered immediately.

  • "reverseSensorState": V1 Scout systems can get into a state where all of the sensor states are reversed. If this option is set to true, it reverses the sensor state of access sensors, door panels, and motion sensors reported to HomeKit so they work correctly in this scenario.

Example

Update the "platforms" section of your ~/.homebridge/config.json:

{
  "platforms": [
    {
      "platform": "ScoutAlarm",
      "auth": {
        "email": "email@example.com",
        "password": "password123"
      },
      "modes": {
        "stay": ["Home"],
        "away": ["Away", "Vacation"],
        "night": ["Night"]
      }
    }
  ]
}

Device Support

Supported Devices

Scout Device HomeKit Accessory Category HomeKit Services
Hub SECURITY_SYSTEM SecuritySystem
BatteryService
TemperatureSensor¹
Door Panel SENSOR ContactSensor
HumiditySensor¹
TemperatureSensor¹
Access Sensor SENSOR ContactSensor
TemperatureSensor¹
Motion Sensor¹ SENSOR MotionSensor
TemperatureSensor
Water Sensor SENSOR LeakSensor
TemperatureSensor
Smoke Alarm SENSOR SmokeSensor
CarbonMonoxideSensor²
Key Pad SENSOR HumiditySensor
TemperatureSensor

¹ Not supported by Scout's original mesh-based hardware. These devices do not have humidity or temperature sensors, and the motion sensors do not properly trigger motion events.

² Only supported by First Alert's smoke/CO alarm — not by Scout's smoke-only alarm.

Unsupported Devices

Scout Device Feature Request
Glass Break Sensor #27
Video Doorbell #18
Indoor Camera #17
Siren/Zigbee Repeater #26
Panic Button
Remote Control

Credits

  • @Tom2527, for their assistance in debugging and testing v1 hardware support.
  • Scout Security Inc, for providing a open, well-designed API and supplying free motion and water sensors for this project.