Trait libftd2xx::FtdiCommon[−][src]

pub trait FtdiCommon {
    const DEVICE_TYPE: DeviceType;

Show methods
    fn handle(&mut self) -> FT_HANDLE;

    fn device_type(&mut self) -> Result<DeviceType, FtStatus> { ... }

    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> { ... }

}
Expand description

FTD2XX functions common to all devices.

Associated Constants

FTDI device type.

Required methods

Get the FTDI device handle.

Provided methods

Identify device type.

This will attempt to identify the device using the the device_info method, if that method fails it will then try to determine the device type from the value stored in the EEPROM. If the EEPROM value does not match a known device this function returns FtStatus::OTHER_ERROR, though there may be other conditions in the vendor driver that also return this code.

This is not a native function in libftd2xx, this works around a bug in libftd2xx, see https://github.com/newAM/libftd2xx-rs/pull/37 for more information.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
let dev_type = ft.device_type()?;
println!("Device type: {:?}", dev_type);

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

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

This function sends a reset command to the device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

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

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)?;

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)?;

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))?;

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))?;

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))?;

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

This function disables flow control for the device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

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

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

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

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)?;

Set the baud rate for the device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

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

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)?;

Set the Data Terminal Ready (DTR) control signal.

Example

use libftd2xx::{Ftdi, FtdiCommon};

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

Clear the Data Terminal Ready (DTR) control signal.

Example

use libftd2xx::{Ftdi, FtdiCommon};

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

Set the Request to Send (RTS) control signal.

Example

use libftd2xx::{Ftdi, FtdiCommon};

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

Clear the Request to Send (RTS) control signal.

Example

use libftd2xx::{Ftdi, FtdiCommon};

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

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)?;

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

Sets the BREAK condition for the device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

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

Resets the BREAK condition for the device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

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

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])?;
}

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

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

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()],
};

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)?;

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

This function purges the transmit buffers in the device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

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

This function purges the receive buffers in the device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

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

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

Example

use libftd2xx::{Ftdi, FtdiCommon};

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

Close an open device.

Example

use libftd2xx::{Ftdi, FtdiCommon};

let mut ft = Ftdi::new()?;
ft.close()?;
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"),
}
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()?;
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()?;

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

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

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)?;

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

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

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

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

Implementors