repository·main·Indexed 20 days ago
https://github.com/eblot/pyftdiA pure Python user-space driver for FTDI devices supporting UART, GPIO, SPI, I2C, and JTAG protocols. It provides support for various FTDI bridge chips (including FT232R, FT232H, FT2232H, and FT4232H) and includes CLI tools such as ftconf for EEPROM configuration, ftdi_urls for device discovery, i2cscan for bus scanning, and pyterm for serial terminal emulation. Requires Python 3.9+ and supports macOS, Linux, and FreeBSD.
EEPROM support in pyftdi is under active development. Because different FTDI models implement different feature maps, some features may be incorrectly decoded.
To interact with the EEPROM, use the high-level EEPROM API.
PyFtdi is a pure Python user-space driver for popular FTDI devices. It allows you to interface with FTDI chips to implement various communication protocols without needing kernel-level drivers.
The pyftdi.gpio module allows for direct driving of GPIO pins on an FTDI device.
Important Constraints:
SPI API or I2C API documentation instead of this direct GPIO API.PyFtdi provides several ways to access FTDI IO pins depending on your use case:
GpioController implementations (GpioAsyncController, GpioSyncController, or GpioMpsseController) for full, direct access to FTDI pins as raw I/O.SpiGpioPort or I2cGpioPort to access free pins that are not reserved by the SPI or I2C features.Limitations:
The pyftdi.ftdi module provides direct access to the low-level FTDI hardware.
Note: It is highly recommended to use the dedicated high-level APIs instead of this module. Most features required for standard development are available through the specialized API modules (e.g., GPIO, MPSSE, I2C, SPI, etc.). Use this module only if you have specific requirements that the high-level APIs do not support.
You can use special URL syntax to find and list available FTDI devices:
Using the syntax ftdi:///? (or ftdi:///\? in shells like zsh to escape the question mark) will print available devices to standard output and raise a SystemExit. This is a quick way to see available URLs with serial numbers or bus:address selectors.
To enumerate devices without interrupting execution (i.e., without raising SystemExit), use the following helper methods on the Ftdi class:
pyftdi.ftdi.Ftdi.list_devices(url)pyftdi.ftdi.Ftdi.show_devices(url)Both methods accept the same URL syntax used for connections.
from pyftdi.ftdi import Ftdi
# List devices without exiting the script
devices = Ftdi.list_devices("ftdi://")
print(devices)I2C requires open-collector/open-drain lines with pull-up resistors.
Due to the MPSSE engine and USB latency, write operations are relatively slow because each byte must be acknowledged by the slave before the next is sent. While read operations are optimized in PyFtdi v0.51+, this library is not recommended for high-speed I2C write requirements. For high-speed needs, consider a dedicated I2C master like the FT4222H.
In PyFtdi, Ports and Interfaces are treated as synonyms. An interface is an independent hardware communication port on an FTDI device. Each interface can be configured independently (e.g., one as UART, another as I2C + GPIO).
Port Widths by Hardware Model:
DBUS)ADBUS/ACBUS)ADBUS/ACBUS and BDBUS/BCBUS)ADBUS/ACBUS and BDBUS/BCBUS)ADBUS, BDBUS, CDBUS, DDBUS)DBUS)DBUS)Note: Avoid using legacy terms 'wide' or 'narrow'; use the actual port width instead.
When a specific feature (like I2C) is enabled, certain pins are reserved for that feature's protocol (e.g., SCL, SDA). These reserved pins are no longer available as standard GPIOs.
If a feature reserves the first $N$ pins, the lowest accessible GPIO pin will be bit $N$. For example, if I2C reserves bits 0, 1, and 2, the first available GPIO is bit 3 (AD3). When interacting with the GPIO controller in this state, you must account for these reserved bits in your bitmasks.
# Example: Using I2C feature which reserves bits 0, 1, 2
i2c = I2cController()
i2c.configure('ftdi:///1', direction=0x78)
gpio = i2c.get_gpio()
# Read current state
pins = gpio.read()
# Mask out the I2C bits (0x07 = bits 0, 1, 2)
pins &= 0x07
# Set AD4 (bit 4)
pins |= 1 << 4
# Update GPIO output
gpio.write(pins)PyFtdi supports using FTDI devices as SPI masters in both half-duplex (write or read) and full-duplex (synchronous write and read) modes.
Supported SPI Modes:
Key Capabilities & Limitations:
In UART mode, you have limited access to the lower 8 pins as GPIO. Note that direction is hardcoded, pins cannot be addressed atomically, and some pins are unavailable if hardware flow control is enabled. You access these pins using their UART assigned names as attributes on the PySerial port object:
| Bit | UART | Direction | API |
|---|---|---|---|
| b0 | TX | Out | port.write(buffer) |
| b1 | RX | In | buffer = port.read(count) |
| b2 | RTS | Out | port.rts = state |
| b3 | CTS | In | state = port.cts |
| b4 | DTR | Out | port.dtr = state |
| b5 | DSR | In | state = port.dsr |
| b6 | DCD | In | state = port.dcd |
| b7 | RI | In | state = port.ri |
PyFtdi provides three GpioController variants depending on your hardware requirements and timing needs:
GpioAsyncController: The most common API. It allows reading current input levels and changing output levels. When using byte buffers instead of single bytes, pins are sampled/updated at a configurable regular pace. Note that the exact timing of input sampling cannot be controlled.GpioSyncController: Designed for precise timing. A new GPIO input sample is captured exactly when GPIO output pins are updated. It uses an exchange() method instead of separate read() and write() calls. When using byte buffers, pins are sampled/updated at a configurable regular pace.GpioMpsseController: Used to access the MSB pins of wide ports (12- or 16-pin FTDI devices). Note that LSB and MSB pins are not addressed atomically; there is a short delay between sampling/updating the LSB and MSB parts of the same wide port.Note on Port Width: Both GpioAsyncController and GpioSyncController are restricted to the 8 LSB pins (bits 0-7). For wider ports, use GpioMpsseController to access the MSB pins.