Documentation updates.

alarmdecoder/decoder.py

@@ -20,30 +20,30 @@ class AlarmDecoder(object):
     """
 
     # High-level Events
-    on_arm = event.Event('This event is called when the panel is armed.')
-    on_disarm = event.Event('This event is called when the panel is disarmed.')
-    on_power_changed = event.Event('This event is called when panel power switches between AC and DC.')
-    on_alarm = event.Event('This event is called when the alarm is triggered.')
-    on_fire = event.Event('This event is called when a fire is detected.')
-    on_bypass = event.Event('This event is called when a zone is bypassed.')
-    on_boot = event.Event('This event is called when the device finishes booting.')
-    on_config_received = event.Event('This event is called when the device receives its configuration.')
-    on_zone_fault = event.Event('This event is called when :py:class:`alarmdecoder.zonetracking.Zonetracker` detects a zone fault.')
-    on_zone_restore = event.Event('This event is called when :py:class:`alarmdecoder.zonetracking.Zonetracker` detects that a fault is restored.')
-    on_low_battery = event.Event('This event is called when the device detects a low battery.')
-    on_panic = event.Event('This event is called when the device detects a panic.')
-    on_relay_changed = event.Event('This event is called when a relay is opened or closed on an expander board.')
+    on_arm = event.Event("This event is called when the panel is armed.\n\n**Callback definition:** *def callback(device)*")
+    on_disarm = event.Event("This event is called when the panel is disarmed.\n\n**Callback definition:** *def callback(device)*")
+    on_power_changed = event.Event("This event is called when panel power switches between AC and DC.\n\n**Callback definition:** *def callback(device, status)*")
+    on_alarm = event.Event("This event is called when the alarm is triggered.\n\n**Callback definition:** *def callback(device, status)*")
+    on_fire = event.Event("This event is called when a fire is detected.\n\n**Callback definition:** *def callback(device, status)*")
+    on_bypass = event.Event("This event is called when a zone is bypassed.  \n\n\n\n**Callback definition:** *def callback(device, status)*")
+    on_boot = event.Event("This event is called when the device finishes booting.\n\n**Callback definition:** *def callback(device)*")
+    on_config_received = event.Event("This event is called when the device receives its configuration. \n\n**Callback definition:** *def callback(device)*")
+    on_zone_fault = event.Event("This event is called when :py:class:`~alarmdecoder.zonetracking.Zonetracker` detects a zone fault.\n\n**Callback definition:** *def callback(device, zone)*")
+    on_zone_restore = event.Event("This event is called when :py:class:`~alarmdecoder.zonetracking.Zonetracker` detects that a fault is restored.\n\n**Callback definition:** *def callback(device, zone)*")
+    on_low_battery = event.Event("This event is called when the device detects a low battery.\n\n**Callback definition:** *def callback(device, status)*")
+    on_panic = event.Event("This event is called when the device detects a panic.\n\n**Callback definition:** *def callback(device, status)*")
+    on_relay_changed = event.Event("This event is called when a relay is opened or closed on an expander board.\n\n**Callback definition:** *def callback(device, message)*")
 
     # Mid-level Events
-    on_message = event.Event('This event is called when any message is received.')
-    on_lrr_message = event.Event('This event is called when an :py:class:`alarmdecoder.messages.LRRMessage` is received.')
-    on_rfx_message = event.Event('This event is called when an :py:class:`alarmdecoder.messages.RFMessage` is received.')
+    on_message = event.Event("This event is called when any message is received.\n\n**Callback definition:** *def callback(device, message)*")
+    on_lrr_message = event.Event("This event is called when an :py:class:`~alarmdecoder.messages.LRRMessage` is received.\n\n**Callback definition:** *def callback(device, message)*")
+    on_rfx_message = event.Event("This event is called when an :py:class:`~alarmdecoder.messages.RFMessage` is received.\n\n**Callback definition:** *def callback(device, message)*")
 
     # Low-level Events
-    on_open = event.Event('This event is called when the device has been opened.')
-    on_close = event.Event('This event is called when the device has been closed.')
-    on_read = event.Event('This event is called when a line has been read from the device.')
-    on_write = event.Event('This event is called when data has been written to the device.')
+    on_open = event.Event("This event is called when the device has been opened.\n\n**Callback definition:** *def callback(device)*")
+    on_close = event.Event("This event is called when the device has been closed.\n\n**Callback definition:** *def callback(device)*")
+    on_read = event.Event("This event is called when a line has been read from the device.\n\n**Callback definition:** *def callback(device, data)*")
+    on_write = event.Event("This event is called when data has been written to the device.\n\n**Callback definition:** *def callback(device, data)*")
 
     # Constants
     KEY_F1 = unichr(1) + unichr(1) + unichr(1)
@@ -291,7 +291,7 @@ class AlarmDecoder(object):
         :param data: panel data to parse
         :type data: string
 
-        :returns: :py:class:`alarmdecoder.messages.Message`
+        :returns: :py:class:`~alarmdecoder.messages.Message`
         """
         if data is None:
             raise InvalidMessageError()
@@ -331,7 +331,7 @@ class AlarmDecoder(object):
         :param data: RF message to parse
         :type data: string
 
-        :returns: :py:class:`alarmdecoder.messages.RFMessage`
+        :returns: :py:class:`~alarmdecoder.messages.RFMessage`
         """
         msg = RFMessage(data)
 
@@ -346,7 +346,7 @@ class AlarmDecoder(object):
         :param data: LRR message to parse
         :type data: string
 
-        :returns: :py:class:`alarmdecoder.messages.LRRMessage`
+        :returns: :py:class:`~alarmdecoder.messages.LRRMessage`
         """
         msg = LRRMessage(data)
 
@@ -395,8 +395,8 @@ class AlarmDecoder(object):
         """
         Updates internal device states.
 
-        :param message: :py:class:`alarmdecoder.messages.Message` to update internal states with
-        :type message: :py:class:`alarmdecoder.messages.Message`, :py:class:`alarmdecoder.messages.ExpanderMessage`, :py:class:`alarmdecoder.messages.LRRMessage`, or :py:class:`alarmdecoder.messages.RFMessage`
+        :param message: :py:class:`~alarmdecoder.messages.Message` to update internal states with
+        :type message: :py:class:`~alarmdecoder.messages.Message`, :py:class:`~alarmdecoder.messages.ExpanderMessage`, :py:class:`~alarmdecoder.messages.LRRMessage`, or :py:class:`~alarmdecoder.messages.RFMessage`
         """
         if isinstance(message, Message):
             self._update_power_status(message)
@@ -416,7 +416,7 @@ class AlarmDecoder(object):
         Uses the provided message to update the AC power state.
 
         :param message: message to use to update
-        :type message: :py:class:`alarmdecoder.messages.Message`
+        :type message: :py:class:`~alarmdecoder.messages.Message`
 
         :returns: bool indicating the new status
         """
@@ -433,7 +433,7 @@ class AlarmDecoder(object):
         Uses the provided message to update the alarm state.
 
         :param message: message to use to update
-        :type message: :py:class:`alarmdecoder.messages.Message`
+        :type message: :py:class:`~alarmdecoder.messages.Message`
 
         :returns: bool indicating the new status
         """
@@ -451,7 +451,7 @@ class AlarmDecoder(object):
         Uses the provided message to update the zone bypass state.
 
         :param message: message to use to update
-        :type message: :py:class:`alarmdecoder.messages.Message`
+        :type message: :py:class:`~alarmdecoder.messages.Message`
 
         :returns: bool indicating the new status
         """
@@ -469,7 +469,7 @@ class AlarmDecoder(object):
         Uses the provided message to update the armed state.
 
         :param message: message to use to update
-        :type message: :py:class:`alarmdecoder.messages.Message`
+        :type message: :py:class:`~alarmdecoder.messages.Message`
 
         :returns: bool indicating the new status
         """
@@ -491,7 +491,7 @@ class AlarmDecoder(object):
         Uses the provided message to update the battery state.
 
         :param message: message to use to update
-        :type message: :py:class:`alarmdecoder.messages.Message`
+        :type message: :py:class:`~alarmdecoder.messages.Message`
 
         :returns: boolean indicating the new status
         """
@@ -511,7 +511,7 @@ class AlarmDecoder(object):
         Uses the provided message to update the fire alarm state.
 
         :param message: message to use to update
-        :type message: :py:class:`alarmdecoder.messages.Message`
+        :type message: :py:class:`~alarmdecoder.messages.Message`
 
         :returns: boolean indicating the new status
         """
@@ -531,7 +531,7 @@ class AlarmDecoder(object):
         Uses the provided message to update the expander states.
 
         :param message: message to use to update
-        :type message: :py:class:`alarmdecoder.messages.ExpanderMessage`
+        :type message: :py:class:`~alarmdecoder.messages.ExpanderMessage`
 
         :returns: boolean indicating the new status
         """
@@ -545,10 +545,10 @@ class AlarmDecoder(object):
 
     def _update_zone_tracker(self, message):
         """
-        Trigger an update of the :py:class:`alarmdecoder.messages.Zonetracker`.
+        Trigger an update of the :py:class:`~alarmdecoder.messages.Zonetracker`.
 
         :param message: message to update the zonetracker with
-        :type message: :py:class:`alarmdecoder.messages.Message`, :py:class:`alarmdecoder.messages.ExpanderMessage`, :py:class:`alarmdecoder.messages.LRRMessage`, or :py:class:`alarmdecoder.messages.RFMessage`
+        :type message: :py:class:`~alarmdecoder.messages.Message`, :py:class:`~alarmdecoder.messages.ExpanderMessage`, :py:class:`~alarmdecoder.messages.LRRMessage`, or :py:class:`~alarmdecoder.messages.RFMessage`
         """
 
         # Retrieve a list of faults.

alarmdecoder/devices.py

@@ -35,10 +35,10 @@ class Device(object):
     """
 
     # Generic device events
-    on_open = event.Event('This event is called when the device has been opened.')
-    on_close = event.Event('This event is called when the device has been closed.')
-    on_read = event.Event('This event is called when a line has been read from the device.')
-    on_write = event.Event('This event is called when data has been written to the device.')
+    on_open = event.Event("This event is called when the device has been opened.\n\n**Callback definition:** *def callback(device)*")
+    on_close = event.Event("This event is called when the device has been closed.\n\n**Callback definition:** def callback(device)*")
+    on_read = event.Event("This event is called when a line has been read from the device.\n\n**Callback definition:** def callback(device, data)*")
+    on_write = event.Event("This event is called when data has been written to the device.\n\n**Callback definition:** def callback(device, data)*")
 
     def __init__(self):
         """
@@ -124,7 +124,7 @@ class Device(object):
             Constructor
 
             :param device: device used by the reader thread
-            :type device: :py:class:`alarmdecoder.devices.Device`
+            :type device: :py:class:`~alarmdecoder.devices.Device`
             """
             threading.Thread.__init__(self)
             self._device = device
@@ -177,7 +177,7 @@ class USBDevice(Device):
         Returns all FTDI devices matching our vendor and product IDs.
 
         :returns: list of devices
-        :raises: :py:class:`alarmdecoder.util.CommError`
+        :raises: :py:class:`~alarmdecoder.util.CommError`
         """
         cls.__devices = []
 
@@ -209,7 +209,7 @@ class USBDevice(Device):
         :type device: tuple
 
         :returns: :py:class:`USBDevice` object utilizing the specified device
-        :raises: :py:class:`alarmdecoder.util.NoDeviceError`
+        :raises: :py:class:`~alarmdecoder.util.NoDeviceError`
         """
         cls.find_all()
 
@@ -228,9 +228,10 @@ class USBDevice(Device):
         """
         Starts the device detection thread.
 
-        :param on_attached: function to be called when a device is attached
+        :param on_attached: function to be called when a device is attached  **Callback definition:** *def callback(thread, device)*
         :type on_attached: function
-        :param on_detached: function to be called when a device is detached
+        :param on_detached: function to be called when a device is detached  **Callback definition:** *def callback(thread, device)*
+
         :type on_detached: function
         """
         cls.__detect_thread = USBDevice.DetectThread(on_attached, on_detached)
@@ -344,7 +345,7 @@ class USBDevice(Device):
                                  reader thread.
         :type no_reader_thread: bool
 
-        :raises: :py:class:`alarmdecoder.util.NoDeviceError`
+        :raises: :py:class:`~alarmdecoder.util.NoDeviceError`
         """
         # Set up defaults
         if baudrate is None:
@@ -398,7 +399,7 @@ class USBDevice(Device):
         :param data: data to write
         :type data: string
 
-        :raises: :py:class:`alarmdecoder.util.CommError`
+        :raises: :py:class:`~alarmdecoder.util.CommError`
         """
         try:
             self._device.write_data(data)
@@ -413,7 +414,7 @@ class USBDevice(Device):
         Reads a single character from the device.
 
         :returns: character read from the device
-        :raises: :py:class:`alarmdecoder.util.CommError`
+        :raises: :py:class:`~alarmdecoder.util.CommError`
         """
         ret = None
 
@@ -436,7 +437,7 @@ class USBDevice(Device):
         :type purge_buffer: bool
 
         :returns: line that was read
-        :raises: :py:class:`alarmdecoder.util.CommError`, :py:class:`alarmdecoder.util.TimeoutError`
+        :raises: :py:class:`~alarmdecoder.util.CommError`, :py:class:`~alarmdecoder.util.TimeoutError`
         """
 
         def timeout_event():
@@ -496,16 +497,16 @@ class USBDevice(Device):
         """
         Thread that handles detection of added/removed devices.
         """
-        on_attached = event.Event('This event is called when an `AD2USB`_ device has been detected.')
-        on_detached = event.Event('This event is called when an `AD2USB`_ device has been removed.')
+        on_attached = event.Event("This event is called when an `AD2USB`_ device has been detected.\n\n**Callback definition:** def callback(thread, device*")
+        on_detached = event.Event("This event is called when an `AD2USB`_ device has been removed.\n\n**Callback definition:** def callback(thread, device*")
 
         def __init__(self, on_attached=None, on_detached=None):
             """
             Constructor
 
-            :param on_attached: Function to call when a device is attached
+            :param on_attached: Function to call when a device is attached  **Callback definition:** *def callback(thread, device)*
             :type on_attached: function
-            :param on_detached: Function to call when a device is detached
+            :param on_detached: Function to call when a device is detached  **Callback definition:** *def callback(thread, device)*
             :type on_detached: function
             """
             threading.Thread.__init__(self)
@@ -568,7 +569,7 @@ class SerialDevice(Device):
         :type pattern: string
 
         :returns: list of devices
-        :raises: :py:class:`alarmdecoder.util.CommError`
+        :raises: :py:class:`~alarmdecoder.util.CommError`
         """
         devices = []
 
@@ -626,7 +627,7 @@ class SerialDevice(Device):
                                  reader thread.
         :type no_reader_thread: bool
 
-        :raises: :py:class:`alarmdecoder.util.NoDeviceError`
+        :raises: :py:class:`~alarmdecoder.util.NoDeviceError`
         """
         # Set up the defaults
         if baudrate is None:
@@ -676,7 +677,7 @@ class SerialDevice(Device):
         :param data: data to write
         :type data: string
 
-        :raises: py:class:`alarmdecoder.util.CommError`
+        :raises: py:class:`~alarmdecoder.util.CommError`
         """
         try:
             self._device.write(data)
@@ -695,7 +696,7 @@ class SerialDevice(Device):
         Reads a single character from the device.
 
         :returns: character read from the device
-        :raises: :py:class:`alarmdecoder.util.CommError`
+        :raises: :py:class:`~alarmdecoder.util.CommError`
         """
         ret = None
 
@@ -718,7 +719,7 @@ class SerialDevice(Device):
         :type purge_buffer: bool
 
         :returns: line that was read
-        :raises: :py:class:`alarmdecoder.util.CommError`, :py:class:`alarmdecoder.util.TimeoutError`
+        :raises: :py:class:`~alarmdecoder.util.CommError`, :py:class:`~alarmdecoder.util.TimeoutError`
         """
 
         def timeout_event():
@@ -895,7 +896,7 @@ class SocketDevice(Device):
                                  thread.
         :type no_reader_thread: bool
 
-        :raises: :py:class:`alarmdecoder.util.NoDeviceError`, :py:class:`alarmdecoder.util.CommError`
+        :raises: :py:class:`~alarmdecoder.util.NoDeviceError`, :py:class:`~alarmdecoder.util.CommError`
         """
 
         try:
@@ -949,7 +950,7 @@ class SocketDevice(Device):
         :type data: string
 
         :returns: number of bytes sent
-        :raises: :py:class:`alarmdecoder.util.CommError`
+        :raises: :py:class:`~alarmdecoder.util.CommError`
         """
         data_sent = None
 
@@ -971,7 +972,7 @@ class SocketDevice(Device):
         Reads a single character from the device.
 
         :returns: character read from the device
-        :raises: :py:class:`alarmdecoder.util.CommError`
+        :raises: :py:class:`~alarmdecoder.util.CommError`
         """
         data = None
 
@@ -994,7 +995,7 @@ class SocketDevice(Device):
         :type purge_buffer: bool
 
         :returns: line that was read
-        :raises: :py:class:`alarmdecoder.util.CommError`, :py:class:`alarmdecoder.util.TimeoutError`
+        :raises: :py:class:`~alarmdecoder.util.CommError`, :py:class:`~alarmdecoder.util.TimeoutError`
         """
 
         def timeout_event():
@@ -1046,7 +1047,7 @@ class SocketDevice(Device):
         """
         Initializes our device as an SSL connection.
 
-        :raises: :py:class:`alarmdecoder.util.CommError`
+        :raises: :py:class:`~alarmdecoder.util.CommError`
         """
 
         try:

alarmdecoder/messages.py

@@ -115,7 +115,7 @@ class Message(BaseMessage):
         :param data: message data
         :type data: string
 
-        :raises: :py:class:`alarmdecoder.util.InvalidMessageError`
+        :raises: :py:class:`~alarmdecoder.util.InvalidMessageError`
         """
         match = self._regex.match(data)
 
@@ -196,7 +196,7 @@ class ExpanderMessage(BaseMessage):
         :param data: message data
         :type data: string
 
-        :raises: :py:class:`alarmdecoder.util.InvalidMessageError`
+        :raises: :py:class:`~alarmdecoder.util.InvalidMessageError`
         """
         try:
             header, values = data.split(':')
@@ -259,7 +259,7 @@ class RFMessage(BaseMessage):
         :param data: message data
         :type data: string
 
-        :raises: :py:class:`alarmdecoder.util.InvalidMessageError`
+        :raises: :py:class:`~alarmdecoder.util.InvalidMessageError`
         """
         try:
             self.raw = data
@@ -320,7 +320,7 @@ class LRRMessage(BaseMessage):
         :param data: message data to parse
         :type data: string
 
-        :raises: :py:class:`alarmdecoder.util.InvalidMessageError`
+        :raises: :py:class:`~alarmdecoder.util.InvalidMessageError`
         """
         try:
             self.raw = data

alarmdecoder/util.py

@@ -62,7 +62,7 @@ class Firmware(object):
         :param progress_callback: callback function used to report progress
         :type progress_callback: function
 
-        :raises: :py:class:`alarmdecoder.util.NoDeviceError`, :py:class:`alarmdecoder.util.TimeoutError`
+        :raises: :py:class:`~alarmdecoder.util.NoDeviceError`, :py:class:`~alarmdecoder.util.TimeoutError`
         """
 
         def do_upload():

alarmdecoder/zonetracking.py

@@ -72,8 +72,8 @@ class Zonetracker(object):
     Handles tracking of zones and their statuses.
     """
 
-    on_fault = event.Event('This event is called when the device detects a zone fault.')
-    on_restore = event.Event('This event is called when the device detects that a fault is restored.')
+    on_fault = event.Event("This event is called when the device detects a zone fault.\n\n**Callback definition:** *def callback(device, zone)*")
+    on_restore = event.Event("This event is called when the device detects that a fault is restored.\n\n**Callback definition:** *def callback(device, zone)*")
 
     EXPIRE = 30
     """Zone expiration timeout."""
@@ -129,7 +129,7 @@ class Zonetracker(object):
         Update zone statuses based on the current message.
 
         :param message: message to use to update the zone tracking
-        :type message: :py:class:`alarmdecoder.messages.Message` or :py:class:`alarmdecoder.messages.ExpanderMessage`
+        :type message: :py:class:`~alarmdecoder.messages.Message` or :py:class:`~alarmdecoder.messages.ExpanderMessage`
         """
         if isinstance(message, ExpanderMessage):
             if message.type == ExpanderMessage.ZONE:

docs/build/html/_sources/index.txt

@@ -3,17 +3,50 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to alarmdecoder's documentation!
+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 <http://github.com/nutechsoftware/alarmdecoder>`_.
-
 .. _Alarm Decoder: http://www.alarmdecoder.com
 .. _AD2USB: http://www.alarmdecoder.com
 .. _AD2SERIAL: http://www.alarmdecoder.com
 .. _AD2PI: http://www.alarmdecoder.com
+.. _examples: http://github.com/nutechsoftware/alarmdecoder/tree/master/examples
+
+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 <http://github.com/nutechsoftware/alarmdecoder>`_.
+
+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:
 

docs/build/html/alarmdecoder.html

@@ -24,7 +24,7 @@
     <script type="text/javascript" src="_static/underscore.js"></script>
     <script type="text/javascript" src="_static/doctools.js"></script>
     <link rel="top" title="alarmdecoder  documentation" href="index.html" />
-    <link rel="prev" title="Welcome to alarmdecoder’s documentation!" href="index.html" /> 
+    <link rel="prev" title="Welcome to Alarm Decoder’s documentation!" href="index.html" /> 
   </head>
   <body>
     <div class="related">
@@ -37,7 +37,7 @@
           <a href="py-modindex.html" title="Python Module Index"
              >modules</a> |</li>
         <li class="right" >
-          <a href="index.html" title="Welcome to alarmdecoder’s documentation!"
+          <a href="index.html" title="Welcome to Alarm Decoder’s documentation!"
              accesskey="P">previous</a> |</li>
         <li><a href="index.html">alarmdecoder  documentation</a> &raquo;</li> 
       </ul>
@@ -62,120 +62,140 @@
 <dt id="alarmdecoder.decoder.AlarmDecoder.on_arm">
 <tt class="descname">on_arm</tt><a class="headerlink" href="#alarmdecoder.decoder.AlarmDecoder.on_arm" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when the panel is armed.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.decoder.AlarmDecoder.on_disarm">
 <tt class="descname">on_disarm</tt><a class="headerlink" href="#alarmdecoder.decoder.AlarmDecoder.on_disarm" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when the panel is disarmed.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.decoder.AlarmDecoder.on_power_changed">
 <tt class="descname">on_power_changed</tt><a class="headerlink" href="#alarmdecoder.decoder.AlarmDecoder.on_power_changed" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when panel power switches between AC and DC.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device, status)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.decoder.AlarmDecoder.on_alarm">
 <tt class="descname">on_alarm</tt><a class="headerlink" href="#alarmdecoder.decoder.AlarmDecoder.on_alarm" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when the alarm is triggered.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device, status)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.decoder.AlarmDecoder.on_fire">
 <tt class="descname">on_fire</tt><a class="headerlink" href="#alarmdecoder.decoder.AlarmDecoder.on_fire" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when a fire is detected.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device, status)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.decoder.AlarmDecoder.on_bypass">
 <tt class="descname">on_bypass</tt><a class="headerlink" href="#alarmdecoder.decoder.AlarmDecoder.on_bypass" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when a zone is bypassed.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device, status)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.decoder.AlarmDecoder.on_boot">
 <tt class="descname">on_boot</tt><a class="headerlink" href="#alarmdecoder.decoder.AlarmDecoder.on_boot" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when the device finishes booting.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.decoder.AlarmDecoder.on_config_received">
 <tt class="descname">on_config_received</tt><a class="headerlink" href="#alarmdecoder.decoder.AlarmDecoder.on_config_received" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when the device receives its configuration.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.decoder.AlarmDecoder.on_zone_fault">
 <tt class="descname">on_zone_fault</tt><a class="headerlink" href="#alarmdecoder.decoder.AlarmDecoder.on_zone_fault" title="Permalink to this definition">¶</a></dt>
-<dd><p>This event is called when <a class="reference internal" href="#alarmdecoder.zonetracking.Zonetracker" title="alarmdecoder.zonetracking.Zonetracker"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.zonetracking.Zonetracker</span></tt></a> detects a zone fault.</p>
+<dd><p>This event is called when <a class="reference internal" href="#alarmdecoder.zonetracking.Zonetracker" title="alarmdecoder.zonetracking.Zonetracker"><tt class="xref py py-class docutils literal"><span class="pre">Zonetracker</span></tt></a> detects a zone fault.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device, zone)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.decoder.AlarmDecoder.on_zone_restore">
 <tt class="descname">on_zone_restore</tt><a class="headerlink" href="#alarmdecoder.decoder.AlarmDecoder.on_zone_restore" title="Permalink to this definition">¶</a></dt>
-<dd><p>This event is called when <a class="reference internal" href="#alarmdecoder.zonetracking.Zonetracker" title="alarmdecoder.zonetracking.Zonetracker"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.zonetracking.Zonetracker</span></tt></a> detects that a fault is restored.</p>
+<dd><p>This event is called when <a class="reference internal" href="#alarmdecoder.zonetracking.Zonetracker" title="alarmdecoder.zonetracking.Zonetracker"><tt class="xref py py-class docutils literal"><span class="pre">Zonetracker</span></tt></a> detects that a fault is restored.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device, zone)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.decoder.AlarmDecoder.on_low_battery">
 <tt class="descname">on_low_battery</tt><a class="headerlink" href="#alarmdecoder.decoder.AlarmDecoder.on_low_battery" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when the device detects a low battery.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device, status)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.decoder.AlarmDecoder.on_panic">
 <tt class="descname">on_panic</tt><a class="headerlink" href="#alarmdecoder.decoder.AlarmDecoder.on_panic" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when the device detects a panic.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device, status)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.decoder.AlarmDecoder.on_relay_changed">
 <tt class="descname">on_relay_changed</tt><a class="headerlink" href="#alarmdecoder.decoder.AlarmDecoder.on_relay_changed" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when a relay is opened or closed on an expander board.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device, message)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.decoder.AlarmDecoder.on_message">
 <tt class="descname">on_message</tt><a class="headerlink" href="#alarmdecoder.decoder.AlarmDecoder.on_message" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when any message is received.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device, message)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.decoder.AlarmDecoder.on_lrr_message">
 <tt class="descname">on_lrr_message</tt><a class="headerlink" href="#alarmdecoder.decoder.AlarmDecoder.on_lrr_message" title="Permalink to this definition">¶</a></dt>
-<dd><p>This event is called when an <a class="reference internal" href="#alarmdecoder.messages.LRRMessage" title="alarmdecoder.messages.LRRMessage"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.messages.LRRMessage</span></tt></a> is received.</p>
+<dd><p>This event is called when an <a class="reference internal" href="#alarmdecoder.messages.LRRMessage" title="alarmdecoder.messages.LRRMessage"><tt class="xref py py-class docutils literal"><span class="pre">LRRMessage</span></tt></a> is received.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device, message)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.decoder.AlarmDecoder.on_rfx_message">
 <tt class="descname">on_rfx_message</tt><a class="headerlink" href="#alarmdecoder.decoder.AlarmDecoder.on_rfx_message" title="Permalink to this definition">¶</a></dt>
-<dd><p>This event is called when an <a class="reference internal" href="#alarmdecoder.messages.RFMessage" title="alarmdecoder.messages.RFMessage"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.messages.RFMessage</span></tt></a> is received.</p>
+<dd><p>This event is called when an <a class="reference internal" href="#alarmdecoder.messages.RFMessage" title="alarmdecoder.messages.RFMessage"><tt class="xref py py-class docutils literal"><span class="pre">RFMessage</span></tt></a> is received.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device, message)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.decoder.AlarmDecoder.on_open">
 <tt class="descname">on_open</tt><a class="headerlink" href="#alarmdecoder.decoder.AlarmDecoder.on_open" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when the device has been opened.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.decoder.AlarmDecoder.on_close">
 <tt class="descname">on_close</tt><a class="headerlink" href="#alarmdecoder.decoder.AlarmDecoder.on_close" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when the device has been closed.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.decoder.AlarmDecoder.on_read">
 <tt class="descname">on_read</tt><a class="headerlink" href="#alarmdecoder.decoder.AlarmDecoder.on_read" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when a line has been read from the device.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device, data)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.decoder.AlarmDecoder.on_write">
 <tt class="descname">on_write</tt><a class="headerlink" href="#alarmdecoder.decoder.AlarmDecoder.on_write" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when data has been written to the device.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device, data)</em></p>
 </dd></dl>
 
 <dl class="attribute">
@@ -408,24 +428,28 @@ Also supports SSL if using <a class="reference external" href="http://github.com
 <dt id="alarmdecoder.devices.Device.on_open">
 <tt class="descname">on_open</tt><a class="headerlink" href="#alarmdecoder.devices.Device.on_open" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when the device has been opened.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.devices.Device.on_close">
 <tt class="descname">on_close</tt><a class="headerlink" href="#alarmdecoder.devices.Device.on_close" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when the device has been closed.</p>
+<p><strong>Callback definition:</strong> def callback(device)*</p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.devices.Device.on_read">
 <tt class="descname">on_read</tt><a class="headerlink" href="#alarmdecoder.devices.Device.on_read" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when a line has been read from the device.</p>
+<p><strong>Callback definition:</strong> def callback(device, data)*</p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.devices.Device.on_write">
 <tt class="descname">on_write</tt><a class="headerlink" href="#alarmdecoder.devices.Device.on_write" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when data has been written to the device.</p>
+<p><strong>Callback definition:</strong> def callback(device, data)*</p>
 </dd></dl>
 
 <dl class="attribute">
@@ -528,7 +552,7 @@ Also supports SSL if using <a class="reference external" href="http://github.com
 <tbody valign="top">
 <tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">list of devices</td>
 </tr>
-<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.util.CommError</span></tt></a></td>
+<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">CommError</span></tt></a></td>
 </tr>
 </tbody>
 </table>
@@ -562,7 +586,7 @@ by find_all().</td>
 </tr>
 <tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><a class="reference internal" href="#alarmdecoder.devices.USBDevice" title="alarmdecoder.devices.USBDevice"><tt class="xref py py-class docutils literal"><span class="pre">USBDevice</span></tt></a> object utilizing the specified device</td>
 </tr>
-<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#alarmdecoder.util.NoDeviceError" title="alarmdecoder.util.NoDeviceError"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.util.NoDeviceError</span></tt></a></td>
+<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#alarmdecoder.util.NoDeviceError" title="alarmdecoder.util.NoDeviceError"><tt class="xref py py-class docutils literal"><span class="pre">NoDeviceError</span></tt></a></td>
 </tr>
 </tbody>
 </table>
@@ -577,8 +601,8 @@ by find_all().</td>
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
-<li><strong>on_attached</strong> (<em>function</em>) &#8211; function to be called when a device is attached</li>
-<li><strong>on_detached</strong> (<em>function</em>) &#8211; function to be called when a device is detached</li>
+<li><strong>on_attached</strong> (<em>function</em>) &#8211; function to be called when a device is attached  <strong>Callback definition:</strong> <em>def callback(thread, device)</em></li>
+<li><strong>on_detached</strong> (<em>function</em>) &#8211; function to be called when a device is detached  <strong>Callback definition:</strong> <em>def callback(thread, device)</em></li>
 </ul>
 </td>
 </tr>
@@ -649,7 +673,7 @@ reader thread.</li>
 </ul>
 </td>
 </tr>
-<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><a class="reference internal" href="#alarmdecoder.util.NoDeviceError" title="alarmdecoder.util.NoDeviceError"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.util.NoDeviceError</span></tt></a></p>
+<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><a class="reference internal" href="#alarmdecoder.util.NoDeviceError" title="alarmdecoder.util.NoDeviceError"><tt class="xref py py-class docutils literal"><span class="pre">NoDeviceError</span></tt></a></p>
 </td>
 </tr>
 </tbody>
@@ -672,7 +696,7 @@ reader thread.</li>
 <tbody valign="top">
 <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>data</strong> (<em>string</em>) &#8211; data to write</td>
 </tr>
-<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.util.CommError</span></tt></a></td>
+<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">CommError</span></tt></a></td>
 </tr>
 </tbody>
 </table>
@@ -688,7 +712,7 @@ reader thread.</li>
 <tbody valign="top">
 <tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">character read from the device</td>
 </tr>
-<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.util.CommError</span></tt></a></td>
+<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">CommError</span></tt></a></td>
 </tr>
 </tbody>
 </table>
@@ -712,7 +736,7 @@ reading.</li>
 <tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">line that was read</p>
 </td>
 </tr>
-<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.util.CommError</span></tt></a>, <a class="reference internal" href="#alarmdecoder.util.TimeoutError" title="alarmdecoder.util.TimeoutError"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.util.TimeoutError</span></tt></a></p>
+<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">CommError</span></tt></a>, <a class="reference internal" href="#alarmdecoder.util.TimeoutError" title="alarmdecoder.util.TimeoutError"><tt class="xref py py-class docutils literal"><span class="pre">TimeoutError</span></tt></a></p>
 </td>
 </tr>
 </tbody>
@@ -728,12 +752,14 @@ reading.</li>
 <dt id="alarmdecoder.devices.USBDevice.DetectThread.on_attached">
 <tt class="descname">on_attached</tt><a class="headerlink" href="#alarmdecoder.devices.USBDevice.DetectThread.on_attached" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when an <a class="reference external" href="http://www.alarmdecoder.com">AD2USB</a> device has been detected.</p>
+<p><strong>Callback definition:</strong> def callback(thread, device*</p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.devices.USBDevice.DetectThread.on_detached">
 <tt class="descname">on_detached</tt><a class="headerlink" href="#alarmdecoder.devices.USBDevice.DetectThread.on_detached" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when an <a class="reference external" href="http://www.alarmdecoder.com">AD2USB</a> device has been removed.</p>
+<p><strong>Callback definition:</strong> def callback(thread, device*</p>
 </dd></dl>
 
 <dl class="method">
@@ -775,7 +801,7 @@ reading.</li>
 </tr>
 <tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">list of devices</td>
 </tr>
-<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.util.CommError</span></tt></a></td>
+<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">CommError</span></tt></a></td>
 </tr>
 </tbody>
 </table>
@@ -810,7 +836,7 @@ reader thread.</li>
 </ul>
 </td>
 </tr>
-<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><a class="reference internal" href="#alarmdecoder.util.NoDeviceError" title="alarmdecoder.util.NoDeviceError"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.util.NoDeviceError</span></tt></a></p>
+<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><a class="reference internal" href="#alarmdecoder.util.NoDeviceError" title="alarmdecoder.util.NoDeviceError"><tt class="xref py py-class docutils literal"><span class="pre">NoDeviceError</span></tt></a></p>
 </td>
 </tr>
 </tbody>
@@ -833,7 +859,7 @@ reader thread.</li>
 <tbody valign="top">
 <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>data</strong> (<em>string</em>) &#8211; data to write</td>
 </tr>
-<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body">py:class:<cite>alarmdecoder.util.CommError</cite></td>
+<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body">py:class:<cite>~alarmdecoder.util.CommError</cite></td>
 </tr>
 </tbody>
 </table>
@@ -849,7 +875,7 @@ reader thread.</li>
 <tbody valign="top">
 <tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">character read from the device</td>
 </tr>
-<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.util.CommError</span></tt></a></td>
+<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">CommError</span></tt></a></td>
 </tr>
 </tbody>
 </table>
@@ -873,7 +899,7 @@ reading.</li>
 <tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">line that was read</p>
 </td>
 </tr>
-<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.util.CommError</span></tt></a>, <a class="reference internal" href="#alarmdecoder.util.TimeoutError" title="alarmdecoder.util.TimeoutError"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.util.TimeoutError</span></tt></a></p>
+<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">CommError</span></tt></a>, <a class="reference internal" href="#alarmdecoder.util.TimeoutError" title="alarmdecoder.util.TimeoutError"><tt class="xref py py-class docutils literal"><span class="pre">TimeoutError</span></tt></a></p>
 </td>
 </tr>
 </tbody>
@@ -974,7 +1000,7 @@ thread.</li>
 </ul>
 </td>
 </tr>
-<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><a class="reference internal" href="#alarmdecoder.util.NoDeviceError" title="alarmdecoder.util.NoDeviceError"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.util.NoDeviceError</span></tt></a>, <a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.util.CommError</span></tt></a></p>
+<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><a class="reference internal" href="#alarmdecoder.util.NoDeviceError" title="alarmdecoder.util.NoDeviceError"><tt class="xref py py-class docutils literal"><span class="pre">NoDeviceError</span></tt></a>, <a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">CommError</span></tt></a></p>
 </td>
 </tr>
 </tbody>
@@ -999,7 +1025,7 @@ thread.</li>
 </tr>
 <tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">number of bytes sent</td>
 </tr>
-<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.util.CommError</span></tt></a></td>
+<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">CommError</span></tt></a></td>
 </tr>
 </tbody>
 </table>
@@ -1015,7 +1041,7 @@ thread.</li>
 <tbody valign="top">
 <tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">character read from the device</td>
 </tr>
-<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.util.CommError</span></tt></a></td>
+<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">CommError</span></tt></a></td>
 </tr>
 </tbody>
 </table>
@@ -1039,7 +1065,7 @@ reading.</li>
 <tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">line that was read</p>
 </td>
 </tr>
-<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.util.CommError</span></tt></a>, <a class="reference internal" href="#alarmdecoder.util.TimeoutError" title="alarmdecoder.util.TimeoutError"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.util.TimeoutError</span></tt></a></p>
+<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><a class="reference internal" href="#alarmdecoder.util.CommError" title="alarmdecoder.util.CommError"><tt class="xref py py-class docutils literal"><span class="pre">CommError</span></tt></a>, <a class="reference internal" href="#alarmdecoder.util.TimeoutError" title="alarmdecoder.util.TimeoutError"><tt class="xref py py-class docutils literal"><span class="pre">TimeoutError</span></tt></a></p>
 </td>
 </tr>
 </tbody>
@@ -1383,12 +1409,14 @@ devices.</p>
 <dt id="alarmdecoder.zonetracking.Zonetracker.on_fault">
 <tt class="descname">on_fault</tt><a class="headerlink" href="#alarmdecoder.zonetracking.Zonetracker.on_fault" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when the device detects a zone fault.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device, zone)</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="alarmdecoder.zonetracking.Zonetracker.on_restore">
 <tt class="descname">on_restore</tt><a class="headerlink" href="#alarmdecoder.zonetracking.Zonetracker.on_restore" title="Permalink to this definition">¶</a></dt>
 <dd><p>This event is called when the device detects that a fault is restored.</p>
+<p><strong>Callback definition:</strong> <em>def callback(device, zone)</em></p>
 </dd></dl>
 
 <dl class="attribute">
@@ -1433,7 +1461,7 @@ devices.</p>
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>message</strong> (<a class="reference internal" href="#alarmdecoder.messages.Message" title="alarmdecoder.messages.Message"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.messages.Message</span></tt></a> or <a class="reference internal" href="#alarmdecoder.messages.ExpanderMessage" title="alarmdecoder.messages.ExpanderMessage"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.messages.ExpanderMessage</span></tt></a>) &#8211; message to use to update the zone tracking</td>
+<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>message</strong> (<a class="reference internal" href="#alarmdecoder.messages.Message" title="alarmdecoder.messages.Message"><tt class="xref py py-class docutils literal"><span class="pre">Message</span></tt></a> or <a class="reference internal" href="#alarmdecoder.messages.ExpanderMessage" title="alarmdecoder.messages.ExpanderMessage"><tt class="xref py py-class docutils literal"><span class="pre">ExpanderMessage</span></tt></a>) &#8211; message to use to update the zone tracking</td>
 </tr>
 </tbody>
 </table>
@@ -1543,7 +1571,7 @@ devices.</p>
 </ul>
 </td>
 </tr>
-<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><a class="reference internal" href="#alarmdecoder.util.NoDeviceError" title="alarmdecoder.util.NoDeviceError"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.util.NoDeviceError</span></tt></a>, <a class="reference internal" href="#alarmdecoder.util.TimeoutError" title="alarmdecoder.util.TimeoutError"><tt class="xref py py-class docutils literal"><span class="pre">alarmdecoder.util.TimeoutError</span></tt></a></p>
+<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><a class="reference internal" href="#alarmdecoder.util.NoDeviceError" title="alarmdecoder.util.NoDeviceError"><tt class="xref py py-class docutils literal"><span class="pre">NoDeviceError</span></tt></a>, <a class="reference internal" href="#alarmdecoder.util.TimeoutError" title="alarmdecoder.util.TimeoutError"><tt class="xref py py-class docutils literal"><span class="pre">TimeoutError</span></tt></a></p>
 </td>
 </tr>
 </tbody>
@@ -1580,7 +1608,7 @@ devices.</p>
 
   <h4>Previous topic</h4>
   <p class="topless"><a href="index.html"
-                        title="previous chapter">Welcome to alarmdecoder&#8217;s documentation!</a></p>
+                        title="previous chapter">Welcome to Alarm Decoder&#8217;s documentation!</a></p>
   <h3>This Page</h3>
   <ul class="this-page-menu">
     <li><a href="_sources/alarmdecoder.txt"
@@ -1613,7 +1641,7 @@ devices.</p>
           <a href="py-modindex.html" title="Python Module Index"
              >modules</a> |</li>
         <li class="right" >
-          <a href="index.html" title="Welcome to alarmdecoder’s documentation!"
+          <a href="index.html" title="Welcome to Alarm Decoder’s documentation!"
              >previous</a> |</li>
         <li><a href="index.html">alarmdecoder  documentation</a> &raquo;</li> 
       </ul>

docs/build/html/index.html

@@ -6,7 +6,7 @@
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
     
-    <title>Welcome to alarmdecoder’s documentation! &mdash; alarmdecoder  documentation</title>
+    <title>Welcome to Alarm Decoder’s documentation! &mdash; alarmdecoder  documentation</title>
     
     <link rel="stylesheet" href="_static/default.css" type="text/css" />
     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
@@ -48,10 +48,42 @@
         <div class="bodywrapper">
           <div class="body">
             
-  <div class="section" id="welcome-to-alarmdecoder-s-documentation">
-<h1>Welcome to alarmdecoder&#8217;s documentation!<a class="headerlink" href="#welcome-to-alarmdecoder-s-documentation" title="Permalink to this headline">¶</a></h1>
+  <div class="section" id="welcome-to-alarm-decoder-s-documentation">
+<h1>Welcome to Alarm Decoder&#8217;s documentation!<a class="headerlink" href="#welcome-to-alarm-decoder-s-documentation" title="Permalink to this headline">¶</a></h1>
 <p>This is the API documentation for the <a class="reference external" href="http://www.alarmdecoder.com">Alarm Decoder</a> Python library.  It provides support for interacting with the <a class="reference external" href="http://www.alarmdecoder.com">Alarm Decoder</a> (AD2) family of security alarm devices, including the <a class="reference external" href="http://www.alarmdecoder.com">AD2USB</a>, <a class="reference external" href="http://www.alarmdecoder.com">AD2SERIAL</a> and <a class="reference external" href="http://www.alarmdecoder.com">AD2PI</a>.</p>
 <p>The source code, requirements and examples for this project may be found <a class="reference external" href="http://github.com/nutechsoftware/alarmdecoder">here</a>.</p>
+<p>Please see the <a class="reference external" href="http://github.com/nutechsoftware/alarmdecoder/tree/master/examples">examples</a> directory for more samples, but a basic one is included below:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">time</span>
+<span class="kn">from</span> <span class="nn">alarmdecoder</span> <span class="kn">import</span> <span class="n">AlarmDecoder</span>
+<span class="kn">from</span> <span class="nn">alarmdecoder.devices</span> <span class="kn">import</span> <span class="n">USBDevice</span>
+
+<span class="k">def</span> <span class="nf">main</span><span class="p">():</span>
+    <span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">    Example application that prints messages from the panel to the terminal.</span>
+<span class="sd">    &quot;&quot;&quot;</span>
+    <span class="k">try</span><span class="p">:</span>
+        <span class="c"># Retrieve the first USB device</span>
+        <span class="n">device</span> <span class="o">=</span> <span class="n">AlarmDecoder</span><span class="p">(</span><span class="n">USBDevice</span><span class="o">.</span><span class="n">find</span><span class="p">())</span>
+
+        <span class="c"># Set up an event handler and open the device</span>
+        <span class="n">device</span><span class="o">.</span><span class="n">on_message</span> <span class="o">+=</span> <span class="n">handle_message</span>
+        <span class="k">with</span> <span class="n">device</span><span class="o">.</span><span class="n">open</span><span class="p">():</span>
+            <span class="k">while</span> <span class="bp">True</span><span class="p">:</span>
+                <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
+
+    <span class="k">except</span> <span class="ne">Exception</span><span class="p">,</span> <span class="n">ex</span><span class="p">:</span>
+        <span class="k">print</span> <span class="s">&#39;Exception:&#39;</span><span class="p">,</span> <span class="n">ex</span>
+
+<span class="k">def</span> <span class="nf">handle_message</span><span class="p">(</span><span class="n">sender</span><span class="p">,</span> <span class="n">message</span><span class="p">):</span>
+    <span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">    Handles message events from the AlarmDecoder.</span>
+<span class="sd">    &quot;&quot;&quot;</span>
+    <span class="k">print</span> <span class="n">sender</span><span class="p">,</span> <span class="n">message</span><span class="o">.</span><span class="n">raw</span>
+
+<span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s">&#39;__main__&#39;</span><span class="p">:</span>
+    <span class="n">main</span><span class="p">()</span>
+</pre></div>
+</div>
 <p>Table of Contents:</p>
 <div class="toctree-wrapper compound">
 <ul>
@@ -84,7 +116,7 @@
         <div class="sphinxsidebarwrapper">
   <h3><a href="#">Table Of Contents</a></h3>
   <ul>
-<li><a class="reference internal" href="#">Welcome to alarmdecoder&#8217;s documentation!</a><ul>
+<li><a class="reference internal" href="#">Welcome to Alarm Decoder&#8217;s documentation!</a><ul>
 </ul>
 </li>
 <li><a class="reference internal" href="#indices-and-tables">Indices and tables</a></li>

docs/index.rst

@@ -3,17 +3,50 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to alarmdecoder's documentation!
+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 <http://github.com/nutechsoftware/alarmdecoder>`_.
-
 .. _Alarm Decoder: http://www.alarmdecoder.com
 .. _AD2USB: http://www.alarmdecoder.com
 .. _AD2SERIAL: http://www.alarmdecoder.com
 .. _AD2PI: http://www.alarmdecoder.com
+.. _examples: http://github.com/nutechsoftware/alarmdecoder/tree/master/examples
+
+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 <http://github.com/nutechsoftware/alarmdecoder>`_.
+
+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: