From b855f8d2f8e7819af07f90b863e9ec9b91cd2054 Mon Sep 17 00:00:00 2001 From: Eduard van Valkenburg Date: Mon, 31 May 2021 15:06:08 +0200 Subject: [PATCH] Update to SIA docs before release (#18027) --- source/_integrations/sia.markdown | 49 +++++++++++++++++++++++++++---- 1 file changed, 43 insertions(+), 6 deletions(-) diff --git a/source/_integrations/sia.markdown b/source/_integrations/sia.markdown index b17603c9b13..134156a5242 100644 --- a/source/_integrations/sia.markdown +++ b/source/_integrations/sia.markdown @@ -1,6 +1,6 @@ --- title: SIA Alarm Systems -description: Instructions on how to integrate SIA DC-09 Based Alarm systems into Home Assistant. +description: Instructions on how to integrate SIA Based Alarm systems. ha_category: - Alarm ha_release: 2021.6 @@ -12,7 +12,7 @@ ha_codeowners: ha_domain: sia --- -The SIA Alarm Systems integration provides integration with several alarm systems that implement the SIA DC-09 Protocol, including [Ajax Systems](https://ajax.systems/). This protocol is listen-only, so does not allow you to turn on/off your alarm system, it just updates the state to reflect your alarm and allows you to act on that state, for instance turning on all lights and opening the curtains when the alarm triggers. +The SIA Alarm Systems integration provides integration with several alarm systems that implement the SIA Protocol, including [Ajax Systems](https://ajax.systems/). This protocol is listen-only, so does not allow you to turn on/off your alarm system, it just updates the state to reflect your alarm and allows you to act on that state, for instance turning on all lights and opening the curtains when the alarm triggers. The underlying package has support for different variants of SIA, including DC-09, DC-04 and a limited set of ADM-CID. If your alarm system uses the ADM-CID standard and it isn't working, please log an issue [here](https://github.com/eavanvalkenburg/pysiaalarm/issues/new). To use this platform, you need to setup your alarm system to communicate using the SIA Protocol and setup several things on the alarm. This integration basically works by Home Assistant listening on a port for messages from the alarm systems and handling and responding to that message and finally updating one or more entities in Home Assistant. @@ -26,7 +26,7 @@ To use this platform, you need to setup your alarm system to communicate using t 6. Insert Home Assistant listening port. This port must not be used by anything else on the machine Home Assistant is running on, see the notes on [port usage](###Portusage) below. 7. Select Preferred Network. Ethernet is preferred if hub and HA in same network. Multiple networks are not tested. 8. Enable Periodic Reports. The interval with which the alarm systems reports to the monitoring station, default is 1 minute. This component adds 30 seconds before setting the alarm unavailable to deal with slights latencies between ajax and HA and the async nature of HA. -9. Encryption is preferred but optional. Password is 16 ASCII characters. +9. Encryption is preferred but optional. Password is 16, 24 or 32 ASCII characters. {% include integrations/config_flow.md %} @@ -36,7 +36,7 @@ port: account: description: Hub account to communicate with. 3-16 ASCII hex characters. Must be set in the alarm system as explained above. encryption_key: - description: Encoding key. 16 ASCII characters. Must be same, as in hub properties. + description: Encoding key. 16, 24 or 32 ASCII characters. Must be same, as in hub properties. ping_interval: description: Ping interval in minutes that the alarm system uses to send "Automatic communication test report" messages, the component adds 30 seconds before marking all entities for that account (alarm and binary sensors) unavailable. Must be between 1 and 1440 minutes. zones: @@ -45,7 +45,7 @@ additional_account: description: Used to ask if a additional account needs to be included, if so will open a dialog for the next account, after checking the current input. {% endconfiguration_basic %} -ASCII characters are 0-9 and ABCDEF, so a account is something like `346EB` and the encryption key has the same characters but needs to be 16 characters in length. +ASCII characters are 0-9 and ABCDEF, so a account is something like `346EB` and the encryption key has the same characters but needs to be 16, 24 or 32 characters in length. ### Note on monitoring multiple alarm systems @@ -57,4 +57,41 @@ The port used with this component must be a port no other processes use on the m ### Entities -In the initial version, after setup you will see one alarm_control_panel per account and zone combination. This has a attribute for `last_heartbeat` that you could use for a template sensor in order to have that separated out. There is also a attribute for the `last_message` that will hold events happening to moisture and smoke sensors in that zone, entities supporting that will follow. +In the initial version, after setup you will see one alarm_control_panel per account and zone combination. This entity will have 5 attributes that reflect all messages that came in for that account and zone, it includes fields for `last_code`, `zone`, `last_message`, `last_id`, `last_timestamp`. The alarm_control_panel state itself is changed based on a subset of values, including but not limited to codes: `CA`, `CB`, `CG`, `BA`, `TA`, `OA`, `NC`, `NL`, for the full list check the code on GitHub. If you expected the state to change then please log which code it was and create an issue on GitHub as well. + +### Events + +Each event that comes into your systems through SIA is also forwarded to the internal HA event bus, which can then be used to trigger automations directly on the codes that came in there. The events are created with event_type set to `sia_event__`. The event_data holds many fields, see details below. + +{% details "Fields in event_data for HA events emitted by the SIA integration." %} + +- message_type +- receiver +- line +- account +- sequence +- content +- ti +- id +- ri (also known as `zone`) +- code +- message +- x_data +- timestamp +- event_qualifier +- event_type +- partition +- extended_data (list) + - identifier + - name + - description + - length + - characters + - value +- sia_code + - code + - type + - description + - concerns + +{% enddetails %}