gpio - GPIO API

Direct drive GPIO pins of FTDI device.

Note

This mode is mutually exclusive with advanced serial MPSSE features, such as I²C, SPI, JTAG, …

If you need to use GPIO pins and MPSSE interface on the same port, you need to use the dedicated API. This shared mode is supported with the SPI API and the I2C API.

Warning

This API does not provide access to the special CBUS port of FT232R, FT232H, FT230X and FT231X devices. See CBUS GPIOs for details.

Quickstart

See tests/gpio.py example

Classes

class pyftdi.gpio.GpioPort

Duck-type GPIO port for GPIO all controllers.

class pyftdi.gpio.GpioAsyncController

GPIO controller for an FTDI port, in bit-bang asynchronous mode.

GPIO accessible pins are limited to the 8 lower pins of each GPIO port.

Asynchronous bitbang output are updated on write request using the write() method, clocked at the selected frequency.

Asynchronous bitbang input are sampled at the same rate, as soon as the controller is initialized. The GPIO input samples fill in the FTDI HW buffer until it is filled up, in which case sampling stops until the GPIO samples are read out with the read() method. It may be therefore hard to use, except if peek mode is selected, see read() for details.

Note that FTDI internal clock divider cannot generate any arbitrary frequency, so the closest frequency to the request one that can be generated is selected. The actual frequency may be tested to check if it matches the board requirements.

open_from_url(url, direction=0, **kwargs)

Open a new interface to the specified FTDI device in bitbang mode.

Parameters

• url (str) – a FTDI URL selector

• direction (int) – a bitfield specifying the FTDI GPIO direction, where high level defines an output, and low level defines an input

• initial – optional initial GPIO output value

• pace – optional pace in GPIO sample per second

Return type

int

Returns

actual bitbang pace in sample per second

read(readlen=1, peek=None, noflush=False)

Read the GPIO input pin electrical level.

Parameters

• readlen (int) – how many GPIO samples to retrieve. Each sample is 8-bit wide.

• peek (Optional[bool]) – whether to peek/sample the instantaneous GPIO pin values from port, or to use the HW FIFO. The HW FIFO is continously filled up with GPIO sample at the current frequency, until it is full - samples are no longer collected until the FIFO is read. This means than non-peek mode read “old” values, with no way to know at which time they have been sampled. PyFtdi ensures that old sampled values before the completion of a previous GPIO write are discarded. When peek mode is selected, readlen should be 1.

• noflush (bool) – whether to disable the RX buffer flush before reading out data

Return type

Union[int, bytes]

Returns

a 8-bit wide integer if peek mode is used, or a bytes buffer otherwise.

read_port(readlen=1, peek=None, noflush=False)

Read the GPIO input pin electrical level.

Parameters

• readlen (int) – how many GPIO samples to retrieve. Each sample is 8-bit wide.

• peek (Optional[bool]) – whether to peek/sample the instantaneous GPIO pin values from port, or to use the HW FIFO. The HW FIFO is continously filled up with GPIO sample at the current frequency, until it is full - samples are no longer collected until the FIFO is read. This means than non-peek mode read “old” values, with no way to know at which time they have been sampled. PyFtdi ensures that old sampled values before the completion of a previous GPIO write are discarded. When peek mode is selected, readlen should be 1.

• noflush (bool) – whether to disable the RX buffer flush before reading out data

Return type

Union[int, bytes]

Returns

a 8-bit wide integer if peek mode is used, or a bytes buffer otherwise.

set_frequency(frequency)

Set the frequency at which sequence of GPIO samples are read and written.

note: FTDI may update its clock register before it has emptied its internal buffer. If the current frequency is “low”, some yet-to-output bytes may end up being clocked at the new frequency.

Unfortunately, it seems there is no way to wait for the internal buffer to be emptied out. They can be flushed (i.e. discarded), but not synchronized :-(

PyFtdi client should add “some” short delay to ensure a previous, long write request has been fully output @ low freq before changing the frequency.

Beware that only some exact frequencies can be generated. Contrary to the UART mode, an approximate frequency is always accepted for GPIO/bitbang mode. To get the actual frequency, and optionally abort if it is out-of-spec, use frequency() property.

Parameters

frequency (Union[int, float]) – the new frequency, in GPIO samples per second

Return type

None

write(out)

Set the GPIO output pin electrical level, or output a sequence of bytes @ constant frequency to GPIO output pins.

Parameters

out (Union[bytes, bytearray, int]) – a bitfield of GPIO pins, or a sequence of them

Return type

None

write_port(out)

Set the GPIO output pin electrical level, or output a sequence of bytes @ constant frequency to GPIO output pins.

Parameters

out (Union[bytes, bytearray, int]) – a bitfield of GPIO pins, or a sequence of them

Return type

None

class pyftdi.gpio.GpioSyncController

GPIO controller for an FTDI port, in bit-bang synchronous mode.

GPIO accessible pins are limited to the 8 lower pins of each GPIO port.

Synchronous bitbang input and output are synchronized. Eveery time GPIO output is updated, the GPIO input is sampled and buffered.

Update and sampling are clocked at the selected frequency. The GPIO samples are transfer in both direction with the exchange() method, which therefore always returns as many input samples as output bytes.

Note that FTDI internal clock divider cannot generate any arbitrary frequency, so the closest frequency to the request one that can be generated is selected. The actual frequency may be tested to check if it matches the board requirements.

exchange(out)

Set the GPIO output pin electrical level, or output a sequence of bytes @ constant frequency to GPIO output pins.

Parameters

out (Union[bytes, bytearray]) – the byte buffer to output as GPIO

Return type

bytes

Returns

a byte buffer of the same length as out buffer.

set_frequency(frequency)

Set the frequency at which sequence of GPIO samples are read and written.

Parameters

frequency (Union[int, float]) – the new frequency, in GPIO samples per second

Return type

None

class pyftdi.gpio.GpioMpsseController

GPIO controller for an FTDI port, in MPSSE mode.

All GPIO pins are reachable, but MPSSE mode is slower than other modes.

Beware that LSBs (b0..b7) and MSBs (b8..b15) are accessed with two subsequence commands, so a slight delay may occur when sampling or changing both groups at once. In other word, it is not possible to atomically read to / write from LSBs and MSBs. This might be worth checking the board design if atomic access to several lines is required.

read(readlen=1, peek=None)

Read the GPIO input pin electrical level.

Parameters

• readlen (int) – how many GPIO samples to retrieve. Each sample if width() bit wide.

• peek (Optional[bool]) – whether to peak current value from port, or to use MPSSE stream and HW FIFO. When peek mode is selected, readlen should be 1. It is not available with wide ports if some of the MSB pins are configured as input

Return type

Union[int, bytes, Tuple[int]]

Returns

a width() bit wide integer if direct mode is used, a bytes buffer if width() is a byte, a list of integer otherwise (MPSSE mode only).

set_frequency(frequency)

Set the frequency at which sequence of GPIO samples are read and written.

Parameters

frequency (Union[int, float]) – the new frequency, in GPIO samples per second

Return type

None

write(out)

Set the GPIO output pin electrical level, or output a sequence of bytes @ constant frequency to GPIO output pins.

Parameters

out (Union[bytes, bytearray, Iterable[int], int]) – a bitfield of GPIO pins, or a sequence of them

Return type

None

Exceptions

exception pyftdi.gpio.GpioException

Base class for GPIO errors.

Info about GPIO API

See GPIOs for details