= Introduction = [[Image(ParadoxAlarm-Keypad.jpg, align=right)]] The Paradox Alarm plugin is a [http://wiki.micasaverde.com/index.php/Luup_Plugins Luup component] that connects Vera to a Paradox Security Alarm panel (Digiplex DGP-848, EVO or Spectra series) via their Home Automation interface (Paradox PRT3) over USB. Through this interface, events occurring within the Alarm Panel are exposed to Vera including the status of any attached Doors, Windows, Motion Sensors. Each of these is exposed as a ''Motion Sensor'' to Vera, so that standard [http://wiki.micasaverde.com/index.php/Scenes Scenes] (Lights, Notifications, etc) can be established in Vera based upon events occurring within the Alarm Panel. Additionally, the interface exposes the current Armed State, Stay Armed State and whether the Alarm is in Breach. These are also exposed in a ''Scene-aware'' manner so that Vera can respond to them. This plugin works on Vera versions 1.0.9xx. '''WARNING: This plugin ''will not'' work with the 1.1.x versions of Vera's firmware. Once that version has stabilized, I'll move my Vera up and sort out the issues.''' = How does it work = [[Image(ParadoxAlarm-DevicesView.png, align=right, 30%)]] The Paradox Alarm Panel uses a proprietary interface bus, called Combus, to talk to the devices connected to it. The PRT3 Printer Module is a Combus device that acts as a bridge between the Alarm Panel, and a standard USB (or RS-232) device. In addition, it provides a Printer connector for Raw status updates. The PRT3 interface can be configured to expose a set of low-level Alarm Panel messages, via either of it's Serial ports, to a Home Automation device. Similarly, these low-level messages can be sent from the Home Automation device back to the Paradox Alarm Panel to perform various actions. The PRT3 Printer module comes with instructions on how to "wire" it to the Alarm Panel, via it's 4-wire Combus interface, and the subsequent Alarm Panel configuration to get it recognized. == Terminology == Zone:: a specific sensor in the Alarm Panel, such as a Window, Door or Motion Sensor. These may either be hardwired, or wireless, depending upon the type of sensor. Area/Partition:: a collection of Zones. Typically there is a single Area in a house. Larger houses are often split into separate Areas (Upstairs vs Downstairs). External buildings such as Garages and Guest houses are also candidates for additional Areas. Combus:: Paradox Security proprietary prototol. This protocol is used for communications between Paradox System components, such as the Printer Module, Zone Expanders, specialized Motion Sensors and the System Keypads. Remote control:: a Key chain remote control device, used to Arm (Lock), Disarm (Unlock) or set a Panic Alarm Entry Door:: a Zone (door) with a grace period delay attached to it. The Alarm will not go off during the grace period. Breach:: the Alarm is currently going off, either with a Bell, or a Silent Alarm. Arm:: the act of setting the Alarm Panel into the "I'm leaving" state. Stay Arm:: the act of setting the Alarm Panel into the "I'm staying" state. In this state the Motion Sensors don't trip Alarm Breach. Force Arm:: same as ''Arm'' except that some Zones may be left Open Instant Arm:: same as ''Stay Arm'' except there is no grace period on opening an Entry Door. Virtual PGM:: a special type of Zone defined within the Alarm Panel. The Alarm Panel can be configured to establish the conditions under which a Virtual PGM [Zone] is triggered and/or reset. Virtual PGMs events are supported in the code, but are disabled by default to make the UI simpler. One Touch or Quick Arming:: a variant on the Arming modes that typically doesn't require a PIN Code to be entered to initiate the Arming request. == Messages == Depending upon the specific model of Alarm Panel, there will be support for different numbers of Zones, and Areas. At startup of the Paradox Alarm Plugin, messages are exchanged with the Alarm Panel itself to understand how many Zones and Areas are in the Panel, the Labels for these, and the "current" state for any Zone. These low-level messages are varied, but include: * Retrieve a Zone Label * Retrieve a User Label * Retrieve a Area Label * Read the status of a Zone (open/closed) * Read the status of an Area (armed/force-armed, stay-armed/instant-armed, alerting/breach) * Zone status change events * Area status change events * Request Arming/Force-Arming * Request Stay-Arming/Instant-Arming * Trigger Alerting/Breach * Remote control and Voice Activation events == The Paradox Alarm Plugin processing == === Startup processing === The Startup processing for the Alarm Panel plugin looks roughly like: * determine the number of Areas in the System, and their Labels * Child devices created per Area found *''Area '' * determine the number of Zones in the System, and their Labels * create a Child device per Zone found using the Label read from the Alarm Panel * determine the number of Users in the System, and their associated Labels (**for future use) * retrieve the current state of each Area, and "set" it into Vera * retrieve the current state of each Zone, and "set" it into Vera Notes: * During startup processing, "out of band" events received are skipped. This can happen, for example, if someone triggers a motion sensor event as Vera is starting up the plugin during a Vera reboot. * To reduce the number of Zones created, the Plugin will look for "Empty" or "Default" Labels. An Empty/Default Label on a Zone indicates that we'll skip over it. If you want a Zone to be mapped to a !MotionSensor Device then it must have a non-empty, non-default label. This was done to avoid having up to 48, 96 or 192 "unused" !MotionSensor events in Vera. * Zone-based !MotionSensor Devices are created without the [http://wiki.micasaverde.com/index.php/Luup_Lua_extensions#function:_append embedded] flag, so they can be placed in Rooms. These devices are still Parented to the Alarm Panel Device, but can be placed in any Room defined by Vera. The downside of this is that immediately after the installation of the Plugin, all Zones ''must'' be placed into a Room, as defined by the Vera UI. === Event processing === After startup, the system is set running. It receives events and, for those of interest, it translates them into !MotionSensor values to set upon it's Child Devices, in addition to setting Variables directly on the Alarm Area device ==== Alarm Area Scene Events ==== The Alarm Device creates one "Area" child device per Alarm Partition/Area managed by the Alarm Panel. This "Area" child device is used to create Scene behaviors for the Alarm Panel. During Scene creation, the following ''Events'' are exposed by each "Area" device: * ''Partition is Armed'' * ''Partition is Stay Armed'' * ''Partition is Breached'' * ''Partition is Disarmed'' During Advanced Scene creation, the following ''Actions'' are exposed by each "Area" device: * ''!RequestArm'' - Submit a request to Arm the Alarm Partition (with PINCode) * ''!RequestQuickArm'' - Submit a request to Quick, or "!OneTouch", Arm the Alarm Partition (no PINCode required) * ''!RequestStay'' - Submit a request to Stay-Arm the Alarm Partition (with PINCode) * ''!RequestQuickStay'' - Submit a request to Quick, or "!OneTouch", Stay-Arm the Alarm Partition (no PINCode required) * ''!RequestDisarm'' - Submit a request to Disarm the Alarm Partition (PINCode required) * ''!SetVirtualInput'' - Set one of the ![16] Virtual Inputs on the Alarm Panel to Open (0) or Closed (1) NOTE: The Alarm plugin code disables these Actions by default. They must be enabled prior to using them in a Scene definition. ==== Alarm Area Variables ==== This Alarm Panel implements a !DeviceType that gives it the following Variables (through it's !ServiceStateTable). These can be used for Luup scripting: * ''Area '' * ''Disarmed'' - Set whenever the Alarm Area is Disarmed (not Armed and not !StayArmed) * ''Armed'' - Set when the user requests the Alarm Area to Arm, Force Arm, Stay Arm or Instant Arm the Area * ''!StayArmed'' - Set when the user request the Alarm Area to Stay Arm or Instant Arm the Area * ''Breach'' - set when the Alarm Area is in Breach (Siren, Silent etc) ==== Legacy Motion Sensor Values ==== These will eventually be obsoleted: * ''Communication'' !MotionSensor in Vera is set when the Printer Module has difficulty communicating with the Alarm Panel, or the internal buffers are full. NOTE: This version of the Luup Plugin doesn't support remotely Arming, or Disarming, of the Alarm Panel. The underlying Message protocol supports this. === Example event messages === * `G009N001A001` - Arming with Master code, Area 1 * `G013N001A001` - Disarming with Master code, Area 1 * `G004N007A000` - Remote control access, Key 0 * `G004N003A001` - Arm with Stay mode, Area 1 * `G001N015A001` - Zone 15 is Open (Motion), Area 1 * `G000N015A001` - Zone 15 is OK (No motion), Area 1 = Installation = == Hardware Installation == The following section assumes you have a working Paradox Alarm Panel and have successfully connected, and configured, the Paradox Security PTR3 Printer Module. Each of these devices comes with instructions for wiring and basic configuration. If you are not comfortable with this type of Wiring and configuration then contact your Alarm installer ''before'' proceeding. Notes * Configure the PTR3 Module Baud Rate In Paradox EVO Alarm Panels this is Section `[016]` and in Spectra Alarm Panels this is Section `[553]` of the Alarm Panel configuration. The Baud Settings should be configured to `57600` Baud by setting both Options `[2] & [3]` to `[ON]`. You can use a lower Baud rate, but it will slow the communications between Vera and the Alarm Panel. * Configure the PTR3 Module for Home Automation In Paradox EVO Alarm Panels, this is Section `[016]`, Option `[4]`. It should be set to `[ON]` * Set any Zone Labels '''after''' you connect the PRT3 Module to the Combus Only Zone Labels changed/modified ''after'' PRT3 is attached will be correctly recorded in the PRT3 Module. If you set the Zone Labels prior to connecting the PRT3, it'll only list "Default" Labels for each Zone. The Vera-Luup Alarm interface code will skip over these as if they're ''unused'' Zones. Please use the Alarm Panel's Reference and Installation manuals to determine how to setup your Zone Labels. If you've attached the PRT3 Module to an existing Alarm Panel, you can simply re-enter the Zone Labels to "trigger" it to get a copy of them. * Attach Vera to the Paradox PRT3 Module using a USB Cable After attaching Vera to the Paradox PRT3 Module, navigate to the following pane in Vera: ''Devices'' >> ''Luup Plugins'' >> ''Serial Port configuration'' which should show settings similar to these [[Image(ParadoxAlarm-VeraSerialConfig.png, align=right, 30%)]] You can now change the Baud rate to `57600`, matching the Alarm Panel, and press '''(Save)'''. == Software Installation == === Initial Configuration === 1. Download the ZIP file `[http://www.box.net/shared/7z73h1mj6t ParadoxSecurity.1.1.zip]` 1. Expand the ZIP File to extract the 4x files, their names should be exactly as follows: * `D_AlarmPartition1.xml` * `D_ParadoxSecurityEVO.xml` * `I_ParadoxSecurityEVO.xml` * `S_AlarmPartition1.xml` 1. Goto ''Devices'' --> ''Luup plugins'' --> ''Luup files'' 1. Click the '''(Browse)''' buttons on the right, and enter the 4 filenames references above. 1. Select the checkbox "''[x] Restart Luup after upload''" and click '''(Go)''' 1. ... wait whilst it uploads and restarts the Lua engine ... 1. If successful, you'll see the 4x files listed in the System. 1. Navigate to ''Devices'', scroll to the bottom at the ''Add device'' form. 1. Type "`D_ParadoxSecurityEVO.xml`", and click '''(Add Device)''', type in a name, such as ''Paradox Alarm Panel'' against the device then click '''(Save)'''. 1. For the lines that follow, we'll assume that you named the device ''Paradox Alarm Panel'' but you can call it anything. 1. Goto ''Devices'' --> ''Luup plugins'' --> '''''(Serial Port configuration)''''' 1. Select the ''Paradox Alarm Panel [...]'' value for the ''Used by device:'' picklist then click '''(Save)'''. The Alarm Panel Plugin code will now read configuration data from the Alarm Panel, such as the number of Areas, Zones and Users. Once complete, Vera will present you with Vera's ''Unassigned Devices UI'', letting you Assign the Alarm Panel's Zones to [http://wiki.micasaverde.com/index.php/Rooms Rooms] within Vera. Here's a copy of Vera's ''Generic'' Unassigned Devices UI for reference: [[Image(UnnasignedDevices1.jpg, align=right, 30%)]] === Validating the Configuration === This section ''not'' intentionally left blank, it's just not finished yet :) === Advanced Configuration === There are a number of advanced options that can be setup after performing the initial configuration, and validating it's working correctly. These are exposed through Variables listed under: ''Devices'' --> ''Luup plugins'' --> ''Your Alarm Panel Device'' -> ''(+)'' [[Image(ParadoxAlarm-DevicesViewAdvanced.png, align=right, 30%)]] `maxAlarmZones` (number, ''default'' `24`):: The number of Zones that the Alarm Panel Plugin should scan during startup. Depending upon the Alarm panel model, it can support 48, 96, or 192 Zones. Each takes some time to scan. To speed startup, set this parameter to the number of Zones installed within your particular System. `maxAlarmPartitions` (number, ''default'' `1`):: The number of Areas/Partitions that the Alarm Panel Plugin should scan during startup. The Alarm Panel typically supports 4 or more Areas/Partitions but most houses use only one, or maybe 2, of these Partitions. The Alarm Panel Plugin defaults to loading 1 Partition. This parameter may be used to increase the number of Partitions configured into Vera if you have more in your installation. `maxUserCodes` (number, ''default'' `5`):: The number of User codes registered with the Alarm Panel. The Alarm Panel may support 96, 192 or more Users and reducing this parameter decreases the startup time of the Plugin. At this time, only logging messages use the User strings but future functionality may permit ''Scene'' events based upon User descriptions retrieved by this parameter. `enableVirtualInputs` (boolean, ''default'' `false`):: Enable the Alarm Panel's Virtual Inputs to be represented within Vera's UI. Intended for people that use the Paradox Alarm Panel Virtual input functionality. `maxVirtualInputs` (number, ''default'' `5`, if `enableVirtualInputs` is set):: If `enableVirtualInputs` is set, this parameter determines how many Virtual Inputs need to be established within Vera (up to the Max# of Virtual inputs of the Paradox Alarm Panel) `enableRemoteArm` (string, ''default'' `false`):: Enable the use of ''Stay Arm'' (`stay`), ''Stay'' and ''Regular Arm'' (`arm`) or ''Stay'', ''Regular'' and ''Disarm'' (`disarm`) functionality within the Plugin. {{{ #!html CAUTION: Use of the enableRemoteArm parameter may constitute a Security risk. Use at your own risk. }}} = Scenes = The Plugin supports participation in Scenes, by generating Events and accepting/processing Actions. == Events == Each Alarm Partition is exposed as a !AlarmPartition1, and has the following scene capabilities [[Image(ParadoxAlarm-ScenesPartition.png, align=right, 30%)]]Example Alarm Partition Scene * ''Partition is Armed'' * ''Partition is Stay-Armed'' * ''Partition is Breached'' * ''Partition is Disarmed'' Each Alarm Zone is exposed a standard !MotionSensor1, and has the following standard Motion Sensor scene capabilities [[Image(ParadoxAlarm-ScenesZone.png, align=right, 30%)]]Example Alarm Zone Scene * ''A sensor (door/window/motion/etc.) is tripped'' == Actions == Each Alarm Partition is exposed as a !AlarmPartition1, and has the following Actions (if Enabled) [[Image(ParadoxAlarm-ScenesAction.png, align=right, 30%)]]Example Alarm Partition Action * ''!RequestArm'' - Submit a request to Arm the Alarm Partition (with PINCode) * ''!RequestQuickArm'' - Submit a request to Quick, or "!OneTouch", Arm the Alarm Partition (no PINCode required) * ''!RequestStay'' - Submit a request to Stay-Arm the Alarm Partition (with PINCode) * ''!RequestQuickStay'' - Submit a request to Quick, or "!OneTouch", Stay-Arm the Alarm Partition (no PINCode required) * ''!RequestDisarm'' - Submit a request to Disarm the Alarm Partition (PINCode required) * ''!SetVirtualInput'' - Set one of the ![16] Virtual Inputs on the Alarm Panel to Open (0) or Closed (1) = Scripting = ... some Luup scripting please... = Errors = The Paradox Alarm Plugin unconditionally logs all Alarm Panel events in Vera's log file. These events have been translated into their English equivalent from the internal codes that the Alarm Panel uses. Examples include: {{{ #!html 01 ... luup_log:nn: 001:Zone is Open, 015:Motion Upstairs (Zone 15), 001:Area 1
01 ... luup_log:nn: 000:Zone is OK, 015:Motion Upstairs (Zone 15), 001:Area 1
01 ... luup_log:nn: 014:Disarm with User Code, 002:User Code 2, 001:Area 1
01 ... luup_log:nn: 064:Status 1, 000:Armed, 001:Area 1
01 ... luup_log:nn: 009:Arming with Master, 001:User Code 1, 001:Area 1
01 ... luup_log:nn: 004:Non-reportable Event, 007:Remote control access, 000:Occurs in all areas enabled in the system
 }}} = Discussion = In no particular order... * http://forum.micasaverde.com/index.php?topic=2492.0 * http://forum.micasaverde.com/index.php?topic=2134.0 = References = * Paradox Security Systems [http://www.paradox.com/Products/default.asp?PID=184 EVO48/192 Alarm Panel] * Paradox Security Systems [http://www.paradox.com/Products/default.asp?PID=218 PRT3 Printer Module] * Paradox Security Systems [http://www.paradox.com/Products/default.asp?PID=189 K641 Blue Keypad Module] * Paradox Security Systems [http://paradox.com/Products/default.asp?CATID=7&SUBCATID=71&PRD=281 ZX8 8-Zone Expansion Module] * Paradox Security Systems [http://paradox.com/Products/default.asp?CATID=7&SUBCATID=71&PRD=252 MAGELLAN Wireless Expansion Module] * Paradox Security Systems [http://paradox.com/Products/default.asp?CATID=4&SUBCATID=44&PRD=248 MAGELLAN Remote Control with Backlit Buttons] * Paradox Security Systems Digiplex Control Panel (DGP-848) Reference and Installation Manual * Paradox Security Systems APR-PRT3 Installation Manual (PDF) * Paradox Security Systems APR-PRT3 Printer Module: ASCII Protocol Programming Instructions (PDF) * [http://www.lua.org/manual/5.1 Lua 5.1 Reference Manual] * [http://lua-users.org/wiki/LuaTutorial Lua-users Lua Tutorial] * Paradox Expansion Module Mounting Plate for On-Q Legrand Structured Wiring closet (PN: 364638-01)