Many PyFtdi APIs give direct access to the IO pins of the FTDI devices:
GpioController, implemented as
GpioMpsseController(see gpio - GPIO API) gives full access to the FTDI pins as raw I/O pins,
SpiGpioPort(see spi - SPI API) gives access to all free pins of an FTDI interface, which are not reserved for the SPI feature,
I2cGpioPort(see i2c - I2C API) gives access to all free pins of an FTDI interface, which are not reserved for the I2C feature
Gpio raw access is not yet supported with JTAG feature.
It is not possible to use GPIO along with UART mode on the same interface. However, UART mode still provides (very) limited access to GPIO pins, see UART GPIO access for details.
This document presents the common definitions for these APIs and explain how to drive those pins.
An FTDI interface follows the definition of a USB interface: it is an independent hardware communication port with an FTDI device. Each interface can be configured independently from the other interfaces on the same device, e.g. one interface may be configured as an UART, the other one as I2C + GPIO.
It is possible to access two distinct interfaces of the same FTDI device from a multithreaded application, and even from different applications, or Python interpreters. However two applications cannot access the same interface at the same time.
Performing a USB device reset affects all the interfaces of an FTDI device, this is the rationale for not automatically performing a device reset when an interface is initialiazed and configured from PyFtdi.
An FTDI port is ofter used in PyFtdi as a synonym for an interface. This may differ from the FTDI datasheets that sometimes show an interface with several ports (A*BUS, B*BUS). From a software standpoint, ports and interfaces are equivalent: APIs access all the HW port from the same interface at once. From a pure hardware standpoint, a single interface may be depicted as one or two ports.
With PyFtdi, ports and interfaces should be considered as synomyms.
Each port can be accessed as raw input/output pins. At a given time, a pin is either configured as an input or an output function.
The width of a port, that is the number of pins of the interface, depending on the actual hardware, i.e. the FTDI model:
FT232R features a single port, which is 8-bit wide: DBUS,
FT232H features a single port, which is 16-bit wide: ADBUS/ACBUS,
FT2232D features two ports, which are 12-bit wide each: ADBUS/ACBUS and BDBUS/BCBUS,
FT2232H features two ports, which are 16-bit wide each: ADBUS/ACBUS and BDBUS/BCBUS,
FT4232H features four ports, which are 8-bit wide each: ADBUS, BDBUS, CDBUS and DDBUS,
FT230X features a single port, which is 4-bit wide,
FT231X feature a single port, which is 8-bit wide
For historical reasons, 16-bit ports used to be named wide ports and 8-bit
ports used to be called narrow with PyFtdi. This terminology and APIs are
no longer used, but are kept to prevent API break. Please only use the port
width rather than these legacy port types.
0bit represents a low level value on a pin, that is GND
1bit represents a high level value on a pin, that is Vdd which is typically 3.3 volts on most FTDIs
Please refers to the FTDI datasheet of your device for the tolerance and supported analog levels for more details
FT232H supports a specific feature, which is dedicated to better supporting the I2C feature. This specific devices enables an open-collector mode:
Setting a pin to a low level drains it to GND
Setting a pin to a high level sets the pin as High-Z
This feature is automatically activated when I2C feature is enabled on a port, for the two first pins, i.e. SCL and SDA out.
However, PyFTDI does not yet provide an API to enable this mode to the other pins of a port, i.e. for the pins used as GPIOs.
An FTDI pin should either be configured as an input or an ouput. It is mandatory to (re)configure the direction of a pin before changing the way it is used.
0bit represents an input pin, i.e. a pin whose value can be sampled and read via the PyFTDI APIs
1bit represents an output pin, i.e. a pin whose value can be set/written with the PyFTDI APIs
FT232R, FT232H and FT230X/FT231X support an additional port denoted CBUS:
FT232R provides an additional 5-bit wide port, where only 4 LSBs can be used as programmable GPIOs:
FT232H provices an additional 10-bit wide port, where only 4 pins can be used as programmable GPIOs:
FT230X/FT231X provides an additional 4-bit wide port:
Note that CBUS access is slower than regular asynchronous bitbang mode.
CBUS EEPROM configuration¶
Accessing this extra port requires a specific EEPROM configuration.
The EEPROM needs to be configured so that the CBUS pins that need to be used
as GPIOs are defined as
GPIO. Without this special configuration, CBUS
pins are used for other functions, such as driving leds when data is exchanged
over the UART port. Remember to power-cycle the FTDI device after changing its
EEPROM configuration to force load the new configuration.
CBUS GPIO API¶
PyFtdi starting from v0.47 supports CBUS pins as special GPIO port. This port is not mapped as regular GPIO, a dedicated API is reserved to drive those pins:
pyftdi.ftdi.Ftdi.has_cbus()to report whether the device supports CBUS gpios,
pyftdi.ftdi.Ftdi.set_cbus_direction()to configure the port,
pyftdi.ftdi.Ftdi.get_cbus_gpio()to get the logical values from the port,
pyftdi.ftdi.Ftdi.set_cbus_gpio()to set new logical values to the port
Additionally, the EEPROM configuration can be queried to retrieve which CBUS pins have been assigned to GPIO functions:
pyftdi.eeprom.FtdiEeprom.cbus_pins()to report CBUS GPIO pins
The CBUS port is not available through the
pyftdi.gpio.GpioController API, as it cannot be considered as a
regular GPIO port.
CBUS GPIO feature has only be tested with the virtual test framework and a real FT231X HW device. It should be considered as an experimental feature for now.
The GPIO pins of a port are always accessed as an integer, whose supported width depends on the width of the port. These integers should be considered as a bitmap of pins, and are always assigned the same mapping, whatever feature is enabled:
0x01) represents the first pin of a port, i.e. AD0/BD0
0x02) represents the second pin of a port, i.e. AD1/BD1
0x80) represents the seventh pin of a port, i.e. AD7/BD7
bN represents the highest pin of a port, i.e. AD7/BD7 for an 8-bit port, AD15/BD15 for a 16-bit port, etc.
Pins reserved for a specific feature (I2C, SPI, …) cannot be accessed as a regular GPIO. They cannot be arbitrarily written and should be masked out when the GPIO output value is set. See Reserved pins for details.
FT232H CBUS exception¶
Note that there is an exception to this rule for FT232H CBUS port: FTDI has
decided to map non-contiguous CBUS pins as GPIO-capable CBUS pins, that is
CBUS9, where other CBUS-enabled devices
If the CBUS GPIO feature is used with an FT232H device, the pin positions for the GPIO port are not b5 .. b9 but b0 to b3 . This may sounds weird, but CBUS feature is somewhat hack-ish even with FTDI commands, so it did not deserve a special treatment for the sake of handling the weird implementation of FT232H.
Before using a port as GPIO, the port must be configured as GPIO. This is
achieved by either instanciating one of the GpioController or by requesting
the GPIO port from a specific serial bus controller:
SpiController.get_gpio(). All instances
provide a similar API (duck typing API) to configure, read and write to GPIO
Once a GPIO port is instanciated, the direction of each pin should be defined. The direction can be changed at any time. It is not possible to write to / read from a pin before the proper direction has been defined.
To configure the direction, use the set_direction API with a bitmap integer value that defines the direction to use of each pin.
A 8-bit port, dedicated to GPIO, is configured as follows:
BD0, BD3, BD7: input, I for short
BD1-BD2, BD4-BD6: output, O for short
That is, MSB to LSB: I O O O I O O I.
This translates to 0b
0111 0110 as output is
1 and input is
0x76 as an hexa value. This is the direction value to use to
configure() the port.
See also the
set_direction() API to reconfigure the direction of GPIO pins
at any time. This method accepts two arguments. This first arguments,
pins, defines which pins - the ones with the maching bit set - to consider
in the second
direction argument, so there is no need to
preserve/read-modify-copy the configuration of other pins. Pins with their
matching bit reset are not reconfigured, whatever their direction bit.
gpio = GpioAsyncController() gpio.configure('ftdi:///1', direction=0x76) # later, reconfigure BD2 as input and BD7 as output gpio.set_direction(0x84, 0x80)
Using GPIO APIs¶
There are 3 variant of GpioController, depending on which features are needed and how the GPIO port usage is intended. gpio - GPIO API gives in depth details about those controllers. Those controllers are mapped onto FTDI HW features.
GpioAsyncControlleris likely the most useful API to drive GPIOs.
It enables reading current GPIO input pin levels and to change GPIO output pin levels. When vector values (byte buffers) are used instead of scalar value (single byte), GPIO pins are samples/updated at a regular pace, whose frequency can be configured. It is however impossible to control the exact time when input pins start to be sampled, which can be tricky to use with most applications. See gpio - GPIO API for details.
GpioSyncControlleris a variant of the previous API.
It is aimed at precise time control of sampling/updating the GPIO: a new GPIO input sample is captured once every time GPIO output pins are updated. With byte buffers, GPIO pins are samples/updated at a regular pace, whose frequency can be configured as well. The API of
GpioSyncControllerslightly differ from the other GPIO APIs, as the usual
writemethod are replaced with a single
GpioSyncController are restricted to only
access the 8 LSB pins of a port, which means that FTDI device with wider port
(12- and 16- pins) cannot be fully addressed, as only b0 to b7 can be addressed.
GpioMpsseControllerenables access to the MSB pins of wide ports.
However LSB and MSB pins cannot be addressed in a true atomic manner, which means that there is a short delay between sampling/updating the LSB and MSB part of the same wide port. Byte buffer can also be sampled/updated at a regular pace, but the achievable frequency range may differ from the other controllers.
It is recommened to read the
tests/gpio.py files - available from GitHub -
to get some examples on how to use these API variants.
Setting GPIO pin state¶
To write to a GPIO, use the write() method. The caller needs to mask out the bits configured as input, or an exception is triggered:
0to an input pin is ignored
1to an input pin raises an exception
gpio = GpioAsyncController() gpio.configure('ftdi:///1', direction=0x76) # all output set low gpio.write(0x00) # all output set high gpio.write(0x76) # all output set high, apply direction mask gpio.write(0xFF & gpio.direction) # all output forced to high, writing to input pins is illegal gpio.write(0xFF) # raises an IOError gpio.close()
Retrieving GPIO pin state¶
To read a GPIO, use the read() method.
gpio = GpioAsyncController() gpio.configure('ftdi:///1', direction=0x76) # read whole port pins = gpio.read() # ignore output values (optional) pins &= ~gpio.direction gpio.close()
Modifying GPIO pin state¶
A read-modify-write sequence is required.
gpio = GpioAsyncController() gpio.configure('ftdi:///1', direction=0x76) # read whole port pins = gpio.read() # clearing out AD1 and AD2 pins &= ~((1 << 1) | (1 << 2)) # or 0x06 # want AD2=0, AD1=1 pins |= 1 << 1 # update GPIO output gpio.write(pins) gpio.close()
Synchronous GPIO access¶
gpio = GpioSyncController() gpio.configure('ftdi:///1', direction=0x0F, frequency=1e6) outs = bytes(range(16)) ins = gpio.exchange(outs) # ins contains as many bytes as outs gpio.close()
CBUS GPIO access¶
ftdi = Ftdi() ftdi.open_from_url('ftdi:///1') # validate CBUS feature with the current device assert ftdi.has_cbus # validate CBUS EEPROM configuration with the current device eeprom = FtdiEeprom() eeprom.connect(ftdi) # here we use CBUS0 and CBUS3 (or CBUS5 and CBUS9 on FT232H) assert eeprom.cbus_mask & 0b1001 == 0b1001 # configure CBUS0 as output and CBUS3 as input ftdi.set_cbus_direction(0b1001, 0b0001) # set CBUS0 ftdi.set_cbus_gpio(0x1) # get CBUS3 cbus3 = ftdi.get_cbus_gpio() >> 3
# it is possible to open the ftdi object from an existing serial connection: port = serial_for_url('ftdi:///1') ftdi = port.ftdi ftdi.has_cbus # etc...
GPIO pins vs. feature pins¶
It is important to note that the reserved pins do not change the pin assignment, i.e. the lowest pins of a port may become unavailable as regular GPIO when the feature is enabled:
I2C feature reserves the three first pins, as SCL, SDA output, SDA input (w/o clock stretching feature which also reserves another pin). This means that AD0, AD1 and AD2, that is b0, b1, b2 cannot be directly accessed.
The first accessible GPIO pin in this case is no longer AD0 but AD3, which means that b3becomes the lowest bit which can be read/written.
# use I2C feature i2c = I2cController() # configure the I2C feature, and predefines the direction of the GPIO pins i2c.configure('ftdi:///1', direction=0x78) gpio = i2c.get_gpio() # read whole port pins = gpio.read() # clearing out I2C bits (SCL, SDAo, SDAi) pins &= 0x07 # set AD4 pins |= 1 << 4 # update GPIO output gpio.write(pins)