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.
This API for human interface device communication uses kernel mode drivers provided by operating system.
Applications may develop user space drivers using raw HID methods in this class.
|
1: Device discovery listHIDdevicesWithInfoR3 : Information getManufacturerStringRgetProductStringR getSerialNumberStringR getIndexedStringR findDriverServingHIDDeviceR |
2 : Data/Configuration exchange writeOutputReportRreadInputReportR readInputReportWithTimeoutR sendFeatureReportR getFeatureReportR createBlockingHIDIOContextR unblockBlockingHIDIOOperationR destroyBlockingIOContextR |
4 : Miscellaneous openHidDeviceRcloseHidDeviceR flushInputReportQueueR getReportDescriptorR getPhysicalDescriptorR formatReportToHexR |
EXP_UNBLOCK_HIDIO, HID_BLUETOOTH, HID_GENERIC, HID_I2C, HID_USB, mHIDJNIBridge, MODE_PARSED, MODE_RAW, osType| Constructor and Description |
|---|
SerialComRawHID(SerialComHIDJNIBridge mHIDJNIBridge,
int osType)
Construct and allocates a new SerialComRawHID object with given details.
|
| 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.
|
SerialComHIDTransport |
getHIDTransportInstance(int transport)
Returns an instance of class SerialComUSBHID for HID over USB operations.
|
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.
|
public SerialComRawHID(SerialComHIDJNIBridge mHIDJNIBridge, int osType)
Construct and allocates a new SerialComRawHID object with given details.
mHIDJNIBridge - interface class to native library for calling platform specific routines.osType - operating system this library is running on.SerialComException - if the object can not be constructed.public SerialComHIDdevice[] listHIDdevicesWithInfoR() throws 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.
SerialComException - if an I/O error occurs.public String formatReportToHexR(byte[] report, String separator) throws 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.
report - report to be converted into hex string.separator - separator string to be placed between two consecutive bytes (useful
when printing values on console).IllegalArgumentException - if report is null.SerialComExceptionpublic long openHidDeviceR(String pathName, boolean shared) throws 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.
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.SerialComException - if an IO error occurs.IllegalArgumentException - if pathName is null or empty string.SerialComManager.registerUSBHotPlugEventListener(ISerialComUSBHotPlugListener, int, int, String)public boolean closeHidDeviceR(long handle)
throws SerialComException
Closes a HID device.
handle - handle of the device to be closed.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.public long createBlockingHIDIOContextR()
throws 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).
SerialComException - if an I/O error occurs.public boolean unblockBlockingHIDIOOperationR(long context)
throws 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.
context - context obtained from call to createBlockingHIDIOContextR method for blocking
HID I/O operations.SerialComException - if an I/O error occurs.public boolean destroyBlockingIOContextR(long context)
throws SerialComException
Destroys the context that was created by a call to createBlockingHIDIOContextR method for blocking I/O operations uses.
context - context obtained from call to createBlockingIOContext method for blocking
HID I/O operations.SerialComException - if an I/O error occurs.public int writeOutputReportR(long handle,
byte reportId,
byte[] report)
throws 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).
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.SerialComException - if an I/O error occurs.IllegalArgumentException - if report is null or empty array.public int readInputReportR(long handle,
byte[] reportBuffer,
long context)
throws 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.
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.SerialComException - if an I/O error occurs.IllegalArgumentException - if reportBuffer is null or if length is negative.public int readInputReportWithTimeoutR(long handle,
byte[] reportBuffer,
int timeoutValue)
throws 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.
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.SerialComException - if an I/O error occurs.IllegalArgumentException - if reportBuffer is null or if length is negative.public int sendFeatureReportR(long handle,
byte reportId,
byte[] report)
throws 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.
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.SerialComException - if an I/O error occurs.IllegalArgumentException - if report is null or empty array.public int getFeatureReportR(long handle,
byte reportId,
byte[] report)
throws 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.
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.SerialComException - if an I/O error occurs.IllegalArgumentException - if reportBuffer is null or its length is zero.public String getManufacturerStringR(long handle) throws SerialComException
Gives the manufacturer of the HID device.
handle - handle of the HID device whose manufacturer is to be found.SerialComException - if an I/O error occurs.public String getProductStringR(long handle) throws SerialComException
Gives the product name of the HID device.
handle - handle of the HID device whose product name is to be found.SerialComException - if an I/O error occurs.public String getSerialNumberStringR(long handle) throws SerialComException
Gives the serial number of the HID device.
handle - handle of the HID device whose serial number is to be found.SerialComException - if an I/O error occurs.public String getIndexedStringR(long handle, int index) throws SerialComException
Gives the string at the given index of string descriptor from HID device.
Supported on Windows only as serial communication manager library does not use any user space drivers.
handle - handle of the HID device from whom indexed string is to be read.SerialComException - if an I/O error occurs.public String findDriverServingHIDDeviceR(String hidDeviceNode) throws SerialComException
Gives the name of the driver who is driving the given HID device.
hidDeviceNode - device node (port name) for HID device whose driver is to be found.SerialComException - if operation can not be completed successfully.IllegalArgumentException - if argument hidDeviceNode is null or is an empty string.public byte[] getReportDescriptorR(long handle)
throws SerialComException
Gives the report descriptor as supplied by device itself.
handle - handle of the device whose report descriptor is to be obtained.SerialComException - if operation can not be completed successfully.public byte[] getPhysicalDescriptorR(long handle)
throws 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.
handle - handle of the device whose physical descriptor is to be obtained.SerialComException - if operation can not be completed successfully.public boolean flushInputReportQueueR(long handle)
throws SerialComException
Deletes all the input reports from input report buffer maintained by operating system.
handle - handle of the device whose input report queue is to be flushed.SerialComException - if operation can not be completed successfully.public boolean registerInputReportListener(long handle,
IHIDInputReportListener listener,
byte[] inputReportBuffer)
throws SerialComException
Registers a listener which will be invoked whenever an input report is available to read.
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.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.public boolean unregisterInputReportListener(IHIDInputReportListener listener) throws SerialComException
This unregisters listener and terminates worker thread which was delivering input reports.
listener - reference to class which implemented IHIDInputReportListener interface to get input reports.SerialComException - if un-registration fails due to some reason.IllegalArgumentException - if listener is null or given listener is not registered.public SerialComHIDTransport getHIDTransportInstance(int transport) throws SerialComException
Returns an instance of class SerialComUSBHID for HID over USB operations.
transport - one of the HID_USB or HID_BLUETOOTH constants.SerialComException - if operation can not be completed successfully.public boolean readPlatformSpecificInputReportR(long handle,
byte reportId,
byte[] reportBuffer)
throws 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).
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.SerialComException - if an I/O error occurs.public boolean writePlatformSpecificOutputReportR(long handle,
byte reportId,
byte[] reportBuffer)
throws 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.
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.SerialComExceptionCopyright © 2016. All rights reserved.