AD2USB Alarm Interface  

Developer: AB's Plugins
Category: Security & Locks
Github: Github Repo
Assistance: Get help!    Check the online documentation
Plugin ID: com.berkinet.ad2usb
Latest release: v3.4.2 released on Jan. 1, 2024
Release downloaded: 0 times
Requires: Indigo v2022.1.0 or higher
(Check the Releases tab below for older releases that may have different requirements)
  Download latest release

ad2usb Indigo Plugin Documentation

Version 3.4.2

Table of Contents

About

ad2usb is a plugin interface to the NuTech AD2* alarm system interface for Honeywell's Ademco Vista line of alarm panels. It allows you to create Indigo devices for each of your alarm panel's sensors (e.g. door sensor, motion sensor, window sensor, ...) which can then take advantage of many of Indigo's features available for devices. It also allows you to read and send alarm messages by emulating an alarm panel keypad. There are addition features described in this document.

Required Hardware

This plugin requires both a NuTech AlarmDecoder (AD2) alarm interface and an alarm panel. Both the NuTech AD2USB and AD2Pi are supported (see Note 1 for firmware specifics). This interface supports a broad range of alarm panels manufactured by Honeywell and sold under the ADEMCO VISTA brand name and similar panels sold by First Alert. The list of supported panels includes (see Note 2):

  • VISTA-4110XM
  • VISTA-15P
  • VISTA-20P
  • VISTA-21IP
  • VISTA-40
  • VISTA-50P
  • VISTA-128BPT/VISTA Turbo Series (see Note 3)
  • VISTA-250BPT/VISTA Turbo Series (see Note 3)
  • First Alert-FA148CP
  • First Alert-FA148CPSIA
  • First Alert-FA168CPS
  • First Alert-FA168CPSSIA

A more complete list is available from NuTech on their website. While the NuTech AlarmDecoder AD2* interface also supports alarm panels sold by DSC, this plugin is not tested with those panels. Users with DSC panels should look at the DSC Alarm plugin.

Requirement Notes : 1. Requires AlarmDecoder firmware version 2.2a.8.8 (requires Plugin version 3.2.0 and above) or 2.2a.6 (works with any Plugin version). The Trigger Events section of this README identifies which events and which versions of the plugin can process these types of events. The Plugin may not start or run with any other firmware version besides the two listed above. 2. While the panels listed should work, the developer testing for each release is limited to only on a VISTA-20P. Leverage the Indigo ad2usb User Forum to ask other users about their experience with your specific alarm panel model. Since I can test any panel message, I may ask in the Support Forum for parts of your panel message log to test. 3. Works only in the plugin's basic mode

Features

This plugin adds new Indigo options for Devices, Actions, and Trigger Events. See the Indigo Overview for more information about Devices, Actions, and Triggers. Devices will represent all of your Alarm Zones and Keypads. Actions allow you to interact with your Alarm Keypad. Triggers can be defined for any Indigo Device, including devices created via this plugin, and various alarm panel events.

Devices

The ad2usb plugin adds the following device options to Indigo.

Device Type Description ad2usb Keypad The AlarmDecoder Keypad emulator. You must add at least one and can have as many Indigo ad2usb Keypad devices as there are partitions. When selecting the keypad address for your ad2usb Keypad device, it must be a keypad address that is programmed in your alarm panel (this includes the NuTech AlarmDecoder device you programmed as a keypad). For systems with a single partition, which may be the most common setup, you can only have one ad2usb Keypad device and this device will be automatically set to the NuTech AlarmDecoder keypad address. Systems with multiple partitions can have multiple ad2usb Keypad devices defined: one for each partition. However, the keypad address selected for all ad2usb Keypad devices must exist in the alarm panel programming. See the ad2usb Keypad Addresses and Partitions section for some examples scenarios. Keypads can have several states: Ready, Armed Stay, Armed Night Stay, Armed Away, Armed Instant, Armed Max and Fault. A Fault will display as the Keypad state when one or more Alarm Zone devices that are on the same partition as the Keypad become Faulted. One exception to this is if the Alarm Zone is Bypassed. When an Alarm Zone is Bypassed the Indigo UI icon for the Keypad and the bypassed Alarm Zone device will change to the Fault icon but the actual state will not change.The Keypad Device also has several Custom States that are described in a later section. Alarm Zone Standard alarm zone such as window or door sensors. Add one Indigo Alarm Zone device for each sensor you have configured with your alarm panel that you want to integrate with Indigo. Each Alarm Zone device has these three state variables with possible values shown in parenthesis: zoneState (Fault or Clear), onOffState (On or Off), and bypassState (On or Off). States zoneState and onOffState are somewhat redundant since when an alarm zone changes state both change. They exist so you can create triggers on any changes of the state name of your preference.In Basic Mode zones faults are updated from AlarmDecoder's keypad messages. This should be fine for most users. In Advanced Mode zone faults are updated from Expander, Relay, or Wireless messages received by the AlarmDecoder. Valid Alarm Zone numbers are between 1 and 99. Zone Group Creates a group of Alarm Zones. This allows you to create a group of alarm zones devices that treated as single device within Indigo Triggers. Zone groups have the same states as Alarm Zones with the exception they do not have the bypassState. Zone Groups change to Fault (or On) when ANY of their Zone's change from Clear to Fault (or Off to On). Zone Groups change to Clear (or Off) once ALL of their Zones are Clear (or Off). Indigo Managed Virtual Zone The AlarmDecoder's Zone Expander Emulation feature allows the AlarmDecoder to act in place of a physical expander board and make use of virtual zones with your panel. After enabling it on both the alarm panel and the AlarmDecoder you can begin opening and closing zones, which will be relayed back to the panel. See the AlarmDecoder Protocol Documentation for more details.. You can create an Indigo Managed Virtual Zone to use this capability. After creating the Indigo Managed Virtual Zone, you call a specific Action, "Change a Virtual Zone's state", which will change the state of the device in Indigo and send Open or Close messages to your alarm panel. CAUTION: Do not set a trigger on a Virtual Zone's device change to call the "Change a Virtual Zone's state" or you will have an infinite loop. See the "Alarm Zone Actions" section.

ad2usb Keypad Addresses and Partitions

The table and diagrams below offer several examples of how NuTech AlarmDecoder and Indigo ad2usb Keypad devices can be configured. The Keypad Addresses shown below are just examples. Refer to your alarm panel programming guide to determine how to review what keypads are already defined on your alarm panel and their partition numbers and addresses.

Number of Partitions NuTech AlarmDecoder Keypad Address and Partition ad2usb Keypad Device Address and Partition 1 The AlarmDecoder has a default keypad address value of 18 but other values may be selected during the alarm panel programming. The keypad partition number programmed on the alarm panel has to be 1 for a single partition system. Only Partition 1 will be available when configuring the device. Only one ad2usb Keypad is allowed and the address will be automatically set to the same keypad address as the NuTech AlarmDecoder when the AlarmDecoder's CONFIG settings are read (ex: Partition 1, Keypad Address 18). See Figure 1. 2 NuTech AlarmDecoder programmed for Partition 1 and some available keypad address. Two ad2usb Keypad devices can be created. An example setup could be: First ad2usb Keypad device: set to partition 1 and select the same keypad address as the NuTech AlarmDecoder (ex: Partition 1, Keypad Address 19). Second ad2usb Keypad device: set to partition 2 and select an existing keypad address assigned to partition 2 (ex: Partition 2, Keypad Address 18). See Figure 2. 2 NuTech AlarmDecoder programmed for Partition 2 and an available keypad address. Two ad2usb Keypad devices can be created. An example setup could be: First ad2usb Keypad device: set to partition 1 and select an existing keypad address assigned to partition 1 (ex: Partition 1, Keypad Address 17). Second ad2usb Keypad device set to partition 2 and a select the same keypad address as the NuTech AlarmDecoder (ex: Partition 2, Keypad Address 19). 3 or more NuTech AlarmDecoder programmed for Partition 1, or 2, or any valid partition and an available keypad address. Example setup would be one ad2usb Keypad devices per partition: One ad2usb Keypad device: set to the same partition and keypad address as the NuTech AlarmDecoder. All other ad2usb Keypad devices: set to each of the remaining partitions and select a valid and programmed keypad address for that partition. Basic Keypad Example Image Figure 1 - Basic single partition and single ad2usb Keypad setup Advanced Keypad Example Image Figure 2 - Advanced multi-partition and multi-ad2usb Keypad setup

ad2usb Keypad Device Details

Keypad Device State

Many of the Keypad's Device States described below come directly from the AlarmDecoder Keypad Message bit fields. You can use these custom states in Indigo Device Triggers. The table below shows relationship of the ad2usb Keypad device state (panelState), the panel armed mode (armedMode) state of the ad2usb Keypad device, and the HomeKit state (homeKitState):

Keypad Device State (panelState) Value Keypad Device State (panelState) UI Display Armed Mode (armedMode) Value Armed Mode (armedMode) UI Display HomeKit (homeKitState) Value HomeKit (homeKitState) UI Display ready Ready unArmed Not Armed disarmed Disarmed Fault Fault unArmed Not Armed disarmed Disarmed armedStay Armed Stay armedStay Armed Stay armedStay Armed Stay armedNightStay Armed Night Stay armedNightStay Armed Night Stay armedNightStay Armed Night Stay armedAway Armed Away armedAway Armed Away armedAway Armed Away armedInstant Armed Instant armedInstant Armed Instant armedStay Armed Stay armedMax Armed Max armedMax Armed Max armedAway Armed Away alarmOccured Alarm Occurred any any alarmOccured Alarm Triggered alarmOn Alarm Sounding any any alarmOccured Alarm Triggered error Error any any disarmed Disarmed

Keypad Device Additional States

The ad2usb Keypad device has the following additional states:

Custom State Name Device Trigger State Name Values Description (AlarmDecoder Bit field number) LCDLine1 LCD Line 1 String Line one of the your keypad display. LCDLine2 LCD Line 2 String Line one of the your keypad display. acPower AC Power On or Off Indicates if the panel is on AC power. (8) alarmBellOn Panel Alarm Bell On True of False Indicates that an alarm is currently sounding. (11) alarmOccurred Alarm Occurred True of False Indicates that an alarm has occurred. (10) alarmedZone Zone which tripped the alarm Number or "N/A" The Zone number which tripped the alarm or "N/A" if no alarm has been tripped. armedMode Alarm Armed State String The alarm mode of the panel (see the table above for Keypad States) batteryLow Battery Low True of False Indicates the battery is low. (12) checkZones Check Zones True or False Indicates a system issue. Check your keypad and devices. (15) chimeMode Chime Mode On or Off Indicates if the chime is enabled. (9) fireAlarm Fire Alarm On True or False Indicates that there is a fire issue. (14) homeKitState HomeKit State String One of four (4) string values based on the keypad state (panelState). See table above. lastADMessage Last AD2USB Msg Time Date-Time A date-time string of the last time a message was processed by the AlarmDecoder. This is useful when away for extended periods to confirm the Plugin is still processing messages. lastChgBy Last change by Number For LRR messages is user code of the last change of the panel. lastChgTo Last change to String For LRR messages is the last panel state changed by the user. lastChgAt Last change at Date-Time For LRR messages is the late change date-time by the user. panelReady Panel is Ready True of False Indicates if the panel is READY. (1) panelArmed Panel is Armed True of False Indicates if the panel is ARMED. (2 or 3) programMode Programming Mode On or Off Indicates if the keypad is in programming mode. (5) zonesBypassed Zones Bypassed True of False Indicates that one or more zone(s) have been bypassed. (7) zonesBypassList Zones Bypass List String A list of the zone(s) that have been bypassed. zoneFaultList Faulted Zones String A list of faulted zones.

Bypass Rules for Indigo Devices

Indigo will behave the same as an alarm panel for Bypassed devices. The table below outlines Alarm Zone and ad2usb Keypad devices behavior. These behaviors apply to Basic Mode only.

Alarm Zone Bypassed Status Alarm Zone State Indigo Alarm Zone Device State Indigo Alarm Zone Device UI Display Indigo Keypad Device State Indigo Keypad Device UI Display Additional Info Bypassed Clear Bypassed Grey Icon Clear Green Icon Indigo, like the Alarm panel, does not detect changes in the Alarm Zone device's state when Bypassed. The grey icon is shown instead of the green, indicating the Alarm Zone is device Bypassed. Bypassed Fault Bypassed Red Icon Clear Green Icon Indigo, like the Alarm panel, does not detect changes in the Alarm Zone device's state when Bypassed. The Alarm Zone icon will change from grey to red when a Fault is detected on a bypassed zone, but the ad2usb Keypad device will not recognize it as a Fault. The Alarm Zone Indigo device state will remain "Bypass", only the icon in the UI will change. Not Bypassed Clear Clear Green Icon Clear Green Icon Both the Alarm Zone and Keypad Device will show Clear unless another Alarm Zone device on the same partition has Faulted. Keypad devices will Fault when ANY of their Alarm Zone devices Fault and are Clear when ALL of their devices are Clear. Not Bypassed Fault Fault Red Icon Fault Red Icon When an Alarm Zone device change to Fault, the Keypad Device will also change to Fault for the Keypad Device that is on the same partition as the Alarm Zone device. If you have multiple partitions, Keypad Devices with a partition number different from the Alarm Zone will not change state based on Alarm Zone devices on other partitions.

Actions

The ad2usb plugin adds several Actions for ad2usb Keypad and Alarm Zone devices.

Keypad Actions

You can use Indigo Actions to Arm & Disarm your panel and invoke other customized panel events. Arm and Disarm Actions are available using either the Quick Arming (#) function or by providing a user code. Actions that require a use code are noted by the word "CODE" in parenthesis after the Action name. The code is determined based on the Save Alarm Code setting in the plugin's Configure menu described in this README here. Refer to your Alarm Users Guide for description of each of these arm and disarm functions. You can also writes an arbitrary message to the panel via the keypad. By default panel messages are being sent from the keypad number and partition of the NuTech AlarmDecoder (e.g. Partition 1, Keypad address 18). CAUTION: Having detailed knowledge of your alarm panel's operation is recommended before configuring the Write to Panel action.

Keypad Actions Requires Alarm Code? Description (refer to you Alarm Panel Users Guide) Quick Arm-Stay No Performs the alarm panel function by sending Quick Arming for STAY (# + 3) to the keypad. Arms perimeter zones only and entry delay is on. Quick Arm-Instant No Performs the alarm panel function by sending Quick Arming for INSTANT (# + 7) to the keypad. Same as STAY, except entry delay is off. Quick Arm-Away No Performs the alarm panel function by sending Quick Arming for AWAY (# + 2) to the keypad. Arms the entire burglary system, perimeter and interior. Entry delay is on. Quick Arm-Max No Performs the alarm panel function by sending Quick Arming for MAX (# + 4) to the keypad. Same as AWAY, except entry delay is off. Arm-Stay (CODE) Yes Performs the alarm panel function by sending a user code and STAY (CODE + 3) to the keypad. Arms perimeter zones only and entry delay is on. Arm-Night-Stay (CODE) Yes Performs the alarm panel function by sending a user code and NIGHT-STAY (CODE + 33) to the keypad. Arms same as STAY mode, but also arms preselected interior sensors (programmed by your installer), while other interior sensors are left disarmed. Arm-Away (CODE) Yes Performs the alarm panel function by sending a user code and AWAY (CODE + 2) to the keypad. Arms the entire burglary system, perimeter and interior. Entry delay is on. Arm-Instant (CODE) Yes Performs the alarm panel function by sending a user code and AWAY (CODE + 7) to the keypad. Same as STAY, except entry delay is off. Arm-Max (CODE) Yes Performs the alarm panel function by sending a user code and AWAY (CODE + 4) to the keypad. Same as AWAY, except entry delay is off. Disarm (CODE) Yes Performs the alarm panel function by sending a user code and OFF (CODE + 1) to the keypad. This disarms the system. Write To Panel Depends Writes an arbitrary message to the panel via the keypad. To aid in visual appearance, you can add the character + in the string and/or variable and it will be ignored and not sent to the panel. For example, 1234+1 sends 12341 to the panel. By default panel messages are being sent from the keypad number and partition of the NuTech AlarmDecoder (e.g. Partition 1, Keypad address 18). You can prefix the message with 'K' to send the message from a specific keypad number. For example, K19+1234+1 sends the alarm code of 1234 and the 1 (OFF) command. See the AlarmDecoder Protocol page for more details. The field Text to send contains the keypad entries to send to the Alarm Panel (e.g. 12345 = Alarm Code 1234 and keypad 5 places the alarm in Test Mode); or the field can contain an Indigo variable ID (ex: %%v:1929322623%%) whose value contains the keypad entries. CAUTION: Having detailed knowledge of your alarm panel's operation is recommended before configuring this action.

Alarm Zone Actions

Alarm Zone actions are less likely to be used but available since most Alarm Zone devices simply change state based on data being sent from your alarm panel.

Alarm Zone Actions Description Force Alarm Zone state change This Action can be called to force an Alarm Zone's state in Indigo to either Clear or Fault. The Indigo device state is changed but no messages are sent to the AlarmDecoder. It is provided for any special use cases that are needed; but in general is not needed for normal operation. Change a Virtual Zone's state Zone Expander Emulation allows the AlarmDecoder to act in place of a physical expander board and make use of virtual zones with your panel. After enabling it on both the panel and the AlarmDecoder you can begin opening and closing zones, which will be relayed back to the panel. This Action will send Clear (Closed) or Faulted (Open) to your alarm panel for defined zone. See the AlarmDecoder Protocol Documentation for more details

Trigger Events

This plugin's built in devices (ad2usb Keypad, Alarm Zone, etc.) provide numerous ways to create Triggers from the different device state changes. In addition to the ability to add Triggers for Indigo Device state changes, the ad2usb plugin can detect various alarm panel events that you can create Indigo triggers for. These alarm panel reporting events must be enabled on your alarm system. The required settings below are usually already enabled for typical home alarm panels installed by alarm service companies and its possible that no programming changes on your panel will be necessary. When creating Triggers for these plugin events, multiple events can be specified. When multiple events are selected, any of those events will cause the Trigger to be execute. All of the Events listed below, except Alarm Tripped: Countdown started, require all of the following:

  • Either a Long Range Radio (LRR) or emulation of LRR via the AlarmDecoder
  • Enabling of Long Range Radio (LRR) messages on your alarm panel (panel programming field *29)
  • Enabling of the respective reporting event on your alarm panel. For VISTA-15P and VISTA-20P refer to panel programming fields *59 through *76 for the programming fields. Each of these fields is also listed below for each event.

IMPORTANT NOTE: Some, but not all, of these alarm panel events and Triggers you can create from them are functionally redundant with Triggers you can create from the the ad2usb Keypad and Alarm Zone Device state changes. If you create both, then that alarm event will cause BOTH Triggers to execute since the device trigger is determined by Indigo device state change while the Events described below are sent to the plugin by your alarm panel's LRR function. Thus you should typically only create one triggers for any event that can be detected using either method. For example, the AC Power loss can be detected via a change in state of the ad2usb Keypad device or a System Status Event.

System Status Events

Because the developer of this plugin does not have a dedicated panel to test with, not all of the trigger events below have been verified with AlarmDecoder firmware version 2.2a.8.8 which changed the format of these messages. The table below indicates which plugin version supports the various Events and if the event has been verified by the developer through testing on a VISTA-15 panel.

Event Description VISTA-15P and VISTA-20P Programming Fields Available in AlarmDecoder Firmware 2.2a.8.8 (Plugin Version)[Verified or Not Verified] AC Power Loss Indicates that AC power was lost to the alarm panel. NOTE: From what I've read this alert is delayed by a random value of up to 4 hours to prevent alarm monitoring organizations from being overwhelmed. Consider creating an Indigo Device Trigger on the Keypad device as an alternative. *62 Yes (3.2.1 and above)[Verified] AC Power Restore Indicates that AC power was restored *73 Yes (3.2.1 and above)[Verified] Panel Battery Low Alarm panel low battery indication *63 Yes (3.3.0 and above)[Verified] Panel Battery Restore Alarm panel low battery indication *74 Yes (3.3.0 and above)[Verified] RF Battery Low Low battery indication for the RF transmitter *67 Yes (3.3.0 and above)[Not Verified] RF Battery Restore Low battery indication for the RF transmitter restored *75 Yes (3.3.0 and above)[Not Verified] Trouble Indicates that a zone is reporting a tamper or failure *60 Yes (3.3.0 and above)[Verified] Trouble Restore Indicates that the trouble event was restored *71 Yes (3.3.0 and above)[Verified]

Alarm Events

Event Description VISTA-15P and VISTA-20P Programming Fields Available in AlarmDecoder Firmware 2.2a.8.8 (Plugin Version)[Verified or Not Verified] Entry Alarm Indicates that there was an entry alarm (e.g. door) N/A - Refer to Zone Programming to determine what zones are applicable Yes (3.3.0 and above)[Verified] Interior Alarm Indicates that there was an interior alarm (e.g. motion sensor) N/A - Refer to Zone Programming to determine what zones are applicable Yes (3.3.0 and above) (See Note 1)[Verified] Perimeter Alarm Indicates that there was a perimeter alarm N/A - Refer to Zone Programming to determine what zones are applicable Yes (3.3.0 and above)[Not Verified] Aux Alarm Indicates that an auxiliary alarm type was triggered N/A - Refer to Zone Programming to determine what zones are applicable No (See Note 1) Panic Alarm Indicates that there is a panic N/A - Refer to Zone Programming to determine what zones are applicable Yes (3.3.0 and above)[Not Verified] Fire Alarm Indicates that there is a fire N/A - Refer to Zone Programming to determine what zones are applicable Yes (3.3.0 and above)[Not Verified] Audible Alarm Indicates that an audible alarm is in progress N/A - Refer to Zone Programming to determine what zones are applicable Yes (3.3.0 and above)[Not Verified] Silent Alarm Indicates that there was a silent alarm N/A - Refer to Zone Programming to determine what zones are applicable Yes (3.3.0 and above)[Not Verified] Alarm Tripped: Countdown started The alarm has been tripped and the countdown to Disarm has started N/A - this event is detected from changes in the Keypad message Yes (3.2.0 and above)[Verified]

Trigger Event Notes: 1. Requires AlarmDecoder Firmware 2.2a.8.8 2. Not supported with AlarmDecoder Firmware 2.2a.8.8

User Actions

User Actions can detect when a specific Alarm Panel User Number (or any User Number) has initiated any these events: Disarmed, Armed Stay, Armed Away, or Alarm Cancelled. Refer to your Alarm User Manual for information about User Numbers. The Trigger dialog box allows for the selection of multiple events; so you can create a single Trigger for one or more of these Events. You can specify Any User and the event will execute the Trigger regardless of the User Number associated with the event. Alternatively, you can enter a single User Number (ex: 02) or a list of User Numbers comma seperated (ex: 02,07,14). You can also use an Indigo Variable as the User Number(s) in the format:%%v:VARID%% where VARID is the variable ID (ex: %%v:1929322623%%). The variable's value can contain one or more User Numbers.

Event Description VISTA-15P and VISTA-20P Programming Fields Available in AlarmDecoder Firmware 2.2a.8.8 (Plugin Version)[Verified or Not Verified] Armed Stay Detect when your panel is set to Armed Stay. You can detect this for any user or a specific user. *66 Yes (3.2.0 and above)[Verified] Armed Away Detect when your panel is set to Armed Away. You can detect this for any user or a specific user. *66 Yes (3.2.0 and above)[Verified] Disarmed Detect when your panel is Disarmed. You can detect this for any user or a specific user. *65 - also requires *66 to be enabled Yes (3.2.0 and above)[Verified] Cancel Detect when an alarm has been cancelled by a user. You can detect this for any user or a specific user. *68 Yes (3.3.0 and above)[Verified] Walk Test Mode On Detect when a user has entered (enabled) TEST mode. You can detect this for any user or a specific user. Unknown Yes (3.3.4 and above)[Verified] Walk Test Mode Off Detect when a user has exited TEST mode. You can detect this for any user or a specific user. Unknown Yes (3.3.4 and above)[Verified]

Indigo Client UI

General

After you configure the plugin and add your alarm devices to Indigo, the Indigo Client UI will show alarm panel device zone states than alarm panel device address (i.e. the alarm zone number).

Device States

Clear and Fault

The Indigo Client UI will show the Clear or Fault state of the zone. The green circle icon represents Clear and the red circle icon represents Fault.

Bypass

When an Alarm Zone is set to Bypass = On it will display the generic Indigo "Sensor Off" icon (grey circle) and the text "Bypass" in the Indigo Client UI. Bypassed zones do not Fault on the panel and thus will not change state even if the sensor is tripped.

Configuration and Setup

General

Alarm Panel

You need to be familiar with how to program your Alarm panel to add a new keypad address. Refer to your Alarm panel programming guide on how to add a keypad device.

AlarmDecoder

You should familiarize yourself with the setup and configuration of your AlarmDecoder. See NuTech's AlarmDecoder website for details on how to install and configure your AlarmDecoder. This plugin can manage certain configuration parameters of your AlarmDecoder. Use the AlarmDecoder Configuration item from the Plugin's pull-down menu to view and change these settings. Only those AlarmDecoder configuration settings controlled by this plugin will be changed. Other AlarmDecoder configuration settings not managed by this plugin will not be changed. If you will be changing any AlarmDecoder configuration options not managed by this plugin (MASK or CONFIGBITS), it is recommended that you stop the plugin first and restart it after you have made your changes.

When using the AlarmDecoder Configuration menu, you should first use the "Read Config" button to read the AlarmDecoder's current settings. This button will log the current setting to the Indigo event log and update the AlarmDecoder Configuration dialog to match the current AlarmDecoder settings. Configuration settings managed by this plugin should be changed through the Plugin. The AlarmDecoder configuration settings managed by this plugin are below: - ADDRESS - the keypad address - EXP - Emulation of zone expanders 1-5 - REL - Emulation of relay expanders 1-4 - LRR - Emulation of Long Range Radio expander - DEDUPLICATE - If enabled, removes duplicate alphanumeric keypad messages

Indigo Plugin

You should be familiar with installing and configuring Indigo plugins. See Indigo's Managing Plugins documentation for details on installing and upgrading plugins.

Quick Start - First Install

  1. Program your alarm panel to support the NuTech AlarmDecoder as a new keypad device (default from NuTech is "18").
  2. Install and configure your NuTech AlarmDecoder. Use a terminal program or other supported method to configure the AlarmDecoder per NuTech's instructions. For network devices make sure you know the IP address and port (default is 10000) to communicate with the AlarmDecoder. If you're not going to use the default keypad address of "18" change it now. Advanced users should make any additional configuration changes to your AlarmDecoder. In most cases the default settings of the AlarmDecoder are fine and no additional configuration is needed. After this initial setup, many AlarmDecoder settings can be managed from within the plugin. See the AlarmDecoder Configuration section of this document.
  3. Download this plugin from the Indigo Plugin Store.
  4. Double-click the plugin icon to install the plugin within Indigo. Choose "Install and Enable the Plugin"
  5. Choose "AD2SUB Alarm Interface" from the Plugins menu and choose Configure. In many cases you will only need the minimum information the plugin needs to operate:
    • AD2USB connection settings: Configure the IP address and port OR the USB Serial settings of your AlarmDecoder so the plugin knows how to connect to your AlarmDecoder.
    • Number of Partitions: If you have more than one (1) alarm partition change the default of "1" to the number of partitions you have. If you are unsure, leave the setting as "1" partition.
  6. Save the Configuration.
  7. Add a Keypad Device with the same keypad address as the NuTech AlarmDecoder.
  8. Add Zone Devices.

Quick Start - Upgrading the ad2usb plugin

  1. Refer to Indigo's Plugins Menu documentation.
  2. Go to Indigo's Plugins -> Manage Plugins menu
  3. Look to see if ad2usb plugin has an upgrade and if it is compatible with your version of Indigo. If it has an upgrade:
    • Disable the ad2usb plugin
    • Download the latest version of the plugin if it is compatible with your version of Indigo
    • In the MacOS Finder, double-click on the downloaded plugin. Choose "Install and Enable"
    • Verify the new version of the plugin is running via the Plugins -> Manage Plugins menu. The running version number is shown after the plugin name.

Plugin Configuration Details

It is recommended that you Disable and then Enable the Plugin after making Configure changes. A future release should resolve this issue.

AD2USB connection settings

  • Select Local USB Port (for the AD2USB) or IP Network (for the AD2PI Network Appliance).
  • For IP Network enter your IP address and port.

Operating parameters

  • Operate in advanced mode: Most users will be fine with Basic Mode (the default). If Advanced Mode is needed enable it here.
    • Basic Mode - The AlarmDecoder is capable of reading numerous message types. Refer to the Protocol dcoumentation for details (note: the online documentation refers to the latest firmaware of the AlarmDecoder). Basic mode limits your device configuration to Zone Numbers and the Plugin will only process Keypad messages.
    • Advanced Mode - Advanced mode allows you to configure Relay, Expander, and Wireless devices (note: advanced mode is not needed if you have these devices so long as your keypad messages include the zone numbers for these devices).
  • Clear all Zone devices on plugin restart: Enabling this is the recommended setting. When this setting is enabled, all devices are set to Clear on restart of the plugin or when enabling communication of a device that was disabled. If for any reason Indigo and your alarm panel are not reporting the same status of a zone (e.g. Zone 11 is Fault in Indigo but Ready/Clear on your alarm panel) then disabling and then re-enabling communications for that device via the Indigo Client UI will reset the device to Clear. Additionally, when you start or restart (Disable and then Enable) the plugin with this setting on all plugin Alarm Zone devices will be set to Clear.
  • Number of Partitions: Select the number of partitions for your alarm system. Refer to your alarm setup. The default of "1" is typical for most home installations.

Logging Options

  • Log Arm/Disarm events: Choose whether to log arm/disarm events. These events are logged with the log level of INFO and will only be visible in the logs if you log level setting are INFO or DEBUG.
  • Log Unknown LRR Messages: This setting has been added to help identify all the different panel messages with the newer AlarmDecoder firmware v2.2a.8.8. It is turned on by default. It will log unknown Long Range Radio (LRR) reporting events to the Indigo Event log as WARNING messages. An LRR message is considered "unknown" if there is no existing Trigger Event is defined by this Plugin for that message.
  • Indigo Event Log Level: See Logging section.
  • Plugin Log Level: See Logging section.
  • Log Panel Messages: See Logging section.
  • Mask Alarm Codes: This setting (on by default) will attempt to replace anything that looks like an alarm code (4-digits) with CODE in all log files. This feature is intended to increase security of your alarm system.

Saving the Alarm Code

This plugin does not require an alarm code to be saved. Only those functions on the panel that require a code, such as Disarming, Bypass, Night-Stay, etc. will not work unless an alarm code is available to the plugin. For remote monitoring only, an alarm code is not required and does not need to be saved in the plugin. Users of this plugin will need to assess their own security and risks, and what features they plan to use, in order to determine if they want to store an alarm code or not.

There are several ways to store the alarm code via the plugin. You can also store the code in an Indigo Variable, and seperate configuration file, or directly in the Preferences. To save your alarm code, use the Configure menu and enable Save Alarm Code. Once enabled, you have three options: 1. Indigo Variable. You can use an Indigo Variable to store the code. Enter your variable in the in the format:%%v:VARID%% where VARID is the variable ID (ex: %%v:1929322623%%). 2. OTP Configuration File. See the One Time Password Setup section for more information. If you are using OTP, other plugin functions such as HomeKit integration can use the configuration file AD2USB_OTP.cfg that contains the alarm panel User Code for Bypassing, Disarming and Arming your panel. 3. In Preferences. Store the alarm panel User Code within the Configure preferences. Select this option and enter the 4-digit User Code for Bypassing, Disarming and Arming your panel that you wish to use.

One Time Password Setup

Overview

This is an optional feature that requires the installation of additional Python modules and creation of several Indigo variables. Installing the additional modules is not required to use the rest of the features and capabilities of AD2USB; these module are only required for the OTP features.

One Time Passwords (OTP): - Involve a shared secret, stored both on the phone and the server and, optionally, embedded in a QR Code for easier setup on the mobile phone - Can be generated on a phone without internet connectivity; but internet connectivity is required to connect to your Indigo server - Is used as a second factor of authentication; your Reflector login is still secured with a password - Google Authenticator and other OTP client apps allow you to store multiple OTP secrets and provision those using a QR Code

The One Time Password (OTP) features enhances security by allowing you to remotely Bypass Zones, Arm, and Disarm your panel while not passing the alarm panel code over the internet when accessing Indigo remotely or requiring you to store your alarm panel code within any of Indigo configuration items (Variables, Preferences, Triggers, Actions, etc.) that can be accessed by an Indigo Client UI remotely. Instead, your alarm code is stored in a text configuration file in a folder of your choosing on your Indigo Server (NOTE: this plugin running on your Indigo server must be able to read and write to this file). Instead of passing the alarm code in a variable or embedding it elsewhere; this feature allows you to update one of several Indigo Variables (see Setup below for variable details) with a six-digit one time password provided by an OTP app such as Google Authenticator, Authy, or another compatible app on your smartphone. These OTPs expire every 30 seconds and can only be used once. When the Indigo variable's value is updated with a valid OTP the Plugin reads the alarm code from the file on your Indigo server and sends it to the AlarmDecoder as part of one of the limited pre-defined functions associated with each of the variables.

Setup

  1. Install the needed pre-requisites Python module(s) and restart the Indigo Server:

    • pyotp. This module is required to use the OTP features. Install the module via pip3 install pyotp.
    • qrode. This is optional but needed to generate a QR Code PNG image file for easier mobile device setup. Install the module via pip3 install qrcode. The qrcode module will use the Pillow image library which is already installed as part of Indigo 2022.1.
  2. Create a User Code on you alarm panel to use. Test the code on your panel to ensure it can Bypass Zones, Arm and Disarm the system. (NOTE: For this feature, I would not recommend using the master or installer codes. I recommend you use a dedicated User Code for this feature. You may even want to use a User Code with the "Guest" attribute. Guest User Codes cannot be used to disarm the system armed by any other user code. Refer to your Alarm User Manual for more information on Guest User Codes.)

  3. Choose a folder to store your alarm code information. The folder must be created before configuring the path in the next step. The Indigo AD2USB Plugin will not create any folders on you Mac Indigo Server. This folder must be readable and writable by the Indigo Server. NOTE: The Indigo server may not be able to read your Documents folder due to anti-virus software settings.

  4. Select “Configure…” under the AD2USB Alarm Interface Plugin Menu. Select the checkbox Enable OTP to enable the OTP feature. A new text field OTP Configuration Folder will now be visible. This field should contain a valid folder (full directory path - ex: "/Users/myusername/Alarm Panel Info") to store the security configuration file and the QR Code image file. Upon closing the Configure Dialog box the OTP Config file and the QR Code image file will be automatically created. If the files cannot be created - there will be an error message in the Event log. Common reasons are an incorrect folder path or not having permission to the folder. If created, the configuration file is named AD2USB_OTP.cfg. This file contains the shared OTP key and your alarm code to use. The QR Code image file named AD2USB_OTP.png.

  5. Find and edit the file AD2USB_OTP.cfg from Step 4 using a text editor. This file contains both the alarm panel User Code for Bypassing, Disarming and Arming your panel and a new random shared key generated during initial configuration. Update the User Code to the alarm panel code you want to use. Codes are four (4) digits. Save the file as a plain text file. NOTE: Using OTP requires the code to be stored in the AD2USB_OTP.cfg configuration file. The OTP function cannot access an alarm code stored in either an Indigo Variable or the Configure preferences described in the previous section Saving the Alarm Code.

  6. Further restrict permissions on these files (Optional). You can run the Unix chmod command to better secure these new files. From the command prompt cd in to the folder you selected and run these commands: chmod 600 AD2USB_OTP.cfg and chmod 600 AD2USB_OTP.png.

  7. Download and install Google Authenticator (or another OTP alternative) from the App Store. Use the plus (+) button in the lower right to add a new Authenticator OTP. You can scan the QR Code image (recommended) or you can configure it manually by choosing “Enter a setup key”. If configuring manually, enter “Indigo AD2USB” for the Account field. For the Key enter the Shared key from the configuration text file you created. Choose “Time based” and finish by pressing the “Add” button.

  8. Use the plugin menu OTP - Create Variables to create five new Indigo variables: ArmyAwayOTP, ArmStayOTP, BypassOTP, ZonesToBypassOTP, and DisarmOTP. Once created these variables you may want to move them to their own folder.

  9. You can regenerate/change the key and config files at any time using the plugin menu OTP - Regenerate Key/Files. After regenerating the files you will need to re-configure your Google Authenticator application with the new QR Code or manually with the shared key from the updated OTP configuration file.

Alarm Panel Function Required Indigo Variable Description Example Value Arm Away ArmyAwayOTP Update the variable value to a new OTP passcode to perform an Arm Away function on your panel. 123456 Army Stay ArmStayOTP Update the variable value to a new OTP passcode to perform an Arm Stay function on your panel. 334122 N/A ZonesToBypassOTP Enter a comma separated list of the zones to bypass when using the BypassOTP function. Zones 1-9 should be zero-padded (e.g. 09) 11,22,04 Bypass BypassOTP Update the variable value to a new OTP passcode to perform a Bypass function on your panel. The zones to Bypass are read from the ZonesToBypassOTP variable. 665512 Disarm DisarmOTP Update the variable value to a new OTP passcode to perform a Disarm function on your panel. 441666

How to Use OTP

To use the OTP feature open the Google Authenticator app and copy the OTP from your smartphone app and paste the value into the respective variable in Indigo Touch (or the Indigo Client UI) and save the variable. This will automatically invoke the respective alarm function on the Indigo server. Be mindful of the 30 second timeout when using this feature remotely. It may take you a few seconds to copy the six digit code, switch to the Indigo Touch application, paste and update the Indigo variable with the new code, update the Reflector from Indigo Touch, receive the new variable value on the Indigo server, and then validate the OTP. If the 30 seconds has timed out when the Plugin validates the OTP, it will be invalid. OTPs can only be used once, so if you're performing two actions in sequence (e.g. Bypass, then Arm), you will need to wait for the OTP to change to a new code for each action.

Disabling OTP

If you've setup OTP and wish to disable it simply edit the OTP Configuration File and remove both the User Code and the Shared Key; or remove the file entirely. You should also remove/delete the variables created in during setup.

HomeKit Integration

Overview

HomeKit integration requires HomeKitLink-Siri and the enabling of saving an alarm code within the plugin if you plan to use HomeKit to Disarm you panel. HomeKit allows you to view the state of the panel. HomeKit can also perform arming and disarming the panel by calling one of the plugin's built-in Keypad Actions. The tables below describes the states HomeKit can recognize and the actions it can perform.

Alarm Panel State AD2USB Keypad State HomeKit State Notes Armed Stay Armed Stay Stay Armed Armed Away Armed Away Away Armed Armed Night Stay Armed Night Stay Night Armed Ready Ready Disarmed N/A N/A Alarm Triggered Armed Instant Armed Instant Stay Armed HomeKit does not support this state. Stay Armed will appear instead. Armed Max Armed Max Away Armed HomeKit does not support this state. Away Armed will appear instead. HomeKit Action Indigo Action Stay Armed Arm-Stay Away Armed Arm-Away Night Armed Arm-Night-Stay Disarmed Disarm (requires enabling of Save Alarm Code) Alarm Triggered N/A - this happens when Alarm is triggered

Setup

In order to use the Disarm capability, select the checkbox in the plugin Configure menu to enable Save Alarm Code and follow this guide to setup your code in an Indigo Variable, the OTP Configuration file, or directly within preferences. If you have more than one partition, you will also need to designate the partition that HomeKit will be associated with. If you do no specify a partition in the Configure menu, partition 1 will be the default. For other configuration settings, refer to HomeKitLink-Siri.

AlarmDecoder Configuration

Once communication settings have been made in the Plugin Configure dialog, you can make changes to your AlarmDecoder from within the plugin. Select "AlarmDecoder Configuration" under the Plugin menu. AlarmDecoder settings are not stored in the Plugin for versions 3.1.0 and greater, however, each time a "CONFIG" message is read from the AlarmDecoder the current settings will be stored in memory while the plugin is running. These last read settings will be shown in the AlarmDecoder Configuration dialog window when it opens. Because AlarmDecoder settings can be made outside of the plugin the AlarmDecoder Configuration dialog is divided into two (2) sections or steps. The first section/step, "Step 1 - Retrieve the current AlarmDecoder configuration from the device", allows you to attempt to read the current configuration from the AlarmDecoder by pressing the button titled "Read Config". Once the configuration is read the dialog will be updated with a status message and the settings in Step 2 will be updated with the current values from the AlarmDecoder. You should always press the button in this first step before making changes to your AlarmDecoder configuration.

The section titled, "Step 2 - Update the AlarmDecoder configuration" allows you to change some of the AlarmDecoder CONFIG settings (see NuTech documentation). If the "Update" button is pressed, these configuration parameters will be written to the AlarmDecoder and overwrite the respective settings you have on your AlarmDecoder. AlarmDecoder settings ADDRESS, EXP, REL, LRR, and DEDUPLICATE can be changed.

AlarmDecoder Configuration Dialog Box Fields

  • Step 1 - Retrieve the current AlarmDecoder configuration from the device:
    • Read Config (button): Pressing this button will attempt to read the current configuration parameters from the AlarmDecoder. It will replace the current settings in the AlarmDecoder Configure Dialog with the settings read from the AlarmDecoder.
  • Step 2 - Update the AlarmDecoder configuration:
    • Keypad Address (ADDRESS): Required. The keypad address assigned to the AlarmDecoder. Ensure to set this to the address you programmed on your alarm panel. This is also the keypad address you will normally use for your Indigo ad2usb Keypad device for basic single partition systems.
    • Remove duplicate messages (DEDUPLICATE): If enabled, removes duplicate alphanumeric keypad messages.
    • Virtual Zone Expanders(s) (EXP) (Max 2): Zone Expander Emulation allows the AlarmDecoder to act in place of a physical expander board and make use of virtual zones with your panel. After enabling it on both the panel and the AlarmDecoder you can begin opening and closing zones, which will be relayed back to the panel.
    • Virtual Relay Module(s) (REL): Allow the alarm panel to open/close a virtual relay managed by a home automation system.
    • Virtual Long Range Radio (LRR): The AlarmDecoder can emulate a Long Range Radio (LRR) expander and then receive LRR messages from your alarm panel. Enabling this feature may require enabling Long Range Radio output on your alarm panel. Consult your alarm panel's programming guide. AlarmDecoder firmware versions V2.2a.6 and V2.2a.8.8 differ in how LRR messages are structured. The current version of the plugin can only process LRR messages from firmware version V2.2a.6. The newer V2.2a.8.8 firmware's LRR messages will be supported in a future release.

Logging

There are three log files in the standard Indigo Library directory. Each has its own purpose and is described below. 1. Indigo Event Log: The first log is Indigo's event log file with file name format YYYY-MM-DD Events. The Indigo event log is used to log standard Indigo device events, actions, triggers, and plugins. It is configured and managed via Indigo and the plugin can write to it. 2. Plugin Log: The second log is the plugin's log file which is in a subdirectory with the same name as the plugin: com.berkinet.ad2usb. The log files are named using the format plugin.log.YYYY-MM-DD. The plugin log can be used to record detailed debug info for panel messages, AD2USB configuration details, and other panel and plugin specific information. 3. Panel Message Log: The third (optional) log file is in the same directory as the plugin log and named panelMessages.log. It can be enabled via the Configuration menu. There are no logging levels associated with this log file. The panel log will log the messages received from your alarm panel by AlarmDecoder.

Logging levels for the Indigo and plugin log file can be modified in the plugin's configuration dialog. The information captured in each log file varies based on the logging level specified. Having separate settings allows you to capture detailed DEBUG details in the plugin's log but only log INFO messages to the Indigo log. Or for less verbose setting you can log INFO messages and above to the plugin's log bug only WARNING and above to Indigo's log. A summary of logging is below.

Log Level Indigo Event Log & ad2usb Plugin Log CRITICAL Only critical errors will be logged. Critical errors typically result in plugin failure and exit. This option will log the fewest entries. ERROR Critical errors (see above) and non-fatal errors will be logged. Non-fatal errors should be investigated since the plugin may not behave has expected. They could be a result of configuration errors or plugin bugs. WARNING In addition to critical and non-fatal errors, warnings will be logged. Warnings are neither fatal or critical but represent an unexpected condition that is logged. INFO In addition to critical and non-fatal errors and warnings, this setting will log verbose information about the Indigo objects, the plugin, and the alarm panel. Startup, shutdown, and changes to Indigo devices, actions, and triggers will be logged. This log setting is required to log arm/disarm events. It is recommended this is the minimum log level for the plugin log and may be desired setting for the Indigo log for many users. DEBUG In addition to all messages above, detailed debug messages will be logged. These messages are primarily used to understand the changes of internal variables, logic flow, and other details that can aid in the debugging process.

Helpful Troubleshooting Techniques

Plugin and AlarmDecoder Version and Settings

Version 3.0.0 will log the Plugin and AlarmDecoder version and settings to the Indigo log window on startup. Please provide these details with any post on the User Forum.

Enabling the log files

To be able to be supported you'll need to have some level of logging enabled. The recommended settings are: 1. Indigo Event Log - set to Errors, Warning, or Informational - any of those 3 settings will show any plugin errors in the Indigo Log 2. Plugin Log Level - set to "Verbose Debugging", this produces about +/-50MB log daily on a typical system but is essential. The filename is plugin.log. 3. Enable Log Panel Messages: Turn on. This log is +/-5MB daily. It is the raw panel messages from the decoder. The filename is panelMessages.log

The path for logs is /Library/Application Support/Perceptive Automation/Indigo <Version Number>/Logs/com.berkinet.ad2usb. Note that part of the file path indicated as <Version Number> is dependent on your version of Indigo (ex: 2023.1).

Getting Help and Reporting Bugs

Start by asking on the support forum. If more info is needed, I'll typically ask for this via a private message or email:

  • Specify if it is a a USB or IP based AlarmDecoder
  • AlarmDecoder VER and CONFIG settings. These are logged on startup in the Indigo Event log or can be found in the plugin log file.
    • Run the MacOS/Unix commands grep VER plugin.log and grep CONFIG plugin.log to get these settings. The most recent entries are what is needed.
  • A copy of the plugin.log - typically ~500 lines before and after the ERROR entry or message that is causing the strange behavior is more than enough to understand the problem.
  • A copy of the panel message log (panelMessages.log) - typically ~100 lines before and after the time of the ERROR will help isolate the messages and devices from your panel that caused the error.
Release details
Released on: Jan. 1, 2024
Requires: Indigo v2022.1.0+
Downloaded: 0 times 
Changes in this release
  • Updated code to allow for a duplicate of the plugin to run with a different name for scenarios where more than one alarm panel is being managed. Users would also need to edit the Info.plist file on their own and give each new instance a different name and pluginID. Note that this feature is still experimental. This change should have no impact on existing installations with a single alarm panel.
Release details
Released on: Dec. 27, 2023
Requires: Indigo v2022.1.0+
Downloaded: 0 times 
Changes in this release
  • Fixed bug where the "About AD2USB Alarm Interface..." menu item still pointed to old user forum.
  • Fixed bug where enabling of Panel Logging would cause an error that required Plugin to be restarted. Panel logging can now be enabled and disabled without restarting the plugin.
  • Updated README (documentation).
Release details
Released on: April 23, 2023
Requires: Indigo v2022.1.0+
Downloaded: 0 times 
Changes in this release
  • Panel Arming Events are deprecated and removed in this release. Before upgrading, migrate any triggers using Panel Arming Events to User Actions as described in the Release Notes for version 3.3.1. To migrate your existing Panel Arming Events Triggers change the Event from Panel Arming Events (deprecated) to User Actions. The type of Alarm Event and Partition will be set based on the value of your Panel Arming Event setting and the new field "Any User" will be selected by default. Upon saving the Trigger as a User Action Trigger it will be migrated. After upgrading to version 3.4.0 an error message will show on startup if any Panel Arming Events are used in Triggers and those Triggers which were not migrated will need to be deleted to stop the error message.
  • Two new Keypad Device States:
    • Alarm On - this is when the alarm is currently occuring (i.e. the siren is on)
    • Alarm Occurred - this is immediately after the sounding alarm (Alarm On) is disabled via a Disarm (OFF). A second disarm will change the state to Ready
  • New feature allows you to save an alarm code (for Night-Stay, Disarming, etc.) in an Indigo Variable, directly in the Preferences, or via the OTP Configuration file (introduced in version 3.3.1). This code will be used by new Actions that were added in this release (see below). See the latest README for more information on how to configure the alarm code.
  • Changes to Actions:
    • Several Actions have been renamed to more accurately reflect their function. These Actions did not require an alarm code. The id (or actionId) for these Actions remains the same so any custom scripts you may have that called these Actions in should not require updating.
      • Arm-Away has been renamed to Quick Arm-Away
      • Arm-Stay has been renamed to Quick Arm-Stay
      • Arm-Max has been renamed to Quick Arm-Max
      • Arm-Instant has been renamed to Quick Arm-Instant
    • New Actions. Each of the new Actions below requires the saving of the alarm code for use by the Action. If they are called and a valid alarm code is not set, the Action will not be performed and an error will be logged in the Event Log. See your Alarm Panel Users Guide for more information about each of these arming modes
      • Arm-Stay (CODE). This action uses the saved alarm code to perform CODE + 3 (STAY) to arm the panel in STAY mode. It can be used in lieu of Quick Arming if you wish to use a specific User Code.
      • Arm-Night-Stay (CODE). This action uses the saved alarm code to perform CODE + 3 (STAY) + 3 (STAY) to arm the panel in NIGHT-STAY mode.
      • Arm-Away (CODE). This action uses the saved alarm code to perform CODE + 2 (AWAY) to arm the panel in AWAY mode. It can be used in lieu of Quick Arming if you wish to use a specific User Code.
      • Arm-Instant (CODE). This action uses the saved alarm code to perform CODE + 7 (INSTANT) to arm the panel in STAY mode with entry delay turned off. It can be used in lieu of Quick Arming if you wish to use a specific User Code.
      • Arm-Max (CODE). This action uses the saved alarm code to perform CODE + 4 (MAX) to arm the panel in AWAY mode with entry delay turned off. It can be used in lieu of Quick Arming if you wish to use a specific User Code.
      • Disarm (CODE). This action uses the saved alarm CODE + 1 (OFF) to disarm the panel.
  • HomeKit integration is now provided via HomeKitLink-Siri.
    • Requires HomeKitLink-Siri version 0.60 or greater. Refer to HomeKitLink-Siri documentation or release notes to confirm requirements.
    • Within HomeKitLink-Siri you need to select the ad2usb Keypad device to be associated with HomeKit actions and state. This will ensure the HomeKit alarm actions are sent to the desired alarm Keypad and Partition.
    • Within the plugin's Configure menu you need to select if you want HomeKit to use the Quick Arm functions (e.g. #3 for STAY) or use the saved alarm code within the plugin (e.g CODE + 3 for STAY).
    • You must enable the saving of the alarm code to enable HomeKit to Disarm the panel or perform Night-Stay.
    • Added new device state for homeKitState for the ad2usb Keypad device. The state can be one of the five (5) values below. The associated panel states are also listed:
      • armedStay - Armed STAY or Armed INSTANT
      • armedAway - Armed AWAY or Armed MAX
      • armedNightStay - Armed NIGHT-STAY
      • disarmed - Disarmed
      • alarmOccured - Alarm has been triggered: Alarm Sounding or Alarm Occurred
    • Added new hidden Actions for HomeKitLink-Siri to use to arm and disarm the panel. HomeKitLink-Siri will be able disarm the panel (requires a code) or place the alarm in STAY, AWAY, or NIGHT-STAY (requires a code).
  • Custom Panel keypad messages sent via Indigo Variables or defined Actions, etc. can contain a plus character ("+") for readablilty that will be removed before being sent to the keypad. For example "1234+1" will send "12341" to the keypad.
  • Fixed a bug where zone state changes were not logged at INFO level for advanced devices. In additio, logging of zone changes now reports zone state using the more UI friendly states: Fault, Clear, Bypass, Error, or Unknown
  • Fixed a bug where Arm Night Stay was not properly set in the armedMode state of the Keypad device.
  • Fixed a bug where lastADMessage was not getting updated when no Keypad messages are sent (e.g. while the panel was Armed).
  • Updated README (documentation).
Release details
Released on: April 8, 2023
Requires: Indigo v2022.1.0+
Downloaded: 0 times 
Changes in this release
  • Added a new Alarm Zone device state Last Battery Restore. This will log the date/time when the RF Low Battery restore event is detected. This can be used to track the last date/time you replaced a battery in your wireless sensors.
  • Zone numbers that are not valid (not in the range of 1-99) within Keypad Messages and will now log a warning versus an error in the Indigo Event Log.
  • Zone numbers in Alarm Panel messages that are not defined as an Alarm Zone Device in Indigo will log a new warning messages in the Indigo Event Log: "Alarm Panel Message received for Zone:## but Zone Device does not exist in Indigo." This condition previous reported a non-descript error message.
  • Added two new User Events: Walk Test Mode On and Walk Test Mode Off. You can use these to detect when the a user enters (e.g. enables) or exists TEST mode (Alarm Keypad function 5).
Release details
Released on: Jan. 3, 2023
Requires: Indigo v2022.1.0+
Downloaded: 0 times 
Changes in this release

"Write to Panel" Actions variable substitution did not work correctly. This has been fixed. Variables can be anywhere in the string/message (ex: "12346%%v:58295773%%").

Release details
Released on: Jan. 1, 2023
Requires: Indigo v2022.1.0+
Downloaded: 0 times 
Changes in this release
  • Bug fixes.
    • Fixed bug that prevented Keypad State Zone Bypass List from displaying correctly.
    • No longer report an error for AlarmDecoder messages when configuration is retrieved (!UART and !Reading).
  • Changed error messages to warning messages when unknown AlarmDecoder messages are seen.
Release details
Released on: Dec. 25, 2022
Requires: Indigo v2022.1.0+
Downloaded: 3 times 
Changes in this release
  • Added Time-Based One-Time Password Algorithm capability (OTP). Refer to the README on how to use this new capability for added security if you want to arm/disarm your alarm panel remotely using Indigo Touch or Indigo Client UI. This new feature requires the installation of one required and one optional, but recommended, Python modules. If you don't plan on using this capability; you do not need to install these modules and this release and future releases will continue to work. You need to restart the Indigo server after installing these modules.
    • PyOTP. Required for OTP functionality.
    • qrcode. Optional for OTP functionality but required if you plan on generating a QRCODE image for easier setup on your mobile device.
  • Major changes to Plugin Triggers and Events.
    • Triggers created for User Actions have several new features. You can now choose if the Event applies to any user or specific user(s). When listing specific users(s) you can continue to provide a single user code number (ex: 02) or use the new feature of providing a comma seperated list of users (ex: 02,07,11,22). The valid range for user numbers is 1 to 49. You can also provide an Indigo Variable as the user(s) in the format:%%v:VARID%% where VARID is the variable ID (ex: %%v:1929322623%%). The variable's value can contain one or more user codes.
    • Panel Arming Events will be deprecated and removed in the next release. Use the updated User Actions instead. A User Action with the new "Any User" setting is functionally the same as the Panel Arming Events.
      • With this release any Triggers you have based on Panel Arming Events will not allow you to make changes to the Panel Arming Events details but they will continue to work. The Event Log will warn you that these type of Trigger Events exist on startup or execution of the Trigger. In a future release these type of events will be removed and your Panel Arming Event Triggers will cease to work. You can easily migrate these triggers as described next.
      • To migrate your existing Panel Arming Event Triggers simply change the Event from "Panel Arming Events (deprecated)" to "User Actions." The type of Alarm Event and Partition will be set based on the value of your Panel Arming Event setting and the new field "Any User" will be selected by default. Upon saving the Trigger as a User Action Trigger it will be migrated.
      • While you can rollback this release of the plugin, Panel Arming Events Triggers that were migrated will remain User Action Triggers after the rollback and you will need to manually change these back to Panel Arming Events.
    • Fixed two bugs that have existed since version 1.6.0 or earlier. I recommend you review the bug fixes below and then review and update your Triggers if needed before upgrading the plugin.
      • More than one Trigger for an event. If you had more than one Trigger defined for an event, when the event occurred only one of these Triggers would be executed. As of this version, all Triggers defined for an event will be executed. For example, if you had two Triggers defined for a Panel Arming Event of Disarmed, only one of these would be executed when the panel was Disarmed. With this release, both Triggers will be executed.
      • More than one Alarm Event per Trigger. The Trigger dialog box Edit Event Settings... has always allowed selection of multiple Arming, System, or Alarm Events. However, if multiple events were selected, the Trigger would only be run on the first selected event from the list. This bug has been fixed. Multiple events are now supported. For example, you can now have a single Trigger based on User Actions Events for both Arm Stay or Arm Away events that will be executed if either of those events occur.
    • New Events. A new event Alarm Cancelled has been added to User Action Triggers and new event Interior Alarm has been added to Alarm Event Triggers. The Interior Alarm event is only supported in the newer Alarm Decoder firmware version 2.2a.8.8.
  • Added all the remaining Long Range Radio (LRR) events for processing triggers with the newer AlarmDecoder firmware version 2.2a.8.8 except for "ALARM AUX" which was not easily matched SAIC code. If you depended on this event, please post in the forum and I can work with you to identify the correct code. More details are below:
    • Events "Zone BYPASS" On/Off, "24 Hour Non-Burglary Zone" Fault/Clear, "Periodic test report", "Trouble", "Trouble Restore", "AC Power Lost" and "AC Power Restore" were tested and are now able to be processed and will no longer log WARNING messages. (NOTE: From my own testing and research, VISTA panels will only report "AC Power Lost" event after a random delay of up to 4 hours. Thus, most users may not find this feature useful. An alternative is to create a Device State Changed Trigger on the Keypad Device where the state "AC Power" becomes "Off" for loss of power; or "On" when power is restored).
    • New events "Interior Alarm" and "Alarm Cancelled" were tested and have been added as new Indigo Events which you can created Triggers from.
    • All of these remaining events have been added but have not been tested on an actual panel. The README will indicate which have been tested and which have not.
  • Removed logging of leading four digit codes passed to the AlarmDecoder. This is to prevent any user codes from being in the event log and/or files. This setting can be overridden by unselecting the new Configure setting Mask Alarm Codes (checked by default). When masked, the log will replace the four digit code send to panel in the log with CODE+ string. For example, when Disarming the logs will show CODE+1.
  • Renamed menu items Get AlarmDecoder Settings to AlarmDecoder - Get Settings and Get AlarmDecoder Firmware Version to AlarmDecoder - Get Firmware Version
  • Alarm Action "Write to Panel" can now use Indigo Variables.
  • New Keypad State Zone Bypass List added. The value is a string with the list of zones that are bypassed (ex: "11,17,22")
  • Replaced version 3.3.0 released the same day which had a minor bug in OTP key generation - that version has been removed.
Release details
Released on: Sept. 5, 2022
Requires: Indigo v2022.1.0+
Downloaded: 31 times 
Changes in this release
  • Changed Indigo ad2usb Keypad Device custom state "AC Power" (acPower) possible values from "1" or "0" to "On" or "Off". From my own testing any device change trigger you had created on this state change should migrate without any change.
  • Added more Long Range Radio (LRR) events for newer AlarmDecoder firmware version 2.2a.8.8:
    • Now support "AC Power Lost" and "AC Power Restore" events. These LRR events will no longer log WARNING messages. (NOTE: From my own testing and research, VISTA panels will only report this LRR event after a random delay of up to 4 hours. Thus, most users may not find this feature useful. An alternative is to create a Device State Changed Trigger on the Keypad Device where the state "AC Power" becomes "Off" for loss of power; or "On" when power is restored).
    • Events for "Zone BYPASS" On/Off and "24 Hour Non-Burglary Zone" Fault/Clear will no longer log WARNING messages; however the plugin does not yet support creating Triggers on these LRR events.
  • Added new Keypad Custom State 'Last AD2USB Msg Time' (lastADMessage) that shows the last time an AlarmDecoder message has been read. This is useful when away for extended periods to confirm the Plugin is still processing messages since other plugin device states typically do not change.
  • Updated Keypad Device states names in the Trigger dialog from "Ready to Arm" to "Ready" and from "Faulted" to "Fault" for consistency.
  • Fixed a bug preventing the Bypass state from being restored when a zone device is disabled and enabled.
Release details
Released on: Aug. 18, 2022
Requires: Indigo v2022.1.0+
Downloaded: 12 times 
Changes in this release
  • This version is the first to support both AlarmDecoder firmware versions 2.2a.6 and the newer version 2.2a.8.8. The use of the newer firmware could be considered a BETA since the Plugin isn't yet able to read all of the panel messages for Triggers Events when using the newer firmware. It has been released to allow the community to help determine all the newer panel message formats in order to ensure a timely future release can account for all of Trigger Events while using the newer firmware. Users of the older firmware should not have any concerns upgrading to this version.
  • AlarmDecoder Firmware version 2.2a.8.8 is now supported but with some caveats on what Triggers can be detected with this version. With the help of this community, future versions should be able to expand the number of events that can be processed from the panel. Please read these release notes carefully before upgrading.
    • Background. Long Range Radio (LRR) message formats in the AlarmDecoder were changed from firmware version 2.2a.6 to the newer version 2.2a.8.8. The older firmware 2.2a.6 had 25 different LRR message types of which 18 are used by this plugin for possible Trigger Events you can configure (see the updated README section: Trigger Events for details on each event type). The new LRR message format in version 2.2a.8.8 firmware is now based on the SIA DC-05-1999.09 standard. This standard includes over 200 report codes/message types.
    • Current limitation with this Plugin version and firmware 2.2a8.8. Not all possible events were tested on a panel prior to this release. At present only three (3) of the (18) Trigger Events in this plugin have been mapped to the newer LRR message formats: Arm Stay, Arm Away, and Disarm. The updated README also identifies which events are mapped and which are not yet mapped. IMPORTANT: If you upgrade to the newer firmware version any Triggers you have for events not yet identified and mapped to the new codes will NOT be executed.
    • Help is needed identifying and mapping the remaining codes. The remaining eight (8) codes that need to be identified for System Events are: AC Power Lost, AC Power Restore, Battery low, Battery Restore, RF Battery low, RF Battery Restore, Trouble, and Trouble Restore. The remaining seven (7) codes that need to be identified for Alarm Events are: Panic Alarm, Fire Alarm, Audible Alarm, Silent Alarm, Entry Alarm, Aux Alarm, and Perimeter Alarm. To aid in their identification a new logging option has been introduced with this version that will log any unknown LRR messages to the Indigo Event Log Console to help facilitate mapping these LRR messages to existing Trigger Events in future releases of this plugin. Please post any of these warning messages in the User Forum so the new message codes can be readily identified and added to the Plugin.
  • Changes to the Configure Dialog
    • Renamed the section "Log Configuration" to "Logging Options".
    • Moved "Log Arm/Disarm events" option to the "Logging Options" section.
    • Added new setting option: "Log Unknown LRR Messages." This setting has been added to help identify all the different panel messages with the newer AlarmDecoder firmware. It is turned on by default. It will log unknown Long Range Radio (LRR) reporting events to the Indigo Event log as WARNING messages. An LRR message is considered "unknown" if this Plugin does not have a corresponding Trigger Event for that message.
  • New Zone Device state added. A new device state lastFaultTime has been added that will show the last date and time the zone had a Fault.
  • Updated README provides a more detailed explanation of Trigger Events and now has a Table of Contents.
Release details
Released on: Aug. 7, 2022
Requires: Indigo v2022.1.0+
Downloaded: 13 times 
Changes in this release
  • Changes to Alarm Keypad (ad2usb Keypad) device.
    • Changes to the Alarm Keypad Ready/Armed states. Internal to the plugin, the device state displayState for keypad devices has been removed. If you have any Indigo Trigger Types of "Device State Changed" based on the AD2SUB Alarm Keypad Device states Alarm State Changed... (usually the first options in the Trigger pull down) you should disable these Triggers before upgrading and then edit and re-save each of these Triggers after upgrading. Other Triggers based on ad2usb Keypad states other than Alarm State Changed are not impacted by this change.
    • Alarm Keypad (ad2usb Keypad) Device State. In version 3.0.0 the list of valid states were: Ready (Not Armed), Fault, Armed Stay, Armed Away, and Error. Additional states Armed Night-Stay, Armed Instant, and Armed Max have been added. Refer to your alarm panel guide for more information about these states.
    • Multiple Keypad Devices. Read the updated README for information about the rules and behavior for multiple ad2usb Keypad devices. In summary, you can have one ad2usb Keypad Indigo device per partition and should have one, and only one, ad2usb Keypad Indigo device associated with the keypad address of the AlarmDecoder.
  • Clear All Zones Devices configuration setting. The behavior for this setting has changed. When this option was selected all AD2SUB Alarm Interface devices are set to Clear/Ready on restart of the plugin. There is no change in that behavior. What is new is now AD2SUB Alarm Interface devices are also set to Clear/Ready when enabling communication for a single device. Thus, if a single Indigo AD2SUB Alarm Interface device is out of sync with your alarm panel you can first clear the fault for that zone on your alarm panel and then disable and re-enable communications for that device in the Indigo Client UI and it will reset the state to Clear.
  • AlarmDecoder Configuration is now under its own Menu. The AlarmDecoder configuration options have been removed from the Plugin Configure menu to its own menu making a clear separation of when you are changing your Plugin settings versus writing new settings to the AlarmDecoder. With the exception of the keypad address, AlarmDecoder configuration settings are no longer stored as Preferences. The reason for this was several fold, most importantly to not have the Plugin depend on saved AlarmDecoder settings that could be changed at anytime via changes to the AlarmDecoder from a program other than the Plugin. Instead, whenever the Plugin sees a new CONFIG confirmation message it will read the current settings of the AlarmDecoder and update the needed properties and settings.
  • New Menu Options. There are two new menu options in the Plugins, A2USB Alarm Interface menu. The menu Get AlarmDecoder Settings, will send a CONFIG (Settings) message to your AlarmDecoder. The menu Get AlarmDecoder Firmware Version will send a VER (Firmware Version) message. The next time either of these messages are read they will be logged in the Event Log.
  • Added automatic connection reset when the Plugin loses communication with the AlarmDecoder.
  • Fixed a bug when a zone number is not a numeric in the Keypad Message. This would typically result in an error message Error:invalid literal for int() with base 10:
  • Internal. More changes to the new AlarmDecoder message parsing methods. EXP messages are now parsed using the new methods. Please post in the User forum if there are any new WARNING messages in the Indigo Event Log. Read the release notes from version 3.0.0 for more background.
  • The Plugin forum was moved on July 25th. The About Plugin menu in Indigo now redirects to the new Indigo forum for this plugin.
  • Updated README. Even long time users should (re)read the README to review the changes.
Release details
Released on: July 12, 2022
Requires: Indigo v2022.1.0+
Downloaded: 18 times 
Changes in this release
  • IMPORTANT: Python 3 version. Requires Indigo 2022.1 or later.
  • MORE IMPORTANT: This is a major release. Numerous internal changes were required for Python 3 compatibility. Extensive internal changes were made in this release to facilitate more thorough testing in this and future releases. While this release has been tested more than others, not all code paths have been tested. Please see this section of the README for guidance on how to get assistance and the log file settings and entries that may be needed.
  • Changed "Battery" to "RF Battery" in Trigger System Status Events to distinguish it from the Alarm Panel's Battery
  • Bug fix with Virtual Zones that caused a KeyError after a plugin restart when a Virtual Zone is the first zone to Fault before any standard Alarm Zone.
  • Internal. Added new AlarmDecoder message parsing methods. In this release, these new methods are used to read the CONFIG, VER, and LRR messages, all other AlarmDecoder message types are parsed only for the purpose of logging WARNING messages (not an error) to the log files if the new parsing encounters any messages from your AlarmDecoder that the new parsing method is unable to read. This change and these WARNING messages are in preparation for future plugin compatibility with the latest AlarmDecoder firmware version. Warnings messages will be in the format Unable to parse: REASON - message:MSG where REASON and MSG will be an internal reason and the AlarmDecoder message respectively. Please report any of these warning messages in the User Forum.
  • Long Range Radio (LRR) messages (firmware version V2.2a.6 format) processing changes were made to use new message parsing.
  • Added reading of the AlarmDecoder firmware version and settings on startup using new parsing methods (see below). This change is in preparation for compatibility with the newer AlarmDecoder firmware versions. The firmware version and CONFIG settings of the AlarmDecoder will be logged as INFO messages on startup. If the Plugin is identifies and incompatible version of the firmware version it may not start. Currently, only the firmware version V2.2a.6 is compatible with the Plugin.
  • Updated README documentation.
Release details
Released on: June 2, 2022
Requires: Indigo v7.0.2 thru v2022.2
Downloaded: 38 times 
Changes in this release

This is a maintenance release to fix two bugs with Indigo Managed Virtual Zones. Please read the release notes https://github.com/bla260/ad2usb/blob/main/Release_Notes.md.

Release details
Released on: May 26, 2022
Requires: Indigo v7.0.2 thru v2022.2
Downloaded: 12 times 
Changes in this release

This is a maintenance release that most users on 1.8.0 will want to upgrade to. It includes one bug fix and some logging enhancements. Fixed bug "basicBuildDevDict error" and "advancedBuildDevDict error" which would appear in ERROR log during plugin shutdown or restart. Updated the plugin log file (plugin.log) format to include thread ID for better debugging. Continued updated of the README documentation to eventually make this the complete guide to the plugin. Requires AlarmDecoders' firmware, version 2.2a.6.

Release details
Released on: May 21, 2022
Requires: Indigo v7.0.2 thru v2022.2
Downloaded: 9 times 
Changes in this release

This release is mostly internal changes. Visible changes include how Bypass states are displayed in the client UI and the Trigger selection options for Alarm Device state changes. In preparation of Python 3 all plugin communication to/from the AlarmDecoder have been rewritten. While these change should be transparent they were significant. All panel reads and writes and the plugin Configure Dialog (including the "Read ad2usb Config" button) were revised. Zone Group was refactored to always get a group's device state from Indigo versus a local cache. Alarm Zone Device, Zone Group Device, and Indigo Managed Virtual Zone Device states have been updated.

Release details
Released on: May 11, 2022
Requires: Indigo v7.0.2 thru v2022.2
Downloaded: 19 times 
Changes in this release

Updated to use Indigo's Logging API. New optional alarm panel log file. Minor keypad device and Zone Group bug fixes. Changes in preparedness for Python 3.

Release details
Released on: April 1, 2022
Requires: Indigo v5.0.0 thru v2022.2
Downloaded: 15 times 
Changes in this release

This version has no code changes from 1.6.0. It is being released as the first GitHub based version of the ad2usb plugin.

Release details
Released on: Nov. 29, 2017
Requires: Indigo v5.0.0 thru v2022.2
Changes in this release

Support for bypassed zones. several minor bug fixes