Trait libftd2xx::FtdiCommon

pub trait FtdiCommon {
    const DEVICE_TYPE: DeviceType;

    fn handle(&mut self) -> FT_HANDLE;

    fn device_info(&mut self) -> Result<DeviceInfo, FtStatus> { ... }
    fn driver_version(&mut self) -> Result<Version, FtStatus> { ... }
    fn reset(&mut self) -> Result<(), FtStatus> { ... }
    fn set_usb_parameters(
        &mut self, 
        in_transfer_size: u32
    ) -> Result<(), FtStatus> { ... }
    fn set_chars(
        &mut self, 
        event_char: u8, 
        event_enable: bool, 
        error_char: u8, 
        error_enable: bool
    ) -> Result<(), FtStatus> { ... }
    fn set_timeouts(
        &mut self, 
        read_timeout: Duration, 
        write_timeout: Duration
    ) -> Result<(), FtStatus> { ... }
    fn set_deadman_timeout(&mut self, timeout: Duration) -> Result<(), FtStatus> { ... }
    fn set_latency_timer(&mut self, timer: Duration) -> Result<(), FtStatus> { ... }
    fn latency_timer(&mut self) -> Result<Duration, FtStatus> { ... }
    fn set_flow_control_none(&mut self) -> Result<(), FtStatus> { ... }
    fn set_flow_control_rts_cts(&mut self) -> Result<(), FtStatus> { ... }
    fn set_flow_control_dtr_dsr(&mut self) -> Result<(), FtStatus> { ... }
    fn set_flow_control_xon_xoff(
        &mut self, 
        xon: u8, 
        xoff: u8
    ) -> Result<(), FtStatus> { ... }
    fn set_baud_rate(&mut self, baud_rate: u32) -> Result<(), FtStatus> { ... }
    fn set_data_characteristics(
        &mut self, 
        bits_per_word: BitsPerWord, 
        stop_bits: StopBits, 
        parity: Parity
    ) -> Result<(), FtStatus> { ... }
    fn set_dtr(&mut self) -> Result<(), FtStatus> { ... }
    fn clear_dtr(&mut self) -> Result<(), FtStatus> { ... }
    fn set_rts(&mut self) -> Result<(), FtStatus> { ... }
    fn clear_rts(&mut self) -> Result<(), FtStatus> { ... }
    fn set_bit_mode(&mut self, mask: u8, mode: BitMode) -> Result<(), FtStatus> { ... }
    fn bit_mode(&mut self) -> Result<u8, FtStatus> { ... }
    fn set_break_on(&mut self) -> Result<(), FtStatus> { ... }
    fn set_break_off(&mut self) -> Result<(), FtStatus> { ... }
    fn queue_status(&mut self) -> Result<usize, FtStatus> { ... }
    fn status(&mut self) -> Result<DeviceStatus, FtStatus> { ... }
    fn read(&mut self, buf: &mut [u8]) -> Result<usize, FtStatus> { ... }
    fn read_all(&mut self, buf: &mut [u8]) -> Result<(), TimeoutError> { ... }
    fn write_all(&mut self, buf: &[u8]) -> Result<(), TimeoutError> { ... }
    fn write(&mut self, buf: &[u8]) -> Result<usize, FtStatus> { ... }
    fn purge_tx(&mut self) -> Result<(), FtStatus> { ... }
    fn purge_rx(&mut self) -> Result<(), FtStatus> { ... }
    fn purge_all(&mut self) -> Result<(), FtStatus> { ... }
    fn close(&mut self) -> Result<(), FtStatus> { ... }
    fn com_port_number(&mut self) -> Result<Option<u32>, FtStatus> { ... }
    fn reset_port(&mut self) -> Result<(), FtStatus> { ... }
    fn cycle_port(&mut self) -> Result<(), FtStatus> { ... }
    fn modem_status(&mut self) -> Result<ModemStatus, FtStatus> { ... }
    fn eeprom_word_read(&mut self, offset: u32) -> Result<u16, FtStatus> { ... }
    fn eeprom_word_write(
        &mut self, 
        offset: u32, 
        value: u16
    ) -> Result<(), FtStatus> { ... }
    fn eeprom_erase(&mut self) -> Result<(), FtStatus> { ... }
    fn eeprom_user_size(&mut self) -> Result<usize, FtStatus> { ... }
    fn eeprom_user_read(&mut self, buf: &mut [u8]) -> Result<usize, FtStatus> { ... }
    fn eeprom_user_write(&mut self, buf: &[u8]) -> Result<(), FtStatus> { ... }
}

FTD2XX functions common to all devices.

Associated Constants

const DEVICE_TYPE: DeviceType

FTDI device type.

Loading content...

Required methods

fn handle(&mut self) -> FT_HANDLE

Get the FTDI device handle.

Loading content...

Provided methods

fn device_info(&mut self) -> Result<DeviceInfo, FtStatus>

Get device information for an open device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
let info = ft.device_info()?;
println!("Device information: {:?}", info);

fn driver_version(&mut self) -> Result<Version, FtStatus>

Returns the D2XX driver version number.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
let version = ft.driver_version()?;
println!("Driver Version: {}", version);

fn reset(&mut self) -> Result<(), FtStatus>

This function sends a reset command to the device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.reset()?;

fn set_usb_parameters(&mut self, in_transfer_size: u32) -> Result<(), FtStatus>

Set the USB request transfer size.

This function can be used to change the transfer sizes from the default transfer size of 4096 bytes to better suit the application requirements.

Transfer sizes must be set to a multiple of 64 bytes between 64 bytes and 64k bytes. Other values will result in panic.

When set_usb_parameters is called, the change comes into effect immediately and any data that was held in the driver at the time of the change is lost.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.set_usb_parameters(16384)?;

fn set_chars(
    &mut self,
    event_char: u8,
    event_enable: bool,
    error_char: u8,
    error_enable: bool
) -> Result<(), FtStatus>

This function sets the special characters for the device.

This function allows for inserting specified characters in the data stream to represent events firing or errors occurring.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;

// disable all special characters
ft.set_chars(0, false, 0, false)?;

fn set_timeouts(
    &mut self,
    read_timeout: Duration,
    write_timeout: Duration
) -> Result<(), FtStatus>

This function sets the read and write timeouts for the device.

The timeout values are limited to 4,294,967,295 (std::u32::MAX) milliseconds.

The timeout values have a 1 millisecond resolution.

Example

use libftd2xx::{Ftdi, FtdiCommon};
use std::time::Duration;

let mut ft = Ftdi::new()?;

// Set read timeout of 5sec, write timeout of 1sec
ft.set_timeouts(Duration::from_millis(5000), Duration::from_millis(1000))?;

fn set_deadman_timeout(&mut self, timeout: Duration) -> Result<(), FtStatus>

This method allows the maximum time in milliseconds that a USB request can remain outstandingto be set.

The deadman timeout is referred to in FTDI application note AN232B-10 Advanced Driver Options as the USB timeout. It is unlikely that this method will be required by most users.

The default duration is 5 seconds.

The timeout value is limited to 4,294,967,295 (std::u32::MAX) milliseconds.

The timeout value has a 1 millisecond resolution.

use libftd2xx::{Ftdi, FtdiCommon};
use std::time::Duration;

let mut ft = Ftdi::new()?;

// set deadman timeout to 5 seconds
ft.set_deadman_timeout(Duration::from_secs(5))?;

fn set_latency_timer(&mut self, timer: Duration) -> Result<(), FtStatus>

Set the latency timer value.

In the FT8U232AM and FT8U245AM devices, the receive buffer timeout that is used to flush remaining data from the receive buffer was fixed at 16 ms. In all other FTDI devices, this timeout is programmable and can be set at 1 ms intervals between 2ms and 255 ms. This allows the device to be better optimized for protocols requiring faster response times from short data packets.

The valid range for the latency timer is 2 to 255 milliseconds.

The resolution for the latency timer is 1 millisecond.

Note the python FTDI library, pyftdi reports that values lower than 16 ms may result in data loss.

Example

use libftd2xx::{Ftdi, FtdiCommon};
use std::time::Duration;

let mut ft = Ftdi::new()?;

// Set latency timer to 16 milliseconds
ft.set_latency_timer(Duration::from_millis(16))?;

fn latency_timer(&mut self) -> Result<Duration, FtStatus>

Get the current value of the latency timer.

Example

use libftd2xx::{Ftdi, FtdiCommon};
use std::time::Duration;

let mut ft = Ftdi::new()?;
let timer = Duration::from_millis(32);
ft.set_latency_timer(timer)?;
assert_eq!(ft.latency_timer()?, timer);

fn set_flow_control_none(&mut self) -> Result<(), FtStatus>

This function disables flow control for the device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.set_flow_control_none()?;

fn set_flow_control_rts_cts(&mut self) -> Result<(), FtStatus>

This function sets RTS/CTS flow control for the device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.set_flow_control_rts_cts()?;

fn set_flow_control_dtr_dsr(&mut self) -> Result<(), FtStatus>

This function sets DTS/DSR flow control for the device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.set_flow_control_dtr_dsr()?;

fn set_flow_control_xon_xoff(
    &mut self,
    xon: u8,
    xoff: u8
) -> Result<(), FtStatus>

This function sets XON/XOFF flow control for the device.

Arguments

• xon - Character used to signal Xon.
• xoff - Character used to signal Xoff.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.set_flow_control_xon_xoff(0x11, 0x13)?;

fn set_baud_rate(&mut self, baud_rate: u32) -> Result<(), FtStatus>

Set the baud rate for the device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.set_baud_rate(115200)?;

fn set_data_characteristics(
    &mut self,
    bits_per_word: BitsPerWord,
    stop_bits: StopBits,
    parity: Parity
) -> Result<(), FtStatus>

Set the data characteristics for the device.

Example

use libftd2xx::{BitsPerWord, Ftdi, FtdiCommon, Parity, StopBits};

let mut ft = Ftdi::new()?;
ft.set_data_characteristics(BitsPerWord::Bits8, StopBits::Bits1, Parity::No)?;

fn set_dtr(&mut self) -> Result<(), FtStatus>

Set the Data Terminal Ready (DTR) control signal.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.set_dtr()?;

fn clear_dtr(&mut self) -> Result<(), FtStatus>

Clear the Data Terminal Ready (DTR) control signal.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.clear_dtr()?;

fn set_rts(&mut self) -> Result<(), FtStatus>

Set the Request to Send (RTS) control signal.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.set_rts()?;

fn clear_rts(&mut self) -> Result<(), FtStatus>

Clear the Request to Send (RTS) control signal.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.clear_rts()?;

fn set_bit_mode(&mut self, mask: u8, mode: BitMode) -> Result<(), FtStatus>

Enables different chip modes.

Arguments

• mask - This bit mask sets up which bits are inputs and outputs. A bit value of 0 sets the corresponding pin to an input, a bit value of 1 sets the corresponding pin to an output. In the case of CBUS Bit Bang, the upper nibble of this value controls which pins are inputs and outputs, while the lower nibble controls which of the outputs are high and low.
• mode - Bitmode, see the BitMode struct for more details.

For a description of available bit modes for the FT232R, see the application note Bit Bang Modes for the FT232R and FT245R.

For a description of available bit modes for the FT2232, see the application note Bit Mode Functions for the FT2232.

For a description of Bit Bang Mode for the FT232B and FT245B, see the application note FT232B/FT245B Bit Bang Mode.

Application notes are available for download from the FTDI website.

Note that to use CBUS Bit Bang for the FT232R, the CBUS must be configured for CBUS Bit Bang in the EEPROM.

Note that to use Single Channel Synchronous 245 FIFO mode for the FT2232H, channel A must be configured for FT245 FIFO mode in the EEPROM.

Example

use libftd2xx::{BitMode, Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.set_bit_mode(0xFF, BitMode::AsyncBitbang)?;

fn bit_mode(&mut self) -> Result<u8, FtStatus>

Get the instantaneous value of the data bus.

Note: This is not the BitMode as set in set_bit_mode, this is the value (logic high or logic low) of the pins on the bus.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
let bitmode = ft.bit_mode()?;
println!("Data bus state: {}", bitmode);

fn set_break_on(&mut self) -> Result<(), FtStatus>

Sets the BREAK condition for the device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.set_break_off()?;

fn set_break_off(&mut self) -> Result<(), FtStatus>

Resets the BREAK condition for the device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.set_break_off()?;

fn queue_status(&mut self) -> Result<usize, FtStatus>

Gets the number of bytes in the receive queue.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut buf: [u8; 4096] = [0; 4096];
let mut ft = Ftdi::new()?;
let rx_bytes = ft.queue_status()?;

if (rx_bytes > 0) {
    ft.read(&mut buf[0..rx_bytes])?;
}

fn status(&mut self) -> Result<DeviceStatus, FtStatus>

Gets the device status including number of characters in the receive queue, number of characters in the transmit queue, and the current event status.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
let status = ft.status()?;
println!("status={:?}", status);

fn read(&mut self, buf: &mut [u8]) -> Result<usize, FtStatus>

Read data from the device, returning the number of bytes read.

See read_all for more information about reading from the device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

const BUF_SIZE: usize = 256;
let mut buf: [u8; BUF_SIZE] = [0; BUF_SIZE];
let mut ft = Ftdi::new()?;
let bytes_read: usize = ft.read(&mut buf)?;
assert_eq!(bytes_read, BUF_SIZE);

fn read_all(&mut self, buf: &mut [u8]) -> Result<(), TimeoutError>

Read data from the device.

This method does not return until the buffer has been filled, if no timeout has been set. The number of bytes in the receive queue can be determined by calling queue_status, and then an buffer equal to the length of that value can be passed to read_all so that the function reads the device and returns immediately.

When a read timeout value has been specified in a previous call to set_timeouts, read_all returns when the timer expires or when the buffer has been filled, whichever occurs first. If the timeout occurred, read_all reads available data into the buffer and returns the TimeoutError error.

Examples

Read all available data

use libftd2xx::{Ftdi, FtdiCommon};

let mut buf: [u8; 4096] = [0; 4096];
let mut ft = Ftdi::new()?;
let rx_bytes = ft.queue_status()?;

if rx_bytes > 0 {
    ft.read_all(&mut buf[0..rx_bytes])?;
}

Read with a timeout of 5 seconds

use libftd2xx::{Ftdi, FtdiCommon, TimeoutError};
use std::time::Duration;

const BUF_LEN: usize = 4096;
let mut buf: [u8; BUF_LEN] = [0; BUF_LEN];
let mut ft = Ftdi::new()?;

ft.set_timeouts(Duration::from_millis(5000), Duration::from_millis(0))?;

let valid_data = match ft.read_all(&mut buf) {
    Err(e) => match e {
        TimeoutError::Timeout {
            actual: actual,
            expected: expected,
        } => {
            eprintln!("Read timeout occured after 5s! {:?}", e);
            &buf[0..actual]
        }
        TimeoutError::FtStatus(status) => {
            panic!("FTDI Status Error: {:?}", status);
        }
    },
    _ => &buf[0..buf.len()],
};

fn write_all(&mut self, buf: &[u8]) -> Result<(), TimeoutError>

Write data to the device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

const BUF_SIZE: usize = 256;
let buf: [u8; BUF_SIZE] = [0; BUF_SIZE];
let mut ft = Ftdi::new()?;
ft.write_all(&buf)?;

fn write(&mut self, buf: &[u8]) -> Result<usize, FtStatus>

Write data to the device, returning how many bytes were written.

Example

use libftd2xx::{Ftdi, FtdiCommon};

const BUF_SIZE: usize = 256;
let buf: [u8; BUF_SIZE] = [0; BUF_SIZE];
let mut ft = Ftdi::new()?;
let bytes_written: usize = ft.write(&buf)?;
assert_eq!(bytes_written, BUF_SIZE);

fn purge_tx(&mut self) -> Result<(), FtStatus>

This function purges the transmit buffers in the device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.purge_tx()?;

fn purge_rx(&mut self) -> Result<(), FtStatus>

This function purges the receive buffers in the device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.purge_rx()?;

fn purge_all(&mut self) -> Result<(), FtStatus>

This function purges the transmit and receive buffers in the device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.purge_all()?;

fn close(&mut self) -> Result<(), FtStatus>

Close an open device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.close()?;

fn com_port_number(&mut self) -> Result<Option<u32>, FtStatus>

This is supported on Windows only.

Get the COM port associated with a device.

This method is only available when using the Windows CDM driver as both the D2XX and VCP drivers can be installed at the same time.

If no COM port is associated with the device None is returned.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
match ft.com_port_number()? {
    Some(num) => println!("COM{}", num),
    None => println!("no COM port"),
}

fn reset_port(&mut self) -> Result<(), FtStatus>

This is supported on Windows only.

Send a reset command to the port.

This method is available on Windows only.

This function is used to attempt to recover the device upon failure. For the equivalent of a unplug-replug event use FtdiCommon::cycle_port.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.reset_port()?;

fn cycle_port(&mut self) -> Result<(), FtStatus>

This is supported on Windows only.

Send a cycle command to the USB port.

This method is available on Windows only.

The effect of this method is the same as disconnecting then reconnecting the device from the USB port. Possible use of this method is situations where a fatal error has occurred and it is difficult, or not possible, to recover without unplugging and replugging the USB cable. This method can also be used after re-programming the EEPROM to force the FTDI device to read the new EEPROM contents which would otherwise require a physical disconnect-reconnect.

As the current session is not restored when the driver is reloaded, the application must be able to recover after calling this method. It is the responsibility of the application to close the handle after successfully calling this method.

For FT4232H, FT2232H and FT2232 devices, cycle_port will only work under Windows XP and later.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.cycle_port()?;

fn modem_status(&mut self) -> Result<ModemStatus, FtStatus>

Gets the modem status and line status from the device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
let modem_status = ft.modem_status()?;
println!("CTS={}", modem_status.clear_to_send());

fn eeprom_word_read(&mut self, offset: u32) -> Result<u16, FtStatus>

Read a value from an EEPROM location.

Arguments

• offset - EEPROM location to read from.

Example

use libftd2xx::{Ftdi, FtdiCommon};

const LOCATION: u32 = 0x0;
let mut ft = Ftdi::new()?;
let value = ft.eeprom_word_read(LOCATION)?;
println!(
    "The value at EEPROM address 0x{:X} is 0x{:04X}",
    LOCATION, value
);

fn eeprom_word_write(&mut self, offset: u32, value: u16) -> Result<(), FtStatus>

Writes a value to an EEPROM location.

Arguments

• offset - EEPROM location to write to.
• value - Value to write.

Warning

Writing bad values to the EEPROM can brick your device. Please take a moment to read the license for this crate before using this function.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.eeprom_word_write(0x0, 0x1234)?;

fn eeprom_erase(&mut self) -> Result<(), FtStatus>

Erases the entire contents of the EEPROM, including the user area.

Note: The FT232R and FT245R have an internal EEPROM that cannot be erased.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.eeprom_erase()?;

fn eeprom_user_size(&mut self) -> Result<usize, FtStatus>

Get the available size of the EEPROM user area in bytes.

The user area of an FTDI device EEPROM is the total area of the EEPROM that is unused by device configuration information and descriptors. This area is available to the user to store information specific to their application. The size of the user area depends on the length of the Manufacturer, ManufacturerId, Description and SerialNumber strings programmed into the EEPROM.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
let ua_size = ft.eeprom_user_size()?;
println!("EEPROM user area size: {} Bytes", ua_size);

fn eeprom_user_read(&mut self, buf: &mut [u8]) -> Result<usize, FtStatus>

Read the contents of the EEPROM user area.

The size of the user area can be determined with eeprom_user_size.

The function returns the actual number of bytes read into the buffer. If the buffer is larger than the user size the return value will be less than the length of the buffer. The return value should be checked to ensure the expected number of bytes was read.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
let mut buf: [u8; 9] = [0; 9];
let num_read = ft.eeprom_user_read(&mut buf)?;
assert_eq!(buf.len(), num_read);

fn eeprom_user_write(&mut self, buf: &[u8]) -> Result<(), FtStatus>

Write to the EEPROM user area.

An error will be returned when the buffer size is larger than the user area size. The size of the user area can be determined with eeprom_user_size.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
let data = "Hello, World";
ft.eeprom_user_write(&data.as_bytes())?;

Loading content...

Implementors

impl FtdiCommon for Ft232h

const DEVICE_TYPE: DeviceType

fn handle(&mut self) -> FT_HANDLE

impl FtdiCommon for Ft2232h

const DEVICE_TYPE: DeviceType

fn handle(&mut self) -> FT_HANDLE

impl FtdiCommon for Ft4232h

const DEVICE_TYPE: DeviceType

fn handle(&mut self) -> FT_HANDLE

impl FtdiCommon for Ftdi

const DEVICE_TYPE: DeviceType

fn handle(&mut self) -> FT_HANDLE

Loading content...