sjb / libmpsse Goto Github PK

ABOUT

	Libmpsse is a library for interfacing with SPI/I2C devices via FTDI's FT-2232 family of USB to serial
	chips. Additionally, it provides control over the GPIO pins on the FTDI chips and supports a raw
	bitbang mode as well. Based around the libftdi library, it is written in C and includes a Python wrapper 
	courtesy of swig.

LIBRARY API

	In version 1.0 libmpsse was modified to support multiple simultaneous FTDI chips inside a single process,
	which required a change to the API. Thus, the API for libmpsse versions prior to 1.0 are not compatible with 
	the API for versions 1.0 and later.

	The C and Python APIs are very similar, although the Python API has been made more "pythonic". Specifically,
	in Python:

		1) MPSSE is the name of the Python class, not of a method or function as it is in C. The class 
		   constructor takes the same arguments as the MPSSE function in C. If you wish to instead use 
		   the Open method to open a given device, simply do not specify these arguments when calling 
		   the class constructor.

		2) Due to its object-oriented nature, each class instance in Python internally handles the MPSSE
		   context pointer; thus, none of the Python methods in the MPSSE class require this argument.

		3) Size parameters required by the C functions are not used by the corresponding Python methods.

		4) Besides the above described differences, all Python methods have a 1:1 compatibility with their
		   respective C functions. However, in Python the class constructor (MPSSE) and Open method have 
		   sensible defaults for several of their arguments so not all arguments are required. 

	See the README.C and README.PYTHON files for more details.

CODE EXAMPLES

	There are SPI and I2C code examples for both C and Python in the src/examples directory. After installing
	libmpsse, the C examples can be built by running:

		$ make example-code

	There are more detailed descriptions of the SPI and I2C APIs in docs/README.SPI and docs/README.I2C files.

BUILDING APPLICATIONS
	
	To build applications in Python, you must import the mpsse module:

		from mpsse import *

	To build applications in C, you must include the mpsse.h header file:

		#include <mpsse.h>
	
	...and also link your program against the libmpsse library:

		gcc test.c -o test -lmpsse

PHYSICAL CONNECTIONS

	In order to speak to SPI or I2C devices, you must establish the proper physical connections between the target
	device and your FTDI chip. The exact pin out of your target device and FTDI chip will differ based on the chips
	in question, and the appropriate data sheets for each device should be referenced for this information.

	Included in the docs directory is the FTDI MPSSE Basics application note (AN 135). Section 2 of this document
	covers all of the pin configurations for each FTDI chip, as well as example diagrams regarding the physical
	connections between the FTDI chip and your target device.

KNOWN BUGS

	The following are known bugs in libmpsse:

		o In SPI, the Transfer method fails if transfering large data chunks. Use the Read/Write functions 
		  for transferring large chunks of data (~1MB or more).

KNOWN LIMITATIONS

	Libmpsse supports all four SPI modes as well as I2C. However, due to the design of the FTDI MPSSE implementation,
	there are some limitations:

		o All protocols support master mode only.
		o SPI modes 1 and 3 are only partially supported; see the README.SPI for more information.
		o In I2C, the SCL and SDA pins are open drain, but the MPSSE implementation explicitly drives these lines high.
		  Although this is usually fine, it means that some I2C features, such as clock stretching, are not supported.