# `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(*values)

    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 (`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 (`str` | `None`) – 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 (`str` | `None`) – 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 (`int` | `None`) – optional selector, USB bus

      - address (`int` | `None`) – optional selector, USB address on bus

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

      - serial (`str` | `None`) – 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 (`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 (`Callable`[[`int`], `bytes` | `bytearray`] | `None`) – 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 (`int` | `None`) – byte length to read or None

      - eeprom_size (`int` | `None`) – 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 (`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 (`str` | `None`) – a pattern URL to restrict the search

      - out (`TextIO` | `None`) – 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 (`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 (`bytes` | `bytearray`) – data to be written

      - eeprom_size (`int` | `None`) – 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