ftdi - FTDI low-level driver

This module implements access to the low level FTDI hardware. There are very few reasons to use this module directly. Most of PyFtdi features are available through the dedicated APIs.

Classes

class pyftdi.ftdi.Ftdi

FTDI device driver

class BitMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Function selection.

DEFAULT_VENDOR = 1027

Default vendor: FTDI.

DEVICE_NAMES = {512: 'ft232am', 1024: 'ft232bm', 1280: 'ft2232c', 1536: 'ft232r', 1792: 'ft2232h', 2048: 'ft4232h', 2304: 'ft232h', 4096: 'ft-x', 13824: 'ft4232ha'}

Common names of FTDI supported devices.

FIFO_SIZES = {512: (128, 128), 1024: (128, 384), 1280: (128, 384), 1536: (256, 128), 1792: (4096, 4096), 2048: (2048, 2048), 2304: (1024, 1024), 4096: (512, 512), 13824: (2048, 2048)}

FTDI chip internal FIFO sizes

Note that ‘TX’ and ‘RX’ are inverted with the datasheet terminology: Values here are seen from the host perspective, whereas datasheet values are defined from the device perspective

FTDI_VENDOR = 1027

USB VID for FTDI chips.

PRODUCT_IDS = {1027: {'2232': 24592, '2232c': 24592, '2232d': 24592, '2232h': 24592, '230x': 24597, '231x': 24597, '232': 24577, '232h': 24596, '232r': 24577, '234x': 24597, '4232': 24593, '4232h': 24593, '4232ha': 24648, 'ft-x': 24597, 'ft2232': 24592, 'ft2232c': 24592, 'ft2232d': 24592, 'ft2232h': 24592, 'ft230x': 24597, 'ft231x': 24597, 'ft232': 24577, 'ft232h': 24596, 'ft232r': 24577, 'ft234x': 24597, 'ft4232': 24593, 'ft4232h': 24593, 'ft4232ha': 24648}}

Supported products, only FTDI officials ones. To add third parties and customized products, see add_custom_product().

SCHEME = 'ftdi'

URL scheme for UsbTools.

VENDOR_IDS = {'ftdi': 1027}

Supported vendors, only FTDI. To add third parties vendors see add_custom_vendor().

classmethod add_custom_product(vid, pid, pidname='')

Add a custom USB product identifier.

It is required for opening FTDI device with non-standard VID/PID USB identifiers.

Parameters:

  • vid (int) – Vendor ID (USB 16-bit identifier)

  • pid (int) – Product ID (USB 16-bit identifier)

  • pidname (str) – Product name (arbitrary string)

Raises:

ValueError – if the product id is already referenced

Return type:

None

classmethod add_custom_vendor(vid, vidname='')

Add a custom USB vendor identifier.

It can be useful to use a pretty URL for opening FTDI device

Parameters:

  • vid (int) – Vendor ID (USB 16-bit identifier)

  • vidname (str) – Vendor name (arbitrary string)

Raises:

ValueError – if the vendor id is already referenced

Return type:

None

property baudrate: int

Return current baudrate.

property bitbang_enabled: bool

Tell whether some bitbang mode is activated

Returns:

True if the FTDI interface is configured to support bitbanging

calc_eeprom_checksum(data)

Calculate EEPROM checksum over the data

Parameters:

data (Union[bytes, bytearray]) – data to compute checksum over. Must be an even number of bytes

Return type:

int

Returns:

checksum

close(freeze=False)

Close the FTDI interface/port.

Parameters:

freeze (bool) – if set, FTDI port is not reset to its default state on close. This means the port is left with its current configuration and output signals. This feature should not be used except for very specific needs.

Return type:

None

classmethod create_from_url(url)

Create an Ftdi instance from an URL

URL scheme: ftdi://[vendor[:product[:index|:serial]]]/interface

Parameters:

url (str) – FTDI device selector

Return type:

Ftdi

Returns:

a fresh, open Ftdi instance

classmethod decode_modem_status(value, error_only=False)

Decode the FTDI modem status bitfield into short strings.

Parameters:

  • value (bytes) – 2-byte mode status

  • error_only (bool) – only decode error flags

Return type:

Tuple[str, ...]

Returns:

a tuple of status identifiers

property device_port_count: int

Report the count of port/interface of the Ftdi device.

Returns:

the count of ports

property device_version: int

Report the device version, i.e. the kind of device.

See:

ic_name() for a product version of this information.

Returns:

the device version (16-bit integer)

enable_3phase_clock(enable=True)

Enable 3-phase clocking mode, useful in MPSSE mode.

3-phase clock is mostly useful with I2C mode. It is also be used as a workaround to support SPI mode 3.

Parameters:

enable (bool) – whether to enable or disable this mode.

Raises:

FtdiMpsseError – if MPSSE mode is not enabled or device is not capable of 3-phase clocking

Return type:

None

enable_adaptive_clock(enable=True)

Enable adaptative clock mode, useful in MPSEE mode.

Adaptive clock is a unique feature designed for a feedback clock for JTAG with ARM core.

Parameters:

enable (bool) – whether to enable or disable this mode.

Raises:

FtdiMpsseError – if MPSSE mode is not enabled

Return type:

None

enable_drivezero_mode(lines)

Enable drive-zero mode, useful in MPSSE mode.

drive-zero mode is mostly useful with I2C mode, to support the open collector driving mode.

Parameters:

lines (int) – bitfield of GPIO to drive in collector driven mode

Raises:

FtdiMpsseError – if MPSSE mode is not enabled or device is not capable of drive-zero mode

Return type:

None

enable_loopback_mode(loopback=False)

Enable loopback, i.e. connect DO to DI in FTDI MPSSE port for test purposes only. It does not support UART (TX to RX) mode.

Parameters:

loopback (bool) – whether to enable or disable this mode

Return type:

None

property fifo_sizes: Tuple[int, int]

Return the (TX, RX) tupple of hardware FIFO sizes

Returns:

2-tuple of TX, RX FIFO size in bytes

static find_all(vps, nocache=False)

Find all devices that match the vendor/product pairs of the vps list.

Parameters:

  • vps (tuple(int, int)) – a sequence of 2-tuple (vid, pid) pairs

  • nocache (bool) – bypass cache to re-enumerate USB devices on the host

Returns:

a list of 5-tuple (vid, pid, sernum, iface, description) device descriptors

Return type:

list(tuple(int,int,str,int,str))

property frequency_max: float

Tells the maximum frequency for MPSSE clock.

Returns:

the maximum supported frequency in Hz

get_cbus_gpio()

Get the CBUS pins configured as GPIO inputs

Return type:

int

Returns:

bitfield of CBUS read pins

get_cd()

Read terminal status line: Carrier Detect

Return type:

bool

Returns:

CD line logical level

get_cts()

Read terminal status line: Clear To Send

Return type:

bool

Returns:

CTS line logical level

classmethod get_device(url)

Get a USB device from its URL, without opening an instance.

Parameters:

url (str) – input URL to parse

Return type:

Device

Returns:

the USB device that match the specified URL

get_dsr()

Read terminal status line: Data Set Ready

Return type:

bool

Returns:

DSR line logical level

classmethod get_error_string()

Wrapper for legacy compatibility.

Return type:

str

Returns:

a constant, meaningless string

classmethod get_identifiers(url)

Extract the identifiers of an FTDI device from URL, if any

Parameters:

url (str) – input URL to parse

Return type:

Tuple[UsbDeviceDescriptor, int]

get_latency_timer()

Get latency timer.

Return type:

int

Returns:

the current latency (unspecified unit)

get_ri()

Read terminal status line: Ring Indicator

Return type:

bool

Returns:

RI line logical level

property has_cbus: bool

Tell whether the device supports CBUS bitbang.

CBUS bitbanging feature requires a special configuration in EEPROM. This function only reports if the current device supports this mode, not if this mode has been enabled in EEPROM.

EEPROM configuration must be queried to check which CBUS pins have been configured for GPIO/bitbang mode.

Returns:

True if the FTDI device supports CBUS bitbang

Raises:

FtdiError – if no FTDI port is open

property has_drivezero: bool

Tell whether the device supports drive-zero mode, i.e. if the device supports the open-collector drive mode, useful for I2C communication for example.

Returns:

True if the FTDI device features drive-zero mode

Raises:

FtdiError – if no FTDI port is open

property has_mpsse: bool

Tell whether the device supports MPSSE (I2C, SPI, JTAG, …)

Returns:

True if the FTDI device supports MPSSE

Raises:

FtdiError – if no FTDI port is open

property has_wide_port: bool

Tell whether the device supports 16-bit GPIO ports (vs. 8 bits)

Returns:

True if the FTDI device supports wide GPIO port

Raises:

FtdiError – if no FTDI port is open

property ic_name: str

Return the current type of the FTDI device as a string

see also http://www.ftdichip.com/Support/ Documents/TechnicalNotes/TN_100_USB_VID-PID_Guidelines.pdf

Returns:

the identified FTDI device as a string

property is_H_series: bool

Tell whether the device is a high-end FTDI

Returns:

True if the FTDI device is a high-end USB-UART bridge

Raises:

FtdiError – if no FTDI port is open

property is_bitbang_enabled: bool

Tell whether some bitbang mode is activated

Returns:

True if the FTDI interface is configured to support bitbanging

property is_connected: bool

Tells whether this instance is connected to an actual USB slave.

Returns:

the slave connection status

property is_eeprom_internal: bool

Tell whether the device has an internal EEPROM.

Returns:

True if the device has an internal EEPROM.

property is_legacy: bool

Tell whether the device is a low-end FTDI

Returns:

True if the FTDI device can only be used as a slow USB-UART bridge

Raises:

FtdiError – if no FTDI port is open

property is_mpsse: bool

Tell whether the device is configured in MPSSE mode

Returns:

True if the FTDI interface is configured in MPSSE mode

is_mpsse_interface(interface)

Tell whether the interface supports MPSSE (I2C, SPI, JTAG, …)

Return type:

bool

Returns:

True if the FTDI interface supports MPSSE

Raises:

FtdiError – if no FTDI port is open

classmethod list_devices(url=None)

List of URLs of connected FTDI devices.

Parameters:

url (Optional[str]) – a pattern URL to restrict the search

Return type:

List[Tuple[UsbDeviceDescriptor, int]]

Returns:

list of (UsbDeviceDescriptor, interface)

property max_eeprom_size: int

Report the maximum size of the EEPROM. The actual size may be lower, of even 0 if no EEPROM is connected or supported.

Returns:

the maximum size in bytes.

modem_status()

Provide the current modem status as a tuple of set signals

Return type:

Tuple[str, ...]

Returns:

decodede modem status as short strings

property mpsse_bit_delay: float

Delay between execution of two MPSSE SET_BITS commands.

Returns:

minimum delay (actual value might be larger) in seconds

open(vendor, product, bus=None, address=None, index=0, serial=None, interface=1)

Open a new interface to the specified FTDI device.

If several FTDI devices of the same kind (vid, pid) are connected to the host, either index or serial argument should be used to discriminate the FTDI device.

index argument is not a reliable solution as the host may enumerate the USB device in random order. serial argument is more reliable selector and should always be prefered.

Some FTDI devices support several interfaces/ports (such as FT2232H, FT4232H and FT4232HA). The interface argument selects the FTDI port to use, starting from 1 (not 0).

Parameters:

  • vendor (int) – USB vendor id

  • product (int) – USB product id

  • bus (int) – optional selector, USB bus

  • address (int) – optional selector, USB address on bus

  • index (int) – optional selector, specified the n-th matching FTDI enumerated USB device on the host

  • serial (str) – optional selector, specified the FTDI device by its serial number

  • interface (str) – FTDI interface/port

Return type:

None

open_bitbang(vendor, product, bus=None, address=None, index=0, serial=None, interface=1, direction=0, latency=16, baudrate=1000000, sync=False)

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

Bitbang enables direct read or write to FTDI GPIOs.

Parameters:

  • vendor (int) – USB vendor id

  • product (int) – USB product id

  • index (int) – optional selector, specified the n-th matching FTDI enumerated USB device on the host

  • serial (Optional[str]) – optional selector, specified the FTDI device by its serial number

  • interface (int) – FTDI interface/port

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

  • latency (int) – low-level latency to select the USB FTDI poll delay. The shorter the delay, the higher the host CPU load.

  • baudrate (int) – pace to sequence GPIO exchanges

  • sync (bool) – whether to use synchronous or asynchronous bitbang

Return type:

float

Returns:

actual bitbang baudrate in bps

open_bitbang_from_device(device, interface=1, direction=0, latency=16, baudrate=1000000, sync=False)

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

Bitbang enables direct read or write to FTDI GPIOs.

Parameters:

  • device (Device) – FTDI USB device

  • interface (int) – FTDI interface/port

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

  • latency (int) – low-level latency to select the USB FTDI poll delay. The shorter the delay, the higher the host CPU load.

  • baudrate (int) – pace to sequence GPIO exchanges

  • sync (bool) – whether to use synchronous or asynchronous bitbang

Return type:

int

Returns:

actual bitbang baudrate in bps

open_bitbang_from_url(url, direction=0, latency=16, baudrate=1000000, sync=False)

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

Bitbang enables direct read or write to FTDI GPIOs.

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

  • latency (int) – low-level latency to select the USB FTDI poll delay. The shorter the delay, the higher the host CPU load.

  • baudrate (int) – pace to sequence GPIO exchanges

  • sync (bool) – whether to use synchronous or asynchronous bitbang

Return type:

float

Returns:

actual bitbang baudrate in bps

open_from_device(device, interface=1)

Open a new interface from an existing USB device.

Parameters:

  • device (Device) – FTDI USB device (PyUSB instance)

  • interface (int) – FTDI interface to use (integer starting from 1)

Return type:

None

open_from_url(url)

Open a new interface to the specified FTDI device.

Parameters:

url (str) – a FTDI URL selector

Return type:

None

open_mpsse(vendor, product, bus=None, address=None, index=0, serial=None, interface=1, direction=0, initial=0, frequency=6000000.0, latency=16, debug=False)

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

MPSSE enables I2C, SPI, JTAG or other synchronous serial interface modes (vs. UART mode).

If several FTDI devices of the same kind (vid, pid) are connected to the host, either index or serial argument should be used to discriminate the FTDI device.

index argument is not a reliable solution as the host may enumerate the USB device in random order. serial argument is more reliable selector and should always be prefered.

Some FTDI devices support several interfaces/ports (such as FT2232H, FT4232H and FT4232HA). The interface argument selects the FTDI port to use, starting from 1 (not 0). Note that not all FTDI ports are MPSSE capable.

Parameters:

  • vendor (int) – USB vendor id

  • product (int) – USB product id

  • bus (Optional[int]) – optional selector, USB bus

  • address (Optional[int]) – optional selector, USB address on bus

  • index (int) – optional selector, specified the n-th matching FTDI enumerated USB device on the host

  • serial (Optional[str]) – optional selector, specified the FTDI device by its serial number

  • interface (int) – FTDI interface/port

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

  • initial (int) – a bitfield specifying the initial output value

  • frequency (float) – serial interface clock in Hz

  • latency (int) – low-level latency in milliseconds. The shorter the delay, the higher the host CPU load. Do not use shorter values than the default, as it triggers data loss in FTDI.

  • debug (bool) – use a tracer to decode MPSSE protocol

Return type:

float

Returns:

actual bus frequency in Hz

open_mpsse_from_device(device, interface=1, direction=0, initial=0, frequency=6000000.0, latency=16, tracer=False, debug=False)

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

MPSSE enables I2C, SPI, JTAG or other synchronous serial interface modes (vs. UART mode).

If several FTDI devices of the same kind (vid, pid) are connected to the host, either index or serial argument should be used to discriminate the FTDI device.

index argument is not a reliable solution as the host may enumerate the USB device in random order. serial argument is more reliable selector and should always be prefered.

Some FTDI devices support several interfaces/ports (such as FT2232H, FT4232H and FT4232HA). The interface argument selects the FTDI port to use, starting from 1 (not 0). Note that not all FTDI ports are MPSSE capable.

Parameters:

  • device (Device) – FTDI USB device

  • interface (int) – FTDI interface/port

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

  • initial (int) – a bitfield specifying the initial output value

  • frequency (float) – serial interface clock in Hz

  • latency (int) – low-level latency in milliseconds. The shorter the delay, the higher the host CPU load. Do not use shorter values than the default, as it triggers data loss in FTDI.

  • tracer (bool) – use a tracer to decode MPSSE protocol

  • debug (bool) – add more debug traces

Return type:

float

Returns:

actual bus frequency in Hz

open_mpsse_from_url(url, direction=0, initial=0, frequency=6000000.0, latency=16, debug=False)

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

MPSSE enables I2C, SPI, JTAG or other synchronous serial interface modes (vs. UART 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 (int) – a bitfield specifying the initial output value

  • frequency (float) – serial interface clock in Hz

  • latency (int) – low-level latency in milliseconds. The shorter the delay, the higher the host CPU load. Do not use shorter values than the default, as it triggers data loss in FTDI.

  • debug (bool) – use a tracer to decode MPSSE protocol

Return type:

float

Returns:

actual bus frequency in Hz

overwrite_eeprom(data, dry_run=True)

Write the whole EEPROM content, from first to last byte.

Warning

You can brick your device with invalid size or content. Use this function at your own risk, and RTFM.

Parameters:

  • data (Union[bytes, bytearray]) – data to be written (should include the checksum)

  • dry_run (bool) – log what should be written, do not actually change the EEPROM content

Return type:

None

poll_modem_status()

Poll modem status information.

This function allows the retrieve the two status bytes of the device, useful in UART mode.

FTDI device does not have a so-called USB “interrupt” end-point, event polling on the UART interface is done through the regular control endpoint.

see modem_status() to obtain decoded status strings

Return type:

int

Returns:

modem status, as a proprietary bitfield

property port_index: int

Report the port/interface index, starting from 1

Returns:

the port position/index

property port_width: int

Report the width of a single port / interface

Returns:

the width of the port, in bits

Raises:

FtdiError – if no FTDI port is open

purge_buffers()

Clear the buffers on the chip and the internal read buffer.

Return type:

None

purge_rx_buffer()

Clear the USB receive buffer on the chip (host-to-ftdi) and the internal read buffer.

Return type:

None

purge_tx_buffer()

Clear the USB transmit buffer on the chip (ftdi-to-host).

Return type:

None

read_data(size)

Shortcut to received a bytes buffer instead of the array of bytes.

Note that output byte buffer may be shorted than the requested size.

Parameters:

size (int) – the number of bytes to received from the device

Return type:

bytes

Returns:

payload bytes

read_data_bytes(size, attempt=1, request_gen=None)

Read data from the FTDI interface

In UART mode, data contains the serial stream read from the UART interface.

In MPSSE mode, data contains the sequence of data received and processed with the MPSEE engine.

Data buffer is rebuilt from chunk-sized blocks received over the USB bus.

FTDI device always sends internal status bytes, which are stripped out as not part of the data payload.

Because of the multiple buses, buffers, FIFOs, and MPSSE command processing, data might not be immediately available on the host side. The attempt argument can be used to increase the attempt count to retrieve the expected amount of data, before giving up and returning all the received data, which may be shorted than the requested amount.

Parameters:

  • size (int) – the number of bytes to received from the device

  • attempt (int) – attempt cycle count

  • request_gen (Optional[Callable[[int], Union[bytes, bytearray]]]) – a callable that takes the number of bytes read and expect a bytes byffer to send back to the remote device. This is only useful to perform optimized/continuous transfer from a slave device.

Return type:

bytearray

Returns:

payload bytes, as bytes

read_data_get_chunksize()

Get read buffer chunk size.

Return type:

int

Returns:

the size of the write buffer in bytes

read_data_set_chunksize(chunksize=0)

Configure read buffer chunk size.

This is a low-level configuration option, which is not intended to be use for a regular usage.

Parameters:

chunksize (int) – the optional size of the read buffer in bytes, it is recommended to use 0 to force automatic evaluation of the best value.

Return type:

None

read_eeprom(addr=0, length=None, eeprom_size=None)

Read the EEPROM starting at byte address, addr, and returning length bytes. Here, addr and length are in bytes but we access a 16-bit word at a time, so automatically update addr and length to work with word accesses.

Parameters:

  • addr (int) – byte address that desire to read.

  • length (Optional[int]) – byte length to read or None

  • eeprom_size (Optional[int]) – total size in bytes of the eeprom or None

Return type:

bytes

Returns:

eeprom bytes, as an array of bytes

read_pins()

Directly read pin state, circumventing the read buffer. Useful for bitbang mode.

Return type:

int

Returns:

bitfield of FTDI interface input GPIO

reset(usb_reset=False)

Reset FTDI device.

Parameters:

usb_reset (bool) – wether to perform a full USB reset of the device.

Return type:

None

Beware that selecting usb_reset performs a full USB device reset, which means all other interfaces of the same device are also affected.

set_baudrate(baudrate, constrain=True)

Change the current UART or BitBang baudrate.

The FTDI device is not able to use an arbitrary baudrate. Its internal dividors are only able to achieve some baudrates.

PyFtdi attemps to find the closest configurable baudrate and if the deviation from the requested baudrate is too high, it rejects the configuration if constrain is set.

baudrate attribute can be used to retrieve the exact selected baudrate.

BAUDRATE_TOLERANCE defines the maximum deviation between the requested baudrate and the closest FTDI achieveable baudrate, which matches standard UART clock drift (3%). If the achievable baudrate is not within limits, baudrate setting is rejected.

Parameters:

  • baudrate (int) – the new baudrate for the UART.

  • constrain (bool) – whether to validate baudrate is in RS232 tolerance limits or allow larger drift

Raises:

  • ValueError – if deviation from selected baudrate is too large

  • FtdiError – on IO Error

Return type:

int

Returns:

the effective baudrate

set_bitmode(bitmask, mode)

Enable/disable bitbang modes.

Switch the FTDI interface to bitbang mode.

Return type:

None

set_break(break_)

Start or stop a break exception event on the serial line

Parameters:

break – either start or stop break event

Return type:

None

set_cbus_direction(mask, direction)

Configure the CBUS pins used as GPIOs

Parameters:

  • mask (int) – which pins to configure as GPIOs

  • direction (int) – which pins are output (vs. input)

Return type:

None

set_cbus_gpio(pins)

Set the CBUS pins configured as GPIO outputs

Parameters:

pins (int) – bitfield to apply to CBUS output pins

Return type:

None

set_dtr(state)

Set dtr line

Parameters:

state (bool) – new DTR logical level

Return type:

None

set_dtr_rts(dtr, rts)

Set dtr and rts lines at once

Parameters:

  • dtr (bool) – new DTR logical level

  • rts (bool) – new RTS logical level

Return type:

None

set_dynamic_latency(lmin, lmax, threshold)

Set up or disable latency values.

Dynamic latency management is a load balancer to adapt the responsiveness of FTDI read request vs. the host CPU load.

It is mostly useful in UART mode, so that read bandwidth can be increased to the maximum achievable throughput, while maintaining very low host CPU load when no data is received from the UART.

There should be no need to tweak the default values. Use with care.

Minimum latency is limited to 12 or above, at FTDI device starts losing bytes when latency is too short…

Maximum latency value is 255 ms.

Polling latency is reset to lmin each time at least one payload byte is received from the FTDI device.

It doubles, up to lmax, every threshold times no payload has been received from the FTDI device.

Parameters:

  • lmin (int) – minimum latency level (ms)

  • lmax (int) – maximum latenty level (ms)

  • threshold (int) – count to reset latency to maximum level

Return type:

None

set_error_char(errorch, enable)

Set error character

Return type:

None

set_event_char(eventch, enable)

Set the special event character

Return type:

None

set_flowctrl(flowctrl)

Select flowcontrol in UART mode.

Either hardware flow control through RTS/CTS UART lines, software or no flow control.

Parameters:

flowctrl (str) – either ‘hw’ for HW flow control or ‘’ (empty string) for no flow control.

Raises:

ValueError – if the flow control argument is invalid

Return type:

None

Note

How does RTS/CTS flow control work (from FTDI FAQ):

FTxxx RTS# pin is an output. It should be connected to the CTS# input pin of the device at the other end of the UART link.

  • If RTS# is logic 0 it is indicating the FTxxx device can accept more data on the RXD pin.

  • If RTS# is logic 1 it is indicating the FTxxx device cannot accept more data.

RTS# changes state when the chip buffer reaches its last 32 bytes of space to allow time for the external device to stop sending data to the FTxxx device.

FTxxx CTS# pin is an input. It should be connected to the RTS# output pin of the device at the other end of the UART link.

  • If CTS# is logic 0 it is indicating the external device can accept more data, and the FTxxx will transmit on the TXD pin.

  • If CTS# is logic 1 it is indicating the external device cannot accept more data. the FTxxx will stop transmitting within 0~3 characters, depending on what is in the buffer.

    This potential 3 character overrun does occasionally present problems. Customers shoud be made aware the FTxxx is a USB device and not a “normal” RS232 device as seen on a PC. As such the device operates on a packet basis as opposed to a byte basis.

Word to the wise. Not only do RS232 level shifting devices level shift, but they also invert the signal.

set_frequency(frequency)

Change the current MPSSE bus frequency

The FTDI device is not able to use an arbitrary frequency. Its internal dividors are only able to achieve some frequencies.

PyFtdi finds and selects the closest configurable frequency.

Parameters:

frequency (float) – the new frequency for the serial interface, in Hz.

Return type:

float

Returns:

the selected frequency, which may differ from the requested one, in Hz

set_latency_timer(latency)

Set latency timer.

The FTDI chip keeps data in the internal buffer for a specific amount of time if the buffer is not full yet to decrease load on the usb bus.

The shorted the latency, the shorted the delay to obtain data and the higher the host CPU load. Be careful with this option.

Parameters:

latency (int) – latency (unspecified unit)

set_line_property(bits, stopbit, parity, break_=False)

Configure the (RS232) UART characteristics.

Arguments match the valid subset for FTDI HW of pyserial definitions.

Bits accepts one of the following values:

  • 7 for 7-bit characters

  • 8 for 8-bit characters

Stopbit accepts one of the following values:

  • 1 for a single bit

  • 1.5 for a bit and a half

  • 2 for two bits

Parity accepts one of the following strings:

  • N for no parity bit

  • O for odd parity bit

  • E for even parity bit

  • M for parity bit always set

  • S for parity bit always reset

Parameters:

  • bits (int) – data bit count

  • stopbit (Union[int, float]) – stop bit count

  • parity (str) – parity mode as a single uppercase character

  • break – force break event

Return type:

None

set_rts(state)

Set rts line

Parameters:

state (bool) – new RTS logical level

Return type:

None

classmethod show_devices(url=None, out=None)

Print the URLs and descriptors of connected FTDI devices.

Parameters:

  • url (Optional[str]) – a pattern URL to restrict the search

  • out (Optional[TextIO]) – output stream, default to stdout

Return type:

None

property usb_dev: Device

Return the underlying USB Device.

property usb_path: Tuple[int, int, int]

Provide the physical location on the USB topology.

Returns:

a tuple of bus, address, interface; if connected

validate_mpsse()

Check that the previous MPSSE request has been accepted by the FTDI device.

Raises:

FtdiError – if the FTDI device rejected the command.

Return type:

None

write_data(data)

Write data to the FTDI port.

In UART mode, data contains the serial stream to write to the UART interface.

In MPSSE mode, data contains the sequence of MPSSE commands and data.

Data buffer is split into chunk-sized blocks before being sent over the USB bus.

Parameters:

data (Union[bytes, bytearray]) – the byte stream to send to the FTDI interface

Return type:

int

Returns:

count of written bytes

write_data_get_chunksize()

Get write buffer chunk size.

Return type:

int

Returns:

the size of the write buffer in bytes

write_data_set_chunksize(chunksize=0)

Configure write buffer chunk size.

This is a low-level configuration option, which is not intended to be use for a regular usage.

Parameters:

chunksize (int) – the optional size of the write buffer in bytes, it is recommended to use 0 to force automatic evaluation of the best value.

Return type:

None

write_eeprom(addr, data, eeprom_size=None, dry_run=True)

Write multiple bytes to the EEPROM starting at byte address, addr. This function also updates the checksum automatically.

Warning

You can brick your device with invalid size or content. Use this function at your own risk, and RTFM.

Parameters:

  • addr (int) – starting byte address to start writing

  • data (Union[bytes, bytearray]) – data to be written

  • eeprom_size (Optional[int]) – total size in bytes of the eeprom or None

  • dry_run (bool) – log what should be written, do not actually change the EEPROM content

Return type:

None

Exceptions

exception pyftdi.ftdi.FtdiError

Base class error for all FTDI device

exception pyftdi.ftdi.FtdiMpsseError

MPSSE mode not supported on FTDI device

exception pyftdi.ftdi.FtdiFeatureError

Requested feature is not available on FTDI device