Welcome to Alarm Decoder’s documentation!

This is the API documentation for the Alarm Decoder Python library. It provides support for interacting with the Alarm Decoder (AD2) family of security alarm devices, including the AD2USB, AD2SERIAL and AD2PI.

The source code, requirements and examples for this project may be found here.

Please see the examples directory for more samples, but a basic one is included below:

import time
from alarmdecoder import AlarmDecoder
from alarmdecoder.devices import USBDevice

def main():
    """
    Example application that prints messages from the panel to the terminal.
    """
    try:
        # Retrieve the first USB device
        device = AlarmDecoder(USBDevice.find())

        # Set up an event handler and open the device
        device.on_message += handle_message
        with device.open():
            while True:
                time.sleep(1)

    except Exception, ex:
        print 'Exception:', ex

def handle_message(sender, message):
    """
    Handles message events from the AlarmDecoder.
    """
    print sender, message.raw

if __name__ == '__main__':
    main()

Table of Contents:

alarmdecoder Package

decoder Module

Provides the main AlarmDecoder class.

class alarmdecoder.decoder.AlarmDecoder(device)[source]

Bases: object

High-level wrapper around AlarmDecoder (AD2) devices.

on_arm

This event is called when the panel is armed.

Callback definition: def callback(device)

on_disarm

This event is called when the panel is disarmed.

Callback definition: def callback(device)

on_power_changed

This event is called when panel power switches between AC and DC.

Callback definition: def callback(device, status)

on_alarm

This event is called when the alarm is triggered.

Callback definition: def callback(device, zone)

on_alarm_restored

This event is called when the alarm stops sounding.

Callback definition: def callback(device, zone)

on_fire

This event is called when a fire is detected.

Callback definition: def callback(device, status)

on_bypass

This event is called when a zone is bypassed.

Callback definition: def callback(device, status)

on_boot

This event is called when the device finishes booting.

Callback definition: def callback(device)

on_config_received

This event is called when the device receives its configuration.

Callback definition: def callback(device)

on_zone_fault

This event is called when Zonetracker detects a zone fault.

Callback definition: def callback(device, zone)

on_zone_restore

This event is called when Zonetracker detects that a fault is restored.

Callback definition: def callback(device, zone)

on_low_battery

This event is called when the device detects a low battery.

Callback definition: def callback(device, status)

on_panic

This event is called when the device detects a panic.

Callback definition: def callback(device, status)

on_relay_changed

This event is called when a relay is opened or closed on an expander board.

Callback definition: def callback(device, message)

on_message

This event is called when standard panel Message is received.

Callback definition: def callback(device, message)

on_expander_message

This event is called when an ExpanderMessage is received.

Callback definition: def callback(device, message)

on_lrr_message

This event is called when an LRRMessage is received.

Callback definition: def callback(device, message)

on_rfx_message

This event is called when an RFMessage is received.

Callback definition: def callback(device, message)

on_sending_received

This event is called when a !Sending.done message is received from the AlarmDecoder.

Callback definition: def callback(device, status, message)

on_open

This event is called when the device has been opened.

Callback definition: def callback(device)

on_close

This event is called when the device has been closed.

Callback definition: def callback(device)

on_read

This event is called when a line has been read from the device.

Callback definition: def callback(device, data)

on_write

This event is called when data has been written to the device.

Callback definition: def callback(device, data)

KEY_F1 = u'\x01\x01\x01'

Represents panel function key #1

KEY_F2 = u'\x02\x02\x02'

Represents panel function key #2

KEY_F3 = u'\x03\x03\x03'

Represents panel function key #3

KEY_F4 = u'\x04\x04\x04'

Represents panel function key #4

KEY_PANIC = u'\x05\x05\x05'

Represents a panic keypress

BATTERY_TIMEOUT = 30

Default timeout (in seconds) before the battery status reverts.

FIRE_TIMEOUT = 30

Default tTimeout (in seconds) before the fire status reverts.

address = 18

The keypad address in use by the device.

configbits = 65280

The configuration bits set on the device.

address_mask = 4294967295

The address mask configured on the device.

emulate_zone = [False, False, False, False, False]

List containing the devices zone emulation status.

emulate_relay = [False, False, False, False]

List containing the devices relay emulation status.

emulate_lrr = False

The status of the devices LRR emulation.

deduplicate = False

The status of message deduplication as configured on the device.

mode = 0

The panel mode that the AlarmDecoder is in. Currently supports ADEMCO and DSC.

id

The ID of the AlarmDecoder device.

Returns:identification string for the device
battery_timeout

Retrieves the timeout for restoring the battery status, in seconds.

Returns:battery status timeout
fire_timeout

Retrieves the timeout for restoring the fire status, in seconds.

Returns:fire status timeout
internal_address_mask

Retrieves the address mask used for updating internal status.

Returns:address mask
open(baudrate=None, no_reader_thread=False)[source]

Opens the device.

Parameters:
  • baudrate (int) – baudrate used for the device. Defaults to the lower-level device default.
  • no_reader_thread (bool) – Specifies whether or not the automatic reader thread should be started.
close()[source]

Closes the device.

send(data)[source]

Sends data to the AlarmDecoder device.

Parameters:data (string) – data to send
get_config()[source]

Retrieves the configuration from the device. Called automatically by _on_open().

save_config()[source]

Sets configuration entries on the device.

reboot()[source]

Reboots the device.

fault_zone(zone, simulate_wire_problem=False)[source]

Faults a zone if we are emulating a zone expander.

Parameters:
  • zone (int) – zone to fault
  • simulate_wire_problem (bool) – Whether or not to simulate a wire fault
clear_zone(zone)[source]

Clears a zone if we are emulating a zone expander.

Parameters:zone (int) – zone to clear

devices Module

This module contains different types of devices belonging to the AlarmDecoder (AD2) family.

class alarmdecoder.devices.SSL(Error, WantReadError, SysCallError)

Bases: tuple

Error

Alias for field number 0

SysCallError

Alias for field number 2

WantReadError

Alias for field number 1

class alarmdecoder.devices.Device[source]

Bases: object

Base class for all AlarmDecoder (AD2) device types.

on_open

This event is called when the device has been opened.

Callback definition: def callback(device)

on_close

This event is called when the device has been closed.

Callback definition: def callback(device)*

on_read

This event is called when a line has been read from the device.

Callback definition: def callback(device, data)*

on_write

This event is called when data has been written to the device.

Callback definition: def callback(device, data)*

id

Retrieve the device ID.

Returns:identification string for the device
is_reader_alive()[source]

Indicates whether or not the reader thread is alive.

Returns:whether or not the reader thread is alive
stop_reader()[source]

Stops the reader thread.

close()[source]

Closes the device.

class ReadThread(device)[source]

Bases: threading.Thread

Reader thread which processes messages from the device.

READ_TIMEOUT = 10

Timeout for the reader thread.

stop()[source]

Stops the running thread.

run()[source]

The actual read process.

class alarmdecoder.devices.USBDevice(interface=0, vid=None, pid=None)[source]

Bases: alarmdecoder.devices.Device

AD2USB device utilizing PyFTDI’s interface.

PRODUCT_IDS = ((1027, 24577), (1027, 24597))

List of Vendor and Product IDs used to recognize AD2USB devices.

DEFAULT_VENDOR_ID = 1027

Default Vendor ID used to recognize AD2USB devices.

DEFAULT_PRODUCT_ID = 24577

Default Product ID used to recognize AD2USB devices.

FTDI_VENDOR_ID = 1027

DEPRECATED: Vendor ID used to recognize AD2USB devices.

FTDI_PRODUCT_ID = 24577

DEPRECATED: Product ID used to recognize AD2USB devices.

BAUDRATE = 115200

Default baudrate for AD2USB devices.

classmethod find_all(vid=None, pid=None)[source]

Returns all FTDI devices matching our vendor and product IDs.

Returns:list of devices
Raises:CommError
classmethod devices()[source]

Returns a cached list of AD2USB devices located on the system.

Returns:cached list of devices found
classmethod find(device=None)[source]

Factory method that returns the requested USBDevice device, or the first device.

Parameters:device (tuple) – Tuple describing the USB device to open, as returned by find_all().
Returns:USBDevice object utilizing the specified device
Raises:NoDeviceError
classmethod start_detection(on_attached=None, on_detached=None)[source]

Starts the device detection thread.

Parameters:
  • on_attached (function) – function to be called when a device is attached Callback definition: def callback(thread, device)
  • on_detached (function) – function to be called when a device is detached Callback definition: def callback(thread, device)
classmethod stop_detection()[source]

Stops the device detection thread.

serial_number

Retrieves the serial number of the device.

Returns:serial number of the device
description

Retrieves the description of the device.

Returns:description of the device
interface

Retrieves the interface used to connect to the device.

Returns:the interface used to connect to the device
open(baudrate=115200, no_reader_thread=False)[source]

Opens the device.

Parameters:
  • baudrate (int) – baudrate to use
  • no_reader_thread (bool) – whether or not to automatically start the reader thread.
Raises:

NoDeviceError

close()[source]

Closes the device.

fileno()[source]
write(data)[source]

Writes data to the device.

Parameters:data (string) – data to write
Raises:CommError
read()[source]

Reads a single character from the device.

Returns:character read from the device
Raises:CommError
read_line(timeout=0.0, purge_buffer=False)[source]

Reads a line from the device.

Parameters:
  • timeout (float) – read timeout
  • purge_buffer (bool) – Indicates whether to purge the buffer prior to reading.
Returns:

line that was read

Raises:

CommError, TimeoutError

class DetectThread(on_attached=None, on_detached=None)[source]

Bases: threading.Thread

Thread that handles detection of added/removed devices.

on_attached

This event is called when an AD2USB device has been detected.

Callback definition: def callback(thread, device*

on_detached

This event is called when an AD2USB device has been removed.

Callback definition: def callback(thread, device*

stop()[source]

Stops the thread.

run()[source]

The actual detection process.

class alarmdecoder.devices.SerialDevice(interface=None)[source]

Bases: alarmdecoder.devices.Device

AD2USB, AD2SERIAL or AD2PI device utilizing the PySerial interface.

BAUDRATE = 19200

Default baudrate for Serial devices.

static find_all(pattern=None)[source]

Returns all serial ports present.

Parameters:pattern (string) – pattern to search for when retrieving serial ports
Returns:list of devices
Raises:CommError
interface

Retrieves the interface used to connect to the device.

Returns:interface used to connect to the device
open(baudrate=19200, no_reader_thread=False)[source]

Opens the device.

Parameters:
  • baudrate (int) – baudrate to use with the device
  • no_reader_thread (bool) – whether or not to automatically start the reader thread.
Raises:

NoDeviceError

close()[source]

Closes the device.

fileno()[source]
write(data)[source]

Writes data to the device.

Parameters:data (string) – data to write
Raises:py:class:~alarmdecoder.util.CommError
read()[source]

Reads a single character from the device.

Returns:character read from the device
Raises:CommError
read_line(timeout=0.0, purge_buffer=False)[source]

Reads a line from the device.

Parameters:
  • timeout (float) – read timeout
  • purge_buffer (bool) – Indicates whether to purge the buffer prior to reading.
Returns:

line that was read

Raises:

CommError, TimeoutError

class alarmdecoder.devices.SocketDevice(interface=('localhost', 10000))[source]

Bases: alarmdecoder.devices.Device

Device that supports communication with an AlarmDecoder (AD2) that is exposed via ser2sock or another Serial to IP interface.

interface

Retrieves the interface used to connect to the device.

Returns:interface used to connect to the device
ssl

Retrieves whether or not the device is using SSL.

Returns:whether or not the device is using SSL
ssl_certificate

Retrieves the SSL client certificate path used for authentication.

Returns:path to the certificate path or OpenSSL.crypto.X509
ssl_key

Retrieves the SSL client certificate key used for authentication.

Returns:jpath to the SSL key or OpenSSL.crypto.PKey
ssl_ca

Retrieves the SSL Certificate Authority certificate used for authentication.

Returns:path to the CA certificate or OpenSSL.crypto.X509
open(baudrate=None, no_reader_thread=False)[source]

Opens the device.

Parameters:
  • baudrate (int) – baudrate to use
  • no_reader_thread (bool) – whether or not to automatically open the reader thread.
Raises:

NoDeviceError, CommError

close()[source]

Closes the device.

fileno()[source]
write(data)[source]

Writes data to the device.

Parameters:data (string) – data to write
Returns:number of bytes sent
Raises:CommError
read()[source]

Reads a single character from the device.

Returns:character read from the device
Raises:CommError
read_line(timeout=0.0, purge_buffer=False)[source]

Reads a line from the device.

Parameters:
  • timeout (float) – read timeout
  • purge_buffer (bool) – Indicates whether to purge the buffer prior to reading.
Returns:

line that was read

Raises:

CommError, TimeoutError

messages Module

Message representations received from the panel through the AlarmDecoder (AD2) devices.

  • Message: The standard and most common message received from a panel.
  • ExpanderMessage: Messages received from Relay or Zone expander modules.
  • RFMessage: Message received from an RF receiver module.
  • LRRMessage: Message received from a long-range radio module.
class alarmdecoder.messages.BaseMessage[source]

Bases: object

Base class for messages.

raw = None

The raw message text

timestamp = None

The timestamp of the message

dict(**kwargs)[source]

Dictionary representation.

class alarmdecoder.messages.Message(data=None)[source]

Bases: alarmdecoder.messages.BaseMessage

Represents a message from the alarm panel.

ready = False

Indicates whether or not the panel is in a ready state.

armed_away = False

Indicates whether or not the panel is armed away.

armed_home = False

Indicates whether or not the panel is armed home.

backlight_on = False

Indicates whether or not the keypad backlight is on.

programming_mode = False

Indicates whether or not we’re in programming mode.

beeps = -1

Number of beeps associated with a message.

zone_bypassed = False

Indicates whether or not a zone is bypassed.

ac_power = False

Indicates whether or not the panel is on AC power.

chime_on = False

Indicates whether or not the chime is enabled.

alarm_event_occurred = False

Indicates whether or not an alarm event has occurred.

alarm_sounding = False

Indicates whether or not an alarm is sounding.

battery_low = False

Indicates whether or not there is a low battery.

entry_delay_off = False

Indicates whether or not the entry delay is enabled.

fire_alarm = False

Indicates whether or not a fire alarm is sounding.

check_zone = False

Indicates whether or not there are zones that require attention.

perimeter_only = False

Indicates whether or not the perimeter is armed.

system_fault = False

Indicates whether a system fault has occurred.

panel_type = 0

Indicates which panel type was the source of this message.

numeric_code = None

The numeric code associated with the message.

text = None

The human-readable text to be displayed on the panel LCD.

cursor_location = -1

Current cursor location on the keypad.

mask = 4294967295

Address mask this message is intended for.

bitfield = None

The bitfield associated with this message.

panel_data = None

The panel data field associated with this message.

dict(**kwargs)[source]

Dictionary representation.

class alarmdecoder.messages.ExpanderMessage(data=None)[source]

Bases: alarmdecoder.messages.BaseMessage

Represents a message from a zone or relay expansion module.

ZONE = 0

Flag indicating that the expander message relates to a Zone Expander.

RELAY = 1

Flag indicating that the expander message relates to a Relay Expander.

type = None

Expander message type: ExpanderMessage.ZONE or ExpanderMessage.RELAY

address = -1

Address of expander

channel = -1

Channel on the expander

value = -1

Value associated with the message

dict(**kwargs)[source]

Dictionary representation.

class alarmdecoder.messages.RFMessage(data=None)[source]

Bases: alarmdecoder.messages.BaseMessage

Represents a message from an RF receiver.

serial_number = None

Serial number of the RF device.

value = -1

Value associated with this message.

battery = False

Low battery indication

supervision = False

Supervision required indication

loop = [False, False, False, False]

Loop indicators

dict(**kwargs)[source]

Dictionary representation.

class alarmdecoder.messages.LRRMessage(data=None)[source]

Bases: alarmdecoder.messages.BaseMessage

Represent a message from a Long Range Radio.

event_data = None

Data associated with the LRR message. Usually user ID or zone.

partition = -1

The partition that this message applies to.

event_type = None

The type of the event that occurred.

dict(**kwargs)[source]

Dictionary representation.

zonetracking Module

Provides zone tracking functionality for the AlarmDecoder (AD2) device family.

class alarmdecoder.zonetracking.Zone(zone=0, name='', status=0, expander=False)[source]

Bases: object

Representation of a panel zone.

CLEAR = 0

Status indicating that the zone is cleared.

FAULT = 1

Status indicating that the zone is faulted.

CHECK = 2

Status indicating that there is a wiring issue with the zone.

STATUS = {0: 'CLEAR', 1: 'FAULT', 2: 'CHECK'}
zone = 0

Zone ID

name = ''

Zone name

status = 0

Zone status

timestamp = None

Timestamp of last update

expander = False

Does this zone exist on an expander?

class alarmdecoder.zonetracking.Zonetracker(alarmdecoder_object)[source]

Bases: object

Handles tracking of zones and their statuses.

on_fault

This event is called when the device detects a zone fault.

Callback definition: def callback(device, zone)

on_restore

This event is called when the device detects that a fault is restored.

Callback definition: def callback(device, zone)

EXPIRE = 30

Zone expiration timeout.

zones

Returns the current list of zones being tracked.

Returns:dictionary of Zone being tracked
faulted

Retrieves the current list of faulted zones.

Returns:list of faulted zones
update(message)[source]

Update zone statuses based on the current message.

Parameters:message (Message or ExpanderMessage) – message to use to update the zone tracking
expander_to_zone(address, channel, panel_type=0)[source]

Convert an address and channel into a zone number.

Parameters:
  • address (int) – expander address
  • channel (int) – channel
Returns:

zone number associated with an address and channel

util Module

Provides utility classes for the AlarmDecoder (AD2) devices.

exception alarmdecoder.util.NoDeviceError[source]

Bases: exceptions.Exception

No devices found.

exception alarmdecoder.util.CommError[source]

Bases: exceptions.Exception

There was an error communicating with the device.

exception alarmdecoder.util.TimeoutError[source]

Bases: exceptions.Exception

There was a timeout while trying to communicate with the device.

exception alarmdecoder.util.InvalidMessageError[source]

Bases: exceptions.Exception

The format of the panel message was invalid.

class alarmdecoder.util.Firmware[source]

Bases: object

Represents firmware for the AlarmDecoder devices.

STAGE_START = 0
STAGE_WAITING = 1
STAGE_BOOT = 2
STAGE_LOAD = 3
STAGE_UPLOADING = 4
STAGE_DONE = 5
static upload(dev, filename, progress_callback=None)[source]

Uploads firmware to an AlarmDecoder device.

Parameters:
  • filename (string) – firmware filename
  • progress_callback (function) – callback function used to report progress
Raises:

NoDeviceError, TimeoutError

panels Module

Representations of Panels and their templates.

Indices and tables