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

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 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
system.timestamp	HH:MM:SS,DD-MM-YYYY	R	timestamp when the message was received by HSYCO
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
type	string or "unknown"	R	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

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.

note

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.

note

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