Satel Alarm Binding

druciak edited this page May 9, 2017 · 41 revisions

Introduction

This is documentation of openHAB binding for Satel Integra Alarm System which allows you to connect to your alarm system using TCP/IP protocol with ETHM-1 module installed or RS-232 protocol with INT-RS module installed.

For installation of the binding, please see Wiki page Bindings.

NOTE: INT-RS module is supported since version 1.8 of the binding.

Binding Configuration

There are some configuration settings that you can set in the openhab.cfg file. Include the following in your openhab.cfg.

############################### Satel Binding ###################################
#
# Satel ETHM-1 module hostname or IP.
# Leave this commented out for INT-RS module.  
#satel:host=

# ETHM-1 port to use (optional, defaults to 7094), if host setting is not empty.
# INT-RS port to use, if host setting is empty.
#satel:port=7094

# timeout value for both ETHM-1 and INT-RS (optional, in milliseconds, defaults to 5000)
#satel:timeout=5000

# refresh value (optional, in milliseconds, defaults to 10000)
#satel:refresh=10000

# user code for Integra control (optional, if empty binding works in read-only mode)
#satel:user_code=

# encryption key (optional, if empty communication is not encrypted)
#satel:encryption_key=

The only required parameter is satel:host for the ETHM-1 module and satel:port for the INT-RS module. The rest default to the values described in the configuration comments. In order to use ETHM-1 module it is required to enable "integration" protocol for the module in Integra configuration (DLOADX).

Option Description
satel:host Valid only for ETHM-1 module. Specifies either IP or host name of the module
satel:port For INT-RS it specifies the serial port on the host system to which the module is connected, i.e. "COM1" on Windows, "/dev/ttyS0" or "/dev/ttyUSB0" on Linux
For ETHM-1 it specifies the TCP port on which the module listens for new connections. Defaults to 7094.
satel:timeout Timeout value for connect, read and write operations specified in milliseconds. Defaults to 5 seconds
satel:refresh Refresh interval in milliseconds. Defaults to 10 seconds.
satel:user_code Security code (password) of the user used for control operations, like arming, changing state of outputs, etc. It is recommended to use dedicated user for openHAB integration.
satel:encryption_key Key use for encrypting communication between openHAB and ETHM-1 module. To disable encrytpion leave it empty. See also the note below.

NOTE: Encryption requires support for 192 bit AES keys. Oracle Java by default supports only 128 bit keys, therefore "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files" must be installed. OpenJDK supports unlimited AES keys by default.

NOTE: As of version 2.03 ETHM-1 Plus firmware the module disconnects after 25 seconds of inactivity. Setting satel:refresh to value greater than 25000 will cause inability to correctly communicate with the module.

Item Binding

In order to bind to the Integra Alarm system you need to add settings for items defined in your item file. Here is item configuration string syntax:

satel="<object_type>[:<state_type>][:<object_number>,...][:<option>=<value>,...]"

Name of object type, state type and option is case insensitive. For "output" objects state type cannot be specified and must be ommited. object_number must be integer number in range 1-256. Options are comma-separated pairs of name and value separated by = character.

Supported item types: Contact, Switch, Number, Rollershutter. For all but Rollershutter item type only one object_number is allowed. For Rollershutter item there must be exactly two object numbers specified. As there is no information about roller shutter position, state is updated to 0% when "UP" command is received and 100% when "DOWN" command is received, assuming the state will be eventually reached. Number items can be used only if object_number is not given and the number specifies cardinality of objects that are in given state. For example if object is "zone" and state is "violated", item will tell you number of zones violated. See examples section for detailed configuration syntax.

Valid object_type values:

Type Description
zone defines a zone: PIR, contact, etc.
partition defines a partition
output defines an output
doors defines doors
status defines a status item
module defines connection status item
trouble defines a trouble
trouble_memory defines memory of a trouble

Valid state_type values for "zone" objects:

NOTE: Sending commands to zones is available since v1.9 of the binding

Type Notes
violation
tamper
alarm
tamper_alarm
alarm_memory
tamper_alarm_memory
bypass ON command bypasses the zone, OFF unbypasses.
no_violation_trouble
long_violation_trouble
isolate ON command isolates the zone.
masked
masked_memory

Valid state_type values for "partition" objects:

Type Notes
armed ON command arms specified partition in mode 0, OFF disarms. Forces arming if "force_arm" option is specified.
really_armed ON command arms specified partition in mode 0, OFF disarms. Forces arming if "force_arm" option is specified.
armed_mode_1 ON command arms specified partition in mode 1, OFF disarms. Forces arming if "force_arm" option is specified.
armed_mode_2 ON command arms specified partition in mode 2, OFF disarms. Forces arming if "force_arm" option is specified.
armed_mode_3 ON command arms specified partition in mode 3, OFF disarms. Forces arming if "force_arm" option is specified.
first_code_entered
entry_time
exit_time_gt_10
exit_time_lt_10
temporary_blocked
blocked_for_guard
alarm OFF command clears alarms for specified partition
alarm_memory OFF command clears alarms for specified partition
fire_alarm OFF command clears alarms for specified partition
fire_alarm_memory OFF command clears alarms for specified partition
violated_zones
verified_alarms OFF command clears alarms for specified partition
warning_alarms OFF command clears alarms for specified partition

Valid state_type values for "doors" objects:

NOTE: Sending commands to doors is available since v1.9 of the binding

Type Notes
opened ON command opens the doors.
opened_long

Valid state_type values for "status" objects:

Type Notes
service_mode
troubles OFF command clears troubles memory
troubles_memory OFF command clears troubles memory
acu100_present
intrx_present
grade23_set
date_time DateTimeType or StringType command changes Integra date and time

Valid state_type values for "module" objects:

Type Notes
connected status of connection to the module
connected_since date and time when current connection has been established
connection_errors number of consecutive connection errors; clears on successful connection

Valid state_type values for "trouble" objects:

NOTE: Available since v1.10

Type Notes
technical_zone object number range: 1-128
expander_ac object number range: 1-64
expander_batt object number range: 1-64
expander_nobatt object number range: 1-64
system object number range: 1-24, see table below
ptsa_ac AC trouble of CA-64 PTSA modules, object number range: 1-8
ptsa_batt BATT trouble of CA-64 PTSA modules, object number range: 1-8
ptsa_nobatt NO BATT trouble of CA-64 PTSA modules, object number range: 1-8
ethm1 object number range: 1-8
proximity_a object number range: 1-64
proximity_b object number range: 1-64
expander_overload object number range: 1-64
jammed_acu100 object number range: 1-16
device_lobatt object number range: 1-120
device_nocomm object number range: 1-120
output_nocomm object number range: 1-120
expander_nocomm object number range: 1-64
expander_switcherooed object number range: 1-64
keypad_nocomm object number range: 1-8
keypad_switcherooed object number range: 1-8
ethm1_nolan object number range: 1-8
expander_tamper object number range: 1-64
keypad_tamper object number range: 1-8
keypad_init object number range: 1-8
auxiliary_stm object number range: 1-8
master_keyfob object number range: 1-8
user_keyfob object number range: 1-240
device_lobatt1 for Integra 256 Plus - last 120 devices, object number range: 1-120
device_nocomm1 for Integra 256 Plus - last 120 devices, object number range: 1-120
output_nocomm1 for Integra 256 Plus - last 120 devices, object number range: 1-120
technical_zone1 for Integra 256 Plus - zones 129..256, object number range: 1-128

Valid state_type values for "trouble_memory" objects:

NOTE: Available since v1.10

Type Notes
technical_zone object number range: 1-128
expander_ac object number range: 1-64
expander_batt object number range: 1-64
expander_nobatt object number range: 1-64
system object number range: 1-24, see table below
ptsa_ac AC trouble of CA-64 PTSA modules, object number range: 1-8
ptsa_batt BATT trouble of CA-64 PTSA modules, object number range: 1-8
ptsa_nobatt NO BATT trouble of CA-64 PTSA modules, object number range: 1-8
ethm1 object number range: 1-8
proximity_a object number range: 1-64
proximity_b object number range: 1-64
expander_overload object number range: 1-64
jammed_acu100 object number range: 1-16
lcd_restart object number range: 1-8
expander_restart object number range: 1-64
device_lobatt object number range: 1-120
device_nocomm object number range: 1-120
output_nocomm object number range: 1-120
expander_nocomm object number range: 1-64
expander_switcherooed object number range: 1-64
keypad_nocomm object number range: 1-8
keypad_switcherooed object number range: 1-8
ethm1_nolan object number range: 1-8
expander_tamper object number range: 1-64
keypad_tamper object number range: 1-8
keypad_init object number range: 1-8
auxiliary_stm object number range: 1-8
long_violation object number range: 1-128
no_violation object number range: 1-128
zone_tamper object number range: 1-128
technical_zone1 for Integra 256 Plus - zones 129..256, object number range: 1-128
user_keyf | object number range: 1-240
device_lobatt1 for Integra 256 Plus - last 120 devices, object number range: 1-120
device_nocomm1 for Integra 256 Plus - last 120 devices, object number range: 1-120
output_nocomm1 for Integra 256 Plus - last 120 devices, object number range: 1-120
long_violation1 for Integra 256 Plus - zones 129..256, object number range: 1-128
no_violation1 for Integra 256 Plus - zones 129..256, object number range: 1-128
zone_tamper1 for Integra 256 Plus - zones 129..256, object number range: 1-128

System troubles:

Number Description
1 OUT1 trouble
2 OUT2 trouble
3 OUT3 trouble
4 OUT4 trouble
5 +KPD trouble
6 +EX1 or +EX2 trouble
7 BATT trouble
8 AC trouble
9 DT1 trouble
10 DT2 trouble
11 DTM trouble
12 RTC trouble
13 no DTR signal
14 no BATT present
15 external modem initialization trouble
16 external model command (ATE0V1Q0H0S0=0) trouble
17 no voltage on telephone line (INTEGRA 24, 32, 64 and 128)
17 auxiliary ST processor trouble (INTEGRA 128-WRL)
18 bad signal on telephone line
19 no signal on telephone line
20 monitoring to station 1 trouble
21 monitoring to station 2 trouble
22 EEPROM or access to RTC trouble
23 RAM memory trouble
24 INTEGRA main panel restart memory

Valid options:

Name Description
force_arm forces arming for arming commands
commands_only item accepts commands, but state of the item is not updated
invert_state uses 0 as active state (zones and outputs only)

Satel Actions

Available as of openHAB 1.9

NOTE: Satel Binding v1.9+ must be installed in order to use Satel Actions

The Satel Action bundle provides actions to read event log of the connected alarm system, check current connection status and override configured user code.

  • boolean satelIsConnected() - returns true if connected to communication module and false otherwise
  • Object[] satelReadEvent(int eventIndex) - reads event log record for given index; records must be read one by one from most recent record under index -1; see record description below
  • String satelReadDeviceName(String deviceType, int deviceNumber) - reads description of a device; device type must be one of PARTITION, ZONE, USER, EXPANDER, LCD, OUTPUT, TIMER, TELEPHONE, OBJECT
  • void satelSetUserCode(String newUserCode) - overrides configured user code to a given one; allows to execute commands not available for default user configured in the settings
  • void satelResetUserCode() - reverts user code set by satelSetUserCode(String newUserCode) to the value configured in openhab.cfg/satel.cfg.

Event record fields:

Field Type Description
timestamp DateTimeType time when the event happened
partition Integer partition number
event class Enum one of ZONE_ALARMS, PARTITION_ALARMS, ARMING, BYPASSES, ACCESS_CONTROL, TROUBLES, USER_FUNCTIONS, SYSTEM_EVENTS
event code Integer code of the event
restoration flag Boolean
event description String
kind of description Integer
source Integer
object Integer
user control number Integer
next event index Integer index that must be passed to read next record from the log
current event index Integer index of the current record

Examples

Partition item with ability to arm and disarm:

Switch PartitionArmed "Partition armed" { satel="partition:armed:1" }

Sitemap definitions for above example. The second one allows only to arm the partition:

Switch item=PartitionArmed
Switch item=PartitionArmed mappings=[ON="Arm"]

Partition item with ability to force arming:

Switch Partition1 "Partition armed" { satel="partition:armed:1:force_arm" }

Simple contact item:

Contact	Zone1 "Zone #1 violated" { satel="zone:violation:1" }

Zone bypass status with ability to change the state:

Switch	Zone1 "Zone #1 bypass" { satel="zone:bypass:1" }

Number of zones violated:

Number	ZonesViolated "Zones violated [%d]" { satel="zone:violation" }

Simple output item with ability to change its state:

Switch	Output1 "Output #1" { satel="output:1" }

Number of partitions with "alarm" state:

Number PartitionsInAlarm "Partitions alarmed [%d]" { satel="partition:alarm" }

Troubles memory item with clear ability:

Switch TroublesMemory "Troubles in the system" { satel="status:troubles_memory" }

Roller shutter item:

Rollershutter KitchenBlinds "Kitchen blinds" { satel="output:10,11" }

Doors open/closed status with ability to open them:

Switch Doors1 "Doors #1" { satel="doors:opened:1" }

Time synchronization using NTP binding:

DateTime AlarmDateTime "Current time [%1$tF %1$tR]" { satel="status:date_time" }
DateTime NtpDateTime   "NTP time [%1$tF %1$tR]"     {ntp="Europe/Berlin:de_DE" }

Rule for above example:

rule "Alarm time sync"
when
	Item NtpDateTime received update
then
	AlarmDateTime.sendCommand(new StringType(NtpDateTime.state.toString))
end

Connection status, item definition:

Switch AlarmConnection "Connection status" <network> { satel="module:connected" }
DateTime AlarmConnSince "Connected since [%1$tF %1$tR]" { satel="module:connected_since" }

Rule to send email on each alarm with 10 most recent records from the event log:

rule "Satel Action test"
when
        AlarmPart1 changed to ON
then
        var Integer eventIdx = -1
        var String details
        var String msgBody = ""

        if (satelIsConnected()) {
            logInfo("EventLog", "Start")
            (1..10).forEach[
                    val Object[] eventRec = satelReadEvent(eventIdx)
                    val kind = eventRec.get(6) as Integer
                    val source = eventRec.get(7) as Integer
                    val object = eventRec.get(8) as Integer
                    val ucn = eventRec.get(9) as Integer
    
                    if (kind == 0) {
                        details = ""
                    } else if (kind == 1) {
                        details = ", partition: " + satelReadDeviceName("PARTITION", eventRec.get(1)) + ", zone: " + satelReadDeviceName("ZONE", source)
                    } else if (kind == 2) {
                        details = ", partition: " + satelReadDeviceName("PARTITION", eventRec.get(1)) + ", user: " + satelReadDeviceName("USER", source)
                    } else if (kind == 4) {
                        if (source == 0) {
                            details = " (mainboard)"
                        } else if (source <= 128) {
                            details = ", zone: " + satelReadDeviceName("ZONE", source)
                        } else if (source <= 192) {
                            details = ", expander: " + satelReadDeviceName("EXPANDER", source)
                        } else {
                            details = ", lcd: " + satelReadDeviceName("LCD", source)
                        }
                    } else if (kind == 5) {
                        details = ", partition: " + satelReadDeviceName("PARTITION", eventRec.get(1))
                    } else if (kind == 6) {
                        details = ", keypad: " + satelReadDeviceName("LCD", eventRec.get(1)) + ", user: " + satelReadDeviceName("USER", source)
                    } else if (kind == 7) {
                        details = ", user: " + satelReadDeviceName("USER", source)
                    } else if (kind == 15) {
                        details = ", partition: " + satelReadDeviceName("PARTITION", eventRec.get(1)) + ", timer: " + satelReadDeviceName("TIMER", source)
                    } else if (kind == 30) {
                        details = ", keypad: " + satelReadDeviceName("LCD", eventRec.get(1)) + ", ip: " + source + "." + (object*32 + ucn) + details
                    } else if (kind == 31) {
                        details = "." + source + "." + (object*32 + ucn)
                    } else {
                        details = ", kind=" + kind + ", partition=" + eventRec.get(1) + ", source=" + source + ", object=" + object + ", ucn=" + ucn
                    }

                    if (kind != 31) {
                        msgBody = msgBody + "\n" + eventRec.get(0) + ": " + eventRec.get(5) + details
                    }
                    eventIdx = eventRec.get(10)
            ]
            logInfo("EventLog", "End")
            sendMail("you@email.net", "Even log", msgBody)
	}
end

Item definition for the above rule:

Switch AlarmPart1 "Alarm on partition #1" { satel="partition:alarm_memory:1" }

Rule that changes user code for 10 minutes. After that time user code is reverted to the one configured in openhab.cfg.

var String userCode = ""
var Timer keypadTimer = null
var Timer userCodeTimer = null

rule "Keypad char entered"
when
	Item Keypad_Char changed
then
	if (Keypad_Char.state == "-") {
		satelSetUserCode(userCode)
		userCode = ""
		if (userCodeTimer != null) {
			userCodeTime.cancel
		}
		userCodeTimer = createTimer(now.plusMinutes(10)) [|
			logInfo("Keypad", "Reverting user code")
			satelResetUserCode()
		]
	} else if (Keypad_Char.state == "*") {
		satelResetUserCode()
		userCode = ""
	} else {
		userCode = userCode + Keypad_Char.state
	}

	if (keypadTimer != null) {
		keypadTimer.cancel
	}
	keypadTimer = createTimer(now.plusSeconds(5)) [|
		userCode = ""
		Keypad_Char.postUpdate("")
	]
end

Item definition for above rule:

String Keypad_Char ">"

Sitemap keypad to enter user code for above rule:

Text label="Enter user code" icon="settings" {
	Switch item=Keypad_Char mappings=[ "1"="1", "2"="2", "3"="3" ]
	Switch item=Keypad_Char mappings=[ "4"="4", "5"="5", "6"="6" ]
	Switch item=Keypad_Char mappings=[ "7"="7", "8"="8", "9"="9" ]
	Switch item=Keypad_Char mappings=[ "*"="*", "0"="0", "-"="#" ]
}

Security considerations

User for OH integration

To control Integra partitions and outputs you need to provide security code of user in behalf all those operations will be executed. It is highly recommended to use a separate user for openHAB integration with only required access rights set in Integra configuration, like access to certain partitions, etc. This allows you to distinguish actions made by OH and a user using Integra panel, also it will block unwanted operations in case someone breaks into your local network.

Disarming and clearing alarms

Although this binding allows you to configure disarming a partition and clearing alarms for a partion, this should be used only in cases when security is not the priority. Don't forget both these operations can be executed in openHAB without specifying user code, which is required to disarm or clear alarms using Integra panel. Consider adding a keypad in your sitemap to temporarily change user code to execute sensitive operations. You can find such keypad in examples section. Also don't forget to secure your openHAB installation by using HTTPS protocol and setting a user with password. Here is a page about security in openHAB: Security

Media

TO DO

  • troubles support (detailed)

feature overview

Installation

Setup intro

Linux and OS X

Windows

FreeBSD


Configuration

Automation*

User Interfaces

Persistence


Community

(link to openHAB forum)

Development


Bindings


Application Integration

Misc


Samples

A good source of inspiration and tips from users gathered over the years. Be aware that things may have changed since they were written and some examples might not work correctly.

Please update the wiki if you do come across any out of date information.

Binding configurations

Use case examples

Item definition examples

Sitemap definition examples

Collections of Rules on a single page

Single Rules

Scripts

Syntax highlighting for external editors


Release Notes

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.