`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: int¶

Return current baudrate.

Return type: int

property bitbang_enabled: bool¶

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

Return type: int
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.
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: Tuple[int, int]¶

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: float¶

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: 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.

Return type: bool
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.

Return type: bool
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, …)

Return type: bool
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)

Return type: bool
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

Return type: str
Returns: the identified FTDI device as a string

property is_H_series: bool¶

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: bool¶

Tell whether some bitbang mode is activated

Return type: bool
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.

Return type: bool
Returns: the slave connection status

property is_eeprom_internal: bool¶

Tell whether the device has an internal EEPROM.

Return type: bool
Returns: True if the device has an internal EEPROM.

property is_legacy: bool¶

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: bool¶

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)

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.

Return type: int
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.

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: int¶

Report the port/interface index, starting from 1

Return type: int
Returns: the port position/index

property port_width: int¶

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: usb.core.Device¶

Return the underlying USB Device.

Return type: Device

property usb_path: Tuple[int, int, int]¶

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

ftdi - FTDI low-level driver¶

Classes¶

Exceptions¶

`ftdi` - FTDI low-level driver¶