Interface UsbDevice

public interface UsbDevice
USB device.

In order to make control requests and transfer data, the device must be opened and an interface must be claimed. In the open state, this current process has exclusive access to the device.

Information about the device can be queried in both the open and the closed state.

  • Method Details

    • getProductId

      int getProductId()
      USB product ID.
      Returns:
      product ID

    • getVendorId

      int getVendorId()
      USB vendor ID.
      Returns:
      vendor ID

    • getProduct

      String getProduct()
      Product name.
      Returns:
      product name or null if not provided by the device

    • getManufacturer

      String getManufacturer()
      Manufacturer name
      Returns:
      manufacturer name or null if not provided by the device

    • getSerialNumber

      String getSerialNumber()
      Serial number

      Even though this is supposed to be a human-readable string, some devices are known to provide binary data.

      Returns:
      serial number or null if not provided by the device

    • getClassCode

      int getClassCode()
      USB device class code (bDeviceClass from device descriptor).
      Returns:
      class code

    • getSubclassCode

      int getSubclassCode()
      USB device subclass code (bDeviceSubClass from device descriptor).
      Returns:
      subclass code

    • getProtocolCode

      int getProtocolCode()
      USB device protocol (bDeviceProtocol from device descriptor).
      Returns:
      protocol code

    • getUsbVersion

      @NotNull @NotNull Version getUsbVersion()
      USB protocol version supported by this device.
      Returns:
      version

    • getDeviceVersion

      @NotNull @NotNull Version getDeviceVersion()
      Device version (as declared by the manufacturer).
      Returns:
      version

    • detachStandardDrivers

      void detachStandardDrivers()
      Detaches the standard operating-system drivers of this device.

      By detaching the standard drivers, the operating system releases the exclusive access to the device and/or some or all of the device's interfaces. This allows the application to open the device and claim interfaces. It is relevant for device and interfaces implementing standard USB classes, such as HID, CDC and mass storage.

      This method should be called before the device is opened. After the device has been closed, attachStandardDrivers() should be called to restore the previous state.

      On macOS, all device drivers are immediately detached from the device. To execute it, the application must be run as root. Without root privileges, the method does nothing.

      On Linux, this method changes the behavior of claimInterface(int) for this device. The standard drivers will be detached interface by interface when the interface is claimed.

      On Windows, this method does nothing. It is not possible to temporarily change the drivers.

    • attachStandardDrivers

      void attachStandardDrivers()
      Reattaches the standard operating-system drivers to this device.

      By attaching the standard drivers, the operating system claims the device and/or its interfaces if they implement standard USB classes, such as HID, CDC and mass storage. It is used to restore the state before calling detachStandardDrivers().

      This method should be called after the device has been closed.

      On macOS, the application must be run as root. Without root privileges, the method does nothing.

      On Linux, this method changes the behavior of claimInterface(int). Standard drivers will no longer be detached when the interface is claimed. Standard drivers are automatically reattached when the interfaces are released, at the lasted when the device is closed.

      On Windows, this method does nothing.

    • isConnected

      boolean isConnected()
      Indicates if the device is connected.

      When a UsbDevice instance is initially returned by Usb.getDevices() and related methods, it is connected. When the user unplugs the device, the application can still hold on to instance of UsbDevice even though the actual USB device is gone. This method can be used to check if the device is still connected.

      Returns:
      true if the device is connected, false if it is no longer connected

    • open

      void open()
      Opens the device for communication.

    • isOpened

      boolean isOpened()
      Indicates if the device is open.
      Returns:
      true if the device is open, false if it is closed.

    • close

      void close()
      Closes the device.

    • getInterfaces

      @NotNull @NotNull @Unmodifiable List<UsbInterface> getInterfaces()
      Gets the interfaces of this device.

      The returned list is sorted by interface number.

      Returns:
      a list of USB interfaces

    • getInterface

      @NotNull @NotNull UsbInterface getInterface(int interfaceNumber)
      Gets the interface with the specified number.
      Parameters:
      interfaceNumber - the interface number
      Returns:
      the interface
      Throws:
      UsbException - if the interface does not exist

    • getEndpoint

      @NotNull @NotNull UsbEndpoint getEndpoint(UsbDirection direction, int endpointNumber)
      Gets the endpoint with the specified number.
      Parameters:
      direction - the endpoint direction
      endpointNumber - the endpoint number (between 1 and 127)
      Returns:
      the endpoint
      Throws:
      UsbException - if the endpoint does not exist

    • claimInterface

      void claimInterface(int interfaceNumber)
      Claims the specified interface for exclusive use.
      Parameters:
      interfaceNumber - the interface number

    • selectAlternateSetting

      void selectAlternateSetting(int interfaceNumber, int alternateNumber)
      Selects the alternate settings for the specified interface.

      The device must be open and the interface must be claimed for exclusive access.

      Parameters:
      interfaceNumber - interface number
      alternateNumber - alternate setting number

    • releaseInterface

      void releaseInterface(int interfaceNumber)
      Releases the specified interface from exclusive use.
      Parameters:
      interfaceNumber - the interface number

    • controlTransferIn

      byte @NotNull [] controlTransferIn(@NotNull @NotNull UsbControlTransfer transfer, int length)
      Requests data from the control endpoint.

      This method blocks until the device has responded or an error has occurred.

      The control transfer request is sent to endpoint 0. The transfer is expected to have a Data In stage.

      Requests with an interface or an endpoint as recipient are expected to have the interface and endpoint number, respectively, in the lower byte of wIndex. This convention is enforced by Windows. The addressed interface or the interface of the addressed endpoint must have been claimed.

      Parameters:
      transfer - control transfer setup parameters
      length - maximum length of expected data
      Returns:
      received data.

    • controlTransferOut

      void controlTransferOut(@NotNull @NotNull UsbControlTransfer transfer, byte[] data)
      Executes a control transfer request and optionally sends data.

      This method blocks until the device has acknowledge the request or an error has occurred.

      The control transfer request is sent to endpoint 0. The transfer is expected to either have no data stage or a Data Out stage.

      Requests with an interface or an endpoint as recipient are expected to have the interface and endpoint number, respectively, in the lower byte of wIndex. This convention is enforced by Windows. The addressed interface or the interface of the addressed endpoint must have been claimed.

      Parameters:
      transfer - control transfer setup parameters
      data - data to send, or null if the transfer has no data stage.

    • transferOut

      void transferOut(int endpointNumber, byte @NotNull [] data)
      Sends data to this device.

      This method blocks until the data has been sent or an error has occurred.

      This method can send data to bulk and interrupt endpoints.

      If the sent data length is a multiple of the packet size, it is often required to send an additional zero-length packet (ZLP) for the device to actually process the data. This method will not do it automatically.

      Parameters:
      endpointNumber - endpoint number (in the range between 1 and 127)
      data - data to send

    • transferOut

      void transferOut(int endpointNumber, byte @NotNull [] data, int timeout)
      Sends data to this device.

      This method blocks until the data has been sent, the timeout period has expired or an error has occurred. If the timeout expires, a UsbTimeoutException is thrown.

      This method can send data to bulk and interrupt endpoints.

      If the sent data length is a multiple of the packet size, it is often required to send an additional zero-length packet (ZLP) for the device to actually process the data. This method will not do it automatically.

      Parameters:
      endpointNumber - the endpoint number (in the range between 1 and 127)
      data - data to send
      timeout - the timeout period, in milliseconds (0 for no timeout)

    • transferOut

      void transferOut(int endpointNumber, byte @NotNull [] data, int offset, int length, int timeout)
      Sends data to this device.

      This method blocks until the data has been sent, the timeout period has expired or an error has occurred. If the timeout expires, a UsbTimeoutException is thrown.

      This method can send data to bulk and interrupt endpoints.

      If the sent data length is a multiple of the packet size, it is often required to send an additional zero-length packet (ZLP) for the device to actually process the data. This method will not do it automatically.

      Parameters:
      endpointNumber - the endpoint number (in the range between 1 and 127)
      data - buffer containing data to send
      offset - offset of the first byte to send
      length - number of bytes to send
      timeout - the timeout period, in milliseconds (0 for no timeout)

    • transferIn

      byte @NotNull [] transferIn(int endpointNumber)
      Receives data from this device.

      This method blocks until at least a packet has been received or an error has occurred.

      The returned data is the payload of a packet. It can have a length of 0 if the USB device sends zero-length packets to indicate the end of a data unit.

      This method can receive data from bulk and interrupt endpoints.

      Parameters:
      endpointNumber - endpoint number (in the range between 1 and 127, i.e. without the direction bit)
      Returns:
      received data

    • transferIn

      byte @NotNull [] transferIn(int endpointNumber, int timeout)
      Receives data from this device.

      This method blocks until at least a packet has been received, the timeout period has expired or an error has occurred. If the timeout expired, a UsbTimeoutException is thrown.

      The returned data is the payload of a packet. It can have a length of 0 if the USB device sends zero-length packets to indicate the end of a data unit.

      This method can receive data from bulk and interrupt endpoints.

      Parameters:
      endpointNumber - the endpoint number (in the range between 1 and 127, i.e. without the direction bit)
      timeout - the timeout period, in milliseconds (0 for no timeout)
      Returns:
      received data

    • openOutputStream

      @NotNull @NotNull OutputStream openOutputStream(int endpointNumber, int bufferSize)
      Opens a new output stream to send data to a bulk endpoint.

      All data written to this output stream is sent to the specified bulk endpoint. Buffering and concurrent IO requests are used to achieve a high throughput.

      The stream will insert zero-length packets if OutputStream.flush() is called and the last packet size was equal to maximum packet size of the endpoint.

      If transferOut(int, byte[]) and a output stream or multiple output streams are used concurrently for the same endpoint, the behavior is unpredictable.

      Parameters:
      endpointNumber - bulk endpoint number (in the range between 1 and 127)
      bufferSize - approximate buffer size (in bytes)
      Returns:
      the new output stream

    • openOutputStream

      @NotNull default @NotNull OutputStream openOutputStream(int endpointNumber)
      Opens a new output stream to send data to a bulk endpoint.

      The buffer is configured with minimal size. In all other aspects, this method works like openOutputStream(int, int).

      Parameters:
      endpointNumber - bulk endpoint number (in the range between 1 and 127)
      Returns:
      the new output stream

    • openInputStream

      @NotNull @NotNull InputStream openInputStream(int endpointNumber, int bufferSize)
      Opens a new input stream to receive data from a bulk endpoint.

      All data received from the specified bulk endpoint can be read using this input stream. Buffering and concurrent IO requests are used to achieve a high throughput.

      If the buffers contain data when the stream is closed, this data will be discarded. If transferIn(int) and an input stream or multiple input streams are used concurrently for the same endpoint, the behavior is unpredictable.

      Parameters:
      endpointNumber - bulk endpoint number (in the range between 1 and 127, i.e. without the direction bit)
      bufferSize - approximate buffer size (in bytes)
      Returns:
      the new input stream

    • openInputStream

      @NotNull default @NotNull InputStream openInputStream(int endpointNumber)
      Opens a new input stream to receive data from a bulk endpoint.

      The buffer is configured with minimal size. In all other aspects, this method works like openInputStream(int, int).

      Parameters:
      endpointNumber - bulk endpoint number (in the range between 1 and 127, i.e. without the direction bit)
      Returns:
      the new input stream

    • abortTransfers

      void abortTransfers(UsbDirection direction, int endpointNumber)
      Aborts all transfers on an endpoint.

      This operation is not valid on the control endpoint 0.

      Parameters:
      direction - endpoint direction
      endpointNumber - endpoint number (in the range between 1 and 127)

    • clearHalt

      void clearHalt(UsbDirection direction, int endpointNumber)
      Clears an endpoint's halt condition.

      An endpoint is halted (aka stalled) if an error occurs in the communication. Before the communication can resume, the halt condition must be cleared. A halt condition can exist in a single direction only.

      Control endpoint 0 will never be halted.

      Parameters:
      direction - endpoint direction
      endpointNumber - endpoint number (in the range between 1 and 127)

    • getDeviceDescriptor

      byte @NotNull [] getDeviceDescriptor()
      Gets the device descriptor.
      Returns:
      the device descriptor (as a byte array)

    • getConfigurationDescriptor

      byte @NotNull [] getConfigurationDescriptor()
      Gets the configuration descriptor.
      Returns:
      the configuration descriptor (as a byte array)