Package ch.ntb.usb
Class Device
- java.lang.Object
-
- 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 useUSB.getDevice(...)
.
-
-
Method Summary
All Methods Instance Methods Concrete Methods 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 callingupdateDescriptors()
oropen(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 callingupdateDescriptors()
oropen(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 withgetDeviceDescriptor()
andgetConfigDescriptors()
.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.
-
-
-
Method Detail
-
updateDescriptors
public void updateDescriptors() throws USBException
Updates the device and descriptor information from the bus.
The descriptors can be read withgetDeviceDescriptor()
andgetConfigDescriptors()
.- Throws:
USBException
-
getDeviceDescriptor
public Usb_Device_Descriptor getDeviceDescriptor()
Returns the device descriptor associated with this device.
The descriptor is updated by callingupdateDescriptors()
oropen(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 callingupdateDescriptors()
oropen(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 themaxPacketSize
value is updated. If no endpoints are found in the descriptors an exception is thrown.- Parameters:
configuration
- the configuration, seeUsb_Config_Descriptor.getBConfigurationValue()
interface_
- the interface, seeUsb_Interface_Descriptor.getBInterfaceNumber()
altinterface
- the alternate interface, seeUsb_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 todata
- data to write to this endpointsize
- size of the datatimeout
- amount of time in ms the device will try to send the data until a timeout exception is thrownreopenOnTimeout
- 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 fromdata
- data buffer for the data to be readsize
- the maximum requested data sizetimeout
- amount of time in ms the device will try to receive data until a timeout exception is thrownreopenOnTimeout
- 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 todata
- data to write to this endpointsize
- size of the datatimeout
- amount of time in ms the device will try to send the data until a timeout exception is thrownreopenOnTimeout
- 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 fromdata
- data buffer for the data to be readsize
- the maximum requested data sizetimeout
- amount of time in ms the device will try to receive data until a timeout exception is thrownreopenOnTimeout
- 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 fromUSB
(REQ_TYPE_xxx).request
- specific request (USB specification 9.4, bRequest). Use constants fromUSB
(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 buffersize
- 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 thrownreopenOnTimeout
- 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 aUSBTimeoutException
.
This feature is disabled by default.- Parameters:
enable
- true if the device should be reset when first openedtimeout
- 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. SeeUSB.getDevice(short, short, String)
. UseUsb_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.
-
-