Ben Bass avatar Ben Bass committed f1b938e

documentation updates

Comments (0)

Files changed (14)

 *.pyo
 .idea
 build
-docs/_build
+doc/_build
 MANIFEST

doc/advanced_usage.rst

+Advanced Usage
+==============
+
+``libftdi`` function access
+---------------------------
+
+Three attributes of ``Device`` instances are documented which allow direct
+access to the underlying ``libftdi`` functionality.
+
+#. ``fdll`` - this is a reference to the loaded ``libftdi`` library, loaded
+   via ctypes. This should be used with the normal ctypes protocols.
+#. ``ctx`` - this is a reference to the context of the current device
+   context. It is managed as a raw ctypes byte-string, so can be modified
+   if required at the byte-level using appropriate ``ctypes`` methods.
+#. ``ftdi_fn`` - a convenience function wrapper, this is the preferred
+   method for accessing library functions for a specific device instance.
+   This is a function forwarder to the local ``fdll`` attribute, but also
+   wraps the device context and passes it as the first argument. In this
+   way, using ``device.ftdi_fn.ft_xyz`` is more like the D2XX driver
+   provided by FTDI, in which the device context is passed in at
+   initialisation time and then the client no longer needs to care about it.
+   A call to::
+
+    >>> device.ftdi_fn.ft_xyz(1, 2, 3)
+
+   is equivalent to the following::
+
+    >>> device.fdll.ft_xyz(ctypes.byref(device.ctx), 1, 2, 3)
+
+   but has the advantages of being shorter and not requiring ctypes to be
+   in scope.
+
+    incorrect operations using any of these attributes of devices
+    are liable to crash the Python interpreter
+
+Examples
+~~~~~~~~
+
+The following example shows opening a device in serial mode, switching
+temporarily to bit-bang mode, then back to serial and writing a string.
+Why this would be wanted is anyone's guess ;-)
+
+::
+
+    >>> from pylibftdi import Device
+    >>>
+    >>> with Device() as dev:
+    >>>    dev.fn.ftdi_set_bitmode(1, 0x01)
+    >>>    dev.write('\x00\x01\x00')
+    >>>    dev.fn.ftdi_set_bitmode(0, 0x00)
+    >>>    dev.write('Hello World!!!')
+
+
+The libftdi_ documentation should be consulted in conjunction with the
+ctypes_ reference for guidance on using these features.
+
+.. _libftdi: http://www.intra2net.com/en/developer/libftdi/documentation/
+.. _ctypes: http://docs.python.org/library/ctypes.html
+

doc/basic_usage.rst

+Basic Usage
+===========
+
+`pylibftdi` is a minimal Pythonic interface to FTDI devices using libftdi_.
+Rather than simply expose all the methods of the underlying library directly,
+it aims to provide a simpler API for the main use-cases of serial and parallel
+IO, while still allowing the use of the more advanced functions of the library.
+
+.. _libftdi: http://www.intra2net.com/en/developer/libftdi/
+
+General
+-------
+
+The primary interface is the ``Device`` class in the ``pylibftdi`` package; this
+gives serial access on relevant FTDI devices (e.g. the UM232R), providing a
+file-like interface (read, write).  Baudrate is controlled with the ``baudrate``
+property.
+
+If a Device instance is created with ``mode='t'`` (text mode) then read() and
+write() can use the given ``encoding`` (defaulting to latin-1). This doesn't
+make a lot of difference on Python 2 (and can be omitted), but allows easier
+integration with passing unicode strings between devices in Python 3.
+
+Multiple devices are supported by passing the desired device serial number (as
+a string) in the ``device_id`` parameter - this is the first parameter in both
+Device() and BitBangDevice() constructors. Alternatively the device 'description'
+can be given, and an attempt will be made to match this if matching by serial
+number fails.
+
+Examples
+~~~~~~~~
+
+::
+
+    >>> from pylibftdi import Device
+    >>>
+    >>> with Device(mode='t') as dev:
+    ...     dev.baudrate = 115200
+    ...     dev.write('Hello World')
+
+The pylibftdi.BitBangDevice wrapper provides access to the parallel IO mode of
+operation through the ``port`` and ``direction`` properties.  These provide an
+8 bit IO port including all the relevant bit operations to make things simple.
+
+::
+
+    >>> 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
+
+There is support for a number of external devices and protocols, specifically
+for interfacing with HD44780 LCDs using the 4-bit interface.
+

doc/bit_server.rst

-bit_server Module
-=================
-
-.. automodule:: bit_server
-    :members:
-    :undoc-members:
-    :show-inheritance:
 
 latex_elements = {
 # The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
+'papersize': 'a4paper',
 
 # The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
+'pointsize': '11pt',
 
 # Additional stuff for the LaTeX preamble.
 #'preamble': '',
-.. pylibftdi documentation master file, created by
-   sphinx-quickstart on Mon Oct 31 22:36:38 2011.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to pylibftdi's documentation!
 =====================================
 
    :maxdepth: 2
 
    introduction
-   tutorial
+   quickstart
+   installation
+   basic_usage
+   advanced_usage
    pylibftdi
 
 Indices and tables

doc/lcd.rst

-lcd Module
-==========
-
-.. automodule:: lcd
-    :members:
-    :undoc-members:
-    :show-inheritance:

doc/led_flash.rst

-led_flash Module
-================
-
-.. automodule:: led_flash
-    :members:
-    :undoc-members:
-    :show-inheritance:

doc/list_devices.rst

-list_devices Module
-===================
-
-.. automodule:: list_devices
-    :members:
-    :undoc-members:
-    :show-inheritance:

doc/modules.rst

-pylibftdi
-=========
-
-.. toctree::
-   :maxdepth: 4
-
-   pylibftdi

doc/pylibftdi.examples.rst

     :undoc-members:
     :show-inheritance:
 
+:mod:`magic_candle` Module
+--------------------------
+
+.. automodule:: pylibftdi.examples.magic_candle
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`pin_read` Module
+--------------------------
+
+.. automodule:: pylibftdi.examples.pin_read
+    :members:
+    :undoc-members:
+    :show-inheritance:
+

doc/pylibftdi.rst

     :undoc-members:
     :show-inheritance:
 
-:mod:`test_bitbang` Module
---------------------------
-
-.. automodule:: pylibftdi.test_bitbang
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-:mod:`test_common` Module
--------------------------
-
-.. automodule:: pylibftdi.test_common
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-:mod:`test_driver` Module
--------------------------
-
-.. automodule:: pylibftdi.test_driver
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 :mod:`util` Module
 ------------------
 

doc/quickstart.rst

+Quick Start
+===========
+
+Install pylibftdi
+-----------------
+
+See the _installation instructions for more detailed requirements, but
+hopefully things will work by just running the following::
+
+    $ pip install pylibftdi
+
+Connect and enumerate FTDI devices
+----------------------------------
+
+Connect the FTDI device to a free USB port. Run the ``list_devices`` example
+to enumerate connected FTDI devices::
+
+    $ python -m pylibftdi.examples.list_devices
+
+For each connected device, this will show manufacturer, model identifier,
+and serial number. With a single device connected, the output maybe
+something like the following:
+
+    ``FTDI:UM232H:FTUBIOWF``
+
+Though hopefully with a different serial number, or else you've either
+stolen mine, or you are me...
+
+Test some actual IO (well, at least O)
+--------------------------------------
+
+Connect an LED between D0 of your bit-bang capable device and ground, via a
+330 - 1K ohm resistor as appropriate.
+
+Test the installation and functioning of pylibftdi with the following::
+
+    $ python -m pylibftdi.examples.led_flash
+
+The LED should now flash at approximately 1Hz.

doc/tutorial.rst

-Tutorial
-========
-
-pylibftdi is a minimal Pythonic interface to FTDI devices using libftdi_.
-
-.. _libftdi: http://www.intra2net.com/en/developer/libftdi/
-
-Usage
------
-
-The primary interface is the ``Device`` class in the pylibftdi package; this
-gives serial access on relevant FTDI devices (e.g. the UM232R), providing a
-file-like interface (read, write).  Baudrate is controlled with the ``baudrate``
-property.
-
-If a Device instance is created with ``mode='t'`` (text mode) then read() and
-write() can use the given ``encoding`` (defaulting to latin-1). This doesn't
-make a lot of difference on Python 2 (and can be omitted), but allows easier
-integration with passing unicode strings between devices in Python 3.
-
-Multiple devices are supported by passing the desired device serial number (as
-a string) in the ``device_id`` parameter - this is the first parameter in both
-Device() and BitBangDevice() constructors. Alternatively the device 'description'
-can be given, and an attempt will be made to match this if matching by serial
-number fails.
-
-Examples
-~~~~~~~~
-
-::
-
-    >>> from pylibftdi import Device
-    >>>
-    >>> with Device(mode='t') as dev:
-    ...     dev.baudrate = 115200
-    ...     dev.write('Hello World')
-
-The pylibftdi.BitBangDevice wrapper provides access to the parallel IO mode of
-operation through the ``port`` and ``direction`` properties.  These provide an
-8 bit IO port including all the relevant bit operations to make things simple.
-
-::
-
-    >>> 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
-
-There is support for a number of external devices and protocols, specifically
-for interfacing with HD44780 LCDs using the 4-bit interface.
-
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.