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
    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
    Returns the alternative interface.
    This value is only valid after opening the device.
    Returns the configuration descriptors associated with this device.
    The descriptors are updated by calling updateDescriptors() or open(int, int, int).
    int
    Returns the current configuration used.
    This value is only valid after opening the device.
    Returns the Usb_Device instance associated with this device.
    Returns the device descriptor associated with this device.
    The descriptor is updated by calling updateDescriptors() or open(int, int, int).
    protected String
    Returns the optional filename which is set when there are multiple devices with the same vendor and product id.
    int
    Returns the product ID of the device.
    int
    Returns the vendor ID of the device.
    int
    Returns the current interface.
    This value is only valid after opening the device.
    int
    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
    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
    Sends an USB reset to the device.
    void
    setResetOnFirstOpen(boolean enable, int timeout)
    If enabled, the device is reset when first opened.
    void
    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.