Class HidApi
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 Summary
FieldsModifier and TypeFieldDescriptionprivate static final int
Device error codeprivate static final String
Error message if device is not initialisedprivate static HidApiLibrary
The HID API librarystatic boolean
Enables use of the libusb variant of the hidapi native library when running on a Linux platform.private static final int
Default length for wide string buffer -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic void
close
(HidDeviceStructure device) Close a HID devicestatic HidDeviceInfoStructure
enumerateDevices
(int vendor, int product) Enumerate the attached HID devicesstatic void
exit()
Finalise the HID API librarystatic void
Free an enumeration linked liststatic int
getFeatureReport
(HidDeviceStructure device, byte[] data, byte reportId) Get a feature report from a HID devicestatic String
getIndexedString
(HidDeviceStructure device, int idx) Get a string from a HID device, based on its string indexstatic String
static String
getManufacturer
(HidDeviceStructure device) static String
getProductId
(HidDeviceStructure device) static String
getSerialNumber
(HidDeviceStructure device) static void
init()
Initialise the HID API library.static HidDeviceStructure
Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally a serial numberstatic HidDeviceStructure
Open a HID device by its path namestatic int
read
(HidDeviceStructure device, byte[] buffer) Read an Input report from a HID devicestatic int
read
(HidDeviceStructure device, byte[] buffer, int timeoutMillis) Read an Input report from a HID device with timeoutstatic int
sendFeatureReport
(HidDeviceStructure device, byte[] data, byte reportId) Send a Feature report to the device using a simplified interfacestatic boolean
setNonBlocking
(HidDeviceStructure device, boolean nonBlocking) Set the device handle to be non-blockingstatic int
write
(HidDeviceStructure device, byte[] data, int len, byte reportId) Write an Output report to a HID device using a simplified interface
-
Field Details
-
WSTR_LEN
private static final int WSTR_LENDefault length for wide string buffer- See Also:
-
DEVICE_NULL
Error message if device is not initialised- See Also:
-
DEVICE_ERROR
private static final int DEVICE_ERRORDevice error code- See Also:
-
useLibUsbVariant
public static boolean useLibUsbVariantEnables 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
The HID API library
-
-
Constructor Details
-
HidApi
public HidApi()
-
-
Method Details
-
open
Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally a serial number
- Parameters:
vendor
- The vendor IDproduct
- The product IDserialNumber
- 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
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
Close a HID device
- Parameters:
device
- The HID device structure
-
enumerateDevices
Enumerate the attached HID devices
- Parameters:
vendor
- The vendor IDproduct
- The product ID- Returns:
- The device info of the matching device
-
freeEnumeration
Free an enumeration linked list
- Parameters:
list
- The list to free
-
getLastErrorMessage
- Parameters:
device
- The HID device structure- Returns:
- A string describing the last error which occurred
-
getManufacturer
- Parameters:
device
- The HID device- Returns:
- The device manufacturer string
-
getProductId
- Parameters:
device
- The HID device- Returns:
- The device product ID
-
getSerialNumber
- Parameters:
device
- The HID device- Returns:
- The device serial number
-
setNonBlocking
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 devicenonBlocking
- True if non-blocking mode is required- Returns:
- True if successful
-
read
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 devicebuffer
- 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
Read an Input report from a HID device with timeout
- Parameters:
device
- The HID devicebuffer
- The buffer to read intotimeoutMillis
- 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
Get a feature report from a HID device
HID API notesUnder 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 devicedata
- The buffer to contain the reportreportId
- 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
Send a Feature report to the device using a simplified interface
HID API notesUnder 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 devicedata
- 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
Write an Output report to a HID device using a simplified interface
HID API notesIn 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 17hid_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 devicedata
- 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
Get a string from a HID device, based on its string index
- Parameters:
device
- The HID deviceidx
- The index- Returns:
- The string
-