All chapters

Alarm panels

Huntress receives events from conventional alarm control panels that report over IP with SIA DC-09 or Ademco Contact ID, the protocols used by Bosch, DSC, Honeywell and almost every other manufacturer. It sits beside, not in place of, an alarm receiving centre: the panel can report to both.

What a panel is in Huntress#

An alarm panel belongs to a place and has an account code: the identifier the panel puts in every message. Huntress looks the panel up by that code and normalises each event code into the common ontology. Panels can have named zones, each optionally linked to a sensor, so a panel zone and a stand-alone detector share one history.

Account codes#

An account code is 1 to 16 hexadecimal characters. Huntress compares codes in upper case without leading zeros, so 0ABC and abc are the same. The code you program into the panel is the one shown on the panel's page; if you leave it empty, Huntress generates a random 8-character code. Account codes are unique across all organisations on a server, because the TCP protocols carry no organisation: a code already used elsewhere is refused.

SIA DC-09 (port 2000)#

DC-09 wraps SIA events in a framed TCP message with a CRC. Huntress listens on port 2000. The panel's IP communicator must be programmed to report to your server's address and that port. Huntress accepts SIA-DCS (SIA events), ADM-CID (Contact ID inside DC-09) and NULL (supervision) messages and answers each one:

DC-09 replies
Reply	Meaning
ACK	The event was stored. It is sent only after storing, never before.
NAK	The frame was damaged (bad CRC or format). The panel should retry.
DUH	The frame was intact but cannot be processed: a missing or wrong key, or an unencrypted frame for a panel that has a key.

A NULL supervision message marks the panel as seen and stores nothing. An unknown account code gets the same ACK as a known one and the event is discarded, so account codes cannot be probed.

Encrypted DC-09#

For AES-encrypted DC-09 (AES-CBC, zero initial vector), enter the panel's key on the alarm panel's settings page: 32, 48 or 64 hexadecimal digits, or 16, 24 or 32 characters, exactly as programmed in the panel. Panels disagree on which form they mean, so Huntress tries both readings and keeps the one that decrypts to a valid message.

A panel that has a key must report encrypted; an unencrypted frame gets DUH. A panel without a key cannot send encrypted frames.
An encrypted frame must be stamped within 40 seconds before to 20 seconds after the server's clock. This is the replay protection, so keep both clocks right; a rejected frame is answered with the server's time and panels adjust their own from it.
The reply is encrypted too. The key is a secret like a token: it is shown only on the panel's settings page and never logged.

Contact ID (port 2001)#

Plain Contact ID over TCP arrives on port 2001 as one ASCII line: ACCT MT QXYZ GG CCC, where ACCT is the 4-digit hexadecimal account, MT the message type (18), Q the qualifier (1 new event, 3 restore, 6 previously reported), XYZ the 3-digit event code, GG the partition and CCC the zone or user number. Huntress answers 0x06 (ACK) after storing and 0x15 (NAK) otherwise, which makes the panel retry. This port has no encryption.

Not for the open internetPorts 2000 and 2001 are plain TCP. There is no TLS on any alarm-panel listener. Keep them on a trusted network or a VPN, or restrict them to your panels' addresses in the firewall.

HTTP submission#

A panel or gateway can also post to /hunt/{panelToken} with a panel token (shown on the panel's page, different from the account code):

A SIA DC-03 message

curl -X POST https://<host>/hunt/<panel-token> \
  -H "Content-Type: application/x-sia-dc03" \
  -d 'N ri+0001#0000/0000/[1234]|BA0101|'

A Contact ID message

curl -X POST https://<host>/hunt/<panel-token> \
  -H "Content-Type: application/x-contact-id" \
  -d '1234 18 1130 01 001'

Zones and partitions#

Name a panel's zones on its page (zone numbers up to 65535, at most 200 per panel). An event from an unnamed zone is shown as “Zone N”. Link a zone to a sensor and the panel's events for that zone appear in the sensor's history too. The partition (group) number in each message is stored with the event and with the zone's state; Huntress has no separate partition setup.

Verified alarms#

Some codes are the manufacturer's statement that an alarm has been independently confirmed: SIA BV (burglary verified), BG, BM, FM, FV, HV and Contact ID 139. When one arrives, the incident it opens or joins is raised to confidence C5 Verified automatically. The star in the event reference marks these.

Arming state and commands#

Open and close events from the panel become armed away, armed stay and disarmed events. A rule can test them with the Sensor state condition (armed or disarmed), judged from the most recent arming event of the place in the last 24 hours, not per panel or partition.

No panel controlHuntress listens to a panel; it cannot arm or disarm it. The Arm zone and Disarm zone rule actions send a command to an integration URL that you provide, for example a gateway or a script that talks to your panel. Huntress can also be armed on its own, without a panel: see Arming.

Supervision keeps the panel's last-seen time current. Huntress does not yet mark a silent panel offline by itself; to be told when a panel stops reporting, supervise its zones with a sensor that has uptime monitoring or a rule that watches for the absence of events.

Provisioning#

Panels can be created and extended by script with POST /api/v1/panels/ensure. See Provisioning API.