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)

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'}

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)}

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, '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}}

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

Return current baudrate.

Return type

int

property bitbang_enabled

Tell whether some bitbang mode is activated

Return type

bool

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()

Close the FTDI interface/port.

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

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

Return type

int

Returns

the count of ports

property device_version

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

See

ic_name() for a product version of this information.

Return type

int

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

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

Return type

Tuple[int, int]

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

Tells the maximum frequency for MPSSE clock.

Return type

float

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

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.

Return type

bool

Returns

True if the FTDI device supports CBUS bitbang

Raises

FtdiError – if no FTDI port is open

property has_drivezero

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.

Return type

bool

Returns

True if the FTDI device features drive-zero mode

Raises

FtdiError – if no FTDI port is open

property has_mpsse

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

Return type

bool

Returns

True if the FTDI device supports MPSSE

Raises

FtdiError – if no FTDI port is open

property has_wide_port

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

Return type

bool

Returns

True if the FTDI device supports wide GPIO port

Raises

FtdiError – if no FTDI port is open

property ic_name

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

Return type

str

Returns

the identified FTDI device as a string

property is_H_series

Tell whether the device is a high-end FTDI

Return type

bool

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

Tell whether some bitbang mode is activated

Return type

bool

Returns

True if the FTDI interface is configured to support bitbanging

property is_connected

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

Return type

bool

Returns

the slave connection status

property is_legacy

Tell whether the device is a low-end FTDI

Return type

bool

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

Tell whether the device is configured in MPSSE mode

Return type

bool

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)

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

Delay between execution of two MPSSE SET_BITS commands.

Return type

float

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 and FT4232H). 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 and FT4232H). 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 and FT4232H). 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

Report the port/interface index, starting from 1

Return type

int

Returns

the port position/index

property port_width

Report the width of a single port / interface

Return type

int

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], bytes]]) – 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

bytes

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.

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

Return type

None

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

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.

Return type

None

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

Return the underlying USB Device.

Return type

Device

property usb_path

Provide the physical location on the USB topology.

Return type

Tuple[int, int, int]

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