コード例 #1
0
ファイル: dionysus.py プロジェクト: junganghu/olympus
class Dionysus(Olympus):
  """Dionysus

  Concrete Class that implements Dionysus specific communication functions
  """

  def __init__(self, idVendor=0x0403, idProduct=0x8530, debug = False):
    Olympus.__init__(self, debug)
    self.vendor = idVendor
    self.product = idProduct
    self.dev = Ftdi()
    self._open_dev()

    self.name = "Dionysus"

  def __del__(self):
    self.dev.close()

  def _open_dev(self):
    """_open_dev
    
    Open an FTDI communication channel

    Args:
      Nothing

    Returns:
      Nothing

    Raises:
      Exception
    """
    frequency = 30.0E6
#Latency can go down t 2 but when set there is a small chance that there is a crash
    latency = 4
    self.dev.open(self.vendor, self.product, 0)
    # Drain input buffer
    self.dev.purge_buffers()

    # Reset
    # Enable MPSSE mode
    self.dev.set_bitmode(0x00, Ftdi.BITMODE_SYNCFF)
    # Configure clock

    frequency = self.dev._set_frequency(frequency)
    # Set latency timer
    self.dev.set_latency_timer(latency)
    # Set chunk size
    self.dev.write_data_set_chunksize(0x10000)
    self.dev.read_data_set_chunksize(0x10000)

    self.dev.set_flowctrl('hw')
    self.dev.purge_buffers()


  def read(self, device_id, address, length = 1, mem_device = False):
    """read

    read data from the Olympus image

    Args:
      device_id: Device identification number, found in the DRT
      address: Address of the register/memory to read
      mem_device: True if the device is on the memory bus
      length: Number of 32 bit words to read from the FPGA

    Returns:
      A byte array containing the raw data returned from Olympus

    Raises:
      OlympusCommError
    """
    read_data = Array('B')

    write_data = Array('B', [0xCD, 0x02]) 
    if mem_device:
      if self.debug:
        print "memory device"
      write_data = Array ('B', [0xCD, 0x12])
  
    fmt_string = "%06X" % (length) 
    write_data.fromstring(fmt_string.decode('hex'))
    offset_string = "00"
    if not mem_device:
      offset_string = "%02X" % device_id

    write_data.fromstring(offset_string.decode('hex'))

    addr_string = "%06X" % address
    write_data.fromstring(addr_string.decode('hex'))
    if self.debug:
      print "data read string: " + str(write_data)

    self.dev.purge_buffers()
    self.dev.write_data(write_data)

    timeout = time.time() + self.read_timeout
    rsp = Array('B')
    while time.time() < timeout:
      response = self.dev.read_data(1)
      if len(response) > 0:
        rsp = Array('B')
        rsp.fromstring(response)
        if rsp[0] == 0xDC:
          if self.debug:
            print "Got a response"  
          break

    if len(rsp) > 0:
      if rsp[0] != 0xDC:
        if self.debug:
          print "Response not found"  
        raise OlympusCommError("Did not find identification byte (0xDC): %s" % str(rsp))
    else:
      if self.debug:      
        print "No Response found"
      raise OlympusCommError("Timeout while waiting for a response")

    #I need to watch out for the modem status bytes
    read_count = 0
    response = Array('B')
    rsp = Array('B')
    timeout = time.time() + self.read_timeout

    while (time.time() < timeout) and (read_count < (length * 4 + 8)):
      response = self.dev.read_data((length * 4 + 8 ) - read_count)
      temp  = Array('B')
      temp.fromstring(response)
      #print "temp: %s", str(temp)
      if (len(temp) > 0):
        rsp += temp
        read_count = len(rsp)
    
    if self.debug:
      print "read length = %d, total length = %d" % (len(rsp), (length * 4 + 8))
      print "time left on timeout: %d" % (timeout - time.time())

    if self.debug:
      print "response length: " + str(length * 4 + 8)
      print "response status:\n\t" + str(rsp[:8])
      print "response data:\n" + str(rsp[8:])

    return rsp[8:]
    

  def write(self, device_id, address, data=None, mem_device = False):
    """write

    Write data to an Olympus image

    Args:
      device_id: Device identification number, found in the DRT
      address: Address of the register/memory to read
      mem_device: True if the device is on the memory bus
      data: Array of raw bytes to send to the device

    Returns:
      Nothing

    Raises:
      OlympusCommError
    """
    length = len(data) / 4

    # ID 01 NN NN NN OO AA AA AA DD DD DD DD
      # ID = ID BYTE (0xCD)
      # 01 = Write Command
      # NN = Size of write (3 bytes)
      # OO = Offset of device
      # AA = Address (4 bytes)
      # DD = Data (4 bytes)

    #create an array with the identification byte (0xCD)
    #and code for write (0x01)

    data_out = Array('B', [0xCD, 0x01]) 
    if mem_device:
      if self.debug:
        print "memory device"
      data_out = Array ('B', [0xCD, 0x11])
    
    """
    print "write command:\n\t" + str(data_out[:9])
    for i in range (0, len(data_out)):
      print str(hex(data_out[i])) + ", ",
    print " "
    """

 

    #append the length into the frist 32 bits
    fmt_string = "%06X" % (length) 
    data_out.fromstring(fmt_string.decode('hex'))
    offset_string = "00"
    if not mem_device:
      offset_string = "%02X" % device_id
    data_out.fromstring(offset_string.decode('hex'))
    addr_string = "%06X" % address
    data_out.fromstring(addr_string.decode('hex'))
    
    data_out.extend(data)

    """
    #if (self.debug):
    print "data write string:\n"
    print "write command:\n\t" + str(data_out[:9])
    for i in range (0, 9):
      print str(hex(data_out[i])) + ", ",
    print " "
    """


    #print "write data:\n" + str(data_out[9:])

    #avoid the akward stale bug
    self.dev.purge_buffers()

    self.dev.write_data(data_out)
    rsp = Array('B')

    timeout = time.time() + self.read_timeout
    while time.time() < timeout:
      response = self.dev.read_data(1)
      if len(response) > 0:
        rsp = Array('B')
        rsp.fromstring(response)
        if rsp[0] == 0xDC:
          if self.debug:
            print "Got a response"  
          break

    if (len(rsp) > 0):
      if rsp[0] != 0xDC:
        if self.debug:
          print "Response not found"  
        raise OlympusCommError("Did not find identification byte (0xDC): %s" % str(rsp))

    else:
      if self.debug:
        print "No Response"
      raise OlympusCommError("Timeout while waiting for a response")

    response = self.dev.read_data(8)
    rsp = Array('B')
    rsp.fromstring(response)

    if self.debug:
      print "Response: " + str(rsp)

  def ping(self):
    """ping

    Pings the Olympus image

    Args:
      Nothing

    Returns:
      Nothing

    Raises:
      OlympusCommError
    """
    data = Array('B')
    data.extend([0XCD, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]);
    if self.debug:
      print "Sending ping...",
    self.dev.write_data(data)
    rsp = Array('B')
    temp = Array('B')

    timeout = time.time() + self.read_timeout

    while time.time() < timeout:
      response = self.dev.read_data(5)
      if self.debug:
        print ".",
      rsp = Array('B')
      rsp.fromstring(response)
      temp.extend(rsp)
      if 0xDC in rsp:
        if self.debug:
          print "Got a response"  
          print "Response: %s" % str(temp)
        break

    if not 0xDC in rsp:
      if self.debug:
        print "ID byte not found in response"  
        print "temp: " + str(temp)
      raise OlympusCommError("Ping response did not contain ID: %s" % str(temp))

    index  = rsp.index(0xDC) + 1

    read_data = Array('B')
    read_data.extend(rsp[index:])
    num = 3 - index
    read_data.fromstring(self.dev.read_data(num))
    if self.debug:
      print "Success!"
    return


  def reset(self):
    """reset

    Software reset the Olympus FPGA Master, this may not actually reset the
    entire FPGA image

    Args:
      Nothing

    Returns:
      Nothing

    Raises:
      OlympusCommError: A failure of communication is detected
    """
    data = Array('B')
    data.extend([0XCD, 0x03, 0x00, 0x00, 0x00]);
    if self.debug:
      print "Sending reset..."
    self.dev.purge_buffers()
    self.dev.write_data(data)

  def dump_core(self):
    """dump_core

    reads the state of the wishbone master prior to a reset, useful for
    debugging

    Args:
      Nothing

    Returns:
      Array of 32-bit values to be parsed by core_analyzer

    Raises:
      AssertionError: This function must be overriden by a board specific
      implementation
      OlympusCommError: A failure of communication is detected
    """

    data = Array('B')
    data.extend([0xCD, 0x0F, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]);
    print "Sending core dump request..."

    self.dev.purge_buffers()
    self.dev.write_data(data)

    core_dump = Array('L')
    wait_time = 5
    timeout = time.time() + wait_time

    temp = Array ('B')
    while time.time() < timeout:
      response = self.dev.read_data(1)
      rsp = Array('B')
      rsp.fromstring(response)
      temp.extend(rsp)
      if 0xDC in rsp:
        print "Got a response"  
        break

    if not 0xDC in rsp:
      print "Response not found"  
      raise OlympusCommError("Response Not Found")

    rsp = Array('B')
    read_total = 4
    read_count = len(rsp)

    #get the number of items from the address
    timeout = time.time() + wait_time
    while (time.time() < timeout) and (read_count < read_total):
      response = self.dev.read_data(read_total - read_count)
      temp  = Array('B')
      temp.fromstring(response)
      if (len(temp) > 0):
        rsp += temp
        read_count = len(rsp)

    print "Length of read: %d" % len(rsp)
    print "Data: %s" % str(rsp)
    count  = ( rsp[1] << 16 | rsp[2] << 8 | rsp[3]) * 4
    print "Number of core registers: %d" % (count / 4)

    #get the core dump data
    timeout = time.time() + wait_time
    read_total  = count
    read_count  = 0
    temp = Array ('B')
    rsp = Array('B')
    while (time.time() < timeout) and (read_count < read_total):
      response = self.dev.read_data(read_total - read_count)
      temp  = Array('B')
      temp.fromstring(response)
      if (len(temp) > 0):
        rsp += temp
        read_count = len(rsp)

    print "Length read: %d" % (len(rsp) / 4)
    print "Data: %s" % str(rsp)
    core_data = Array('L')
    for i in range (0, count, 4):
      print "count: %d" % i
      core_data.append(rsp[i] << 24 | rsp[i + 1] << 16 | rsp[i + 2] << 8 | rsp[i + 3])
    
    #if self.debug:
    print "core data: " + str(core_data)

    return core_data



 

  def wait_for_interrupts(self, wait_time = 1):
    """wait_for_interrupts
    
    listen for interrupts for the specified amount of time

    Args:
      wait_time: the amount of time in seconds to wait for an interrupt

    Returns:
      True: Interrupts were detected
      False: No interrupts detected

    Raises:
      Nothing
    """
    timeout = time.time() + wait_time

    temp = Array ('B')
    while time.time() < timeout:
      response = self.dev.read_data(1)
      rsp = Array('B')
      rsp.fromstring(response)
      temp.extend(rsp)
      if 0xDC in rsp:
        if self.debug:
          print "Got a response"  
        break

    if not 0xDC in rsp:
      if self.debug:
        print "Response not found"  
      return False

    read_total = 9
    read_count = len(rsp)

    #print "read_count: %s" % str(rsp)
    while (time.time() < timeout) and (read_count < read_total):
      response = self.dev.read_data(read_total - read_count)
      temp  = Array('B')
      temp.fromstring(response)
      #print "temp: %s", str(temp)
      if (len(temp) > 0):
        rsp += temp
        read_count = len(rsp)

    #print "read_count: %s" % str(rsp)
   

    index  = rsp.index(0xDC) + 1

    read_data = Array('B')
    read_data.extend(rsp[index:])
    #print "read_data: " + str(rsp)

    self.interrupts = read_data[-4] << 24 | read_data[-3] << 16 | read_data[-2] << 8 | read_data[-1]
    
    if self.debug:
      print "interrupts: " + str(self.interrupts)
    return True


  def comm_debug(self):
    """comm_debug

    A function that the end user will probably not interract with
    This is here to simply debug a communication medium

    Args:
      Nothing

    Returns:
      Nothing

    Raises:
      Nothing
    """
    #self.dev.set_dtr_rts(True, True)
    #self.dev.set_dtr(False)
    print "CTS: " + str(self.dev.get_cts())
#    print "DSR: " + str(self.dev.get_dsr())
    s1 = self.dev.modem_status()
    print "S1: " + str(s1)
コード例 #2
0
class USBDevice(Device):
    """
    `AD2USB`_ device utilizing PyFTDI's interface.
    """

    # Constants
    PRODUCT_IDS = ((0x0403, 0x6001), (0x0403, 0x6015))
    """List of Vendor and Product IDs used to recognize `AD2USB`_ devices."""
    DEFAULT_VENDOR_ID = PRODUCT_IDS[0][0]
    """Default Vendor ID used to recognize `AD2USB`_ devices."""
    DEFAULT_PRODUCT_ID = PRODUCT_IDS[0][1]
    """Default Product ID used to recognize `AD2USB`_ devices."""

    # Deprecated constants
    FTDI_VENDOR_ID = DEFAULT_VENDOR_ID
    """DEPRECATED: Vendor ID used to recognize `AD2USB`_ devices."""
    FTDI_PRODUCT_ID = DEFAULT_PRODUCT_ID
    """DEPRECATED: Product ID used to recognize `AD2USB`_ devices."""

    BAUDRATE = 115200
    """Default baudrate for `AD2USB`_ devices."""

    __devices = []
    __detect_thread = None

    @classmethod
    def find_all(cls, vid=None, pid=None):
        """
        Returns all FTDI devices matching our vendor and product IDs.

        :returns: list of devices
        :raises: :py:class:`~alarmdecoder.util.CommError`
        """
        if not have_pyftdi:
            raise ImportError(
                'The USBDevice class has been disabled due to missing requirement: pyftdi or pyusb.'
            )

        cls.__devices = []

        query = cls.PRODUCT_IDS
        if vid and pid:
            query = [(vid, pid)]

        try:
            cls.__devices = Ftdi.find_all(query, nocache=True)

        except (usb.core.USBError, FtdiError) as err:
            raise CommError(
                'Error enumerating AD2USB devices: {0}'.format(str(err)), err)

        return cls.__devices

    @classmethod
    def devices(cls):
        """
        Returns a cached list of `AD2USB`_ devices located on the system.

        :returns: cached list of devices found
        """
        return cls.__devices

    @classmethod
    def find(cls, device=None):
        """
        Factory method that returns the requested :py:class:`USBDevice` device, or the
        first device.

        :param device: Tuple describing the USB device to open, as returned
                       by find_all().
        :type device: tuple

        :returns: :py:class:`USBDevice` object utilizing the specified device
        :raises: :py:class:`~alarmdecoder.util.NoDeviceError`
        """
        if not have_pyftdi:
            raise ImportError(
                'The USBDevice class has been disabled due to missing requirement: pyftdi or pyusb.'
            )

        cls.find_all()

        if len(cls.__devices) == 0:
            raise NoDeviceError('No AD2USB devices present.')

        if device is None:
            device = cls.__devices[0]

        vendor, product, sernum, ifcount, description = device

        return USBDevice(interface=sernum, vid=vendor, pid=product)

    @classmethod
    def start_detection(cls, on_attached=None, on_detached=None):
        """
        Starts the device detection thread.

        :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  **Callback definition:** *def callback(thread, device)*

        :type on_detached: function
        """
        if not have_pyftdi:
            raise ImportError(
                'The USBDevice class has been disabled due to missing requirement: pyftdi or pyusb.'
            )

        cls.__detect_thread = USBDevice.DetectThread(on_attached, on_detached)

        try:
            cls.find_all()
        except CommError:
            pass

        cls.__detect_thread.start()

    @classmethod
    def stop_detection(cls):
        """
        Stops the device detection thread.
        """
        if not have_pyftdi:
            raise ImportError(
                'The USBDevice class has been disabled due to missing requirement: pyftdi or pyusb.'
            )

        try:
            cls.__detect_thread.stop()

        except Exception:
            pass

    @property
    def interface(self):
        """
        Retrieves the interface used to connect to the device.

        :returns: the interface used to connect to the device
        """
        return self._interface

    @interface.setter
    def interface(self, value):
        """
        Sets the interface used to connect to the device.

        :param value: may specify either the serial number or the device index
        :type value: string or int
        """
        self._interface = value
        if isinstance(value, int):
            self._device_number = value
        else:
            self._serial_number = value

    @property
    def serial_number(self):
        """
        Retrieves the serial number of the device.

        :returns: serial number of the device
        """

        return self._serial_number

    @serial_number.setter
    def serial_number(self, value):
        """
        Sets the serial number of the device.

        :param value: serial number of the device
        :type value: string
        """
        self._serial_number = value

    @property
    def description(self):
        """
        Retrieves the description of the device.

        :returns: description of the device
        """
        return self._description

    @description.setter
    def description(self, value):
        """
        Sets the description of the device.

        :param value: description of the device
        :type value: string
        """
        self._description = value

    def __init__(self, interface=0, vid=None, pid=None):
        """
        Constructor

        :param interface: May specify either the serial number or the device
                          index.
        :type interface: string or int
        """
        if not have_pyftdi:
            raise ImportError(
                'The USBDevice class has been disabled due to missing requirement: pyftdi or pyusb.'
            )

        Device.__init__(self)

        self._device = Ftdi()

        self._interface = 0
        self._device_number = 0
        self._serial_number = None

        self._vendor_id = USBDevice.DEFAULT_VENDOR_ID
        if vid:
            self._vendor_id = vid

        self._product_id = USBDevice.DEFAULT_PRODUCT_ID
        if pid:
            self._product_id = pid

        self._endpoint = 0
        self._description = None

        self.interface = interface

    def open(self, baudrate=BAUDRATE, no_reader_thread=False):
        """
        Opens the device.

        :param baudrate: baudrate to use
        :type baudrate: int
        :param no_reader_thread: whether or not to automatically start the
                                 reader thread.
        :type no_reader_thread: bool

        :raises: :py:class:`~alarmdecoder.util.NoDeviceError`
        """
        # Set up defaults
        if baudrate is None:
            baudrate = USBDevice.BAUDRATE

        self._read_thread = Device.ReadThread(self)

        # Open the device and start up the thread.
        try:
            self._device.open(self._vendor_id, self._product_id,
                              self._endpoint, self._device_number,
                              self._serial_number, self._description)

            self._device.set_baudrate(baudrate)

            if not self._serial_number:
                self._serial_number = self._get_serial_number()

            self._id = self._serial_number

        except (usb.core.USBError, FtdiError) as err:
            raise NoDeviceError('Error opening device: {0}'.format(str(err)),
                                err)

        except KeyError as err:
            raise NoDeviceError(
                'Unsupported device. ({0:04x}:{1:04x})  You probably need a newer version of pyftdi.'
                .format(err[0][0], err[0][1]))

        else:
            self._running = True
            self.on_open()

            if not no_reader_thread:
                self._read_thread.start()

        return self

    def close(self):
        """
        Closes the device.
        """
        try:
            Device.close(self)

            # HACK: Probably should fork pyftdi and make this call in .close()
            self._device.usb_dev.attach_kernel_driver(self._device_number)

        except Exception:
            pass

    def fileno(self):
        """
        File number not supported for USB devices.
    
        :raises: NotImplementedError
        """
        raise NotImplementedError('USB devices do not support fileno()')

    def write(self, data):
        """
        Writes data to the device.

        :param data: data to write
        :type data: string

        :raises: :py:class:`~alarmdecoder.util.CommError`
        """
        try:
            self._device.write_data(data)

            self.on_write(data=data)

        except FtdiError as err:
            raise CommError('Error writing to device: {0}'.format(str(err)),
                            err)

    def read(self):
        """
        Reads a single character from the device.

        :returns: character read from the device
        :raises: :py:class:`~alarmdecoder.util.CommError`
        """
        ret = None

        try:
            ret = self._device.read_data(1)

        except (usb.core.USBError, FtdiError) as err:
            raise CommError('Error reading from device: {0}'.format(str(err)),
                            err)

        return ret

    def read_line(self, timeout=0.0, purge_buffer=False):
        """
        Reads a line from the device.

        :param timeout: read timeout
        :type timeout: float
        :param purge_buffer: Indicates whether to purge the buffer prior to
                             reading.
        :type purge_buffer: bool

        :returns: line that was read
        :raises: :py:class:`~alarmdecoder.util.CommError`, :py:class:`~alarmdecoder.util.TimeoutError`
        """
        def timeout_event():
            """Handles read timeout event"""
            timeout_event.reading = False

        timeout_event.reading = True

        if purge_buffer:
            self._buffer = b''

        got_line, ret = False, None

        timer = threading.Timer(timeout, timeout_event)
        if timeout > 0:
            timer.start()

        try:
            while timeout_event.reading:
                buf = self._device.read_data(1)

                if buf != b'':
                    ub = bytes_hack(buf)

                    self._buffer += ub

                    if ub == b"\n":
                        self._buffer = self._buffer.rstrip(b"\r\n")

                        if len(self._buffer) > 0:
                            got_line = True
                            break
                else:
                    time.sleep(0.01)

        except (usb.core.USBError, FtdiError) as err:
            raise CommError('Error reading from device: {0}'.format(str(err)),
                            err)

        else:
            if got_line:
                ret, self._buffer = self._buffer, b''

                self.on_read(data=ret)

            else:
                raise TimeoutError(
                    'Timeout while waiting for line terminator.')

        finally:
            timer.cancel()

        return ret

    def purge(self):
        """
        Purges read/write buffers.
        """
        self._device.purge_buffers()

    def _get_serial_number(self):
        """
        Retrieves the FTDI device serial number.

        :returns: string containing the device serial number
        """
        return usb.util.get_string(self._device.usb_dev, 64,
                                   self._device.usb_dev.iSerialNumber)

    class DetectThread(threading.Thread):
        """
        Thread that handles detection of added/removed devices.
        """
        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  **Callback definition:** *def callback(thread, device)*
            :type on_attached: function
            :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)

            if on_attached:
                self.on_attached += on_attached

            if on_detached:
                self.on_detached += on_detached

            self._running = False

        def stop(self):
            """
            Stops the thread.
            """
            self._running = False

        def run(self):
            """
            The actual detection process.
            """
            self._running = True

            last_devices = set()

            while self._running:
                try:
                    current_devices = set(USBDevice.find_all())

                    for dev in current_devices.difference(last_devices):
                        self.on_attached(device=dev)

                    for dev in last_devices.difference(current_devices):
                        self.on_detached(device=dev)

                    last_devices = current_devices

                except CommError:
                    pass

                time.sleep(0.25)
コード例 #3
0
class USBDevice(Device):
    """
    `AD2USB`_ device utilizing PyFTDI's interface.
    """

    # Constants
    PRODUCT_IDS = ((0x0403, 0x6001), (0x0403, 0x6015))
    """List of Vendor and Product IDs used to recognize `AD2USB`_ devices."""
    DEFAULT_VENDOR_ID = PRODUCT_IDS[0][0]
    """Default Vendor ID used to recognize `AD2USB`_ devices."""
    DEFAULT_PRODUCT_ID = PRODUCT_IDS[0][1]
    """Default Product ID used to recognize `AD2USB`_ devices."""

    # Deprecated constants
    FTDI_VENDOR_ID = DEFAULT_VENDOR_ID
    """DEPRECATED: Vendor ID used to recognize `AD2USB`_ devices."""
    FTDI_PRODUCT_ID = DEFAULT_PRODUCT_ID
    """DEPRECATED: Product ID used to recognize `AD2USB`_ devices."""


    BAUDRATE = 115200
    """Default baudrate for `AD2USB`_ devices."""

    __devices = []
    __detect_thread = None

    @classmethod
    def find_all(cls, vid=None, pid=None):
        """
        Returns all FTDI devices matching our vendor and product IDs.

        :returns: list of devices
        :raises: :py:class:`~alarmdecoder.util.CommError`
        """
        if not have_pyftdi:
            raise ImportError('The USBDevice class has been disabled due to missing requirement: pyftdi or pyusb.')

        cls.__devices = []

        query = cls.PRODUCT_IDS
        if vid and pid:
            query = [(vid, pid)]

        try:
            cls.__devices = Ftdi.find_all(query, nocache=True)

        except (usb.core.USBError, FtdiError) as err:
            raise CommError('Error enumerating AD2USB devices: {0}'.format(str(err)), err)

        return cls.__devices

    @classmethod
    def devices(cls):
        """
        Returns a cached list of `AD2USB`_ devices located on the system.

        :returns: cached list of devices found
        """
        return cls.__devices

    @classmethod
    def find(cls, device=None):
        """
        Factory method that returns the requested :py:class:`USBDevice` device, or the
        first device.

        :param device: Tuple describing the USB device to open, as returned
                       by find_all().
        :type device: tuple

        :returns: :py:class:`USBDevice` object utilizing the specified device
        :raises: :py:class:`~alarmdecoder.util.NoDeviceError`
        """
        if not have_pyftdi:
            raise ImportError('The USBDevice class has been disabled due to missing requirement: pyftdi or pyusb.')

        cls.find_all()

        if len(cls.__devices) == 0:
            raise NoDeviceError('No AD2USB devices present.')

        if device is None:
            device = cls.__devices[0]

        vendor, product, sernum, ifcount, description = device

        return USBDevice(interface=sernum, vid=vendor, pid=product)

    @classmethod
    def start_detection(cls, on_attached=None, on_detached=None):
        """
        Starts the device detection thread.

        :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  **Callback definition:** *def callback(thread, device)*

        :type on_detached: function
        """
        if not have_pyftdi:
            raise ImportError('The USBDevice class has been disabled due to missing requirement: pyftdi or pyusb.')

        cls.__detect_thread = USBDevice.DetectThread(on_attached, on_detached)

        try:
            cls.find_all()
        except CommError:
            pass

        cls.__detect_thread.start()

    @classmethod
    def stop_detection(cls):
        """
        Stops the device detection thread.
        """
        if not have_pyftdi:
            raise ImportError('The USBDevice class has been disabled due to missing requirement: pyftdi or pyusb.')

        try:
            cls.__detect_thread.stop()

        except Exception:
            pass

    @property
    def interface(self):
        """
        Retrieves the interface used to connect to the device.

        :returns: the interface used to connect to the device
        """
        return self._interface

    @interface.setter
    def interface(self, value):
        """
        Sets the interface used to connect to the device.

        :param value: may specify either the serial number or the device index
        :type value: string or int
        """
        self._interface = value
        if isinstance(value, int):
            self._device_number = value
        else:
            self._serial_number = value

    @property
    def serial_number(self):
        """
        Retrieves the serial number of the device.

        :returns: serial number of the device
        """

        return self._serial_number

    @serial_number.setter
    def serial_number(self, value):
        """
        Sets the serial number of the device.

        :param value: serial number of the device
        :type value: string
        """
        self._serial_number = value

    @property
    def description(self):
        """
        Retrieves the description of the device.

        :returns: description of the device
        """
        return self._description

    @description.setter
    def description(self, value):
        """
        Sets the description of the device.

        :param value: description of the device
        :type value: string
        """
        self._description = value

    def __init__(self, interface=0, vid=None, pid=None):
        """
        Constructor

        :param interface: May specify either the serial number or the device
                          index.
        :type interface: string or int
        """
        if not have_pyftdi:
            raise ImportError('The USBDevice class has been disabled due to missing requirement: pyftdi or pyusb.')

        Device.__init__(self)

        self._device = Ftdi()

        self._interface = 0
        self._device_number = 0
        self._serial_number = None

        self._vendor_id = USBDevice.DEFAULT_VENDOR_ID
        if vid:
            self._vendor_id = vid

        self._product_id = USBDevice.DEFAULT_PRODUCT_ID
        if pid:
            self._product_id = pid

        self._endpoint = 0
        self._description = None

        self.interface = interface

    def open(self, baudrate=BAUDRATE, no_reader_thread=False):
        """
        Opens the device.

        :param baudrate: baudrate to use
        :type baudrate: int
        :param no_reader_thread: whether or not to automatically start the
                                 reader thread.
        :type no_reader_thread: bool

        :raises: :py:class:`~alarmdecoder.util.NoDeviceError`
        """
        # Set up defaults
        if baudrate is None:
            baudrate = USBDevice.BAUDRATE

        self._read_thread = Device.ReadThread(self)

        # Open the device and start up the thread.
        try:
            self._device.open(self._vendor_id,
                              self._product_id,
                              self._endpoint,
                              self._device_number,
                              self._serial_number,
                              self._description)

            self._device.set_baudrate(baudrate)

            if not self._serial_number:
                self._serial_number = self._get_serial_number()

            self._id = self._serial_number

        except (usb.core.USBError, FtdiError) as err:
            raise NoDeviceError('Error opening device: {0}'.format(str(err)), err)

        except KeyError as err:
            raise NoDeviceError('Unsupported device. ({0:04x}:{1:04x})  You probably need a newer version of pyftdi.'.format(err[0][0], err[0][1]))

        else:
            self._running = True
            self.on_open()

            if not no_reader_thread:
                self._read_thread.start()

        return self

    def close(self):
        """
        Closes the device.
        """
        try:
            Device.close(self)

            # HACK: Probably should fork pyftdi and make this call in .close()
            self._device.usb_dev.attach_kernel_driver(self._device_number)

        except Exception:
            pass

    def fileno(self):
        """
        File number not supported for USB devices.
    
        :raises: NotImplementedError
        """
        raise NotImplementedError('USB devices do not support fileno()')

    def write(self, data):
        """
        Writes data to the device.

        :param data: data to write
        :type data: string

        :raises: :py:class:`~alarmdecoder.util.CommError`
        """
        try:
            self._device.write_data(data)

            self.on_write(data=data)

        except FtdiError as err:
            raise CommError('Error writing to device: {0}'.format(str(err)), err)

    def read(self):
        """
        Reads a single character from the device.

        :returns: character read from the device
        :raises: :py:class:`~alarmdecoder.util.CommError`
        """
        ret = None

        try:
            ret = self._device.read_data(1)

        except (usb.core.USBError, FtdiError) as err:
            raise CommError('Error reading from device: {0}'.format(str(err)), err)

        return ret

    def read_line(self, timeout=0.0, purge_buffer=False):
        """
        Reads a line from the device.

        :param timeout: read timeout
        :type timeout: float
        :param purge_buffer: Indicates whether to purge the buffer prior to
                             reading.
        :type purge_buffer: bool

        :returns: line that was read
        :raises: :py:class:`~alarmdecoder.util.CommError`, :py:class:`~alarmdecoder.util.TimeoutError`
        """

        def timeout_event():
            """Handles read timeout event"""
            timeout_event.reading = False
        timeout_event.reading = True

        if purge_buffer:
            self._buffer = b''

        got_line, ret = False, None

        timer = threading.Timer(timeout, timeout_event)
        if timeout > 0:
            timer.start()

        try:
            while timeout_event.reading:
                buf = self._device.read_data(1)

                if buf != b'':
                    ub = bytes_hack(buf)

                    self._buffer += ub

                    if ub == b"\n":
                        self._buffer = self._buffer.rstrip(b"\r\n")

                        if len(self._buffer) > 0:
                            got_line = True
                            break
                else:
                    time.sleep(0.01)

        except (usb.core.USBError, FtdiError) as err:
            raise CommError('Error reading from device: {0}'.format(str(err)), err)

        else:
            if got_line:
                ret, self._buffer = self._buffer, b''

                self.on_read(data=ret)

            else:
                raise TimeoutError('Timeout while waiting for line terminator.')

        finally:
            timer.cancel()

        return ret

    def purge(self):
        """
        Purges read/write buffers.
        """
        self._device.purge_buffers()

    def _get_serial_number(self):
        """
        Retrieves the FTDI device serial number.

        :returns: string containing the device serial number
        """
        return usb.util.get_string(self._device.usb_dev, 64, self._device.usb_dev.iSerialNumber)

    class DetectThread(threading.Thread):
        """
        Thread that handles detection of added/removed devices.
        """
        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  **Callback definition:** *def callback(thread, device)*
            :type on_attached: function
            :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)

            if on_attached:
                self.on_attached += on_attached

            if on_detached:
                self.on_detached += on_detached

            self._running = False

        def stop(self):
            """
            Stops the thread.
            """
            self._running = False

        def run(self):
            """
            The actual detection process.
            """
            self._running = True

            last_devices = set()

            while self._running:
                try:
                    current_devices = set(USBDevice.find_all())

                    for dev in current_devices.difference(last_devices):
                        self.on_attached(device=dev)

                    for dev in last_devices.difference(current_devices):
                        self.on_detached(device=dev)

                    last_devices = current_devices

                except CommError:
                    pass

                time.sleep(0.25)