Ben Bass avatar Ben Bass committed af158ca

add some questions to the docs

Comments (0)

Files changed (2)

+pylibftdi questions
+===================
+
+None of these are yet frequently asked, and perhaps they never will be...
+But they are still questions, and they relate to pylibftdi.
+
+Which devices are recommended?
+------------------------------
+
+While I used to do a lot of soldering, I prefer the cleaner way of
+breadboarding nowadays. As such I can strongly recommend the FTDI DIP
+modules which plug into a breadboard nice and easy, can be self-powered
+from USB, and can be re-used for dozens of different projects.
+
+I've used (and test against) the following, all of which have 0.1" pin
+spacing in two rows 0.5" or 0.6" apart, so will sit across the central
+divide of any breadboard:
+
+UB232R
+  a small 8 pin device with mini-USB port; serial and CBUS bit-bang.
+
+UM245R
+  a 24-pin device with parallel FIFO modes. Full-size USB type B socket.
+
+UM232R
+  a 24-pin device with serial and bit-bang modes. Full-size USB type B
+  socket.
+
+UM232H
+  this contains a more modern FT232H device, and libftdi support is
+  fairly recent (requires 0.20 or later). Supports USB 2.0 Hi-Speed mode
+  though, and lots of interesting modes (I2C, SPI, JTAG...) which I've not
+  looked at yet. Mini-USB socket.
+
+Personally I'd go with the UM232R device for compatibility. It works great
+with both UART and bit-bang IO, which I target as the two main use-cases
+for pylibftdi. The UM232H is certainly feature-packed though, and I hope
+to support some of the more interesting modes in future.
+
+How do I set the baudrate?
+--------------------------
+
+In both serial and parallel mode, the internal baudrate generator (BRG) is
+set using the ``baudrate`` property of the ``Device`` instance. Reading this
+will show the current baudrate (which defaults to 9600); writing to it
+will attempt to set the BRG to that value.
+
+On failure to set the baudrate, it will remain at its previous setting.
+
+In parallel mode, the actual bytes-per-second rate of parallel data is
+16x the programmed BRG value. This is an effect of the FTDI devices
+themselves, and is not hidden by pylibftdi.
+
+How do I send unicode over a serial connection?
+-----------------------------------------------
+
+If a ``Device`` instance is created with ``mode='t'``, then text-mode is
+activated. This is analogous to opening files; after all, the API is
+intentionally modelled on file objects whereever possible.
+
+When text-mode is used, an encoding can be specified. The default is
+``latin-1`` for the very practical reason that it is transparent to 8-bit
+binary data; by default a text-mode serial connection looks just like a
+binary mode one.
+
+An alternative encoding can be used provided in the same constructor call
+used to instantiate the ``Device`` class, e.g.::
+
+    >>> dev = Device(mode='t', encoding='utf-8')
+
+Read and write operations will then return / take unicode values.
+
+Whether it is sensible to try and send unicode over a ftdi connection is
+a separate issue... At least consider doing codec operations at a higher
+level in your application.
+
+How do I run the tests?
+-----------------------
+
+Tests aren't included in the distutils distribution, so clone the
+repository and run from there::
+
+    $ hg clone http://bitbucket.org/codedstructure/pylibftdi
+    <various output stuff>
+    $ cd pylibftdi
+    $ python -m unittest discover
+    ...............
+    ----------------------------------------------------------------------
+    Ran 15 tests in 0.025s
+
+    OK
+    $
+
    installation
    basic_usage
    advanced_usage
+   how_to
    pylibftdi
 
 Indices and tables
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.