org.lsst.ccs.drivers.usb
Class UsbComm

java.lang.Object
  org.lsst.ccs.drivers.usb.UsbComm

public class UsbComm
extends Object

Communicates with a USB device

Author:

Owen Saxton

Field Summary

static int	CFG_ATTR_REMOTE_WAKE Configuration attribute - remote wakeup
static int	CFG_ATTR_SELF_POWER Configuration attribute - self-powered
static int	DEV_CLASS_CDC_CTRL Device class - CDC control
static int	DEV_CLASS_DIAGNOSTIC Device class - diagnostic
static int	DEV_CLASS_HUB Device class - hub
static int	DEV_CLASS_INTERFACE Device class - see interface
static int	DEV_CLASS_MISC Device class - miscellaneous
static int	DEV_CLASS_VENDOR_SPEC Device class - vendor specific
static int	DEV_SPEED_FULL Device speed - full
static int	DEV_SPEED_LOW Device speed - low
static int	DEV_SPEED_UNDEFINED Device speed - undefined
static int	DEV_SPEED_UNKNOWN Device speed - unknown
static int	EP_ATTR_BULK Endpoint attribute - bulk data
static int	EP_ATTR_CONTROL Endpoint attribute - control
static int	EP_ATTR_INTERRUPT Endpoint attribute - interrupt
static int	EP_ATTR_ISOCHRONOUS Endpoint attribute - isochronous
static int	IFC_CLASS_APP_SPEC Interface class - application specific
static int	IFC_CLASS_AUDIO Interface class - audio
static int	IFC_CLASS_CDC_CTRL Interface class - CDC control
static int	IFC_CLASS_CDC_DATA Interface class - CDC data
static int	IFC_CLASS_CONTENT_SEC Interface class security x
static int	IFC_CLASS_DIAGNOSTIC Interface class - diagnostic
static int	IFC_CLASS_HEALTHCARE Interface class - personal healthcare
static int	IFC_CLASS_HID Interface class - human interface
static int	IFC_CLASS_IMAGE Interface class - still image
static int	IFC_CLASS_MASS_STORE Interface class - mass storage
static int	IFC_CLASS_MISC Interface class - miscellaneous
static int	IFC_CLASS_PHYSICAL Interface class - physical
static int	IFC_CLASS_PRINTER Interface class - printer
static int	IFC_CLASS_SMART_CARD Interface class - smart card
static int	IFC_CLASS_VENDOR_SPEC Interface class - vendor specific
static int	IFC_CLASS_VIDEO Interface class - video
static int	IFC_CLASS_WIRELESS Interface class - wireless

Constructor Summary

UsbComm()
Constructor

Method Summary

void	claim(int iface, boolean force) Claims an interface
UsbDevice	findDevice(int vid, int pid) Finds a USB device and sets it as current
UsbDevice	findDevice(int vid, int pid, int index) Finds a USB device and sets it as current
UsbDevice	findDevice(int vid, int pid, String serial) Finds a USB device and sets it as current
UsbDevice	findDevice(int vid, int pid, String serial, int index) Finds a USB device and sets it as current
static List	findDevices(int vid, int pid, String serial) Finds USB devices
UsbConfiguration	getConfiguration() Gets the active USB configuration for the current device
UsbDevice	getDevice() Gets the current USB device
static UsbEndpoint	getEndpoint(UsbInterface iface, int epAddr) Gets a USB endpoint for the specified interface.
static List	getEndpoints(UsbInterface iface) Gets all USB endpoints for the specified interface.
UsbInterface	getInterface(int iface) Gets the active setting of the specified USB interface of the current device
static UsbInterface	getInterface(UsbDevice device, int iface) Gets the active setting of the specified USB interface of the specified device.
int	getSpeed() Gets the speed of the current device *** Re-do ***
static int	getSpeed(UsbDevice device) Gets the speed of a device *** Deprecated ***
UsbCommPipe	open(int iface, int epAddr) Opens a connection to a device's endpoint
int	read(int type, int rqst, int value, int index, byte[] data, int timeout) Reads data from the control endpoint
int	read(int type, int rqst, int value, int index, byte[] data, int offs, int leng, int timeout) Reads data from the control endpoint
void	release(int iface) Releases an interface
void	setConfiguration(int cfgNum) Sets the active USB configuration for the current device
void	setDevice(UsbDevice device) Sets the current USB device
void	setInterface(int iface, int setting) Sets the active setting of the specified USB interface of the current device
int	write(int type, int rqst, int value, int index, byte[] data) Writes data to the control endpoint
int	write(int type, int rqst, int value, int index, byte[] data, int offs, int leng) Writes data to the control endpoint

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEV_SPEED_UNDEFINED

public static final int DEV_SPEED_UNDEFINED

Device speed - undefined

See Also:

Constant Field Values

DEV_SPEED_UNKNOWN

public static final int DEV_SPEED_UNKNOWN

Device speed - unknown

See Also:

Constant Field Values

DEV_SPEED_LOW

public static final int DEV_SPEED_LOW

Device speed - low

See Also:

Constant Field Values

DEV_SPEED_FULL

public static final int DEV_SPEED_FULL

Device speed - full

See Also:

Constant Field Values

DEV_CLASS_INTERFACE

public static final int DEV_CLASS_INTERFACE

Device class - see interface

See Also:

Constant Field Values

DEV_CLASS_CDC_CTRL

public static final int DEV_CLASS_CDC_CTRL

Device class - CDC control

See Also:

Constant Field Values

DEV_CLASS_HUB

public static final int DEV_CLASS_HUB

Device class - hub

See Also:

Constant Field Values

DEV_CLASS_DIAGNOSTIC

public static final int DEV_CLASS_DIAGNOSTIC

Device class - diagnostic

See Also:

Constant Field Values

DEV_CLASS_MISC

public static final int DEV_CLASS_MISC

Device class - miscellaneous

See Also:

Constant Field Values

DEV_CLASS_VENDOR_SPEC

public static final int DEV_CLASS_VENDOR_SPEC

Device class - vendor specific

See Also:

Constant Field Values

CFG_ATTR_SELF_POWER

public static final int CFG_ATTR_SELF_POWER

Configuration attribute - self-powered

See Also:

Constant Field Values

CFG_ATTR_REMOTE_WAKE

public static final int CFG_ATTR_REMOTE_WAKE

Configuration attribute - remote wakeup

See Also:

Constant Field Values

IFC_CLASS_AUDIO

public static final int IFC_CLASS_AUDIO

Interface class - audio

See Also:

Constant Field Values

IFC_CLASS_CDC_CTRL

public static final int IFC_CLASS_CDC_CTRL

Interface class - CDC control

See Also:

Constant Field Values

IFC_CLASS_HID

public static final int IFC_CLASS_HID

Interface class - human interface

See Also:

Constant Field Values

IFC_CLASS_PHYSICAL

public static final int IFC_CLASS_PHYSICAL

Interface class - physical

See Also:

Constant Field Values

IFC_CLASS_IMAGE

public static final int IFC_CLASS_IMAGE

Interface class - still image

See Also:

Constant Field Values

IFC_CLASS_PRINTER

public static final int IFC_CLASS_PRINTER

Interface class - printer

See Also:

Constant Field Values

IFC_CLASS_MASS_STORE

public static final int IFC_CLASS_MASS_STORE

Interface class - mass storage

See Also:

Constant Field Values

IFC_CLASS_CDC_DATA

public static final int IFC_CLASS_CDC_DATA

Interface class - CDC data

See Also:

Constant Field Values

IFC_CLASS_SMART_CARD

public static final int IFC_CLASS_SMART_CARD

Interface class - smart card

See Also:

Constant Field Values

IFC_CLASS_CONTENT_SEC

public static final int IFC_CLASS_CONTENT_SEC

Interface class security x

See Also:

Constant Field Values

IFC_CLASS_VIDEO

public static final int IFC_CLASS_VIDEO

Interface class - video

See Also:

Constant Field Values

IFC_CLASS_HEALTHCARE

public static final int IFC_CLASS_HEALTHCARE

Interface class - personal healthcare

See Also:

Constant Field Values

IFC_CLASS_DIAGNOSTIC

public static final int IFC_CLASS_DIAGNOSTIC

Interface class - diagnostic

See Also:

Constant Field Values

IFC_CLASS_WIRELESS

public static final int IFC_CLASS_WIRELESS

Interface class - wireless

See Also:

Constant Field Values

IFC_CLASS_MISC

public static final int IFC_CLASS_MISC

Interface class - miscellaneous

See Also:

Constant Field Values

IFC_CLASS_APP_SPEC

public static final int IFC_CLASS_APP_SPEC

Interface class - application specific

See Also:

Constant Field Values

IFC_CLASS_VENDOR_SPEC

public static final int IFC_CLASS_VENDOR_SPEC

Interface class - vendor specific

See Also:

Constant Field Values

EP_ATTR_CONTROL

public static final int EP_ATTR_CONTROL

Endpoint attribute - control

See Also:

Constant Field Values

EP_ATTR_ISOCHRONOUS

public static final int EP_ATTR_ISOCHRONOUS

Endpoint attribute - isochronous

See Also:

Constant Field Values

EP_ATTR_BULK

public static final int EP_ATTR_BULK

Endpoint attribute - bulk data

See Also:

Constant Field Values

EP_ATTR_INTERRUPT

public static final int EP_ATTR_INTERRUPT

Endpoint attribute - interrupt

See Also:

Constant Field Values

Constructor Detail

UsbComm

public UsbComm()
        throws UsbException

Constructor

Throws:

UsbException

Method Detail

findDevices

public static List findDevices(int vid,
                               int pid,
                               String serial)
                        throws UsbException

Finds USB devices

The tree of USB devices is searched, looking for devices whose vendor and product IDs match the ones specified. If a non-null serial number is provided, this must be matched as well.

Parameters:

vid - The vendor ID, or -1 if any vendor ID matches.

pid - The product ID, or -1 if any product ID matches.

serial - The serial number, or null if the serial number is not to be matched.

Returns:

The list of matching UsbDevices, empty if no matches found.

Throws:

UsbException

findDevice

public UsbDevice findDevice(int vid,
                            int pid)
                     throws UsbException

Finds a USB device and sets it as current

The tree of USB devices is searched, looking for the first device whose vendor & product IDs match the ones specified. The current device is set to the resultant device, possibly null.

Parameters:

vid - The vendor ID

pid - The product ID

Returns:

The matching UsbDevice or null if no match found.

Throws:

UsbException - if a device is already open.

findDevice

public UsbDevice findDevice(int vid,
                            int pid,
                            String serial)
                     throws UsbException

Finds a USB device and sets it as current

The tree of USB devices is searched, looking for the first device whose vendor & product IDs, and serial number, match the ones specified. The serial number may be null to indicate that any serial number will match. The current device is set to the resultant device, possibly null.

Parameters:

vid - The vendor ID

pid - The product ID

serial - The serial number, or null if the serial number is not to be matched.

Returns:

The matching UsbDevice or null if no match found.

Throws:

UsbException - if a device is already open.

findDevice

public UsbDevice findDevice(int vid,
                            int pid,
                            int index)
                     throws UsbException

Finds a USB device and sets it as current

The tree of USB devices is searched, looking for devices whose vendor & product IDs match the ones specified. From this list of matches, the one with the specified index, starting at 0, is selected. The current device is set to the resultant device, possibly null.

Parameters:

vid - The vendor ID

pid - The product ID

index - The index, starting at 0, of the instance of matching devices to select.

Returns:

The matching UsbDevice or null if no match found.

Throws:

UsbException - if a device is already open.

findDevice

public UsbDevice findDevice(int vid,
                            int pid,
                            String serial,
                            int index)
                     throws UsbException

Finds a USB device and sets it as current

The tree of USB devices is searched, looking for devices whose vendor & product IDs, and serial number, match the ones specified. From this list of matches, the one with the specified index, starting at 0, is selected. The serial number may be null to indicate that any serial number will match. The current device is set to the resultant device, possibly null.

Parameters:

vid - The vendor ID

pid - The product ID

serial - The serial number, or null if the serial number is not to be matched.

index - The index, starting at 0, of the instance of matching devices to select.

Returns:

The matching UsbDevice or null if no match found.

Throws:

UsbException - if a device is already open.

getDevice

public UsbDevice getDevice()

Gets the current USB device

Returns:

The USB device object

setDevice

public void setDevice(UsbDevice device)
               throws UsbException

Sets the current USB device

Parameters:

device - The UsbDevice object to set. Can be null.

Throws:

UsbException - if a device is already open.

getConfiguration

public UsbConfiguration getConfiguration()

Gets the active USB configuration for the current device

Returns:

The USB configuration object

setConfiguration

public void setConfiguration(int cfgNum)
                      throws UsbException

Sets the active USB configuration for the current device

Note: fails if an interface has been claimed

Parameters:

cfgNum - The number of the configuration to set

Throws:

UsbException - if no device set, configuration number is invalid, or interface claimed

getInterface

public UsbInterface getInterface(int iface)

Gets the active setting of the specified USB interface of the current device

Parameters:

iface - The number, starting from 0, of the interface .

Returns:

The USB interface object, or null

getInterface

public static UsbInterface getInterface(UsbDevice device,
                                        int iface)

Gets the active setting of the specified USB interface of the specified device. *** Deprecated ***

Parameters:

device - The USB device

iface - The number, starting from 0, of the interface.

Returns:

The USB interface object, or null

setInterface

public void setInterface(int iface,
                         int setting)
                  throws UsbException

Sets the active setting of the specified USB interface of the current device

Note: fails if the interface has not been claimed

Parameters:

iface - The number, starting from 0, of the interface.

setting - The setting number, starting from 0, to use.

Throws:

UsbException - if no device set, setting or interface number is invalid, or interface not claimed

getEndpoint

public static UsbEndpoint getEndpoint(UsbInterface iface,
                                      int epAddr)

Gets a USB endpoint for the specified interface. *** Deprecated ***

Parameters:

iface - The USB interface to use

epAddr - The address of the endpoint to get.

Returns:

The USB endpoint object, or null

getEndpoints

public static List getEndpoints(UsbInterface iface)

Gets all USB endpoints for the specified interface. *** Deprecated ***

Parameters:

iface - The USB interface to use

Returns:

The list of USB endpoint objects

getSpeed

public int getSpeed()

Gets the speed of the current device *** Re-do ***

Returns:

The speed of the device, encoded locally.

getSpeed

public static int getSpeed(UsbDevice device)

Gets the speed of a device *** Deprecated ***

Parameters:

device - The USB device

Returns:

The speed of the device, encoded locally.

claim

public void claim(int iface,
                  boolean force)
           throws UsbException

Claims an interface

Parameters:

iface - The number, starting from 0, of the interface.

force - Set to true if claiming the device interface is to be forced, allowing the use of devices claimed by another driver or user.

Throws:

UsbException - if no device set, device not configured, interface number invalid, etc

release

public void release(int iface)
             throws UsbException

Releases an interface

Throws:

UsbException

open

public UsbCommPipe open(int iface,
                        int epAddr)
                 throws UsbException

Opens a connection to a device's endpoint

The device is assumed to be configured, and the specified interface is used.

Parameters:

iface - The number of the interface to use, starting at 0.

epaddr - The address of the endpoint to be opened.

Throws:

UsbException - if the device has not been set or the requested interface or endpoints do not exist.

UsbClaimException - if the interface cannot be claimed.

write

public int write(int type,
                 int rqst,
                 int value,
                 int index,
                 byte[] data)
          throws UsbException

Writes data to the control endpoint

Parameters:

type - The request type

rqst - The request

value - The value

index - The index

data - Byte array of data to be written.

Returns:

The number of bytes of data actually written.

Throws:

UsbException - if the out endpoint is not open.

write

public int write(int type,
                 int rqst,
                 int value,
                 int index,
                 byte[] data,
                 int offs,
                 int leng)
          throws UsbException

Writes data to the control endpoint

Parameters:

type - The request type

rqst - The request

value - The value

index - The index

data - Byte array containing the data to be written.

offs - The offset of the first byte to be written.

leng - The number of bytes to be written.

Returns:

The number of bytes of data actually written.

Throws:

UsbException - if the out endpoint is not open.

read

public int read(int type,
                int rqst,
                int value,
                int index,
                byte[] data,
                int timeout)
         throws UsbException,
                UsbTimeoutException

Reads data from the control endpoint

Parameters:

type - The request type

rqst - The request

value - The value

index - The index

data - Byte array to receive the read data.

timeout - The maximum time, in milliseconds, to wait for data.

Returns:

The number of bytes read.

Throws:

UsbException - if the in endpoint is not open.

UsbTimeoutException - if the read times out.

read

public int read(int type,
                int rqst,
                int value,
                int index,
                byte[] data,
                int offs,
                int leng,
                int timeout)
         throws UsbException,
                UsbTimeoutException

Reads data from the control endpoint

Parameters:

type - The request type

rqst - The request

value - The value

index - The index

data - Byte array to receive the read data.

offs - The offset in data where the read data is to start.

leng - The number of bytes of data to read.

timeout - The maximum time, in milliseconds, to wait for data.

Returns:

The number of bytes read.

Throws:

UsbException - if the in endpoint is not open.

UsbTimeoutException - if the read times out.