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
const DEVICE_TYPE: DeviceType
const DEVICE_TYPE: DeviceType
FTDI device type.
Required methods
Provided methods
fn device_type(&mut self) -> Result<DeviceType, FtStatus>
fn device_type(&mut self) -> Result<DeviceType, FtStatus>
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);
fn device_info(&mut self) -> Result<DeviceInfo, FtStatus>
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>
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);
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))?;
fn latency_timer(&mut self) -> Result<Duration, FtStatus>
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>
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>
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>
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()?;
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>
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)?;
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 theBitMode
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);
fn set_break_on(&mut self) -> Result<(), FtStatus>
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>
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>
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>
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);
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()?;
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>
fn reset_port(&mut self) -> Result<(), FtStatus>
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>
fn cycle_port(&mut self) -> Result<(), FtStatus>
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>
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());
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)?;
fn eeprom_erase(&mut self) -> Result<(), FtStatus>
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>
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);
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())?;