Alarm Systems¶

An alarm system uses sensors and keypads to implement a stateful security system. It can be disarmed, armed, and raises events when an alarm is triggered.

Arming and disarming is done by:

• REST-API request
• Keypads via PIN code
• Keyfobs

Alarms are be triggered by:

• Motion sensors
• Open/close sensors
• Vibration sensors
• Switch button events
• Light state changes
• Externally via REST-API

An alarm system simplifies the configuration of a Zigbee security system for REST-API clients. It aligns with the design of traditional security systems, allowing to bridge with integrations in home automation systems like:

• Homebridge https://www.npmjs.com/package/homebridge-alarm-panel
• Home Assistant https://www.home-assistant.io/integrations/manual

Basics¶

The alarm systems REST-API is designed with the following high level principles.

Arm modes¶

There are four arm modes which determine when alarms are triggered.

Entry and exit delays¶

Each arm mode has configurable entry and exit delays, in the range of 0–255 seconds.

• Exit delays allow leaving the house, after arming the alarm system, without triggering an alarm.
  
• Entry delays allow entering the house while the alarm system is armed, to disarm it before an alarm is triggered.

Alarm trigger durations¶

Each arm mode has a configurable trigger duration, in the range of 0–255 seconds.

A trigger duration determines how long a alarm system stays in the in_alarm state, when an alarm is triggered. For example, when an alarm is triggered in the armed_away state, the alarm system moves to the in_alarm state for 120 seconds (default alarm trigger duration), and generates events, after that it returns to the armed_away state.

PIN codes¶

A PIN code protects arming and disarming the alarm system. It’s compared to the entered code of keypads and REST-API requests for arming and disarming.

Important: PIN codes are configured for whole alarm system, not a single keypad. Multiple keypads, as well as the REST-API refer to the same PIN codes.

Currently only one PIN code, aka “code0”, is supported. In future multiple PIN codes can be configured. Internally a PIN code has the state “enabled” or “disabled”. This makes it possible to dynamically enable a PIN code, for example a rule enables the guest PIN code on weekends.

Create alarm system ¶

POST /api/<apikey>/alarmsystems

Creates a new alarm system. After creation the arm mode is set to disarmed.

Parameters¶

Example request data¶

{ "name": "Guest house alarm system" }

Response¶

HTTP/1.1 200 OK

[ { "success": { "id": "2" } } ]

Response fields¶

Possible errors¶

400 Bad Request

403 Forbidden

Get all alarm systems ¶

GET /api/<apikey>/alarmsystems

Returns a list of all alarm systems.

Parameters¶

None

Response¶

HTTP/1.1 200 OK

{

  "1": {
    "name": "default",
    "config": {
        "armmode": "armed_away",
        "configured": true,
        "disarmed_entry_delay": 0,
        "disarmed_exit_delay": 0,
        "armed_away_entry_delay": 120,
        "armed_away_exit_delay": 120,
        "armed_away_trigger_duration": 120,
        "armed_stay_entry_delay": 120,
        "armed_stay_exit_delay": 120,
        "armed_stay_trigger_duration": 120,
        "armed_night_entry_delay": 120,
        "armed_night_exit_delay": 120,
        "armed_night_trigger_duration": 120
    },
    "state": {
        "armstate": "armed_away",
        "seconds_remaining": 0
    },
    "devices": {
        "ec:1b:bd:ff:fe:6f:c3:4d-01-0501": {
            "armmask": "none"
        },
        "00:15:8d:00:02:af:95:f9-01-0101": {
            "armmask": "AN",
            "trigger": "state/vibration"
        }
    }
  }
}

Response fields¶

See Get alarm system for a full description of the attributes.

Possible errors¶

403 Forbidden

Get alarm system ¶

GET /api/<apikey>/alarmsytems/<id>

Returns all attributes of an alarm system.

Parameters¶

None

Response¶

HTTP/1.1 200 OK

{
    "name": "default",
    "config": {
        "armmode": "armed_away",
        "configured": true,
        "disarmed_entry_delay": 0,
        "disarmed_exit_delay": 0,
        "armed_away_entry_delay": 120,
        "armed_away_exit_delay": 120,
        "armed_away_trigger_duration": 120,
        "armed_stay_entry_delay": 120,
        "armed_stay_exit_delay": 120,
        "armed_stay_trigger_duration": 120,
        "armed_night_entry_delay": 120,
        "armed_night_exit_delay": 120,
        "armed_night_trigger_duration": 120
    },
    "state": {
        "armstate": "armed_away",
        "seconds_remaining": 0
    },
    "devices": {
        "ec:1b:bd:ff:fe:6f:c3:4d-01-0501": {
            "armmask": "none"
        },
        "00:15:8d:00:02:af:95:f9-01-0101": {
            "armmask": "AN",
            "trigger": "state/vibration"
        }
    }
}

Response fields¶

Config object¶

The default values for entry_delay, exit_delay, and trigger_duration are 120 seconds. Delay options are described in Entry and exit delays.

State object¶

Devices object¶

The keys in the devices object refer to the uniqueid of a light, sensor, or keypad.

Possible errors¶

403 Forbidden

404 Not Found

Set alarm system attributes ¶

PUT /api/<apikey>/alarmsystems/<id>

Sets attributes of an alarm system.

Parameters¶

Example request data¶

{
  "name": "Home alarm system"
}

Response¶

HTTP/1.1 200 OK

[ { "success": { "/alarmsystems/1/name": "Home alarm system" } } ]

Possible errors¶

400 Bad Request

403 Forbidden

404 Not Found

Set alarm system configuration ¶

PUT /api/<apikey>/alarmsystems/<id>/config

This request configures the basic configuration of an alarm system.

Parameters¶

The PIN code code0 is verified when a keypad tries to arm or disarm the alarm system. It is also required to change the target armmode via REST-API.

Example request data¶

{
  "code0": "12345"
}

Response¶

HTTP/1.1 200 OK

[ { "success": { "/alarmsystems/1/config/configured": true } } ]

Possible errors¶

400 Bad Request

403 Forbidden

404 Not Found

Add keypad to alarm system ¶

PUT /api/<apikey>/alarmsystems/<id>/device/<uniqueid>

A keypad can be added to exactly one alarm system.

→ After pairing a keypad as sensor, it’s automatically added to the default alarm system with id “1”.

• Keypads use the the alarm system PIN code (see Update alarm system configuration), which is verified each time the keypad arms or disarms the alarm system.
• If a valid PIN code is entered on the keypad, the alarm system’s state changes according to the requested arm or disarm command.
• Important: For REST-API clients a keypad is a read-only sensor. The alarm system automatically takes care of: controlling the keypad’s panel state, entry and exit delays, and state transitions.

Parameters¶

Empty JSON object.

{ }

Response¶

HTTP/1.1 200 OK

[ { "success": { "added": "/alarmsystems/1/device/ec:1b:bd:ff:fe:6f:c3:4d-01-0501" } } ]

Sensor resource¶

Each Keypad is represented by a “ZHAAncillaryControl” /sensor resource, which is wired to the alarm system and automatically reflects its state on the keypad panel.

Example Linkind keypad

GET /api/12345/sensors/ec:1b:bd:ff:fe:6f:c3:4d-01-0501

{
    "config": {
        "battery": 95,
        "enrolled": 1,
        "on": true,
        "pending": [],
        "reachable": true
    },
    "ep": 1,
    "etag": "5aaa1c6bae8501f59929539c6e8f44d6",
    "lastseen": "2021-07-25T18:07Z",
    "manufacturername": "lk",
    "modelid": "ZB-KeypadGeneric-D0002",
    "name": "AncillaryControl 41",
    "state": {
        "action": "armed_stay",
        "lastupdated": "2021-07-25T18:02:51.172",
        "lowbattery": false,
        "panel": "exit_delay",
        "seconds_remaining": 55,
        "tampered": false
    },
    "swversion": "3.13",
    "type": "ZHAAncillaryControl",
    "uniqueid": "ec:1b:bd:ff:fe:6f:c3:4d-01-0501"
}

The read-only attribute state.action contains the last action a user invoked on the keypad.

When a keypad requests a new arm mode it is not set immediately, first the state machine transitions through various states with exit and entry delays.

The read-only attribute state.panel represents the state machine and mirrors the alarm system state.armstate attribute. It reflects what is shown on the panel (when activated by the keypad’s proximity sensor).

Note that due its shared nature, the attribute can also be controlled by other keypads, and by arming and disarming the alarm system via REST-API request.

Possible errors¶

403 Forbidden

404 Not Found

Add device to alarm system ¶

PUT /api/<apikey>/alarmsystems/<id>/device/<uniqueid>

A device can be linked to exactly one alarm system. If it is added to another alarm system, it is automatically removed from the prior one.

This request is used for adding and also for updating a device entry.

The uniqueid refers to sensors, lights, or keypads. Adding a light can be useful, e.g. when an alarm should be triggered, after a light is powered or switched on in the basement.

Example request data¶

PUT /api/12345/alarmsystems/1/device/00:15:8d:00:02:af:95:f9-01-0101

{
    "armmask": "AN",
    "trigger": "state/vibration"
}

Parameters¶

{ }

Response¶

HTTP/1.1 200 OK

[ { "success": { "added": "/alarmsystems/1/device/00:15:8d:00:02:af:95:f9-01-0101" } } ]

Remove device from alarm system ¶

DELETE /api/<apikey>/alarmsystems/<id>/device/<uniqueid>

Removes a device from an alarm system. Note that the respective sensor or light resource is not deleted, only the link to the alarm system.

Parameters¶

None

Response¶

HTTP/1.1 200 OK

[ { "success": { "removed": "/alarmsystems/1/device/00:15:8d:00:02:af:95:f9-01-0101" } } ]

Possible errors¶

403 Forbidden

404 Not Found

Arm and disarm via REST-API ¶

PUT /api/<apikey>/alarmsystems/<id>/disarm
PUT /api/<apikey>/alarmsystems/<id>/arm_away
PUT /api/<apikey>/alarmsystems/<id>/arm_stay
PUT /api/<apikey>/alarmsystems/<id>/arm_night

To arm or disarm an alarm system, the REST-API provides four requests, one for each mode. The request body is required to specify a valid code0 PIN code, which is verified to protect against unauthorized access.

When arming or disarming the alarm system via REST-API, all keypads will reflect the state changes on their panels automatically. Note that the configured entry and exit delays are processed before the final target armmode is reached.

Parameters¶

Example request data¶

PUT /api/12345/alarmsystems/1/arm_away

{
    "code0": "12345"
}

Response¶

HTTP/1.1 200 OK

[ { "success": { "/alarmsystems/1/config/armmode": "armed_stay" } } ]

Trigger alarm via REST-API ¶

TODO