Satel Alarm Binding - jfederico/openhab GitHub Wiki
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.
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.
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 |
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 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) |
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 and check current connection status.
-
boolean satelIsConnected()- returnstrueif connected to communication module andfalseotherwise -
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
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 |
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("[email protected]", "Even log", msgBody)
}
end
Item definition for the above rule:
Switch AlarmPart1 "Alarm on partition #1" { satel="partition:alarm_memory:1" }
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. 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
- troubles support (detailed)