Merge pull request #53 from bp1222/break-modes-add-tornado

Break out thread implementation, add Tornado Support

Author: mattdodge

.travis.yml

@@ -3,5 +3,7 @@ python:
   - "2.7"
   - "3.4"
   - "3.5"
+install:
+    pip install -e .[tornado]
 # command to run tests
-script: nosetests
+script: py.test

README.rst

@@ -59,6 +59,13 @@ in the root of the source tree:
 
 This will automatically install the package for you.
 
+Install with Tornado Support
+----------------------------
+
+::
+    pip install xbee[tornado]
+
+
 Documentation
 =============
 
@@ -80,7 +87,9 @@ PySerial
 Additional Dependencies
 -----------------------
 
-To run automated tests: `Nose <https://github.com/nose-devs/nose/>`_
+If wanting to use the Tornado IOLoop: `Tornado <http://www.tornadoweb.org/>`_
+
+To run automated tests: `pytest <https://docs.pytest.org>`_
 
 To build the documentation: `Sphinx <http://sphinx-doc.org/>`_
 
@@ -101,3 +110,4 @@ Contributors
 * Amit Synderman
 * Marco Sangalli
 * James Saunders james@saunders-family.net
+* David Walker dwalker@n.io

docs/source/index.rst

@@ -42,7 +42,12 @@ Usage
    must be enabled. For instructions about how to do this, see
    the documentation for your XBee device.
 
-Synchonous Mode
+.. note::
+    The default implementation of the python-xbee library is to 
+    use threads.  There is an implementation that utilizes the
+    Tornado IOLoop, if imported.
+
+Threaded Synchonous Mode
 ~~~~~~~~~~~~~~~
 
 The following code demonstrates a minimal use-case for the
@@ -67,7 +72,7 @@ print out any data frames which arrive from a connected XBee
 device. Be aware that wait_read_frame() will block until
 a valid frame is received from the associated XBee device.
 
-Asynchronous Mode
+Threaded Asynchronous Mode
 ~~~~~~~~~~~~~~~~~
 
 The xbee package is used only slightly differently when 
@@ -110,6 +115,46 @@ to handle receiving and processing incoming data from an
 XBee device. This example is functionally equivalent to the non-asyncronous
 example above.
 
+Tornado IOLoop
+~~~~~~~~~~~~~~~~~~
+Tornado provides a simple and easy to use IOLoop for asynchronous listening
+for XBee communications.  The library usage is seemingly identical to the
+threaded implementation, excepting importing and yielding.  The example
+highlights the key differences::
+
+    import serial
+    from tornado import ioloop, gen
+    from xbee.tornado import XBee
+
+    serial_port = serial.Serial('/dev/ttyUSB0', 9600)
+
+    def print_data(data):
+        """
+        This method is called whenever data is received
+        from the associated XBee device. Its first and
+        only argument is the data contained within the
+        frame.
+        """
+        print data
+
+    @gen.coroutine
+    def main():
+        xbee = XBee(serial_port, callback=print_data)
+
+        try:
+            while True:
+                yield gen.sleep(0.001)
+        except KeyboardInterrupt:
+            ioloop.IOLoop.current().stop()
+        finally
+            xbee.halt()
+            serial_port.close()
+
+    ioloop.IOLoop.current().spawn_callback(main)
+    ioloop.IOLoop.current().start()
+    ioloop.IOLoop.current().close()
+
+
 Additional Examples
 ~~~~~~~~~~~~~~~~~~~
 

examples/alarm.py

@@ -6,11 +6,11 @@
 By Paul Malmsten, 2010
 pmalmsten@gmail.com
 
-This module will communicate with a remote XBee device in order to 
+This module will communicate with a remote XBee device in order to
 implement a simple alarm clock with bed occupancy detection.
 """
 import serial
-from xbee import XBee
+from xbee.thread import XBee
 
 class DataSource(object):
     """
@@ -20,133 +20,133 @@ class DataSource(object):
     def next_alarm_time(self, current_time):
         """
         next_alarm_time: datetime -> datetime
-        
+
         Returns the next time at which the alarm should activate
         """
         raise NotImplemented()
-        
+
 class AlarmDevice(object):
     """
-    Represents alarm harware, such as input and output to an from 
+    Represents alarm harware, such as input and output to an from
     the real world
     """
-    
+
     def __init__(self, hw):
         self.hw = hw
-        
+
     def activate(self):
         """
         activate: None -> None
-        
+
         Activates noise-making features
         """
         raise NotImplementedError()
-        
+
     def deactivate(self):
         """
         deactivate: None -> None
-        
+
         Deactivates noise-making features
         """
         raise NotImplementedError()
-        
+
     def bed_occupied(self):
         """
         bed_occupied: None -> Boolean
-        
+
         Determines whether the bed is currently occupied
         """
         raise NotImplementedError()
-        
+
 class WakeupRoutine(object):
     """
     Represents a process by which a user should be awoken with a
     particular AlarmDevice
     """
-    
+
     def __init__(self, device):
         self.device = device
-        
+
     def trigger(self):
         """
         trigger: None -> None
-        
-        Begins the specified wakeup process with the given hardware 
+
+        Begins the specified wakeup process with the given hardware
         device. Does not relinquish control until the wakeup process is
         complete.
         """
         raise NotImplementedError()
-        
+
 # ================= Custom Classes =============================
 
 class TestSource(DataSource):
     def __init__(self, time):
         super(TestSource, self).__init__()
         self.next_time = time
-    
+
     def next_alarm_time(self, current_time):
         return self.next_time
-        
+
 class XBeeAlarm(AlarmDevice):
     DETECT_THRESH = 350
-    
+
     def __init__(self, serial_port, remote_addr):
         # Open serial port, construct XBee1, configure remote device,
         # store as hardware
         self.remote_addr = remote_addr
-        
+
         ser = serial.Serial(serial_port)
         xbee = XBee(ser)
-        
+
         super(XBeeAlarm, self).__init__(xbee)
-        
+
         # Reset remote device
         self._reset()
-        
+
     def _reset(self):
         """
         reset: None -> None
-        
+
         Resets the remote XBee device to a standard configuration
         """
         # Analog pin 0
         self.hw.remote_at(
             dest_addr=self.remote_addr,
             command='D0',
             parameter='\x02')
-        
+
         # Disengage remote LED, buzzer
         self.deactivate()
         self._set_send_samples(False)
-            
+
     def _set_LED(self, status):
         """
         _set_LED: boolean -> None
-        
+
         Sets the status of the remote LED
         """
         # DIO pin 1 (LED), active low
         self.hw.remote_at(
             dest_addr=self.remote_addr,
             command='D1',
             parameter='\x04' if status else '\x05')
-            
+
     def _set_buzzer(self, status):
         """
         _set_buzzer: boolean -> None
-        
+
         Sets the status of the remote buzzer
         """
         # DIO pin 1 (LED), active low
         self.hw.remote_at(
             dest_addr=self.remote_addr,
             command='D2',
             parameter='\x05' if status else '\x04')
-            
+
     def _set_send_samples(self, status):
         """
         _set_send_samples: boolean -> None
-        
+
         Sets whether the remote device will send data samples once every
         second.
         """
@@ -159,83 +159,83 @@ def _set_send_samples(self, status):
     def activate(self):
         """
         activate: None -> None
-        
+
         Remote XBee starts making noise and turns on LED
         """
         self._set_LED(True)
         self._set_buzzer(True)
-        
+
     def deactivate(self):
         """
         activate: None -> None
-        
+
         Remote XBee starts making noise and turns on LED
         """
         self._set_LED(False)
         self._set_buzzer(False)
-        
+
     def bed_occupied(self):
         """
         bed_occupied: None -> boolean
-        
+
         Determines whether the bed is currently occupied by requesting
         data from the remote XBee and comparing the analog value with
         a threshold.
         """
-        
+
         # Receive samples from the remote device
         self._set_send_samples(True)
-        
+
         while True:
             packet = self.hw.wait_read_frame()
-            
+
             if 'adc-0' in packet['samples'][0]:
                 # Stop receiving samples from the remote device
                 self._set_send_samples(False)
                 return packet['samples'][0]['adc-0'] > XBeeAlarm.DETECT_THRESH
-                
-        
+
+
 class SimpleWakeupRoutine(WakeupRoutine):
     """
-    When triggered, activates the alarm if the bed is occupied. The 
+    When triggered, activates the alarm if the bed is occupied. The
     alarm continues until the bed is no longer occupied.
     """
-    
+
     def trigger(self):
         from time import sleep
-        
+
         pulse_delay = 0.1
-        
-        
+
+
         if self.device.bed_occupied():
              # Initial alarm
             for x in range(0, 5):
                 self.device.activate()
                 sleep(pulse_delay)
                 self.device.deactivate()
                 sleep(pulse_delay)
-            
+
             # Allow time to escape
             sleep(30)
-            
+
             # Extended alarm
             duration = 1
             pause = 10
-            
+
             while self.device.bed_occupied():
                 self.device.activate()
                 sleep(duration)
                 self.device.deactivate()
                 sleep(pause)
                 duration *= 2
-            
+
 def main():
     """
     Run through simple demonstration of alarm concept
     """
     alarm = XBeeAlarm('/dev/ttyUSB0', '\x56\x78')
     routine = SimpleWakeupRoutine(alarm)
-    
+
     from time import sleep
     while True:
         """