com.qualcomm.robotcore.hardware.usb

Interface RobotUsbDevice

All Known Implementing Classes:

RobotUsbDeviceFtdi, RobotUsbDeviceImplBase, RobotUsbDevicePretendModernRobotics, RobotUsbDeviceTty

public interface RobotUsbDevice

RobotUsbDevice is an interface to USB devices that are commuicated with using a serial communication stream. This is in contrast to more other USB devices that use the full capabilities of USB. See http://www.usb.org/developers/defined_class. Note that this is not to be confused with RobotUsbDeviceTty.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	RobotUsbDevice.Channel
static class	RobotUsbDevice.FirmwareVersion
static class	RobotUsbDevice.USBIdentifiers

Method Summary

Modifier and Type	Method and Description
void	close() Closes the device
boolean	getDebugRetainBuffers()
DeviceManager.UsbDeviceType	getDeviceType()
RobotUsbDevice.FirmwareVersion	getFirmwareVersion() Returns the firmware version of this USB device, or null if no such version is known.
java.lang.String	getProductName()
SerialNumber	getSerialNumber()
RobotUsbDevice.USBIdentifiers	getUsbIdentifiers() Returns the USB-level vendor and product id of this device.
boolean	isAttached() Returns whether or not this USB device is known to be physically attached
boolean	isOpen() Returns whether the device is open or not
void	logRetainedBuffers(long nsOrigin, long nsTimerExpire, java.lang.String tag, java.lang.String format, java.lang.Object... args)
boolean	mightBeAtUsbPacketStart() Answers as to whether we're it's probably the case we're at the start of a Usb packet.
int	read(byte[] data, int ibFirst, int cbToRead, long msTimeout, TimeWindow timeWindow) Reads a requested number of bytes from the device.
void	requestReadInterrupt(boolean interruptRequested) Interrupts any reads that are currently pending inside the device, possibly waiting on a perhaps lengthy timeout.
void	resetAndFlushBuffers() Resets the remote USB device comm-layer as best we can.
void	setBaudRate(int rate) Sets the rate of data transmission used to communicate with the device.
void	setBreak(boolean enable) Sets or unsets a break state on the communication line
void	setDataCharacteristics(byte dataBits, byte stopBits, byte parity) Set the Data Characteristics
void	setDebugRetainBuffers(boolean retain)
void	setDeviceType(DeviceManager.UsbDeviceType deviceType)
void	setFirmwareVersion(RobotUsbDevice.FirmwareVersion version) Sets the firmware version of this USB device.
void	setLatencyTimer(int latencyTimer) Set the latency timer
void	skipToLikelyUsbPacketStart() Skips to the beginning of a USB packet, if not already there.
void	write(byte[] data) Write to device

Method Detail

setDebugRetainBuffers

void setDebugRetainBuffers(boolean retain)

getDebugRetainBuffers

boolean getDebugRetainBuffers()

logRetainedBuffers

void logRetainedBuffers(long nsOrigin,
                        long nsTimerExpire,
                        java.lang.String tag,
                        java.lang.String format,
                        java.lang.Object... args)

setBaudRate

void setBaudRate(int rate)
          throws RobotUsbException

Sets the rate of data transmission used to communicate with the device.

Parameters:

rate - baud rate

Throws:

RobotUsbException

setDataCharacteristics

void setDataCharacteristics(byte dataBits,
                            byte stopBits,
                            byte parity)
                     throws RobotUsbException

Set the Data Characteristics

Parameters:

dataBits - data bits

stopBits - stop bits

parity - parity

Throws:

RobotUsbException

setLatencyTimer

void setLatencyTimer(int latencyTimer)
              throws RobotUsbException

Set the latency timer

Parameters:

latencyTimer - latency timer

Throws:

RobotUsbException

setBreak

void setBreak(boolean enable)
       throws RobotUsbException

Sets or unsets a break state on the communication line

Parameters:

enable - whether or not to set a break state

Throws:

RobotUsbException

resetAndFlushBuffers

void resetAndFlushBuffers()
                   throws RobotUsbException

Resets the remote USB device comm-layer as best we can. Additionally, flushes any incoming or outgoing data buffers on this end of the line.

Throws:

RobotUsbException

write

void write(byte[] data)
    throws java.lang.InterruptedException,
           RobotUsbException

Write to device

Parameters:

data - byte array

Throws:

java.lang.InterruptedException

RobotUsbException

skipToLikelyUsbPacketStart

void skipToLikelyUsbPacketStart()

Skips to the beginning of a USB packet, if not already there. It is safe to err on the side of saying we're at the start when in fact we may not be. The point of this is that the packet start can have significance for resynchronization.

mightBeAtUsbPacketStart

boolean mightBeAtUsbPacketStart()

Answers as to whether we're it's probably the case we're at the start of a Usb packet. No is definitive; yes is uncertain.

read

int read(byte[] data,
         int ibFirst,
         int cbToRead,
         long msTimeout,
         TimeWindow timeWindow)
  throws RobotUsbException,
         java.lang.InterruptedException

Reads a requested number of bytes from the device.

Parameters:

data - byte array into which to read the data

ibFirst - first index in data at which to read the data

cbToRead - number of bytes to read

msTimeout - amount of time to wait, in ms, for data to become available to read

timeWindow - optional place to return information as to when the data was read

Returns:

number of bytes read into byte array, or 0 if the timeout was hit

Throws:

RobotUsbException

java.lang.InterruptedException

requestReadInterrupt

void requestReadInterrupt(boolean interruptRequested)

Interrupts any reads that are currently pending inside the device, possibly waiting on a perhaps lengthy timeout.

close

void close()

Closes the device

isOpen

boolean isOpen()

Returns whether the device is open or not

isAttached

boolean isAttached()

Returns whether or not this USB device is known to be physically attached

getFirmwareVersion

RobotUsbDevice.FirmwareVersion getFirmwareVersion()

Returns the firmware version of this USB device, or null if no such version is known.

See Also:

setFirmwareVersion(FirmwareVersion)

setFirmwareVersion

void setFirmwareVersion(RobotUsbDevice.FirmwareVersion version)

Sets the firmware version of this USB device. Note that this does not actually change the persistent firmware version inside the device, only our local copy of it here.

See Also:

getFirmwareVersion()

getUsbIdentifiers

RobotUsbDevice.USBIdentifiers getUsbIdentifiers()

Returns the USB-level vendor and product id of this device. All the devices we are interested in use FTDI chips (2018.06.01: no longer true: webcams!), which report as vendor 0x0403. Modern Robotics modules (currently?) use a product id of 0x6001 and bcdDevice of 0x0600. Lynx modules use a product id of 0x6015 and bcdDevice of 0x1000. Note that for FTDI, only the upper byte of the two-byte bcdDevice seems to be of significance. "Every Universal Serial Bus (USB) device must be able to provide a single device descriptor that contains relevant information about the device. The USB_DEVICE_DESCRIPTOR structure describes a device descriptor. Windows uses that information to derive various sets of information. For example, the idVendor and idProduct fields specify vendor and product identifiers, respectively. Windows uses those field values to construct a hardware ID for the device. To view the hardware ID of a particular device, open Device Manager and view device properties. In the Details tab, the Hardware Ids property value indicates the hardware ID ("USB\XXX") that is generated by Windows. The bcdUSB field indicates the version of the USB specification to which the device conforms. For example, 0x0200 indicates that the device is designed as per the USB 2.0 specification. The bcdDevice value indicates the device-defined revision number. The USB driver stack uses bcdDevice, along with idVendor and idProduct, to generate hardware and compatible IDs for the device. You can view the those identifiers in Device Manager. The device descriptor also indicates the total number of configurations that the device supports"

See Also:

USB Device Descriptors

getSerialNumber

SerialNumber getSerialNumber()

getProductName

java.lang.String getProductName()

setDeviceType

void setDeviceType(DeviceManager.UsbDeviceType deviceType)

getDeviceType

DeviceManager.UsbDeviceType getDeviceType()