org.lsst.ccs.drivers.usb

Class UsbLib

java.lang.Object

org.lsst.ccs.drivers.usb.UsbLib

public class UsbLib
extends Object

Routines to interface to libusb

Author:

Owen Saxton

Field Summary

Fields

Modifier and Type	Field and Description
static int	CFG_ATTR_REMOTE_WAKE Configuration attribute - remote wakeup
static int	CFG_ATTR_SELF_POWER Configuration attribute - self-powered
static int	CLASS_APP_SPEC Device class - application specific
static int	CLASS_AUDIO Device class - audio
static int	CLASS_COMM Device class - CDC control
static int	CLASS_CONTENT_SEC Device class security x
static int	CLASS_DATA Device class - CDC data
static int	CLASS_DIAGNOSTIC Device class - diagnostic
static int	CLASS_HEALTHCARE Device class - personal healthcare
static int	CLASS_HID Device class - human interface
static int	CLASS_HUB Device class - hub
static int	CLASS_IMAGE Device class - still image
static int	CLASS_INTERFACE Device class - see interface
static int	CLASS_MASS_STORE Device class - mass storage
static int	CLASS_MISC Device class - miscellaneous
static int	CLASS_PHYSICAL Device class - physical
static int	CLASS_PRINTER Device class - printer
static int	CLASS_SMART_CARD Device class - smart card
static int	CLASS_VENDOR_SPEC Device class - vendor specific
static int	CLASS_VIDEO Device class - video
static int	CLASS_WIRELESS Device class - wireless
static int	EP_ATTR_BULK Endpoint attribute - bulk data
static int	EP_ATTR_BULK_STREAM Endpoint attribute - bulk stream
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	EP_DIRECTION_IN Endpoint direction - in
static int	SPEED_FULL Device speed - full
static int	SPEED_HIGH Device speed - high
static int	SPEED_LOW Device speed - low
static int	SPEED_SUPER Device speed - super
static int	SPEED_UNKNOWN Device speed - unknown

Constructor Summary

Constructors

Constructor and Description
UsbLib()

Method Summary

Modifier and Type	Method and Description
static void	attachKernelDriver(long devh, int intfc) Re-attach kernel driver to an interface.
static UsbConfiguration	buildConfiguration(long cdesc, UsbDevice devc) Builds a complete configuration from its descriptor.
static int	bulkTransfer(long devh, int endp, byte[] data, int offset, int leng, int timeout) Transfers bulk data on an endpoint.
static void	claimInterface(long devh, int intfc) Claims an interface.
static void	clearHalt(long devh, int endp) Clears a halt condition on an endpoint.
static void	close(long devh) Closes a device.
static int	controlTransfer(long devh, int type, int rqst, int value, int index, byte[] data, int offset, int leng, int timeout) Transfers data on the control endpoint.
static void	detachKernelDriver(long devh, int intfc) Detach kernel driver from an interface.
static void	freeConfigDescriptor(long cdesc) Frees a configuration descriptor.
static long	getActiveConfigDescriptor(long devc) Gets the active configuration descriptor handle.
static long[]	getAltSettingDescriptors(long iface) Gets the alternate settings in an interface.
static int	getBusNumber(long devc) Gets the bus number for a device.
static long	getConfigDescriptor(long devc, int index) Gets a configuration descriptor handle.
static long	getConfigDescriptorByValue(long devc, int value) Gets a configuration descriptor handle using its value.
static int	getConfiguration(long devh) Gets the number of the active configuration.
static UsbDevice	getDevice(int vendor, int product, String serial, int index) Gets the device matching vendor, product, serial and index.
static int	getDeviceAddress(long devc) Gets the address of a device.
static long[]	getDeviceList(long ctxt) Gets the list of available USB devices.
static List<UsbDevice>	getDevices(int vendor, int product, String serial) Gets the list of devices matching vendor, product and serial.
static int	getDeviceSpeed(long devc) Gets the speed of a device.
static long[]	getEndpointDescriptors(long idesc) Gets the endpoints in an interface.
static long[]	getInterfaces(long cdesc) Gets the interfaces in a configuration.
static int	getMaxPacketSize(long devc, int endp) Gets the maximum packet size for an endpoint.
static int	getPortNumber(long devc) Gets the port number for a device.
static String	getStringDescriptorAscii(long devh, int index) Gets a string descriptor.
static int	interruptTransfer(long devh, int endp, byte[] data, int offset, int leng, int timeout) Transfers interrupt data on an endpoint.
static boolean	kernelDriverActive(long devh, int intfc) Determines if kernel driver is active on an interface.
static UsbConfigurationDescriptor	newConfigurationDescriptor(long cdesc) Creates a configuration descriptor object.
static UsbDeviceDescriptor	newDeviceDescriptor(long devc) Gets the device descriptor.
static UsbEndpointDescriptor	newEndpointDescriptor(long edesc) Creates an endpoint descriptor object.
static UsbInterfaceDescriptor	newInterfaceDescriptor(long idesc) Creates an interface descriptor object.
static long	open(long devc) Opens a device for subsequent I/O operations.
static void	releaseInterface(long devh, int intfc) Releases an interface.
static void	resetDevice(long devh) Resets a device.
static void	setAutoDetachKernelDriver(long devh, boolean enable) Enables/disables the auto detach kernel driver capability.
static void	setConfiguration(long devh, int conf) Sets the active configuration.
static void	setInterfaceAltSetting(long devh, int intfc, int alt) Sets an alternate setting for an interface.
static void	unrefDevice(long devc) Unreferences a device.

Methods inherited from class java.lang.Object

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

Field Detail

SPEED_UNKNOWN

public static final int SPEED_UNKNOWN

Device speed - unknown

See Also:

Constant Field Values

SPEED_LOW

public static final int SPEED_LOW

Device speed - low

See Also:

Constant Field Values

SPEED_FULL

public static final int SPEED_FULL

Device speed - full

See Also:

Constant Field Values

SPEED_HIGH

public static final int SPEED_HIGH

Device speed - high

See Also:

Constant Field Values

SPEED_SUPER

public static final int SPEED_SUPER

Device speed - super

See Also:

Constant Field Values

CLASS_INTERFACE

public static final int CLASS_INTERFACE

Device class - see interface

See Also:

Constant Field Values

CLASS_AUDIO

public static final int CLASS_AUDIO

Device class - audio

See Also:

Constant Field Values

CLASS_COMM

public static final int CLASS_COMM

Device class - CDC control

See Also:

Constant Field Values

CLASS_HID

public static final int CLASS_HID

Device class - human interface

See Also:

Constant Field Values

CLASS_PHYSICAL

public static final int CLASS_PHYSICAL

Device class - physical

See Also:

Constant Field Values

CLASS_IMAGE

public static final int CLASS_IMAGE

Device class - still image

See Also:

Constant Field Values

CLASS_PRINTER

public static final int CLASS_PRINTER

Device class - printer

See Also:

Constant Field Values

CLASS_MASS_STORE

public static final int CLASS_MASS_STORE

Device class - mass storage

See Also:

Constant Field Values

CLASS_HUB

public static final int CLASS_HUB

Device class - hub

See Also:

Constant Field Values

CLASS_DATA

public static final int CLASS_DATA

Device class - CDC data

See Also:

Constant Field Values

CLASS_SMART_CARD

public static final int CLASS_SMART_CARD

Device class - smart card

See Also:

Constant Field Values

CLASS_CONTENT_SEC

public static final int CLASS_CONTENT_SEC

Device class security x

See Also:

Constant Field Values

CLASS_VIDEO

public static final int CLASS_VIDEO

Device class - video

See Also:

Constant Field Values

CLASS_HEALTHCARE

public static final int CLASS_HEALTHCARE

Device class - personal healthcare

See Also:

Constant Field Values

CLASS_DIAGNOSTIC

public static final int CLASS_DIAGNOSTIC

Device class - diagnostic

See Also:

Constant Field Values

CLASS_WIRELESS

public static final int CLASS_WIRELESS

Device class - wireless

See Also:

Constant Field Values

CLASS_MISC

public static final int CLASS_MISC

Device class - miscellaneous

See Also:

Constant Field Values

CLASS_APP_SPEC

public static final int CLASS_APP_SPEC

Device class - application specific

See Also:

Constant Field Values

CLASS_VENDOR_SPEC

public static final int 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

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

EP_ATTR_BULK_STREAM

public static final int EP_ATTR_BULK_STREAM

Endpoint attribute - bulk stream

See Also:

Constant Field Values

EP_DIRECTION_IN

public static final int EP_DIRECTION_IN

Endpoint direction - in

See Also:

Constant Field Values

Constructor Detail

UsbLib

public UsbLib()

Method Detail

getDevices

public static List<UsbDevice> getDevices(int vendor,
                                         int product,
                                         String serial)
                                  throws org.lsst.ccs.drivers.commons.DriverException

Gets the list of devices matching vendor, product and serial. If a non-null serial number is specified and an otherwise matching device cannot be opened or has no serial number, it is treated as not matching.

Parameters:

vendor - The vendor ID; or -1 to match all

product - The product ID; or -1 to match all

serial - The serial number, which matches if it is contained in the device's number; or null to match all

Returns:

The list of matching device objects

Throws:

org.lsst.ccs.drivers.commons.DriverException

getDevice

public static UsbDevice getDevice(int vendor,
                                  int product,
                                  String serial,
                                  int index)
                           throws org.lsst.ccs.drivers.commons.DriverException

Gets the device matching vendor, product, serial and index. If a non-null serial number is specified and an otherwise matching device cannot be opened or has no serial number, it is treated as not matching.

Parameters:

vendor - The vendor ID, or -1 to match all

product - The product ID, or -1 to match all

serial - The serial number, which matches if it is contained in the device's number; or null to match all

index - The index of the device in the list of matching devices

Returns:

The matching device object, or null if no match

Throws:

org.lsst.ccs.drivers.commons.DriverException

buildConfiguration

public static UsbConfiguration buildConfiguration(long cdesc,
                                                  UsbDevice devc)

Builds a complete configuration from its descriptor.

Parameters:

cdesc - The configuration descriptor handle

devc - The associated device object

Returns:

The configuration object

getDeviceList

public static long[] getDeviceList(long ctxt)
                            throws org.lsst.ccs.drivers.commons.DriverException

Gets the list of available USB devices.

Parameters:

ctxt - The library context

Returns:

The array of handles for each USB device

Throws:

org.lsst.ccs.drivers.commons.DriverException

getBusNumber

public static int getBusNumber(long devc)

Gets the bus number for a device.

Parameters:

devc - The device handle

Returns:

The device's bus number

getPortNumber

public static int getPortNumber(long devc)

Gets the port number for a device.

Parameters:

devc - The device handle

Returns:

The device's port number

getDeviceAddress

public static int getDeviceAddress(long devc)

Gets the address of a device.

Parameters:

devc - The device handle

Returns:

The device's address

getDeviceSpeed

public static int getDeviceSpeed(long devc)

Gets the speed of a device.

Parameters:

devc - The device handle

Returns:

The device's speed

getMaxPacketSize

public static int getMaxPacketSize(long devc,
                                   int endp)

Gets the maximum packet size for an endpoint.

Parameters:

devc - The device handle

endp - The endpoint address

Returns:

The device's maximum packet size

unrefDevice

public static void unrefDevice(long devc)

Unreferences a device.

Parameters:

devc - The device handle

open

public static long open(long devc)
                 throws org.lsst.ccs.drivers.commons.DriverException

Opens a device for subsequent I/O operations.

Parameters:

devc - The device handle

Returns:

The device's open handle

Throws:

org.lsst.ccs.drivers.commons.DriverException

close

public static void close(long devh)

Closes a device.

Parameters:

devh - The open handle

getConfiguration

public static int getConfiguration(long devh)
                            throws org.lsst.ccs.drivers.commons.DriverException

Gets the number of the active configuration.

Parameters:

devh - The open handle

Returns:

The active configuration number

Throws:

org.lsst.ccs.drivers.commons.DriverException

setConfiguration

public static void setConfiguration(long devh,
                                    int conf)
                             throws org.lsst.ccs.drivers.commons.DriverException

Sets the active configuration.

Parameters:

devh - The open handle

conf - The number of the configuration to make active

Throws:

org.lsst.ccs.drivers.commons.DriverException

claimInterface

public static void claimInterface(long devh,
                                  int intfc)
                           throws org.lsst.ccs.drivers.commons.DriverException

Claims an interface.

Parameters:

devh - The open handle

intfc - The number of the interface to claim

Throws:

org.lsst.ccs.drivers.commons.DriverException

releaseInterface

public static void releaseInterface(long devh,
                                    int intfc)
                             throws org.lsst.ccs.drivers.commons.DriverException

Releases an interface.

Parameters:

devh - The open handle

intfc - The number of the interface to release

Throws:

org.lsst.ccs.drivers.commons.DriverException

setInterfaceAltSetting

public static void setInterfaceAltSetting(long devh,
                                          int intfc,
                                          int alt)
                                   throws org.lsst.ccs.drivers.commons.DriverException

Sets an alternate setting for an interface.

Parameters:

devh - The open handle

intfc - The interface number

alt - The alternate setting number

Throws:

org.lsst.ccs.drivers.commons.DriverException

kernelDriverActive

public static boolean kernelDriverActive(long devh,
                                         int intfc)
                                  throws org.lsst.ccs.drivers.commons.DriverException

Determines if kernel driver is active on an interface.

Parameters:

devh - The open handle

intfc - The interface number

Returns:

Whether a kernel driver is avtive

Throws:

org.lsst.ccs.drivers.commons.DriverException

detachKernelDriver

public static void detachKernelDriver(long devh,
                                      int intfc)
                               throws org.lsst.ccs.drivers.commons.DriverException

Detach kernel driver from an interface.

Parameters:

devh - The open handle

intfc - The interface number

Throws:

org.lsst.ccs.drivers.commons.DriverException

attachKernelDriver

public static void attachKernelDriver(long devh,
                                      int intfc)
                               throws org.lsst.ccs.drivers.commons.DriverException

Re-attach kernel driver to an interface.

Parameters:

devh - The open handle

intfc - The interface number

Throws:

org.lsst.ccs.drivers.commons.DriverException

setAutoDetachKernelDriver

public static void setAutoDetachKernelDriver(long devh,
                                             boolean enable)
                                      throws org.lsst.ccs.drivers.commons.DriverException

Enables/disables the auto detach kernel driver capability.

Parameters:

devh - The open handle

enable - Whether to enable (true) or disable (false)

Throws:

org.lsst.ccs.drivers.commons.DriverException

clearHalt

public static void clearHalt(long devh,
                             int endp)
                      throws org.lsst.ccs.drivers.commons.DriverException

Clears a halt condition on an endpoint.

Parameters:

devh - The open handle

endp - The endpoint address

Throws:

org.lsst.ccs.drivers.commons.DriverException

resetDevice

public static void resetDevice(long devh)
                        throws org.lsst.ccs.drivers.commons.DriverException

Resets a device.

Parameters:

devh - The open handle

Throws:

org.lsst.ccs.drivers.commons.DriverException

newDeviceDescriptor

public static UsbDeviceDescriptor newDeviceDescriptor(long devc)
                                               throws org.lsst.ccs.drivers.commons.DriverException

Gets the device descriptor.

Parameters:

devc - The device handle

Returns:

The device descriptor object

Throws:

org.lsst.ccs.drivers.commons.DriverException

getActiveConfigDescriptor

public static long getActiveConfigDescriptor(long devc)
                                      throws org.lsst.ccs.drivers.commons.DriverException

Gets the active configuration descriptor handle. The memory associated with the handle must be released after it is no longer needed by calling freeConfigDescriptor.

Parameters:

devc - The device handle

Returns:

The configuration descriptor handle

Throws:

org.lsst.ccs.drivers.commons.DriverException

getConfigDescriptor

public static long getConfigDescriptor(long devc,
                                       int index)
                                throws org.lsst.ccs.drivers.commons.DriverException

Gets a configuration descriptor handle. The memory associated with the handle must be released after it is no longer needed by calling freeConfigDescriptor.

Parameters:

devc - The device handle

index - The index of the descriptor

Returns:

The configuration descriptor handle

Throws:

org.lsst.ccs.drivers.commons.DriverException

getConfigDescriptorByValue

public static long getConfigDescriptorByValue(long devc,
                                              int value)
                                       throws org.lsst.ccs.drivers.commons.DriverException

Gets a configuration descriptor handle using its value. The memory associated with the handle must be released after it is no longer needed by calling freeConfigDescriptor.

Parameters:

devc - The device handle

value - The descriptor value (number)

Returns:

The configuration descriptor handle

Throws:

org.lsst.ccs.drivers.commons.DriverException

freeConfigDescriptor

public static void freeConfigDescriptor(long cdesc)

Frees a configuration descriptor.

Parameters:

cdesc - The configuration descriptor handle

newConfigurationDescriptor

public static UsbConfigurationDescriptor newConfigurationDescriptor(long cdesc)

Creates a configuration descriptor object.

Parameters:

cdesc - The configuration descriptor handle

Returns:

The configuration descriptor object

getInterfaces

public static long[] getInterfaces(long cdesc)

Gets the interfaces in a configuration.

Parameters:

cdesc - The configuration descriptor handle

Returns:

The array of interface handles

getAltSettingDescriptors

public static long[] getAltSettingDescriptors(long iface)

Gets the alternate settings in an interface.

Parameters:

iface - The interface handle

Returns:

The array of alternate setting interface descriptor handles

newInterfaceDescriptor

public static UsbInterfaceDescriptor newInterfaceDescriptor(long idesc)

Creates an interface descriptor object.

Parameters:

idesc - The interface descriptor handle

Returns:

The interface descriptor object

getEndpointDescriptors

public static long[] getEndpointDescriptors(long idesc)

Gets the endpoints in an interface.

Parameters:

idesc - The interface descriptor handle

Returns:

The array of endpoint descriptor handles

newEndpointDescriptor

public static UsbEndpointDescriptor newEndpointDescriptor(long edesc)

Creates an endpoint descriptor object.

Parameters:

edesc - The endpoint descriptor handle

Returns:

The endpoint descriptor object

getStringDescriptorAscii

public static String getStringDescriptorAscii(long devh,
                                              int index)
                                       throws org.lsst.ccs.drivers.commons.DriverException

Gets a string descriptor.

Parameters:

devh - The open handle

index - The index of the string descriptor

Returns:

The string descriptor as an ASCII string

Throws:

org.lsst.ccs.drivers.commons.DriverException

controlTransfer

public static int controlTransfer(long devh,
                                  int type,
                                  int rqst,
                                  int value,
                                  int index,
                                  byte[] data,
                                  int offset,
                                  int leng,
                                  int timeout)
                           throws org.lsst.ccs.drivers.commons.DriverException

Transfers data on the control endpoint.

Parameters:

devh - The open handle

type - The transfer type

rqst - The request parameter

value - The value parameter

index - The index parameter

data - The array to or from which the data is transferred

offset - The offset to the start of the transferred data

leng - The number of bytes to transfer

timeout - The timeout (ms)

Returns:

The number of bytes transferred

Throws:

org.lsst.ccs.drivers.commons.DriverException

bulkTransfer

public static int bulkTransfer(long devh,
                               int endp,
                               byte[] data,
                               int offset,
                               int leng,
                               int timeout)
                        throws org.lsst.ccs.drivers.commons.DriverException

Transfers bulk data on an endpoint.

Parameters:

devh - The open handle

endp - The endpoint address.

data - The array to or from which the data is transferred

offset - The offset to the start of the transferred data

leng - The number of bytes to transfer

timeout - The timeout (ms)

Returns:

The number of bytes transferred

Throws:

org.lsst.ccs.drivers.commons.DriverException

interruptTransfer

public static int interruptTransfer(long devh,
                                    int endp,
                                    byte[] data,
                                    int offset,
                                    int leng,
                                    int timeout)
                             throws org.lsst.ccs.drivers.commons.DriverException

Transfers interrupt data on an endpoint.

Parameters:

devh - The open handle

endp - The endpoint address.

data - The array to or from which the data is transferred

offset - The offset to the start of the transferred data

leng - The number of bytes to transfer

timeout - The timeout (ms)

Returns:

The number of bytes transferred

Throws:

org.lsst.ccs.drivers.commons.DriverException