Package ch.ntb.usb

Class 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

      Constructors 
      Modifier Constructor Description
      protected Device​(short idVendor, short idProduct)  
      protected Device​(short idVendor, short idProduct, java.lang.String filename)  
    • 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 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

      • 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
      • close

        public void close()
                   throws USBException
        Release the claimed interface and close the opened device.
        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.