[alarmdecoder] Initial contribution (openhab#7189)

* [alarmdecoder] Initial commit of OH2 version Signed-off-by: Bob Adair <bob.github@att.net>
andrewfg · Aug 31, 2020 · 357e8d6 · 357e8d6
1 parent 47b5464
commit 357e8d6
Show file tree

Hide file tree

Showing 38 changed files with 3,341 additions and 0 deletions.
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -8,6 +8,7 @@
 /bundles/org.openhab.binding.adorne/ @theiding
 /bundles/org.openhab.binding.airquality/ @kubawolanin
 /bundles/org.openhab.binding.airvisualnode/ @3cky
+/bundles/org.openhab.binding.alarmdecoder/ @bobadair @billfor @berndpfrommer
 /bundles/org.openhab.binding.allplay/ @dominicdesu
 /bundles/org.openhab.binding.amazondashbutton/ @OLibutzki
 /bundles/org.openhab.binding.amazonechocontrol/ @mgeramb

diff --git a/bom/openhab-addons/pom.xml b/bom/openhab-addons/pom.xml
@@ -31,6 +31,11 @@
       <artifactId>org.openhab.binding.airvisualnode</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.alarmdecoder</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.allplay</artifactId>

diff --git a/bundles/org.openhab.binding.alarmdecoder/.classpath b/bundles/org.openhab.binding.alarmdecoder/.classpath
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<classpath>
+	<classpathentry kind="src" output="target/classes" path="src/main/java">
+		<attributes>
+			<attribute name="optional" value="true"/>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry excluding="**" kind="src" output="target/classes" path="src/main/resources">
+		<attributes>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="src" output="target/test-classes" path="src/test/java">
+		<attributes>
+			<attribute name="optional" value="true"/>
+			<attribute name="maven.pomderived" value="true"/>
+			<attribute name="test" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.8">
+		<attributes>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="con" path="org.eclipse.m2e.MAVEN2_CLASSPATH_CONTAINER">
+		<attributes>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="output" path="target/classes"/>
+</classpath>
diff --git a/bundles/org.openhab.binding.alarmdecoder/.project b/bundles/org.openhab.binding.alarmdecoder/.project
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>org.openhab.binding.alarmdecoder</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>org.eclipse.jdt.core.javabuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.m2e.core.maven2Builder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>org.eclipse.jdt.core.javanature</nature>
+		<nature>org.eclipse.m2e.core.maven2Nature</nature>
+	</natures>
+</projectDescription>
diff --git a/bundles/org.openhab.binding.alarmdecoder/NOTICE b/bundles/org.openhab.binding.alarmdecoder/NOTICE
@@ -0,0 +1,13 @@
+This content is produced and maintained by the openHAB project.
+
+* Project home: https://www.openhab.org
+
+== Declared Project Licenses
+
+This program and the accompanying materials are made available under the terms
+of the Eclipse Public License 2.0 which is available at
+https://www.eclipse.org/legal/epl-2.0/.
+
+== Source Code
+
+https://github.com/openhab/openhab-addons
diff --git a/bundles/org.openhab.binding.alarmdecoder/README.md b/bundles/org.openhab.binding.alarmdecoder/README.md
@@ -0,0 +1,267 @@
+# Alarm Decoder Binding
+
+The [Alarm Decoder](http://www.alarmdecoder.com) from Nu Tech Software Solutions is a hardware adapter that interfaces with Ademco/Honeywell and DSC alarm panels.
+It acts essentially like a keypad, reading and writing messages on the serial bus that connects keypads with the main panel.
+
+There are several versions of the adapter available: 
+
+* *AD2PI* or *AD2PHAT* - A board that plugs into a Raspberry Pi and offers network-based TCP connectivity
+* *AD2SERIAL* - Attaches to a host via a serial port
+* *AD2USB* - Attaches to a host via USB
+
+This binding allows openHAB to access the state of wired or wireless contacts and motion detectors connected to supported alarm panels, as well as the state of attached keypads and the messages send to attached LRR devices.
+Support is also available for sending keypad commands, including special/programmable keys supported by your panel.
+
+For those upgrading from the OH1 version of the binding, the [original OH1 README](https://www.openhab.org/v2.5/addons/bindings/alarmdecoder1/) file is available for reference.
+
+## Supported Things
+
+The binding supports the following thing types:
+
+* `ipbridge` - Supports TCP connection to the AD.
+* `serialbridge` - Supports serial/USB connection to the AD.
+* `keypad` - Reports keypad status and optionally sends keypad messages.
+* `zone` - Reports status from zone expanders and relay expanders, and also from built-in zones via emulation.
+* `rfzone` - Reports status from RF zones.
+* `lrr` - Reports messages sent from the panel to a Long Range Radio (LRR) or emulated LRR device.
+
+## Discovery
+
+Background discovery is currently supported for `zone` and `rfzone` things.
+If the bridge `discovery` parameter is set to *true*, the first time a status message is seen from each zone or RF zone a corresponding thing will appear in the inbox.
+Leaving the `discovery` parameter set to *false* during normal operation is recommended, as it will slightly reduce resource consumption by the binding.
+
+## Prerequisites
+
+The process for wiring the Alarm Decoder into the alarm panel and configuring it is described in the Alarm Decoder Quick Start guide for your model.
+Before working on the main panel, it is advisable to put the alarm system in test mode, and un-plug the phone connection to it for good measure.
+Don't forget to plug it back in when you are finished!
+
+Understanding exactly what expansion boards are connected to the main panel is crucial for a successful setup of the AlarmDecoder and also helpful in interpreting the messages from the alarmdecoder.
+While many of the expansion devices don't have labels on the outside, inserting a flat screwdriver into the right slot and prying gently will usually uncover a circuit board with numbers on it that can be web searched.
+
+Although not mentioned in the Quick Start guide, configuring virtual relay boards is absolutely necessary on panels like the Honeywell Vista 20p and similar, or else all of the eight on-board zones will not be visible!
+
+## Thing Configuration
+
+Alarm Decoder things can be configured through openHAB's management UI, or manually via configuration files.
+When first configuring the binding it is probably easiest to configure it via the management UI, even if you plan to use configuration files later.
+If you enable the *discovery* option on the bridge, as you fault zones (e.g. open doors and windows, trigger motion detectors, etc.) they should appear in the discovery inbox.
+
+### ipbridge
+
+The `ipbridge` thing supports a TCP/IP connection to an Alarm Decoder device such as *AD2PI* or *AD2PHAT*.
+
+* `hostname` (required) The hostname or IP address of the Alarm Decoder device
+* `tcpPort` (default = 10000) TCP port number for the Alarm Decoder connection
+* `discovery` (default = false) Enable automatic discovery of zones and RF zones
+* `reconnect` (1-60, default = 2) The period in minutes that the handler will wait between connection checks and connection attempts
+* `timeout` (0-60, default = 5) The period in minutes after which the connection will be reset if no valid messages have been received. Set to 0 to disable.
+
+Thing config file example:
+
+```
+Bridge alarmdecoder:ipbridge:ad1 [ hostname="cerberus.home", tcpPort=10000, discovery=true ] {
+  Thing ...
+  Thing ...
+}
+```
+
+### serialbridge
+
+The `serialbridge` thing supports a serial or USB connection to an Alarm Decoder device such as *AD2SERIAL* or *AD2USB*.
+
+Parameters:
+
+* `serialPort` (required) The name of the serial port used to connect to the Alarm Decoder device
+* `bitrate` Speed of the serial connection
+* `discovery` (default=false) Enable automatic discovery of zones and RF zones
+
+Thing config file example:
+
+```
+Bridge alarmdecoder:serialbridge:ad1 [ serialPort="/dev/ttyS1", bitrate=115200, discovery=true ] {
+  Thing ...
+  Thing ...
+}
+```
+
+### zone
+
+The `zone` thing reports status from zone expanders and relay expanders, and also from built-in zones via emulation.
+
+Parameters:
+
+* `address` (required) Zone address
+* `channel` (required) Zone channel
+
+Thing config file example:
+
+```
+  Thing zone frontdoor [ address=10, channel=1 ]
+```
+
+### rfzone
+
+The `rfzone` thing reports status from wireless zones, such as 5800 series RF devices, if your alarm panel has an RF receiver.
+
+Parameters:
+
+* `serial` (required) Serial number of the RF zone
+
+Thing config file example:
+
+```
+  Thing rfzone motion1 [ serial=0180010 ]
+```
+
+### keypad
+
+The `keypad` thing reports keypad status and optionally sends keypad messages.
+For panels that support multiple keypad addresses, it can be configured with an address mask of one or more keypad(s) for which it will receive messages.
+When sending messages, it will send from the configured keypad address if only one is configured.
+If a mask containing multiple addresses or 0 (all) is configured, it will send messages from the Alarm Decoder's configured address.
+
+Commands sent from the keypad thing are limited to the set of valid keypad command characters supported by the Alarm Decoder (0-9,*,#,<,>).
+In addition, the characters A-H will be translated to special keys 1-8.
+Command strings containing invalid characters will be ignored.
+
+Parameters:
+
+* `addressMask` (required) Keypad address mask (0 = All addresses)
+* `sendCommands` (default = false) Allow keypad commands to be sent to the alarm system from openHAB. Enabling this means the alarm system will be only as secure as your openHAB system.
+* `sendStar` (default = false) When disarmed/faulted, automatically send the * character to obtain zone fault information.
+* `commandMapping` (optional) Comma separated list of key/value pairs mapping integers to command strings for `intcommand` channel.
+
+Thing config file example:
+
+```
+  Thing keypad keypad1 [ addressMask=0, sendCommands=true ]
+```
+
+### lrr
+
+The `lrr` thing reports messages sent to a Long Range Radio (LRR) or emulated LRR device.
+These are specifically formatted messages as described in the [SIA DC-05-1999.09](http://www.alarmdecoder.com/wiki/index.php/File:SIA-ContactIDCodes_Protocol.pdf) standard for Contact ID reporting.
+For panels that support multiple partitions, the partition for which a given lrr thing will receive messages can be defined.
+
+* `partition` (default = 0) Partition for which to receive LRR events (0 = All)
+
+Thing config file example:
+
+```
+  Thing lrr lrr [ partition=0 ]
+```
+
+## Channels
+
+The alarmdecoder things expose the following channels:
+
+**zone**
+
+|  channel     | type    |RO/RW| description                  |
+|--------------|---------|-----|------------------------------|
+| contact      | Contact |RO   |Zone contact state            |
+
+**rfzone**
+
+|  channel     | type    |RO/RW| description                  |
+|--------------|---------|-----|------------------------------|
+| lowbat       | Switch  | RO  |Low battery                   |
+| supervision  | Switch  | RO  |Supervision warning           |
+| loop1        | Contact | RO  |Loop 1 state                  |
+| loop2        | Contact | RO  |Loop 2 state                  |
+| loop3        | Contact | RO  |Loop 3 state                  |
+| loop4        | Contact | RO  |Loop 4 state                  |
+
+**keypad**
+
+|  channel     | type    |RO/RW| description                  |
+|--------------|---------|-----|------------------------------|
+| zone         | Number  | RO  |Zone number for status        |
+| text         | String  | RO  |Keypad message text           |
+| armedaway    | Switch  | RO  |Armed/Away Indicator          |
+| armedhome    | Switch  | RO  |Armed/Stay Indicator          |
+| backlight    | Switch  | RO  |Keypad backlight on           |
+| program      | Switch  | RO  |Programming mode              |
+| beeps        | Number  | RO  |Number of beeps for message   |
+| bypassed     | Switch  | RO  |Zone bypassed                 |
+| acpower      | Switch  | RO  |Panel on AC power             |
+| chime        | Switch  | RO  |Chime enabled                 |
+| alarmoccurred| Switch  | RO  |Alarm occurred in the past    |
+| alarm        | Switch  | RO  |Alarm is currently sounding   |
+| lowbat       | Switch  | RO  |Low battery warning           |
+| delayoff     | Switch  | RO  |Entry delay off               |
+| fire         | Switch  | RO  |Fire detected                 |
+| sysfault     | Switch  | RO  |System fault                  |
+| perimeter    | Switch  | RO  |Perimeter only                |
+| command      | String  | RW  |Keypad command                |
+| intcommand   | Number  | RW  |Integer keypad command        |
+
+*Note* - The `intcommand` channel is provided for backward compatibility with the OH1 version of the binding.
+The integer to command string mappings are provided by the optional keypad `commandMapping` parameter.
+The default mapping is "0=0,1=1,2=2,3=3,4=4,5=5,6=6,7=7,8=8,9=9,10=*,11=#".
+
+**lrr**
+
+|  channel     | type    |RO/RW| description                  |
+|--------------|---------|-----|------------------------------|
+| partition    | Number  | RO  |Partition number (0=system)   |
+| eventdata    | Number  | RO  |CID event data (user or zone) |
+| cidmessage   | String  | RO  |SIA Contact ID Protocol msg.  |
+| reportcode   | String  | RO  |CID report code               |
+
+## Full Example
+
+Example ad.things file:
+
+```
+Bridge alarmdecoder:ipbridge:ad1 [ hostname="cerberus.home", tcpPort=10000, discovery=true ] {
+    Thing zone frontdoor [ address=10, channel=1 ]
+    Thing zone backdoor [ address=11, channel=1 ]
+    Thing rfzone motion1 [ serial=0180010 ]
+    Thing keypad keypad1 [ addressMask=0, sendCommands=true ]
+    Thing lrr lrr [ partition=0 ]
+}
+```
+
+Example ad.items file:
+
+```
+Number KeypadZone "Zone [%d]"  {channel="alarmdecoder:keypad:ad1:keypad1:zone"}
+String KeypadText "Message" {channel="alarmdecoder:keypad:ad1:keypad1:text"}
+Switch KeypadArmedAway "Armed Away" {channel="alarmdecoder:keypad:ad1:keypad1:armedaway"}
+Switch KeypadArmedHome  "Armed Home" {channel="alarmdecoder:keypad:ad1:keypad1:armedhome"}
+Switch KeypadAlarm "Alarm" {channel="alarmdecoder:keypad:ad1:keypad1:alarm"}
+Switch KeypadFire "Fire" {channel="alarmdecoder:keypad:ad1:keypad1:fire"}
+String KeypadCmd "Command" {channel="alarmdecoder:keypad:ad1:keypad1:command"}
+
+Contact FrontDoorContact "Front Door Zone" {channel="alarmdecoder:zone:ad1:frontdoor:contact"}
+
+Switch Motion1Lowbat "Low Battery" {channel="alarmdecoder:rfzone:ad1:motion1:lowbat"}
+Switch Motion1Supervision "Supervision Warning" {channel="alarmdecoder:rfzone:ad1:motion1:supervision"}
+Contact Motion1Loop1 "Loop 1" {channel="alarmdecoder:rfzone:ad1:motion1:loop1"}
+Contact Motion1Loop2 "Loop 2" {channel="alarmdecoder:rfzone:ad1:motion1:loop2"}
+Contact Motion1Loop3 "Loop 3" {channel="alarmdecoder:rfzone:ad1:motion1:loop3"}
+Contact Motion1Loop4 "Loop 4" {channel="alarmdecoder:rfzone:ad1:motion1:loop4"}
+
+Number LrrPartition "Partition Number [%d]" {channel="alarmdecoder:lrr:ad1:lrr:partition"}
+Number LrrEventData "CID Event Data [%d]" {channel="alarmdecoder:lrr:ad1:lrr:eventdata"}
+String LrrMessage "CID Message" {channel="alarmdecoder:lrr:ad1:lrr:cidmessage"}
+String LrrReportCode "CID Report Code" {channel="alarmdecoder:lrr:ad1:lrr:reportcode"}
+```
+
+*Note: For brevity, not every possible keypad channel is linked to an item in the above example.*
+
+## Thing Actions
+
+The `ipbridge` and `serialbridge` things expose the following action to the automation engine:
+
+*reboot* - Send command to reboot the Alarm Decoder device. Accepts no parameters.
+
+## Quirks
+
+The alarmdecoder device cannot query the panel for the state of individual zones.
+For this reason, the binding puts contacts into the "unknown" state (UNDEF), *until the panel goes into the READY state*.
+At that point, all contacts for which no update messages have arrived are presumed to be in the CLOSED state.
+In other words: to get to a clean slate after an openHAB restart, close all doors/windows such that the panel is READY.
diff --git a/bundles/org.openhab.binding.alarmdecoder/pom.xml b/bundles/org.openhab.binding.alarmdecoder/pom.xml
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.openhab.addons.bundles</groupId>
+    <artifactId>org.openhab.addons.reactor.bundles</artifactId>
+    <version>2.5.5-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.alarmdecoder</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: Alarm Decoder Binding</name>
+
+</project>
diff --git a/bundles/org.openhab.binding.alarmdecoder/src/main/feature/feature.xml b/bundles/org.openhab.binding.alarmdecoder/src/main/feature/feature.xml
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<features name="org.openhab.binding.alarmdecoder-${project.version}" xmlns="http://karaf.apache.org/xmlns/features/v1.4.0">
+	<repository>mvn:org.openhab.core.features.karaf/org.openhab.core.features.karaf.openhab-core/${ohc.version}/xml/features</repository>
+
+	<feature name="openhab-binding-alarmdecoder" description="alarmdecoder Binding" version="${project.version}">
+		<feature>openhab-runtime-base</feature>
+		<feature>openhab-transport-serial</feature>
+		<bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.alarmdecoder/${project.version}</bundle>
+	</feature>
+</features>