Repository files navigation

Created byNiccolò Zapponi andMichael Shamoon.

An [unofficial]Homebridge plugin to integrate the SimpliSafe 3 home security system with HomeKit.

• Works with native Homebridge andoznu/docker-homebridge.
• Compatible with the officialConfig UI X plugin which isrecommended for easiest usage.

Supercharge your SimpliSafe system and integrate with HomeKit the right way!This plugin supports:

• Real time event streaming: get immediate notifications anytime the alarm is armed / disarmed / triggered.
• Sensors: always be on top of your home with immediate access to the sensor status. Create smart automations directly from the Home app (e.g. when the front door is opened, turn the lights on).
• Door locks: lock, unlock and monitor the battery status of your smart door locks.
• Cameras: view your indoor or doorbell cameras directly from the Home app, receive doorbell notifications and motion snapshots.
• Battery monitoring: the Home app will notify you if the battery level of one of your sensors is low.

Here are some example screenshots:

This plugin supports installation and changing settings (forconfig.js) via the popularConfig UI X plugin which is recommended for easiest usage.

Either install and configure using Config UI X or you can manually install the plugin by running:

npm install -g --unsafe-perm homebridge-simplisafe3

If installing manually, add the following configuration to theplatforms array in your Homebridgeconfig.json and then proceed withauthentication.

{    "platform": "homebridge-simplisafe3.SimpliSafe 3",    "name": "Home Alarm"}

In 2021, SimpliSafe transitioned to only supporting a protocol called OAuth for authentication. This requires the user to authenticate in a browser and it is not possible to circumvent this and authenticate directly against the API. This plugin provides two ways to obtain credentials:

1. Users ofConfig UI X (which is included in many Homebridge installations) can initiate this process from the plugin settings. A button will launch the authentication process and you will have to copy and paste the final URL back into the plugin settings. This process involves a few steps:

   1. Upon clicking the "Launch SimpliSafe Login" button you are taken to the SimpliSafe login page. If you are already logged in this step is skipped.
   2. You will be redirected to a page requesting you to approve the login, either via email or 2FA.
   3. After approval, most browsers will not redirect you to the final URL (begins withcom.SimpliSafe.mobile://) but will show an error in the console from which you will need to copy & paste the URL back into the Homebridge settings UI. See notes below about using certain browsers / platforms.
   • ℹ️Many browsers (e.g. Chrome) will not redirect you and will only show an error in the Console (e.g. View > Developer Tools > Javascript Console) and you will have to copy and paste the URL from the error message.
   • Safari v15.1+ neither displays the URL in the console nor visually in the URL bar and thus is not recommended for this process.
   • Also note that this process cannot be performed on a mobile device.

2. Alternatively the plugin provides a command-line method for authenticating. The process works the same as above and can be run usinghomebridge-simplisafe3 login. If you are using a non-standard storage location for Homebridge pass the-d argument e.g.homebridge-simplisafe3 login -d /path/to/storage/.

• The plugin is designed to persistently and proactively maintain authentication with SimpliSafe but obviously this is not perfect. When authentication with SimpliSafe fails, the plugin sets theStatus Fault property of the Alarm totrue. Though you are not able to see this property in the Home app, it can be viewed in other HomeKit apps and you can create automations based on this, for example to send you an email or notification when this happens using the excellenthomebridge-messenger plugin. For more details on an example notification setup seethis discussion.
• TheStatus Fault property will also be set in the event of the plugin failing to set an alarm state either because of auth failure or for example errors communicating with the SimpliSafe API. This can help alert you if the alarm state did not successfully change.

These enable camera support. SeeCamera Support for more details.

Type: boolean (defaultfalse)

Switch this on to get more details about your sensors and plugin behavior in your Homebridge logs. This can be useful if you are having trouble or need to report an issue.

Type: string

Add this parameter in case you have multiple protected locations or accounts with SimpliSafe, this is your "account number" in Simplisafe. The best way to ensure you have the correct number is to check under theSimpliSafe web control panel > View Account and look foraccount # next to the correct plan. For most users this is the same as the serial number at the bottom of your base unit.

Type: integer (default15 seconds)

The frequency with which the plugin will poll sensors (e.g. Entry sensors), since entry sensor changes (opening/closing) are not pushed from SimpliSafe. Warning: setting this value too low will likely lead to your IP address being (temporarily) blocked by SimpliSafe.

Type: boolean (defaulttrue)

By default, the plugin will persist accessories to avoid losing automations etc. Set this tofalse to remove old accessories that no longer exist in SimpliSafe from HomeKit.

Type: array

Accepts a list of SimpliSafe device serial numbers (which can be found in the SS app) and excludes these devices from HomeKit.

* SimpliCams provide motion notifications only if the privacy shutter is open.

** The default SimpliSafe settings for motion sensors are "Disabled" when alarm is "Off" or "Home", in which case motion events will not be accurate since they won't always trigger. For consistency of the Home app, motion sensors need to be switched to either "Secret Alert" or "Alarm" inevery alarm mode for the sensors to appear in the app.For example, setting the motion sensor to Secret Alert in Off and Home mode and Alarm in Away modewill display it in the Home app, whereas setting it to Disabled in Off mode, Secret Alert in Home mode and Alarm in Away modewon't, since the sensor state and automations in the Home app would be inaccurate.Using the "Secret Alert" setting will allow for motion events at all times but note thatthis will also record a video clip when motion events are triggered.

All devices also support low battery warnings.

To enable camera support, simply switch"cameras": true in yourconfig.json (or set via Config UI X admin). Currently only the SimpliCam and Video Doorbell Pro are supported.

This plugin includesffmpeg-for-homebridge to automatically include a compatible build of ffmpeg and thus the plugin works "out of the box" without requiring a custom ffmpeg build.

For advanced scenarios including specifying a custom ffmpeg build or command line arguments, you can set them via plugin settings in Config UI X or manually inconfig.json*:

"cameraOptions": {    "ffmpegPath": "/path/to/custom/ffmpeg",    "sourceOptions": "-format: flv ... (any other ffmpeg argument)",    "videoOptions": "-vcodec h264_omx -tune false ... (any other ffmpeg argument)",    "audioOptions": "-ar 256k ... (any other ffmpeg argument)"}

Any arguments provided insourceOptions,videoOptions andaudioOptions will be added to the list of arguments passed to ffmpeg, or will replace the default ones if these already exist.To add an argument that requires no additional parameter, e.g.-re, then add it as"-re".To remove a default argument, define it withfalse as its value, e.g."-tune false".

The bundled build of ffmpegincludes hardware acceleration on supported Raspberry Pi models but in order to enable this you must check the settingAdvanced Camera Settings >Enable Hardware Acceleration for Raspberry Pi (or set"enableHwaccelRpi" under"cameraOptions" totrue inconfig.json).

Note that enabling this option assumes you are using the bundled version of ffmpeg and thus may not work if you specify a custom one.

• If you are running Homebridgeoznu/docker-homebridge camera streaming is limited to 720px wide.
• Due to transcoding requirements, when using a Raspberry Pi 3b video feeds will disconnect after ~20 seconds. RPi 4 or newer is recommended. Seeissue #147

All feedback is welcomed. For bugs please open an issue here. For feature requests or questions please use discussions.

The officialHomebridge Discord server andReddit community are other great places to ask for help.