ch.ntb.usb
Class Device

java.lang.Object
  extended by ch.ntb.usb.Device

public class Device
extends java.lang.Object

This class represents an USB device.
To get an instance of an USB device use USB.getDevice(...).


Constructor Summary
protected Device(short idVendor, short idProduct)
           
protected Device(short idVendor, short idProduct, java.lang.String filename)
           
 
Method Summary
 void close()
          Release the claimed interface and close the opened device.
 int controlMsg(int requestType, int request, int value, int index, byte[] data, int size, int timeout, boolean reopenOnTimeout)
          Performs a control request to the default control pipe on a device.
The parameters mirror the types of the same name in the USB specification.
 int getAltinterface()
          Returns the alternative interface.
This value is only valid after opening the device.
 Usb_Config_Descriptor[] getConfigDescriptors()
          Returns the configuration descriptors associated with this device.
The descriptors are updated by calling updateDescriptors() or open(int, int, int).
 int getConfiguration()
          Returns the current configuration used.
This value is only valid after opening the device.
 Usb_Device getDevice()
          Returns the Usb_Device instance associated with this device.
 Usb_Device_Descriptor getDeviceDescriptor()
          Returns the device descriptor associated with this device.
The descriptor is updated by calling updateDescriptors() or open(int, int, int).
protected  java.lang.String getFilename()
          Returns the optional filename which is set when there are multiple devices with the same vendor and product id.
 int getIdProduct()
          Returns the product ID of the device.
 int getIdVendor()
          Returns the vendor ID of the device.
 int getInterface()
          Returns the current interface.
This value is only valid after opening the device.
 int getMaxPacketSize()
          Returns the maximum packet size in bytes which is allowed to be transmitted at once.
The value is determined by reading the endpoint descriptor(s) when opening the device.
 boolean isOpen()
          Check if the device is open.
This checks only for a valid device handle.
 void open(int configuration, int interface_, int altinterface)
          Opens the device and claims the specified configuration, interface and altinterface.
First the bus is enumerated.
 int readBulk(int in_ep_address, byte[] data, int size, int timeout, boolean reopenOnTimeout)
          Read data from the device using a bulk transfer.
 int readInterrupt(int in_ep_address, byte[] data, int size, int timeout, boolean reopenOnTimeout)
          Read data from the device using a interrupt transfer.
 void reset()
          Sends an USB reset to the device.
 void setResetOnFirstOpen(boolean enable, int timeout)
          If enabled, the device is reset when first opened.
 void updateDescriptors()
          Updates the device and descriptor information from the bus.
The descriptors can be read with getDeviceDescriptor() and getConfigDescriptors().
 int writeBulk(int out_ep_address, byte[] data, int size, int timeout, boolean reopenOnTimeout)
          Write data to the device using a bulk transfer.
 int writeInterrupt(int out_ep_address, byte[] data, int size, int timeout, boolean reopenOnTimeout)
          Write data to the device using a interrupt transfer.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Device

protected Device(short idVendor,
                 short idProduct)

Device

protected Device(short idVendor,
                 short idProduct,
                 java.lang.String filename)
Method Detail

updateDescriptors

public void updateDescriptors()
                       throws USBException
Updates the device and descriptor information from the bus.
The descriptors can be read with getDeviceDescriptor() and getConfigDescriptors().

Throws:
USBException

getDeviceDescriptor

public Usb_Device_Descriptor getDeviceDescriptor()
Returns the device descriptor associated with this device.
The descriptor is updated by calling updateDescriptors() or open(int, int, int).

Returns:
the device descriptor associated with this device or null

getConfigDescriptors

public Usb_Config_Descriptor[] getConfigDescriptors()
Returns the configuration descriptors associated with this device.
The descriptors are updated by calling updateDescriptors() or open(int, int, int).

Returns:
the configuration descriptors associated with this device or null

open

public void open(int configuration,
                 int interface_,
                 int altinterface)
          throws USBException
Opens the device and claims the specified configuration, interface and altinterface.
First the bus is enumerated. If the device is found its descriptors are read and the maxPacketSize value is updated. If no endpoints are found in the descriptors an exception is thrown.

Parameters:
configuration - the configuration, see Usb_Config_Descriptor.getBConfigurationValue()
interface_ - the interface, see Usb_Interface_Descriptor.getBInterfaceNumber()
altinterface - the alternate interface, see Usb_Interface_Descriptor.getBAlternateSetting(). If no alternate interface must be set -1 can be used.
Throws:
USBException

close

public void close()
           throws USBException
Release the claimed interface and close the opened device.

Throws:
USBException

reset

public void reset()
           throws USBException
Sends an USB reset to the device. The device handle will no longer be valid. To use the device again, open(int, int, int) must be called.

Throws:
USBException

writeBulk

public int writeBulk(int out_ep_address,
                     byte[] data,
                     int size,
                     int timeout,
                     boolean reopenOnTimeout)
              throws USBException
Write data to the device using a bulk transfer.

Parameters:
out_ep_address - endpoint address to write to
data - data to write to this endpoint
size - size of the data
timeout - amount of time in ms the device will try to send the data until a timeout exception is thrown
reopenOnTimeout - if set to true, the device will try to open the connection and send the data again before a timeout exception is thrown
Returns:
the actual number of bytes written
Throws:
USBException

readBulk

public int readBulk(int in_ep_address,
                    byte[] data,
                    int size,
                    int timeout,
                    boolean reopenOnTimeout)
             throws USBException
Read data from the device using a bulk transfer.

Parameters:
in_ep_address - endpoint address to read from
data - data buffer for the data to be read
size - the maximum requested data size
timeout - amount of time in ms the device will try to receive data until a timeout exception is thrown
reopenOnTimeout - if set to true, the device will try to open the connection and receive the data again before a timeout exception is thrown
Returns:
the actual number of bytes read
Throws:
USBException

writeInterrupt

public int writeInterrupt(int out_ep_address,
                          byte[] data,
                          int size,
                          int timeout,
                          boolean reopenOnTimeout)
                   throws USBException
Write data to the device using a interrupt transfer.

Parameters:
out_ep_address - endpoint address to write to
data - data to write to this endpoint
size - size of the data
timeout - amount of time in ms the device will try to send the data until a timeout exception is thrown
reopenOnTimeout - if set to true, the device will try to open the connection and send the data again before a timeout exception is thrown
Returns:
the actual number of bytes written
Throws:
USBException

readInterrupt

public int readInterrupt(int in_ep_address,
                         byte[] data,
                         int size,
                         int timeout,
                         boolean reopenOnTimeout)
                  throws USBException
Read data from the device using a interrupt transfer.

Parameters:
in_ep_address - endpoint address to read from
data - data buffer for the data to be read
size - the maximum requested data size
timeout - amount of time in ms the device will try to receive data until a timeout exception is thrown
reopenOnTimeout - if set to true, the device will try to open the connection and receive the data again before a timeout exception is thrown
Returns:
the actual number of bytes read
Throws:
USBException

controlMsg

public int controlMsg(int requestType,
                      int request,
                      int value,
                      int index,
                      byte[] data,
                      int size,
                      int timeout,
                      boolean reopenOnTimeout)
               throws USBException
Performs a control request to the default control pipe on a device.
The parameters mirror the types of the same name in the USB specification.

Parameters:
requestType - USB device request type (USB specification 9.3, bmRequestType). Use constants from USB (REQ_TYPE_xxx).
request - specific request (USB specification 9.4, bRequest). Use constants from USB (REQ_xxx).
value - field that varies according to request (USB specification 9.4, wValue)
index - field that varies according to request (USB specification 9.4, wIndex)
data - the send/receive buffer
size - the buffer size. 0 is a valid value, but there must still be a dummy data buffer provided.
timeout - amount of time in ms the device will try to send/receive data until a timeout exception is thrown
reopenOnTimeout - if set to true, the device will try to open the connection and send/receive the data again before a timeout exception is thrown
Returns:
the number of bytes written/read
Throws:
USBException

getIdProduct

public int getIdProduct()
Returns the product ID of the device.

Returns:
the product ID of the device.

getIdVendor

public int getIdVendor()
Returns the vendor ID of the device.

Returns:
the vendor ID of the device.

getAltinterface

public int getAltinterface()
Returns the alternative interface.
This value is only valid after opening the device.

Returns:
the alternative interface. This value is only valid after opening the device.

getConfiguration

public int getConfiguration()
Returns the current configuration used.
This value is only valid after opening the device.

Returns:
the current configuration used. This value is only valid after opening the device.

getInterface

public int getInterface()
Returns the current interface.
This value is only valid after opening the device.

Returns:
the current interface. This value is only valid after opening the device.

getMaxPacketSize

public int getMaxPacketSize()
Returns the maximum packet size in bytes which is allowed to be transmitted at once.
The value is determined by reading the endpoint descriptor(s) when opening the device. It is invalid before the device is opened! Note that if some endpoints use different packet sizes the maximum packet size is return. This value may be used to determine if a device is opened in fullspeed or highspeed mode.

Returns:
the maximum packet size

isOpen

public boolean isOpen()
Check if the device is open.
This checks only for a valid device handle. It doesn't check if the device is still attached or working.

Returns:
true if the device is open

setResetOnFirstOpen

public void setResetOnFirstOpen(boolean enable,
                                int timeout)
If enabled, the device is reset when first opened.
This will only happen once. When the application is started, the device state is unknown. If the device is not reset, read or write may result in a USBTimeoutException.

This feature is disabled by default.

Parameters:
enable - true if the device should be reset when first opened
timeout - the timeout between the reset and the reopening

getFilename

protected java.lang.String getFilename()
Returns the optional filename which is set when there are multiple devices with the same vendor and product id. See USB.getDevice(short, short, String). Use Usb_Device.getFilename() to read the filename of a device.

Returns:
the filename if set or null

getDevice

public Usb_Device getDevice()
Returns the Usb_Device instance associated with this device. This value is only valid after opening the device.

Returns:
the Usb_Device instance associated with this device.