Class HidApi


  • public class HidApi
    extends java.lang.Object

    JNA utility class to provide the following to low level operations:

    • Direct access to the HID API library through JNA
    Since:
    0.0.1  
    • Field Detail

      • WSTR_LEN

        private static final int WSTR_LEN
        Default length for wide string buffer
        See Also:
        Constant Field Values
      • DEVICE_NULL

        private static final java.lang.String DEVICE_NULL
        Error message if device is not initialised
        See Also:
        Constant Field Values
      • useLibUsbVariant

        public static boolean useLibUsbVariant

        Enables use of the libusb variant of the hidapi native library when running on a Linux platform.

        The default is hidraw which enables Bluetooth devices but requires udev rules.

      • hidApiLibrary

        private static HidApiLibrary hidApiLibrary
        The HID API library
    • Constructor Detail

      • HidApi

        public HidApi()
    • Method Detail

      • open

        public static HidDeviceStructure open​(int vendor,
                                              int product,
                                              java.lang.String serialNumber)

        Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally a serial number

        Parameters:
        vendor - The vendor ID
        product - The product ID
        serialNumber - The serial number
        Returns:
        The device or null if not found
      • init

        public static void init()

        Initialise the HID API library. Should always be called before using any other API calls.

      • exit

        public static void exit()

        Finalise the HID API library

      • open

        public static HidDeviceStructure open​(java.lang.String path)

        Open a HID device by its path name

        Parameters:
        path - The device path (e.g. "0003:0002:00")
        Returns:
        The device or null if not found
      • close

        public static void close​(HidDeviceStructure device)

        Close a HID device

        Parameters:
        device - The HID device structure
      • enumerateDevices

        public static HidDeviceInfoStructure enumerateDevices​(int vendor,
                                                              int product)

        Enumerate the attached HID devices

        Parameters:
        vendor - The vendor ID
        product - The product ID
        Returns:
        The device info of the matching device
      • freeEnumeration

        public static void freeEnumeration​(HidDeviceInfoStructure list)

        Free an enumeration linked list

        Parameters:
        list - The list to free
      • getLastErrorMessage

        public static java.lang.String getLastErrorMessage​(HidDeviceStructure device)
        Parameters:
        device - The HID device structure
        Returns:
        A string describing the last error which occurred
      • getManufacturer

        public static java.lang.String getManufacturer​(HidDeviceStructure device)
        Parameters:
        device - The HID device
        Returns:
        The device manufacturer string
      • getProductId

        public static java.lang.String getProductId​(HidDeviceStructure device)
        Parameters:
        device - The HID device
        Returns:
        The device product ID
      • getSerialNumber

        public static java.lang.String getSerialNumber​(HidDeviceStructure device)
        Parameters:
        device - The HID device
        Returns:
        The device serial number
      • setNonBlocking

        public static boolean setNonBlocking​(HidDeviceStructure device,
                                             boolean nonBlocking)

        Set the device handle to be non-blocking

        In non-blocking mode calls to hid_read() will return immediately with a value of 0 if there is no data to be read. In blocking mode, hid_read() will wait (block) until there is data to read before returning

        Non-blocking can be turned on and off at any time

        Parameters:
        device - The HID device
        nonBlocking - True if non-blocking mode is required
        Returns:
        True if successful
      • read

        public static int read​(HidDeviceStructure device,
                               byte[] buffer)

        Read an Input report from a HID device

        Input reports are returned to the host through the INTERRUPT IN endpoint. The first byte will contain the Report ID if the device uses numbered reports.

        Parameters:
        device - The HID device
        buffer - The buffer to read into (allow an extra byte if device supports multiple report IDs)
        Returns:
        The actual number of bytes read and -1 on error. If no packet was available to be read and the handle is in non-blocking mode, this function returns 0.
      • read

        public static int read​(HidDeviceStructure device,
                               byte[] buffer,
                               int timeoutMillis)

        Read an Input report from a HID device with timeout

        Parameters:
        device - The HID device
        buffer - The buffer to read into
        timeoutMillis - The number of milliseconds to wait before giving up
        Returns:
        The actual number of bytes read and -1 on error. If no packet was available to be read within the timeout period returns 0.
      • getFeatureReport

        public static int getFeatureReport​(HidDeviceStructure device,
                                           byte[] data,
                                           byte reportId)

        Get a feature report from a HID device

        HID API notes

        Under the covers the HID library will set the first byte of data[] to the Report ID of the report to be read. Upon return, the first byte will still contain the Report ID, and the report data will start in data[1]

        This method handles all the wide string and array manipulation for you

        Parameters:
        device - The HID device
        data - The buffer to contain the report
        reportId - The report ID (or (byte) 0x00)
        Returns:
        The number of bytes read plus one for the report ID (which has been removed from the first byte), or -1 on error.
      • sendFeatureReport

        public static int sendFeatureReport​(HidDeviceStructure device,
                                            byte[] data,
                                            byte reportId)

        Send a Feature report to the device using a simplified interface

        HID API notes

        Under the covers, feature reports are sent over the Control endpoint as a Set_Report transfer. The first byte of data[] must contain the Report ID. For devices which only support a single report, this must be set to 0x0. The remaining bytes contain the report data

        Since the Report ID is mandatory, calls to hid_send_feature_report() will always contain one more byte than the report contains.

        For example, if a hid report is 16 bytes long, 17 bytes must be passed to hid_send_feature_report(): the Report ID (or 0x00, for devices which do not use numbered reports), followed by the report data (16 bytes). In this example, the bytes written would be 17.

        This method handles all the array manipulation for you

        Parameters:
        device - The HID device
        data - The feature report data (will be widened and have the report ID pre-pended)
        reportId - The report ID (or (byte) 0x00)
        Returns:
        This function returns the actual number of bytes written and -1 on error.
      • write

        public static int write​(HidDeviceStructure device,
                                byte[] data,
                                int len,
                                byte reportId)

        Write an Output report to a HID device using a simplified interface

        HID API notes

        In USB HID the first byte of the data packet must contain the Report ID. For devices which only support a single report, this must be set to 0x00. The remaining bytes contain the report data. Since the Report ID is mandatory, calls to hid_write() will always contain one more byte than the report contains.

        For example, if a hid report is 16 bytes long, 17 bytes must be passed to hid_write(), the Report ID (or 0x00, for devices with a single report), followed by the report data (16 bytes). In this example, the length passed in would be 17

        hid_write() will send the data on the first OUT endpoint, if one exists. If it does not, it will send the data through the Control Endpoint (Endpoint 0)

        Parameters:
        device - The device
        data - The report data to write (should not include the Report ID)
        len - The length of the report data (should not include the Report ID)
        reportId - The report ID (or (byte) 0x00)
        Returns:
        The number of bytes written, or -1 if an error occurs
      • getIndexedString

        public static java.lang.String getIndexedString​(HidDeviceStructure device,
                                                        int idx)

        Get a string from a HID device, based on its string index

        Parameters:
        device - The HID device
        idx - The index
        Returns:
        The string