Installation

Prerequisites

PyFTDI relies on PyUSB, which requires a native dependency: libusb 1.x.

The actual command to install depends on your OS and/or your distribution, see below

Debian/Ubuntu Linux

apt-get install libusb-1.0

On Linux, you also need to create a udev configuration file to allow user-space processes to access to the FTDI devices. There are many ways to configure udev, here is a typical setup:

# /etc/udev/rules.d/11-ftdi.rules

# FT232AM/FT232BM/FT232R
SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="6001", GROUP="plugdev", MODE="0664"
# FT2232C/FT2232D/FT2232H
SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="6010", GROUP="plugdev", MODE="0664"
# FT4232/FT4232H
SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="6011", GROUP="plugdev", MODE="0664"
# FT232H
SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="6014", GROUP="plugdev", MODE="0664"
# FT230X/FT231X/FT234X
SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="6015", GROUP="plugdev", MODE="0664"

Note

Accessing FTDI devices with custom VID/PID

You need to add a line for each device with a custom VID / PID pair you declare, see Custom USB vendor and product IDs for details.

You need to unplug / plug back the FTDI device once this file has been created so that udev loads the rules for the matching device, or alternatively, inform the udev daemon about the changes:

sudo udevadm control --reload-rules
sudo udevadm trigger

With this setup, be sure to add users that want to run PyFtdi to the plugdev group, e.g.

sudo adduser $USER plugdev

Remember that you need to log out / log in to get the above command effective, or start a subshell to try testing PyFtdi:

newgrp plugdev

Homebrew macOS

brew install libusb

Windows

Windows is not officially supported (i.e. not tested) but some users have reported successful installations. Windows requires a specific libusb backend installation.

Zadig

The probably easiest way to deal with libusb on Windows is to use Zadig

  1. Start up the Zadig utility

  2. Select Options/List All Devices, then select the FTDI devices you want to communicate with. Its names depends on your hardware, i.e. the name stored in the FTDI EEPROM.

  • With FTDI devices with multiple channels, such as FT2232 (2 channels) and FT4232 (4 channels), you must install the driver for the composite parent, not for the individual interfaces. If you install the driver for each interface, each interface will be presented as a unique FTDI device and you may have difficulties to select a specific FTDI device port once the installation is completed. To make the composite parents to appear in the device list, uncheck the Options/Ignore Hubs or Composite Parents menu item.

  • Be sure to select the parent device, i.e. the device name should not end with (Interface N), where N is the channel number.

    • for example Dual RS232-HS represents the composite parent, while Dual RS232-HS (Interface 0) represents a single channel of the FTDI device. Always select the former.

  1. Select libusb-win32 (not WinUSB) in the driver list.

  2. Click on Replace Driver

See also Libusb on Windows

Python

Python dependencies

Dependencies should be automatically installed with PIP.

  • pyusb >= 1.0.0, != 1.2.0

  • pyserial >= 3.0

Do not install PyUSB from GitHub development branch (master, …). Always prefer a stable, tagged release.

PyUSB 1.2.0 also broke the backward compatibility of the Device API, so it will not work with PyFtdi.

Installing with PIP

PIP should automatically install the missing dependencies.

pip3 install pyftdi

Installing from source

If you prefer to install from source, check out a fresh copy from PyFtdi github repository.

git clone https://github.com/eblot/pyftdi.git
cd pyftdi
# note: 'pip3' may simply be 'pip' on some hosts
pip3 install -r requirements.txt
python3 setup.py install

Generating the documentation

Follow Installing from source then:

pip3 install setuptools wheel sphinx sphinx_autodoc_typehints
# Shpinx Read the Doc theme seems to never get a release w/ fixed issues
pip3 install -U -e git+https://github.com/readthedocs/sphinx_rtd_theme.git@2b8717a3647cc650625c566259e00305f7fb60aa#egg=sphinx_rtd_theme
sphinx-build -b html pyftdi/doc .

The documentation may be accessed from the generated index.html entry file.

Post-installation sanity check

Open a shell, or a CMD on Windows

python3  # or 'python' on Windows
from pyftdi.ftdi import Ftdi
Ftdi.show_devices()

should list all the FTDI devices available on your host.

Alternatively, you can invoke ftdu_urls.py script that lists all detected FTDI devices. See the Tools chapter for details.

  • Example with 1 FT232H device with a serial number and 1 FT2232 device with no serial number, connected to the host:

    Available interfaces:
  ftdi://ftdi:232h:FT1PWZ0Q/1   (C232HD-DDHSP-0)
  ftdi://ftdi:2232/1            (Dual RS232-HS)
  ftdi://ftdi:2232/2            (Dual RS232-HS)

Note that FTDI devices with custom VID/PID are not listed with this simple command, please refer to the PyFtdi API to add custom identifiers, i.e. see pyftdi.ftdi.Ftdi.add_custom_vendor() and pyftdi.ftdi.Ftdi.add_custom_product() APIs.

Custom USB vendor and product IDs

PyFtdi only recognizes FTDI official vendor and product IDs.

If you have an FTDI device with an EEPROM with customized IDs, you need to tell PyFtdi to support those custom USB identifiers.

Custom PID

To support a custom product ID (16-bit integer) with the official FTDI ID, add the following code before any call to an FTDI open() method.

from pyftdi.ftdi import Ftdi

Ftdi.add_custom_product(Ftdi.DEFAULT_VENDOR, product_id)

Custom VID

To support a custom vendor ID and product ID (16-bit integers), add the following code before any call to an FTDI open() method.

from pyftdi.ftdi import Ftdi

Ftdi.add_custom_vendor(vendor_id)
Ftdi.add_custom_product(vendor_id, product_id)

You may also specify an arbitrary string to each method if you want to specify a URL by custom vendor and product names instead of their numerical values:

from pyftdi.ftdi import Ftdi

Ftdi.add_custom_vendor(0x1234, 'myvendor')
Ftdi.add_custom_product(0x1234, 0x5678, 'myproduct')

f1 = Ftdi.create_from_url('ftdi://0x1234:0x5678/1')
f2 = Ftdi.create_from_url('ftdi://myvendor:myproduct/2')

Note

Remember that on OSes that require per-device access permissions such as Linux, you also need to add the custom VID/PID entry to the configuration file, see Linux installation udev rule file.