Commits

Ben Bass committed 1423675

in progress docs for serial and bitbang modes

  • Participants
  • Parent commits 58f8f40

Comments (0)

Files changed (3)

+Bit-bang mode
+=============
+
+Bit-bang mode allows the programmer direct access (both read and write) to the state of the IO lines from a compatible FTDI device.
+
+The interface provided by FTDI is intended to mirror the type of usage on a microcontroller, and is similar to the 'user port' on many old 8-bit computers such as the BBC Micro and Commodore 64.
+
+The basic model is to have two 8 bit ports - one for data, and one for 'direction'. The data port maps each of the 8 bits to 8 independent IO signals, each of which can be configured separately as an 'input' or an 'output'.
+
+In pylibftdi, the data port is given by the ``port`` attribute of a BitBangDevice instance, and the direction control is provided by the ``direction`` attribute. Both these attributes are implemented as Python properties, so no method calls are needed on them - simple read and write in Python-land converts to read and write in the physical world seen by the FTDI device.
+
+The direction register maps to 
+
+where each bit maps to a separate digital signal, 
+
+Read-Modify-Write
+-----------------
+
+Port vs Latch
+
+Via the augmented assignment operations, pylibftdi ``BitBangDevice`` instances support read-modify-write operations, such as arithmetic (``+=`` etc), bitwise (``&=``), and other logical operations such as shift (``<<=``)
+
+Examples
+~~~~~~~~
+
+::
+
+    >>> from pylibftdi import BitBangDevice
+    >>>
+    >>> with BitBangDevice('FTE00P4L') as bb:
+    ...     bb.direction = 0x0F  # four LSB are output(1), four MSB are input(0)
+    ...     bb.port |= 2         # set bit 1
+    ...     bb.port &= 0xFE      # clear bit 0
+
+
+    >>> with BitBangDevice() as bb:
+    ...     bb.port = 1
+    ...     while True:
+    ...         # Rotate the value in bb.port
+    ...         bb.port = ((bb.port << 1) | ((bb.port >> 8) & 1)) & 0xFF
+    ...         time.sleep(1)
+
+
+The `Bus` class
+---------------
+
+Dealing with bit masks and shifts gets messy quickly. Some languages such as C and C++ provide direct support for accessing bits - or series of consecutive bits - with bitfields. The ``Bus`` class provides the facility to provide a similar level of support to pylibftdi ``BitBangDevice`` classes.
+
+As an example, consider an HD44780 LCD display. These have a data channel of either 4 or 8 bits, and a number of additional status lines - ``rs`` which acts as a register select pin - indicating whether a data byte is a command (0) or data (1), and ``e`` - clock enable.::
+
+    class LCD(object):
+        """
+        The UM232R/245R is wired to the LCD as follows:
+           DB0..3 to LCD D4..D7 (pin 11..pin 14)
+           DB6 to LCD 'RS' (pin 4)
+           DB7 to LCD 'E' (pin 6)
+        """
+        data = Bus(0, 4)
+        rs = Bus(6)
+        e = Bus(7)
    quickstart
    installation
    basic_usage
+   bitbang
+   serial
    advanced_usage
    how_to
    troubleshooting
+Serial mode
+===========
+
+The default mode of pylibftdi devices is to behave as a serial UART device, similar to the 'COM1' device found on older PCs. Nowadays most PCs operate with serial devices over USB-serial adapters, which may often include their own FTDI chips. To remain compatible with the RS232 standard however, these adapters will often include level-shifting circuitry which is of no benefit in communicating with other circuits operating at the 3.3 or 5 volt levels the FTDI hardware uses.
+
+The default serial configuration is 9600 baud, 8 data bits, 1 stop bit and no parity (sometimes referred to as 8-N-1_). This is the default configuration of the old 'COM' devices back to the days of the original IBM PC and MS-DOS.
+
+.. _8-N-1: http://en.wikipedia.org/wiki/8-N-1
+
+
+Setting line parameters
+-----------------------
+
+Changing line parameters other than the baudrate is supported via use of the underlying FTDI function calls.
+
+
+
+Subclassing `Device` - A MIDI device
+------------------------------------
+
+To abstract application code from the details of any particular interface, it may be helpful to subclass the ``Device`` class, providing the required configuration in the ``__init__`` method to act in a certain way. For example, the MIDI_ protocol used by electronic music devices is an asynchronous serial protocol operating at 31250 baud, and with the same 8-N-1 parameters which pylibftdi defaults to.
+
+.. _MIDI: http://www.midi.org
+
+Creating a ``MidiDevice`` subclass of ``Device`` is straightforward::
+
+    class MidiDevice(Device):
+        "subclass of pylibftdi.Device configured for MIDI"
+
+        def __init__(self, *o, **k):
+            Device.__init__(self, *o, **k)
+            self.baudrate = 31250
+
+Note it is important that the superclass ``__init__`` is called first; calling it on an uninitialised ``Device`` would fail, and even if it succeeded, the superclass ``__init__`` method resets ``baudrate`` to 9600 anyway to ensure a consistent setup for devices which may have been previously used with different parameters.
+
+Use of the ``MidiDevice`` class is simple - as a pylibftdi Device instance, it provides a file-based API. Simply ``read()`` and ``write()`` the data to an instance of the class::
+
+    >>> m = MidiDevice()
+    >>> m.write('\x90\x80\x80')
+    >>> time.sleep(1)
+    >>> m.write('\x80\x00')
+