SIASERVER
The SIASERVER driver implements a SIA (Security Industry Association protocol) server, specifically following the DC-09 specification. It has been developed and tested with HSYCO acting as a SIA DC-09 server, though compatibility with other SIA protocol variants is possible but not guaranteed.
Communication
The driver listens for incoming TCP connections from SIA-compatible devices, decodes the received messages (including optional decryption), and exposes the most relevant fields as datapoints. It also allows sending control or response messages.
HSYCO Configuration
Add a SIASERVER I/O Server in the I/O Servers section of the Settings and set its parameters:
| Name | Default | Values | Description |
|---|---|---|---|
| port | 6410 | number | TCP port number on which the server listens |
| threads | 1 | number | number of threads used to handle connections |
| timestampdelayoffset | 20 | 0-86400 | maximum allowed time (in seconds) in the future for a valid message timestamp. If set to 0 the timestamp validation is disabled |
| timestampadvanceoffset | 40 | 0-86400 | maximum allowed time (in seconds) in the past for a valid message timestamp. If set to 0 the timestamp validation is disabled |
| encryption | false | false | enable AES encryption based on AES/CBC/NoPadding |
| true | disable encryption | ||
| encryptiontype | aes-128 | aes-128 | encryption mode if encryption is enabled is AES-128 |
| aes-256 | encryption mode if encryption is enabled is AES-256 | ||
| secret | string | secret key for AES encryption. Must match the key configured in the SIA device. |
High Availability
- Shutdown when inactive: defaults to false.
Datapoints
The most important datapoints are “event”, “crc.error”, and “timestamp.error”. “event” contains the meaningful part of the SIA message. All other datapoints are useful for debugging purposes. “timestamp.seconds.elapsed” can be useful for writing an EVENTS program that sends a notification if no SIA messages are received for an extended period of time.
| Datapoint | Type | R | Description |
|---|---|---|---|
| account | string | R | the SIA account number that sent the message |
| crc.calculated | hex string | R | locally calculated CRC based on the received message payload |
| crc.error | 0 | R | no CRC errrors |
| 1 | R | CRC error | |
| crc.received | hex string | R | CRC value received in the message |
| crcpayload | string | R | message payload used to compute the CRC |
| decrypted.message | string | R | decrypted message body, if encryption is enabled |
| event | string | R | SIA event message. Could be empty, in case, for example of a NULL message |
| last.response.sent | string | R | the last response message sent to the SIA device |
| last.command.sent | string | R | the last RSP command sent to the SIA device |
| received.raw | string | R | raw incoming message, as received |
| seq | number | R | sequence number of the message |
| timestamp | string or "unknown" | R | timestamp extracted from the message (if present) |
| timestamp.seconds.diff | number | R | difference in seconds between system timestamp and SIA message timestamp |
| timestamp.seconds.elapsed | number | R | number of seconds since the last SIA message was received. Updated every 60 seconds of when a new message is received |
| type | string or "unknown" | R | received message type parsed from the protocol |
| timestamp.error | 0 | R | no timestamp errrors |
| 1 | R | timestamp error | |
| command | <rcvr>-<pref>-<payload> | W | send the command to the SIA on premises equipment. rcrv and pref are numbers. See the next section for details |
| commands.queue | clear | W | clear the commands queue |
| commands.queue.length | number | R | the length of the commands queue |
I/O Server Logic
This I/O Server listens for SIA protocol commands on the TCP port specified in the driver options.
Upon receiving a valid SIA command:
It responds with an ACK (Acknowledge) if the timestamp check is either correct or disabled.
Otherwise, it responds with a NAK (Negative Acknowledge) and the current timestamp.
When a NULL command is received, the server responds with an ACK unless there are commands queued. In that case, it sends the oldest command from the command buffer. This logic applies identically in both encrypted and clear (unencrypted) modes
Sending Commands
You can send a command to a connected SIA device by writing a value to the command datapoint.
SIA commands to be sent are queued in a first-in, first-out (FIFO) buffer and transmitted one at a time upon receipt of a NULL message from the on-premises equipment.
Therefore, to facilitate immediate command transmission, it is recommended to reduce the time interval between consecutive NULL messages to a few seconds.
For encrypted messages, commands will have the identifier *RSP. The timestamp, in SIA format, will be appended and encrypted at the end of the message, just before the carriage return.
The syntax is the following
<driverid>.<command> = <rcvr>-<pref>-<payload>
Where:
rcvr: receiver number - The premise equipment may be programmed to further extend the identification provided by the account number and account prefix by providing a receiver number. This field is optional.
pref: account prefix - The account prefix can be programmed into the premises equipment to extend the identification provided by the account number. This field is mandatory.
payload: the SIA message payload, in which the #acct (account number) part before the brackets [ and ] may not match the account number contained within the message data.
Examples of valid payloads:
#12345[#12345"TEST"]
or
#12345[#7890"TEST"]
Examples of EVENTS programming:
TIME : IO sia.command = "0-0-#12345[COMMAND]"
In this example:
- receiver number = 0
- account prefix = 0
- the payload is #12345[COMMAND]
If encryption is enabled, only the content after the first square bracket (COMMAND] in this case) will be encrypted. The rest of the payload #12345 remains in clear text.
This behavior complies with the SIA DC-09 specification, where encryption applies exclusively to the message body after the first [ till the <CR> char at the end of the message.
TIME : IO sia.command = "2-[COMMAND]"
In this example:
- receiver number = omitted, not present
- account prefix = 2
- the payload is [COMMAND]
If encryption is enabled, only the content after the first square bracket (COMMAND] in this case) will be encrypted.
This behavior complies with the SIA DC-09 specification, where encryption applies exclusively to the message body after the first [ till the <CR> char at the end of the message.
TIME : {
ioSet("sia.command", "0-[#12345|\\\"TEST\\\"AWAYARM,1]");
}
In this example:
- receiver number = 0
- account prefix = 0
- the payload is #12345|"TEST"DISARM,1,2,3]
If encryption is enabled, only the content after the first square bracket (#12345|\\\"TEST\\\"AWAYARM,1] in this case) will be encrypted.
This behavior complies with the SIA DC-09 specification, where encryption applies exclusively to the message body after the first [ till the <CR> char at the end of the message. Note that the characters \\\ are used to escape the " character.
Release Notes
3.10.0
- initial release
SIA is a trademark of Security Industry Association