Module net.codecrete.usb
Package net.codecrete.usb

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

    • productId

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

    • vendorId

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

    • product

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

    • manufacturer

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

    • serialNumber

      String serialNumber()
      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

    • classCode

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

    • subclassCode

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

    • protocolCode

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

    • usbVersion

      Version usbVersion()
      USB protocol version supported by this device.
      Returns:
      version

    • deviceVersion

      Version deviceVersion()
      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.

    • open

      void open()
      Opens the device for communication.

    • isOpen

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

    • close

      void close()
      Closes the device.

    • interfaces

      List<USBInterface> interfaces()
      Gets the interfaces of this device.
      Returns:
      a list of USB interfaces

    • getInterface

      USBInterface getInterface(int interfaceNumber)
      Gets the interface with the specified number.
      Parameters:
      interfaceNumber - the interface number
      Returns:
      the interface, or null if no interface with the given number exists

    • getEndpoint

      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, or null if no endpoint with the given direction and number exists

    • 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[] controlTransferIn(USBControlTransfer setup, 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:
      setup - control transfer setup parameters
      length - maximum length of expected data
      Returns:
      received data.

    • controlTransferOut

      void controlTransferOut(USBControlTransfer setup, 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:
      setup - control transfer setup parameters
      data - data to send, or null if the transfer has no data stage.

    • transferOut

      void transferOut(int endpointNumber, byte[] 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[] 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)

    • transferIn

      byte[] 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[] 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

      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

      default 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

      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

      default 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)

    • configurationDescriptor

      byte[] configurationDescriptor()
      Gets the configuration descriptor.
      Returns:
      the configuration descriptor (as a byte array)