com.serialpundit.hid

Class SerialComRawHID

java.lang.Object

com.serialpundit.hid.SerialComHID

com.serialpundit.hid.SerialComRawHID

public final class SerialComRawHID
extends SerialComHID

Contains APIs to communicate with a HID class device in raw mode. The reports sent/received will not be parsed. The application must understand meaning and format of each field in report exchanged.

The application using HID protocol is advantageous when deploying the application in a corporate environment sensitive to the installation of kernel code(driver).

This API for human interface device communication uses kernel mode drivers provided by operating system by default.

Applications may develop user space drivers using raw HID methods in this class.

1: Device discovery listHIDdevicesWithInfoR 3 : Information getManufacturerStringR getProductStringR getSerialNumberStringR getIndexedStringR findDriverServingHIDDeviceR

2 : Data/Configuration exchange writeOutputReportR readInputReportR readInputReportWithTimeoutR sendFeatureReportR getFeatureReportR createBlockingHIDIOContextR unblockBlockingHIDIOOperationR destroyBlockingIOContextR

4 : Miscellaneous openHidDeviceR closeHidDeviceR flushInputReportQueueR getReportDescriptorR getPhysicalDescriptorR formatReportToHexR

Author:

Rishi Gupta

Field Summary

Fields inherited from class com.serialpundit.hid.SerialComHID

EXP_UNBLOCK_HIDIO, HID_BLUETOOTH, HID_GENERIC, HID_I2C, HID_USB, MODE_PARSED, MODE_RAW

Constructor Summary

Constructors

Constructor and Description
SerialComRawHID(String libDirectory, String loadedLibName) Construct and allocates a new SerialComRawHID object with given details and load/link native libraries if required.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	closeHidDeviceR(long handle) Closes a HID device.
long	createBlockingHIDIOContextR() Prepares a context that should be passed to readInputReportR, unblockBlockingHIDIOOperationR and destroyBlockingIOContextR methods.
boolean	destroyBlockingIOContextR(long context) Destroys the context that was created by a call to createBlockingHIDIOContextR method for blocking I/O operations uses.
String	findDriverServingHIDDeviceR(String hidDeviceNode) Gives the name of the driver who is driving the given HID device.
boolean	flushInputReportQueueR(long handle) Deletes all the input reports from input report buffer maintained by operating system.
String	formatReportToHexR(byte[] report, String separator) Converts report read from HID device to hexadecimal string.
int	getFeatureReportR(long handle, byte reportId, byte[] report) Read a feature report to the HID device.
String	getIndexedStringR(long handle, int index) Gives the string at the given index of string descriptor from HID device.
String	getManufacturerStringR(long handle) Gives the manufacturer of the HID device.
byte[]	getPhysicalDescriptorR(long handle) Gives the physical descriptor for the given HID device.
String	getProductStringR(long handle) Gives the product name of the HID device.
byte[]	getReportDescriptorR(long handle) Gives the report descriptor as supplied by device itself.
String	getSerialNumberStringR(long handle) Gives the serial number of the HID device.
SerialComHIDdevice[]	listHIDdevicesWithInfoR() Find all the device instances claiming to be HID device.
long	openHidDeviceR(String pathName, boolean shared) Opens a HID device for communication using its path name.
int	readInputReportR(long handle, byte[] reportBuffer, long context) Reads input report from the given HID device.
int	readInputReportWithTimeoutR(long handle, byte[] reportBuffer, int timeoutValue) Try to read input report from HID device within the given timeout limit.
boolean	readPlatformSpecificInputReportR(long handle, byte reportId, byte[] reportBuffer) Read input report from given HID device and handles inconsistencies in reports internally using facilities provided by operating system.
boolean	registerInputReportListener(long handle, IHIDInputReportListener listener, byte[] inputReportBuffer) Registers a listener which will be invoked whenever an input report is available to read.
int	sendFeatureReportR(long handle, byte reportId, byte[] report) Send a feature report to the HID device.
boolean	unblockBlockingHIDIOOperationR(long context) Unblocks any blocked operation if it exist.
boolean	unregisterInputReportListener(IHIDInputReportListener listener) This unregisters listener and terminates worker thread which was delivering input reports.
int	writeOutputReportR(long handle, byte reportId, byte[] report) Sends the given output report to the HID device.
boolean	writePlatformSpecificOutputReportR(long handle, byte reportId, byte[] reportBuffer) Sends an output report to given HID device and handles inconsistencies in reports internally using facilities provided by operating system.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SerialComRawHID

public SerialComRawHID(String libDirectory,
               String loadedLibName)
                throws IOException

Construct and allocates a new SerialComRawHID object with given details and load/link native libraries if required.

Parameters:

libDirectory - absolute path of directory to be used for native library extraction.

loadedLibName - library name without extension (do not append .so, .dll or .dylib etc.).

Throws:

IOException - if libDirectory does not exist, or is not a regular directory or is not writable, if native libraries are not found or can not be loaded/linked or initialized etc.

Method Detail

listHIDdevicesWithInfoR

public SerialComHIDdevice[] listHIDdevicesWithInfoR()
                                             throws com.serialpundit.core.SerialComException

Find all the device instances claiming to be HID device.

Returns an array of SerialComHIDdevice objects containing information about HID devices as found by this library. The HID devices found may be USB HID or Bluetooth HID device. Application can call various methods on returned SerialComHIDdevice object to get specific information like vendor id and product id etc.

The information about HID device returned includes, transport, vendor ID, product ID, serial number, product, manufacturer, USB bus number, USB device number, location ID etc. In situations where two or more devices with exactly same vendor ID, product ID and serial number are present into system, information like location can be used to further categories them into unique devices. Application can also use some custom protocol to identify devices that are of interest to them.

If you know that the HID device is USB device than consider using listUSBHIDdevicesWithInfo method in SerialComUSBHID class.

Returns:

list of the HID devices with information about them or empty array if no device matching given criteria found.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

formatReportToHexR

public String formatReportToHexR(byte[] report,
                        String separator)
                          throws com.serialpundit.core.SerialComException

Converts report read from HID device to hexadecimal string. This may be useful when report is to be passed to next level as hex data or report is to be feed into external HID report parser tool.

Parameters:

report - report to be converted into hex string.

separator - separator string to be placed between two consecutive bytes (useful when printing values on console).

Returns:

constructed hex string if report.length > 0 otherwise empty string.

Throws:

IllegalArgumentException - if report is null.

com.serialpundit.core.SerialComException

openHidDeviceR

public long openHidDeviceR(String pathName,
                  boolean shared)
                    throws com.serialpundit.core.SerialComException

Opens a HID device for communication using its path name. Applications should first list HID devices to get the path of the desired device using methods like listUSBHIDdevicesWithInfo etc.

Applications can register USB hot plug listener to get notified when the desired USB device is plugged into system. Once the listener is invoked indicating device is added, application can find the device node representing this USB-HID device and proceed to open it.

In Linux it may be required to add correct udev rules so as to grant permission to access to the USB-HID device. Refer this udev rule file for MCP2200 as an example : https://github.com/RishiGupta12/serial-communication-manager/blob/master/tools-and-utilities/99-scm-mcp2200-hid.rules

In Windows, a unique physical device object (PDO) is created for each Top Level Collection described by the Report Descriptor and there will be device instance for each Top Level Collection. This means same USB HID interface may have many HID device instances associated with it.

Windows supports many top level collection and some of them might be opened in shared mode while may be available for exclusive access only. Some of the HID devices may be reserved for system use only and operating system may provide a dedicated framework/driver and API for it. Some devices need to be switched from keyboard emulation mode to HID mode to make them accessible by application.

Parameters:

pathName - device node full path for Unix-like OS and device instance for Windows (as obtained by listing HID devices).

shared - set to true if the device is to be opened in shared mode otherwise false for exclusive access.

Returns:

handle of the opened HID device.

Throws:

com.serialpundit.core.SerialComException - if an IO error occurs.

IllegalArgumentException - if pathName is null or empty string.

closeHidDeviceR

public boolean closeHidDeviceR(long handle)
                        throws com.serialpundit.core.SerialComException

Closes a HID device.

Parameters:

handle - handle of the device to be closed.

Returns:

true if device's handle closed successfully.

Throws:

com.serialpundit.core.SerialComException - if fails to close the device or an IO error occurs.

IllegalStateException - if application tries to close handle when input report listener still exist.

createBlockingHIDIOContextR

public long createBlockingHIDIOContextR()
                                 throws com.serialpundit.core.SerialComException

Prepares a context that should be passed to readInputReportR, unblockBlockingHIDIOOperationR and destroyBlockingIOContextR methods.

Application must catch exception thrown by this method. When this method returns and exception with message SerialComHID.EXP_UNBLOCK_HIDIO is thrown, it indicates that the blocked read method was explicitly unblocked by another thread (possibly because it is going to close the device).

Returns:

context that should be passed to readInputReportR, unblockBlockingHIDIOOperationR and destroyBlockingIOContextR methods.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

unblockBlockingHIDIOOperationR

public boolean unblockBlockingHIDIOOperationR(long context)
                                       throws com.serialpundit.core.SerialComException

Unblocks any blocked operation if it exist. This causes closing of HID device possible gracefully and return the worker thread that called blocking read/write to return and proceed as per application design.

Parameters:

context - context obtained from call to createBlockingHIDIOContextR method for blocking HID I/O operations.

Returns:

true if blocked operation was unblocked successfully.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

destroyBlockingIOContextR

public boolean destroyBlockingIOContextR(long context)
                                  throws com.serialpundit.core.SerialComException

Destroys the context that was created by a call to createBlockingHIDIOContextR method for blocking I/O operations uses.

Parameters:

context - context obtained from call to createBlockingIOContext method for blocking HID I/O operations.

Returns:

true if the context gets destroyed successfully.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

writeOutputReportR

public int writeOutputReportR(long handle,
                     byte reportId,
                     byte[] report)
                       throws com.serialpundit.core.SerialComException

Sends the given output report to the HID device. Report ID is used to uniquely identify the report.

Output report (controls) may be a sink for application data, for example, an LED that indicates the state of a device. It can represent a command sent from application running on host to USB HID device for example to toggle a GPIO pin or vibrate the motor mounted on gamepad.

If the HID device uses numbered report, reportID should be set to report number. If the HID device does not uses numbered reports reportID must be set to -1. The report (report array) should should contain only report bytes (it should not contain report ID).

Parameters:

handle - handle of the HID device to which this report will be sent.

reportId - unique identifier for the report type or -1 if device does not use report IDs.

report - report to be sent to the HID device.

Returns:

number of bytes sent to the HID device.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

IllegalArgumentException - if report is null or empty array.

readInputReportR

public int readInputReportR(long handle,
                   byte[] reportBuffer,
                   long context)
                     throws com.serialpundit.core.SerialComException

Reads input report from the given HID device.

The size of reportBuffer passed must be large enough to hold the expected number of bytes in input report and one more extra byte if the HID device uses numbered reports. The 1st byte will be report ID if device uses numbered reports otherwise the report data will begin at the first byte.

If input report is read from device, it returns number of bytes read and places data bytes in given buffer. If the device uses numbered reports, first byte in reportBuffer array will be report number. If the device does not uses numbered reports, first byte in reportBuffer will be beginning of data itself.

HID devices with custom firmware provide valid HID report descriptor to comply with USB standards and to make sure that class driver of operating system recognizes device and serve it. However, the data carried in reports may have different meaning and interpretation than what was described in report descriptor. This is the case mainly when developing custom application HID device which can not be strictly categorized as a HID device, however, leverages HID specifications and API to communicate with the host system. Vendors provide a document describing how to interpret a particular byte in report received from device or how to construct an output report.

Parameters:

handle - handle of the HID device from whom input report is to be read.

reportBuffer - byte buffer in which input report will be saved.

context - context obtained by a call to createBlockingIOContext method.

Returns:

number of bytes read from HID device.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

IllegalArgumentException - if reportBuffer is null or if length is negative.

readInputReportWithTimeoutR

public int readInputReportWithTimeoutR(long handle,
                              byte[] reportBuffer,
                              int timeoutValue)
                                throws com.serialpundit.core.SerialComException

Try to read input report from HID device within the given timeout limit.

The size of reportBuffer passed must be large enough to hold the expected number of bytes in input report and one more extra byte if the HID device uses numbered reports. The 1st byte will be report ID if device uses numbered reports otherwise the report data will begin at the first byte.

If input report is read from HID device, it returns number of bytes read and places data bytes in given buffer. If there was no data to read it returns 0.

Input report (controls) are sources of data for application running on host processor (USB Host side) for example X and Y coordinates obtained from touch screen or state of a GPIO pin. It can also be a response to a command sent previously as output report.

Parameters:

handle - handle of the HID device from whom input report is to be read.

reportBuffer - byte buffer in which input report will be saved.

timeoutValue - time in milliseconds after which read must return with whatever data is read till that time or no data read at all.

Returns:

number of bytes read from HID device.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

IllegalArgumentException - if reportBuffer is null or if length is negative.

sendFeatureReportR

public int sendFeatureReportR(long handle,
                     byte reportId,
                     byte[] report)
                       throws com.serialpundit.core.SerialComException

Send a feature report to the HID device. If the HID device uses numbered reports, set reportID to report number. If the HID device does not uses numbered reports set reportID to -1. The report byte array should contain only report data bytes.

Typically, feature reports are sent/received for configuring USB device or USB host at application start-up, or for sending/receiving special event or state information, or for saving any data item that application wish to write in HID device and read it back may be some time later.

Parameters:

handle - handle of the HID device to which this feature report will be sent.

reportId - unique identifier for the report type or -1 if not applicable.

report - feature report to be sent to the HID device.

Returns:

number of bytes sent to HID device.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

IllegalArgumentException - if report is null or empty array.

getFeatureReportR

public int getFeatureReportR(long handle,
                    byte reportId,
                    byte[] report)
                      throws com.serialpundit.core.SerialComException

Read a feature report to the HID device. If the HID device uses numbered reports, set reportID to report number. If the HID device does not uses numbered reports set reportID to -1. If the featured report is read from HID device, data read will be placed in report byte array. This array will contain feature report (excluding report ID).

Typically, feature reports are sent/received for configuring USB device or USB host at application start-up, or for sending/receiving special event or state information, or for saving any data item that application wish to write in HID device and read it back may be some time later.

Parameters:

handle - handle of the HID device from whom feature report is to be read.

reportId - unique identifier for the report type or -1 if not applicable.

report - byte type buffer where feature report will be saved.

Returns:

number of bytes read from HID device.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

IllegalArgumentException - if reportBuffer is null or its length is zero.

getManufacturerStringR

public String getManufacturerStringR(long handle)
                              throws com.serialpundit.core.SerialComException

Gives the manufacturer of the HID device.

Parameters:

handle - handle of the HID device whose manufacturer is to be found.

Returns:

manufacturer name string.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

getProductStringR

public String getProductStringR(long handle)
                         throws com.serialpundit.core.SerialComException

Gives the product name of the HID device.

Parameters:

handle - handle of the HID device whose product name is to be found.

Returns:

product name string of the HID device.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

getSerialNumberStringR

public String getSerialNumberStringR(long handle)
                              throws com.serialpundit.core.SerialComException

Gives the serial number of the HID device.

Parameters:

handle - handle of the HID device whose serial number is to be found.

Returns:

serial number string of the HID device.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

getIndexedStringR

public String getIndexedStringR(long handle,
                       int index)
                         throws com.serialpundit.core.SerialComException

Gives the string at the given index of string descriptor from HID device.

Supported on Windows only as SerialPundit does not use any user space drivers.

Parameters:

handle - handle of the HID device from whom indexed string is to be read.

Returns:

string at given index read from the HID device.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

findDriverServingHIDDeviceR

public String findDriverServingHIDDeviceR(String hidDeviceNode)
                                   throws com.serialpundit.core.SerialComException

Gives the name of the driver who is driving the given HID device.

Parameters:

hidDeviceNode - device node (port name) for HID device whose driver is to be found.

Returns:

name of driver serving given HID device.

Throws:

com.serialpundit.core.SerialComException - if operation can not be completed successfully.

IllegalArgumentException - if argument hidDeviceNode is null or is an empty string.

getReportDescriptorR

public byte[] getReportDescriptorR(long handle)
                            throws com.serialpundit.core.SerialComException

Gives the report descriptor as supplied by device itself.

Parameters:

handle - handle of the device whose report descriptor is to be obtained.

Returns:

HID report descriptor as array of bytes otherwise empty array.

Throws:

com.serialpundit.core.SerialComException - if operation can not be completed successfully.

getPhysicalDescriptorR

public byte[] getPhysicalDescriptorR(long handle)
                              throws com.serialpundit.core.SerialComException

Gives the physical descriptor for the given HID device.

Physical Descriptors are entirely optional. They add complexity and offer very little in return for most devices. However, some devices, particularly those with a large number of identical controls (for example, buttons) will find that Physical Descriptors help different applications assign functionality to these controls in a more consistent manner.

Parameters:

handle - handle of the device whose physical descriptor is to be obtained.

Returns:

HID physical descriptor as array of bytes otherwise empty array.

Throws:

com.serialpundit.core.SerialComException - if operation can not be completed successfully.

flushInputReportQueueR

public boolean flushInputReportQueueR(long handle)
                               throws com.serialpundit.core.SerialComException

Deletes all the input reports from input report buffer maintained by operating system.

Parameters:

handle - handle of the device whose input report queue is to be flushed.

Returns:

true on success.

Throws:

com.serialpundit.core.SerialComException - if operation can not be completed successfully.

registerInputReportListener

public boolean registerInputReportListener(long handle,
                                  IHIDInputReportListener listener,
                                  byte[] inputReportBuffer)
                                    throws com.serialpundit.core.SerialComException

Registers a listener which will be invoked whenever an input report is available to read.

Parameters:

handle - of the HID device for which input reports are to be listened.

listener - instance of class which implements IHIDInputReportListener interface.

inputReportBuffer - byte buffer that will contain report read from HID device.

Returns:

true on success.

Throws:

com.serialpundit.core.SerialComException - if the registration fails due to some reason.

IllegalArgumentException - if input report listener is null.

IllegalStateException - if input report listener already exist for given handle.

unregisterInputReportListener

public boolean unregisterInputReportListener(IHIDInputReportListener listener)
                                      throws com.serialpundit.core.SerialComException

This unregisters listener and terminates worker thread which was delivering input reports.

Parameters:

listener - reference to class which implemented IHIDInputReportListener interface to get input reports.

Returns:

true on success.

Throws:

com.serialpundit.core.SerialComException - if un-registration fails due to some reason.

IllegalArgumentException - if listener is null or given listener is not registered.

readPlatformSpecificInputReportR

public boolean readPlatformSpecificInputReportR(long handle,
                                       byte reportId,
                                       byte[] reportBuffer)
                                         throws com.serialpundit.core.SerialComException

Read input report from given HID device and handles inconsistencies in reports internally using facilities provided by operating system. For example some device send/receive reports which are inconsistent with what was described in their HID report descriptor. For some devices their firmware can not be modified and this is where this method can be used.

For Windows operating system the methods readInputReportWithTimeoutR and readInputReportR uses ReadFile function, whereas readPlatformSpecificInputReportR uses HidD_GetInputReport function.

The size of reportBuffer passed must be equal to the number of bytes(fields) in input report (excluding report ID whether devices uses numbered reports or not).

Parameters:

handle - handle of the HID device from whom input report is to be read.

reportId - unique identifier for the report type or -1 if device does not use report IDs.

reportBuffer - byte buffer in which input report will be saved.

Returns:

true on success.

Throws:

com.serialpundit.core.SerialComException - if an I/O error occurs.

writePlatformSpecificOutputReportR

public boolean writePlatformSpecificOutputReportR(long handle,
                                         byte reportId,
                                         byte[] reportBuffer)
                                           throws com.serialpundit.core.SerialComException

Sends an output report to given HID device and handles inconsistencies in reports internally using facilities provided by operating system. For example some device send/receive reports which are inconsistent with what was described in their HID report descriptor. For some devices their firmware can not be modified and this is where this method can be used.

For Windows operating system the method writeOutputReportR uses WriteFile function, whereas writePlatformSpecificOutputReportR uses HidD_SetOutputReport function.

Parameters:

handle - handle of the HID device to whom this output report is to be sent.

reportId - unique identifier for the report type or -1 if device does not use report IDs.

reportBuffer - buffer containing output report to be sent to device.

Returns:

true on success.

Throws:

com.serialpundit.core.SerialComException