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:

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.

Arm modeDescription
disarmed No alarms are triggered, and the system is inactive.
armed_away Alarms are triggered by all devices in the inner and outer perimeter.
armed_stay Alarms are triggered only by the outer perimeter, e.g. the door open/close sensor or a vibration sensor to detect glass break of a window. Devices in the inner perimeter, like an presence sensor in the kitchen won't trigger an alarm.
armed_night Similar to armed_stay, this mode includes additional devices, which are usually not approached at night, e.g. the window open/close sensor of the living room.

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.

Important

The request is not implemented yet.

Note

This is only needed than more than one alarm system is needed. The “default” alarm system with id “1” is created automatically.

Running multiple alarm systems is useful to seperate areas, for example: One alarm system for the house, and one for the guest house. Each with their own keypads and PIN codes.

Parameters

FieldTypeDescriptionRequired
name String The name of the new alarm system required

Example request data

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

Response


HTTP/1.1 200 OK


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

Response fields

FieldTypeDescription
id String The unique identifier of the alarm system.

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

FieldTypeDescription
name String The alarm system name. RW
config Object The configuration of the alarm system. RW
state Object The current state of the alarm system. R
devices Object List of devices which are added to the alarm system. R
Config object
FieldTypeDescription
armmode String

The target arm mode.

  • "disarmed"
  • "armed_stay"
  • "armed_night"
  • "armed_away"
RW
configured Bool Is true when a PIN code is configured. R
disarmed_entry_delay Number (0–255) The delay in seconds before an alarm is triggered. RW
disarmed_exit_delay Number (0–255) The delay in seconds before the arm mode is armed. RW
armed_away_entry_delay Number (0–255) The delay in seconds before an alarm is triggered. RW
armed_away_exit_delay Number (0–255) The delay in seconds before the arm mode is armed. RW
armed_away_trigger_duration Number (0–255) The alarm trigger duration. RW
armed_stay_entry_delay Number (0–255) The delay in seconds before an alarm is triggered. RW
armed_stay_exit_delay Number (0–255) The delay in seconds before the arm mode is armed. RW
armed_stay_trigger_duration Number (0–255) The alarm trigger duration. RW
armed_night_entry_delay Number (0–255) The delay in seconds before an alarm is triggered. RW
armed_night_exit_delay Number (0–255) The delay in seconds before the arm mode is armed. RW
armed_night_trigger_duration Number (0–255) The alarm trigger duration. RW

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
FieldTypeDescription
armstate String

The current alarm system state, which can be different from the config.armmode during state transitions.

  • "disarmed"
  • "armed_stay"
  • "armed_night"
  • "armed_away"
  • "exit_delay"
  • "entry_delay"
  • "in_alarm"
  • "arming_stay"
  • "arming_night"
  • "arming_away"
R
seconds_remaining Number (0–255)

During "exit_delay" and "entry_delay" states, this value holds the remaining time. In all other states the value is 0.

R
Devices object

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

FieldTypeDescription
armmask String

A combination of arm modes in which the device triggers alarms.

  • A — armed_away
  • N — armed_night
  • S — armed_stay
  • "none" — for keypads and keyfobs
R
trigger String

Specifies arm modes in which the device triggers alarms.

  • "state/presence"
  • "state/open"
  • "state/vibration"
  • "state/buttonevent"
  • "state/on"

This attribute is not available for keypads and keyfobs.

R

Possible errors

403 Forbidden

404 Not Found


Set alarm system attributes 

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

Sets attributes of an alarm system.

Parameters

FieldTypeDescriptionRequired
name String

Name of the alarm system

(max. 32 characters)

optional

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

FieldTypeDescriptionRequired
code0 String

The main PIN code

(4–16 characters)

optional
disarmed_entry_delay Number (0–255) The delay in seconds before an alarm is triggered. optional
disarmed_exit_delay Number (0–255) The delay in seconds before the arm mode is armed. optional
armed_away_entry_delay Number (0–255) The delay in seconds before an alarm is triggered. optional
armed_away_exit_delay Number (0–255) The delay in seconds before the arm mode is armed. optional
armed_away_trigger_duration Number (0–255) The alarm trigger duration. optional
armed_stay_entry_delay Number (0–255) The delay in seconds before an alarm is triggered. optional
armed_stay_exit_delay Number (0–255) The delay in seconds before the arm mode is armed. optional
armed_stay_trigger_duration Number (0–255) The alarm trigger duration. optional
armed_night_entry_delay Number (0–255) The delay in seconds before an alarm is triggered. optional
armed_night_exit_delay Number (0–255) The delay in seconds before the arm mode is armed. optional
armed_night_trigger_duration Number (0–255) The alarm trigger duration. optional

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.

Note

  1. Be aware that some keypads might not support long PIN codes.
  2. The PIN code is write-only, it can’t be read back.
  3. The PIN code is encrypted with scrypt, and stored in the database

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.

Note

The request is the same as Add device to alarm system request, but is allowed to have an empty JSON object as body content.

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.

state.actionDescription
disarmed Sucessful request to disarmed the alarm system.
armed_stay Sucessful request for armed_stay arm mode.
armed_night Sucessful request for armed_night arm mode.
armed_away Sucessful request for armed_away arm mode.
invalid_code The last entered PIN code was invalid.
panic The panic or SOS alarm was triggered.
emergency The emergency alarm was triggert.
fire The fire alarm was triggered.

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.

state.panelEffect on the keypad panel
disarmed Armed and disarmed states are indicated with the respective symbol's LED and one audio beep.
armed_stay
armed_night
armed_away
exit_delay Exit and entry delays are indicated by flashing a symbol's LED and multiple audio beeps. During these states the seconds_remaining attribute holds the remaining time until the next state is reached.
entry_delay
not_ready Error conditions or undefined states, are signaled by audio or flashing a symbol's LED.
in_alarm The alarm state is indicated by intense audio beeps, or a neutral setting if not supported.
arming_stay The arming states are set after the exit_delay state, and before the respective armed state. Like the delay states, they are indicated by multiple audio beeps and flashing a symbol's LED.
arming_night
arming_away

Note

The state.panel attribute is read-only and managed automatically by the alarm system.

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

Note

For keypads and keyfobs the request body can be an empty object.

{ }
FieldTypeDescriptionRequired
armmask String

A combination of arm modes in which the device triggers alarms.

  • A — armed_away
  • N — armed_night
  • S — armed_stay
required
trigger String

Specifies what attribute of a device triggers alarms.

  • "state/presence"
  • "state/open"
  • "state/vibration"
  • "state/buttonevent"
  • "state/on"
  • "state/action"
  • If the parameter is ommited, the default value for the device is selected.
  • The "state/action" refers to the "emergency", "fire", and "panic" buttons of a keypad.
optional

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.

Note

The config/armmode of an alarm system can not be changed with a PUT /config request.

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

FieldTypeDescriptionRequired
code0 String

The configured PIN code of the alarm system.

required

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