The [Alarm Decoder](https://www.alarmdecoder.com) from Nu Tech Software Solutions is a hardware adapter that interfaces with Ademco/Honeywell and DSC alarm panels.
* *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.
## 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.
*`vzone` - Sends commands to virtual 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 looked up via web search.
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.
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` (default = 0) String containing the mask in hex of addresses for which the keypad thing will receive messages (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.
Address masks
Each bit in the 4 bytes of the address mask represents a device address, ranging from device 0 to device 31.
The first byte (left to right) represents devices 0-7, the second 8-15, the third 16-23, and the fourth 24-31.
The mask itself is represented as a string containing a hexadecimal number.
For example, a mask of 03000000 would indicate devices 0 and 1 as follows:
These are normally specifically formatted messages as described in the [SIA DC-05-1999.09](https://www.alarmdecoder.com/wiki/index.php/File:SIA-ContactIDCodes_Protocol.pdf) standard for Contact ID reporting.
They can also, depending on configuration, be other types of messages as described [here](https://www.alarmdecoder.com/wiki/index.php/LRR_Support).
