Package ch.ntb.usb

# Class Device

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

public class Device extends Object
This class represents an USB device.
To get an instance of an USB device use `USB.getDevice(...)`.

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`Device(short idVendor, short idProduct)`
`protected`
`Device(short idVendor, short idProduct, String filename)`

## Method Summary

Modifier and Type
Method
Description
`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 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 Details

### Device

protected Device(short idVendor, short idProduct)

### Device

protected Device(short idVendor, short idProduct, String filename)

## Method Details

### 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 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.