HID USB
1. Overview
This document describes the functionality and communication of the Grayhill Touch Encoder using the USB HID protocol.
The USB interface of the Touch Encoder is designed to conform to the USB HID 1.11 specification. This protocol allows system integrators to retrieve the data from, or send data to, the device using the ubiquitous USB HID support in the host OS. For more information about the USB standard or the USB HID support in your specific host OS, please visit the USB website (usb.org) or contact the OS vendor.
The Touch Encoder connects to the host as a composite USB device with two Generic HID interfaces. The HID interfaces consist of several top-level collections (TLC) to virtually separate different device functions. Each report type generated by either the host (OUT) or the device (IN) will have a unique report ID to denote which interface and TLC it is associated with.
The Generic HID interfaces are primarily used to send data to the host application. However, they also allow the host application to make changes to the configuration of the device, including screen/widget settings.
In order to identify the Touch Encoder within the OS, use the following USB Vendor ID (VID), Product ID (PID) combination:
VID | 0x1658 | Grayhill, Inc. |
PID | 0x0060 | Touch Encoder, 2nd generation Touch Encoder |
2. Generic HID Interfaces
The Touch Encoder’s Generic HID Interfaces are designed to interface with the generic HID support in the host OS. This means that the host OS does not consume the data itself, but that the data needs to be retrieved or transmitted by an application or a driver running on the host device. The host/device also has the ability to send Get_Report/Set_Report requests through endpoint 0.
When new information is available from the device, a new report of the appropriate type is generated. Each report type can be generated by the device at a maximum rate of approximately 60 Hz, although it is possible that the device generates mixed-type reports at a faster rate.
The different types of USB reports for these interfaces are explained below.
3 Interface #0 - System Commands & Raw Input Event Reports
3.1 Command Report (OUT)
Start | Length | Field Name | Values |
|---|---|---|---|
1.1 | 1 Byte | Report ID | 0x02 - Command Report |
2.1 | 1 Byte | Command ID | As described in the following sections |
3.1 | 7 Bytes | Command Data | As described in the following sections |
The Command Report is the lowest-level control available to the USB host controller. It allows modification of system-level attributes, such as the display’s backlight level.
The Command Report is 9 bytes long, with the first byte being the Report ID, the second byte being the Command ID, and the remaining 7 bytes being reserved for any Command-specific data.
3.1.1 Backlight Control
The backlight control command report uses a Command ID of 0x80 (128) and the second command-specific data byte as the new percentage of backlight brightness. The permitted range for the new percentage (data byte 2) is from 0x00 (0%) to 0x64 (100%).
As an example, the report to change the backlight to 100% would look like:
Similarly, the report to change the backlight to 30% would look like:
An Acknowledgment Report will be sent on a successful backlight change.
3.1.2 Reboot Device
The reboot device command report uses a Command ID of 0x44 (68).
As an example, the report to reboot the TE device would look like:
3.1.3 Raw Input Event Report Enable/Disable
The command for enabling/disabling Raw Input Event (RIE) Reports uses a Command ID of 0x08 (8), and the second command-specific data byte indicates whether the RIE Reports should be enabled (1) or disabled (0). For more information on RIE Reports, refer to Raw Input Event Reports.
As an example, the report to enable RIE Reports would look like:
3.1.4 Live Update Request
The live update request command report uses a Command ID of 0x55 (85), and the second command-specific data byte is the Component Type (0 - package, 3 - project). The third through fifth bytes specify the size of the component being updated (little-endian format).
As an example, a request to update a project component with a size of 2212495 (0x21C28F) bytes would look like:
3.2 Acknowledge Report (IN)
Start | Length | Field Name | Values |
|---|---|---|---|
1.1 | 1 Byte | Report ID | 0x05 - Acknowledge Report |
2.1 | 1 Byte | Configuration and Control Command | Command ID |
3.1 | 1 Byte | Acknowledge Code | 1 - Success |
0 - Unknown | |||
-1 - Generic Error | |||
-2...-128 - Reserved | |||
4.1 | 8 Bytes | Configuration and Control Data | Command-specific data |
The Acknowledge Report is used by the device to respond to a Command Report. The Acknowledge Report is 11 bytes long, with the first byte being the Report ID, the second byte being the Command ID, and the third byte being the signed Acknowledge Code. The remaining 8 bytes are reserved for any command-specific data.
3.3 Raw Input Event Reports
The Touch Encoder can optionally be set to send out "raw input event" (RIE) reports whenever a new input event is available and is being processed by the Touch Encoder. Input events are generated when any of the TE's user input devices show a change in their state. Each input device (encoder, touch sensor) generates a different type of RIE report. The following sections describe the different RIE report types being generated when RIE reports are enabled.
3.3.1 Touch RIE Report
Start | Length | Field Name | Values |
|---|---|---|---|
1.1 | 1 Byte | Report ID | 0x0A - Touch RIE Report |
2.1 | 1 Bit | Tip Switch | 0-touch not detected |
1-touch detected | |||
2.2 | 3 Bits | Contact ID | Contact ID |
2.5 | 3 Bits | Contact Count | Contact Count |
2.8 | 1 Bits | Reserved | 0 |
3.1 | 2 Bytes | Contact X-coordinate | 16-bit signed integer data |
5.1 | 2 Bytes | Contact Y-coordinate | 16-bit signed integer data |
7.1 | 2 Bytes | Contact Time Stamp | 0x0000...0xFFFF |
3.3.2 Encoder RIE Report
Start | Length | Field Name | Values |
|---|---|---|---|
1.1 | 1 Byte | Report ID | 0x0B - Encoder RIE Report |
2.1 | 2 Bytes | Encoder Raw Value | 0x0000...0xFFFF |
3.4 Live Update Data Report
Start | Length | Field Name | Values |
|---|---|---|---|
1.1 | 1 Byte | Report ID | 0x08 - Live Update Data |
2.1 | 2 Bytes | Report Payload Size | 0x01...0x03FD |
4.1 | 1021 Bytes | Report Payload |
The Live Update Data Report uses a Report ID of 0x08. Its size is fixed at 1024 bytes. In order to be reassembled properly at the receiving end, the OUT endpoint should be bypassed and, instead, the full 1024-byte report should be sent via the control endpoint EP0 using the Set_Report (Output) request. This also allows for a significantly faster transfer speeds than using the OUT endpoint.
Following the Report ID, two bytes are reserved to specify the number of payload bytes in the update report. The remaining bytes of the report are to be used for the actual payload. The maximum number of payload bytes per report is 1021.
3.5 Live Update Status Report
Start | Length | Field Name | Values |
|---|---|---|---|
1.1 | 1 Byte | Report ID | 0x09 - Live Update Status |
2.1 | 1 Byte | Status Message Type | 0x00...0xFF |
3.1 | 6 Bytes | Status-specific data |
The Live Update Status Report uses a Report ID of 0x09. Its size is fixed at 8 bytes (including the Report ID) and carries as payload the status messages defined in our Live Update guide.
4. Interface #1 - GUIDE
The second interface is reserved for communication specific to the user interface (GUIDE). The following sections describe the different reports that are available in GUIDE.
Each UI screen of a given GUIDE project has a screen ID associated with it. Each screen contains a set of variables, each with an ID associated with it, that influence the appearance and behavior of UI elements. As presented in the upcoming sections, these IDs are used to identify a particular screen or a variable.
Each screen also contains a tree of visual elements that make up the user interface and receive various types of events. Event occurence at a particular element results in an event notification report. In the same fashion as screens and variables, visual elements are also identified by their IDs.
The host can interface with GUIDE by directing the device to transition to different screens, mutate the variables, and by listening to incoming reports informing the host of the occurring state changes and events. The reports along with the associated transfer methods outlined in the next sections provision the host to perform these actions.
The input and output reports are sent using interrupt transfers. Where appropriate, it is also specified if they can be sent using control transfers.
4.1 Screen Report
Screen Input Report
Informs the host of the new active screen. The report can also be obtained with a Get_Report (Input) request, in which case it contains the ID of the currently active screen.
Start | Length | Field Name | Values |
|---|---|---|---|
1.1 | 1 Byte | Report ID | 0x01 - Screen |
2.1 | 1 Byte | Screen ID (current) | 0x01...0xFF |
Screen Output Report
Allows the host to change the active screen. The well-formed report, if processed successfully, is always followed by the Input Report, even if no screen transition took place (requested screen ID equals active screen ID). In case an error occurred when processing the report (report ill-formed, invalid screen ID, etc.), the Error Notification Report is sent instead. The report can also be issued via the Set_Report (Output) request.
Start | Length | Values | |
|---|---|---|---|
1.1 | 1 Byte | Report ID | 0x01 - Screen |
2.1 | 1 Byte | Screen ID (requested) | 0x01...0xFF |
4.2 Variable Report
Allows the host to modify or to obtain the value of a variable of any type.
Variable Output Report
This report serves two purposes: to select a variable to obtain the value of and (optionally) to modify a variable. The report can also be issued via the Set_Report (Output) request.
Start | Length | Field Name | Values |
|---|---|---|---|
1.1 | 1 Byte | Report ID | 0x02 - Variable |
2.1 | 1 Byte | Screen ID | 0x00...0xFF |
3.1 | 1 Byte | Variable ID | 0x00...0xFF |
4.1 | 2 Bytes | Value Size | 0...1024 |
6.1 | 1-? Bytes | Value (mandatory if Value Size > 0) | Value data* |
In order to mutate a variable, the host must issue the report with Value present and set to the desired value and Value Size equal the size of the value in terms of bytes. The content of Value must be suitable for the type of the specified variable. The report, if processed successfully, is followed by the appropriate Variable Notification Report (integer or string), even if the variable value did not change. In case an error occurred when processing the report (report ill-formed, invalid screen or variable ID, etc.), the Error Notification Report follows instead.
Example 1: The following report modifies variable #1 on screen #2 and changes its value to 0x1337.
Example 2: The following report modifies variable #3 on screen #1 and changes its value to "1337". Please note the value includes the terminating character.
Variable Input Report
Provides the host with the value of the requested variable. This report is only available via the Get_Report (Input) request. Please refer to the example in this section for proper usage.
Start | Length | Field Name | Values |
|---|---|---|---|
1.1 | 1 Byte | Report ID | 0x02 - Variable |
2.1 | 1 Byte | Screen ID | 0x00...0xFF |
3.1 | 1 Byte | Variable ID | 0x00...0xFF |
4.1 | 2 Bytes | Value Size | 1...1024 |
6.1 | 1-? Bytes | Value | Value data* |
The process of retrieving the value of a variable is composed of 2 steps. The host must first issue the Output Report as outlined above in order to select a particular variable for retrieval. Note that in this case the host should set Value Size to 0 and omit Value. Once completed, the host can issue the Get_Report (Input) request and expect the input report outlined above containing the value.
Example: Suppose on screen #1 there is a variable #2 that holds the string value "abc". We first issue Output Report of the following form to select variable #2 on screen #1:
Next, we follow with the Get_Report (Input) request specifying report ID of 2. The request yields the following input report:
4.3 Integer Variable Notification Report
Integer Variable Input Report
Informs the host that the value of the specified integer variable has changed.
Start | Length | Field Name | Values |
|---|---|---|---|
1.1 | 1 Byte | Report ID | 0x03 - Integer variable |
2.1 | 1 Byte | Screen ID | 0x00...0xFF |
3.1 | 1 Byte | Variable ID | 0x00...0xFF |
4.1 | 4 Bytes | Value (new) | 32-bit signed integer data |
4.4 String Variable Notification Report
String Variable Input Report
Informs the host that the value of the specified string variable has changed.
Start | Length | Field Name | Values |
|---|---|---|---|
1.1 | 1 Byte | Report ID | 0x04 - String variable |
2.1 | 1 Byte | Screen ID | 0x00...0xFF |
3.1 | 1 Byte | Variable ID | 0x00...0xFF |
4.1 | 61 Bytes | Value (new) | UTF-8 character sequence |
4.5 Knob Event Notification Report
Knob Event Input Report
Start | Length | Field Name | Values |
|---|---|---|---|
1.1 | 1 Byte | Report ID | 0x10 - Knob Event |
2.1 | 1 Byte | Element ID | 0x00...0xFF |
3.1 | 1 Byte | Reserved | 0 |
4.1 | 2 Bytes | Relative Value | 16-bit signed integer data |
4.6 Touch Event Notification Report
Touch Event Input Report
Start | Length | Field Name | Values |
|---|---|---|---|
1.1 | 1 Byte | Report ID | 0x11 - Touch Event |
2.1 | 1 Byte | Element ID | 0x00...0xFF |
3.1 | 3 Bits | Type | 0 - Down |
1 - Move | |||
2 - Up | |||
3 - Enter | |||
4 - Leave | |||
3.4 | 5 Bits | Reserved | 0 |
4.1 | 2 Bytes | X | 16-bit signed integer data |
6.1 | 2 Bytes | Y | 16-bit signed integer data |
4.7 Gesture Event Notification Report
Gesture Event Input Report
Start | Length | Field Name | Values |
|---|---|---|---|
1.1 | 1 Byte | Report ID | 0x12 - Gesture Event |
2.1 | 1 Byte | Element ID | 0x00...0xFF |
3.1 | 1 Bit | Type | 0 - Tap |
1 - Axis-aligned swipe | |||
3.2 | 7 Bits | Reserved | 0 |
4.1 | 4 Bytes | Gesture Data | See below |
Gesture Data varies depending on the value of Type. It is defined as follows:
Tap:
Start
Length
Field Name
Values
4.1
2 Bytes
X
16-bit signed integer data
6.1
2 Bytes
Y
16-bit signed integer data
Axis-Aligned Swipe:
Start
Length
Field Name
Values
4.1
2 Bits
Direction
0 - Up
1 - Down
2 - Left
3 - Right
4.3
6 Bits
Reserved
0
5.1
3 Bytes
Reserved
0
4.8 Scene Event Notification Report
Scene Event Input Report
Start | Length | Field Name | Values |
|---|---|---|---|
1.1 | 1 Byte | Report ID | 0x13 - Scene Event |
2.1 | 1 Byte | Element ID | 0x00...0xFF |
3.1 | 1 Bit | Type | 0 - Input focus change |
1 - Visibility change | |||
3.2 | 7 Bits | Reserved | 0 |
4.1 | 4 Bytes | Data | See below |
Data varies depending on the value of Type. It is defined as follows:
Input Focus Change:
Start
Length
Field Name
Values
4.1
1 Bit
Value
0 - Focus gained
1 - Focus lost
4.2
7 Bits
Reserved
0
5.1
3 Bytes
Reserved
0
Visibility Change:
Start
Length
Field Name
Values
4.1
1 Bit
Value
0 - Hidden
1 - Shown
4.2
7 Bits
Reserved
0
5.1
3 Bytes
Reserved
0
4.9 Error Notification Report
This report is sent in response to a failed attempt to set the active screen or to modify a variable, or when attempting to perform an unsupported request with a known report ID.
Error Notification Input Report
Start | Length | Field Name | Values |
|---|---|---|---|
1.1 | 1 Byte | Report ID | 0x20 - Error |
2.1 | 1 Byte | Failed Report ID | 0x01 - Screen Report Failed |
0x02 - Variable Report Failed |