PyFtdi

Overview

PyFtdi aims at providing a user-space driver for modern FTDI devices, implemented in pure Python language.

Modern FTDI devices include:

• UART-only bridges
  • FT232R (single port, clock up to 6 MHz, 3Mbps)
  • FT230X (single port, clock up to 48 Mhz, 3Mbps)
• UART and multi-serial protocols (SPI, I2C, JTAG) bridges
  • FT2232D (dual port, clock up to 6 MHz)
  • FT232H (single port, clock up to 30 MHz)
  • FT2232H (dual port, clock up to 30 MHz)
  • FT4232H (quad port, clock up to 30 MHz)

Other FTDI devices could also be supported (including FT232* devices), although these devices are not a primary goal for PyFtdi, and therefore have not been tested with PyFtdi.

Primary goals

PyFtdi currently supports the following features:

• UART/Serial USB converter, up to 12Mbps (depending on the FTDI device capability)
• Bitbang/GPIO support
• SPI master
• I2C master
• JTAG master

PyFtdi provides a pyserial compliant API, so it can be used as a drop-in module to access USB-serial converters based on FTDI devices.

Requirements

Python 3.5 or above is required.

PyFtdi relies on PyUSB, which itself depends on one of the following native libraries:

• libusb, tested with 1.0.20

may still work, but are fully untested there are nowaways obsolete.

PyFtdi does not depend on any other native library, and only uses standard Python modules along with PyUSB

PyFtdi has been tested with PyUSB 1.0.0. PyUSB 1.0.0b1 or below is no longer supported.

Note about previous releases

open(), open_mpsse() and open_bitbang arguments have changed in v0.22.0, be sure to update your code or even better use the URL variants (open_from_url, open_mpsse_from_url or open_bitbang_from_url).

If you have no choice but using previous releases of software, such as

• Python (2.6+, 3.3+),
• other PyUSB backends such as the deprecated libusb-0.1, or openusb,
• PyUSB 1.0.0b1 or below,
• pyserial 2.6+ (previous versions of pyserial will NOT work)

please checkout the latest PyFtdi 0.1x series (0.13.3) which provides support for these deprecated environmement, but is no longer actively maintained.

Status

This project is still in beta development stage.

However, PyFtdi is being forked from a closed-source software implementation that has been successfully used for over several years - including serial @ 3Mbps, spi and jtag protocols. PyFtdi is developed as an open-source solution.

Supported features

• All FTDI device ports (UART, MPSSE) can be used simultaneously.

  • However, it is not yet possible to use both GPIO and MPSSE mode on the same port at once

• Several FTDI adapters can be accessed simultaneously from the same Python runtime instance.

• Serial port, up to 12 Mbps. PyFtdi includes a pyserial emulation layer that offers transparent access to the FTDI serial ports through a pyserial- compliant API. The serialext directory contains a minimal serial terminal demonstrating the use of this extension, and a dispatcher automatically selecting the serial backend (pyserial, PyFtdi), based on the serial port name.

• SPI master.

  Supported devices:

  Mode	CPol	CPha	Status
  0	0	0	Supported on all MPSEE devices
  1	0	1	Supported on -H series (FT232H/FT2232H/FT4232H)
  2	1	0	Not supported (FTDI HW limitation)
  3	1	1	Supported on -H series (FT232H/FT2232H/FT4232H)

  PyFtdi can be used with pyspiflash module that demonstrates how to use the FTDI SPI master with a pure-Python serial flash device driver for several common devices.

  Only half-duplex communication is supported for now.

• I2C master. For now, only 7-bit address are supported.

  Supported devices:

  • For now, only FT232H is supported (support for other -H series is planned)

• JTAG is under development and is not fully supported yet.

Installation

• Install native dependency. The actual command to install depends on your OS and/or your distribution. Examples:

  • Debian Linux

    apt-get install libusb-1.0

  • Homebrew macOS

    brew install libusb

• Install Python dependencies

  pip3 install pyusb pip3 install pyserial pip3 install pyftdi

API Overview

UART

# Enable pyserial extensions
import pyftdi.serialext

# Open a serial port on the second FTDI device port @ 3Mbaud
port = pyftdi.serialext.serial_for_url('ftdi://ftdi:2232h/2',
                                       baudrate=3000000)

# Send bytes
port.write(b'Hello World')

# Receive bytes
data = port.read(1024)

SPI

Example: communication with a SPI data flash

# Instanciate a SPI controller
spi = SpiController()

# Configure the first port of the FTDI device as a SPI master
spi.configure('ftdi://ftdi:2232h/1')

# Get a port to a SPI slave w/ /CS on A*BUS3 and SPI mode 0 @ 12MHz
slave = spi.get_port(cs=0, freq=12E6, mode=0)

# Request the JEDEC ID from the SPI slave
jedec_id = slave.exchange([0x9f], 3).tobytes()

I2C

Example: communication with an I2C GPIO expander

# Instanciate an I2C controller
i2c = I2cController()

# Configure the first port of the FTDI device as an I2C master
i2c.configure('ftdi://ftdi:2232h/1')

# Get a port to an I2C slave device
slave = i2c.get_port(0x21)

# Send one byte, then receive one byte
slave.exchange([0x04], 1)

# Write a register to the I2C slave
slave.write_to(0x06, b'\x00')

# Read a register from the I2C slave
slave.read_from(0x00, 1)

URL Scheme

There are generally two ways to open a connection to an Ftdi() object. The first method is to use the open() methods which accept VID, PID, and serial parameters (among others). These methods are:

• open()
• open_mpsse()
• open_bitbang()

The second way to open a connection is to specify connection details using a URL. The URL scheme is defined as:

protocol://[vendor[:product[:index|:serial]]]/interface

Where:

• protocol: always ftdi
• vendor: the USB vendor ID of the manufacturer
  • ex: ftdi or 0x403
• product: the USB product ID of the device
  • ex: 232h or 0x6014
  • Supported product IDs: 0x6001, 0x6010, 0x6011, 0x6014, 0x6015
  • Supported product aliases:
    • 232, 232r, 232h, 2232d, 2232h, 4232h, 230x
    • ft prefix for all aliases is also accepted, as for example ft232h
• serial: the serial number as a string
• index: an integer (not particularly useful, as it depends on the enumeration order on the USB buses)
• interface: the interface of FTDI device, starting from 1
  • ex: 1 for 232*, 1 or 2 for 2232*, 1-4 for 4232* devices

All parameters but the interface are optional, PyFtdi tries to find the best match. Therefore, if you have a single FTDI device connected to your system, ftdi:///1 should be enough.

You can also ask PyFtdi to enumerate all the compatible devices with the special ftdi:///? syntax.

URLs can be used with the same methods as above by appending _from_url to the method name such as:

• open_from_url()
• open_mpsse_from_url()
• open_bitbang_from_url()

Troubleshooting

"Error: No backend available"

libusb native library cannot be loaded. Try helping the dynamic loader:

• On Linux: export LD_LIBRARY_PATH=<path>

  where <path> is the directory containing the libusb-1.*.so library file

• On macOS: export DYLD_LIBRARY_PATH=.../lib

  where <path> is the directory containing the libusb-1.*.dylib library file

"Error: Access denied (insufficient permissions)"

The system may already be using the device.

• On OS X 10.9+: starting with Mavericks, OS X ships with a native FTDI driver that preempts access to the FTDI device.

  The driver can be unloaded this way:

  sudo kextunload [-v] -bundle com.apple.driver.AppleUSBFTDI

  You may want to use an alias or a tiny script such as pyftdi/tools/uphy.sh

  Please note that the system automatically reloads the driver, so it may be useful to move the kernel extension so that the system never loads it.

• This error message may also be triggered whenever the communication port is already in use.

"serial.serialutil.SerialException: Unable to open USB port"

May be caused by a conflict with the FTDI virtual COM port (VCOM). Try uninstalling the driver. On macOS, refer to this FTDI macOs guide.

Slow initialisation on OS X El Capitan

It may take several seconds to open or enumerate FTDI devices.

If you run libusb <= v1.0.20, be sure to read the issue with OS X 10.11+.

Development

PyFtdi is developed on macOS platforms (64-bit kernel), and is validated on a regular basis on Linux hosts.

As it contains no native code, it should work on any PyUSB and libusb supported platforms. However, Ms Windows is a seamless source of issues and is not supported. Your mileage may vary.

Examples

See PyFtdi_tests directory for GPIO examples.

See pyspiflash module for SPI examples.