GIIB 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 web site (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.
2.1 Interface #0 - System Commands & Raw Input Event Reports
2.1.1 Events Data Report (IN)
Start | Length | Field Name | Values |
|---|---|---|---|
1.1 | 8 bits | Report ID | 0x01 - Events Report |
2.1 | 8 bits | Screen Number | 0x01 – Screen #1 at the time of event |
… | |||
0xFF – Screen #255 at the time of event | |||
3.1 | 8 bits | Reserved | Reserved for future use |
4.1 | 8 bits | Event ID | 0x01- Events: Standard (Relative Encoder, Taps, Swipes) |
5.1 | 8 bits | Encoder (relative) | 0x80 – No Change |
0x81 – Clockwise 1 detent | |||
0x82 – Clockwise 2 detents | |||
… | |||
0xFE – Clockwise 126 detents | |||
0x7F – Counter-Clockwise 1 detent | |||
0x7E – Counter-Clockwise 2 detents | |||
… | |||
0x01 – Counter-Clockwise 127 detents | |||
0x00 – Not used | |||
0xFF – Not used | |||
6.1 | 16 bits | Tap Mask | 0x0000 – No Tap detected |
0x0001 – Tap in Zone 1 detected | |||
0x0002 – Tap in Zone 2 detected | |||
0x0004 – Tap in Zone 3 detected | |||
… | |||
0x4000 – Tap in Zone 15 detected | |||
0x8000 – Tap on screen (anywhere) detected | |||
8.1 | 8 bits | Swipe Mask | 0x00 – No Swipe detected |
0x01 – Swipe Up detected | |||
0x02 – Swipe Down detected | |||
0x04 – Swipe Left detected | |||
0x08 – Swipe Right detected | |||
0x80 – Swipe (any direction) detected |
The Events Report is the lowest-level report generated by the Touch Encoder. Even though the Touch Encoder is designed to automatically respond to events occurring on the device, it will also generate this type of report to keep the host application informed about those events as well. In addition to the Events Data Report, the device will also send a Widgets Data (IN) Report to the host when an event causes a screen transition or a Modify Widget Data Report causes a screen transition or change to a widget value. This method of sending a Widget Report as well as the underlying Event Report is implemented in order to allow the host to closely monitor the activity of the device, and for the host to respond appropriately should a data mismatch occur.
2.1.2 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.
2.1.2.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:
2.1.2.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:
2.1.2.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:
2.1.2.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:
2.1.3 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.
2.1.4 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.
2.1.4.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 |
Note: The Contact X and Y-coordinates are in the screen coordinate space.
2.1.4.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* |
* Note: The maximum value for the encoder raw value is limited by the number of detents of the encoder hardware. Default encoder value range: 0...31.
2.1.5 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 carries the live update payload to the device in 1021-byte increments. This type of report uses the Set_Report (Output) feature via Endpoint0, which allows for a significantly faster transfer speed than via the OUT endpoint.
2.1.6 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 carries the status messages defined in our Live Update guide.
2.2 Interface #1 - Widget Data
2.2.1 Widget Data Report (IN)
Start | Length | Field Name | Values |
|---|---|---|---|
1.1 | 8 bits | Report ID | 0x03 - Widget Report |
2.1 | 8 bits | Screen Number | 0x01 – Screen #1 currently being displayed or modified |
… | |||
0xFF – Screen #255 currently being displayed or modified | |||
3.1 | 8 bits | Active Value ID Bitmask | Mask for active/configured IDs on current widget. On screen |
change all active IDs will be set. On single ID change only | |||
that ID will be set. | |||
0x00 – Not used | |||
0x01 – Value ID (Value #1 is active for this screen) | |||
0x02 – Value ID (Value #2 is active for this screen) | |||
0x03 – Value ID (Value #1 and #2 are active for this screen) | |||
… | |||
0xFF – Value ID (All 8 Values active for this widget) | |||
4.1 | 8 bits | Value ID #1 | 0x01 – Value ID #1 |
5.1 | 16 bits | Current Value #1 | Value currently being displayed for the given Value ID |
7.1 | 4 bits | Reserved | 0 |
7.5 | 4 bits | Display Code #1 | Display Code (Decimal Code) for Value ID #1 |
8.1 | 8 bits | Value ID #2 | 0x02 – Value ID #2 |
9.1 | 16 bits | Current Value #2 | Value currently being displayed for the given Value ID |
11.1 | 4 bits | Reserved | 0 |
11.5 | 4 bits | Display Code #2 | Display Code (Decimal Code) for Value ID #2 |
12.1 | 8 bits | Value ID #3 | 0x04 – Value ID #3 |
13.1 | 16 bits | Current Value #3 | Value currently being displayed for the given Value ID |
15.1 | 4 bits | Reserved | 0 |
15.5 | 4 bits | Display Code #3 | Display Code (Decimal Code) for Value ID #3 |
16.1 | 8 bits | Value ID #4 | 0x08 – Value ID #4 |
17.1 | 16 bits | Current Value #4 | Value currently being displayed for the given Value ID |
19.1 | 4 bits | Reserved | 0 |
19.5 | 4 bits | Display Code #4 | Display Code (Decimal Code) for Value ID #4 |
20.1 | 8 bits | Value ID #5 | 0x10 – Value ID #5 |
21.1 | 16 bits | Current Value #5 | Value currently being displayed for the given Value ID |
23.1 | 4 bits | Reserved | 0 |
23.5 | 4 bits | Display Code #5 | Display Code (Decimal Code) for Value ID #5 |
24.1 | 8 bits | Value ID #6 | 0x20 – Value ID #6 |
25.1 | 16 bits | Current Value #6 | Value currently being displayed for the given Value ID |
27.1 | 4 bits | Reserved | 0 |
27.5 | 4 bits | Display Code #6 | Display Code (Decimal Code) for Value ID #6 |
28.1 | 8 bits | Value ID #7 | 0x40 – Value ID #7 |
29.1 | 16 bits | Current Value #7 | Value currently being displayed for the given Value ID |
31.1 | 4 bits | Reserved | 0 |
31.5 | 4 bits | Display Code #7 | Display Code (Decimal Code) for Value ID #7 |
32.1 | 8 bits | Value ID #8 | 0x80 – Value ID #8 |
33.1 | 16 bits | Current Value #8 | Value currently being displayed for the given Value ID |
35.1 | 4 bits | Reserved | 0 |
35.5 | 4 bits | Display Code #8 | Display Code (Decimal Code) for Value ID #8 |
The Widget Data Report is sent automatically by the device to the host whenever an Event or Modify Widget Report causes a screen transition or change in one of the current widget's “Value ID” values. This type of report is used to keep the host informed about the widgets and “in-sync” with the device.
The Current Value field is constrained by the initial conditions, minimum and maximum values, and the step constraints defined during the design stage in the IDE. However, the host has the ability to overwrite or initialize the Current Value field.
The Display Code field contains a code specifying the format that is being applied to the Current Value of the widget. Please refer to section Display Code and Decimal Code.
2.2.2 Modify Widget Data Report (OUT)
Start | Length | Field Name | Values |
|---|---|---|---|
1.1 | 8 bits | Report ID | 0x04 – Modify Widget |
2.1 | 8 bits | Screen Number | 0x00 – Screen #0 to be modified |
0x01 – Screen #1 to be modified | |||
… | |||
0xFF – Screen #255 to be modified | |||
3.1 | 8 bits | Active Value ID Bitmask | Mask for Value IDs being modified with this report. |
0x00 – No modified value | |||
0x01 – Value ID #1 is being modified for this screen | |||
0x02 – Value ID #2 is being modified for this screen | |||
0x03 – Value IDs #1 and #2 are being modified for this screen | |||
… | |||
0xFF – Value ID (All 8 Values are being modified for this screen) | |||
4.1 | 1 bit | Screen Transition Suppressor | 0 – Perform screen transition |
1 – Suppress screen transition | |||
4.2 | 7 bits | Reserved | 0 |
5.1 | 8 bits | Value ID #1 | 0x01 – Value ID #1 (if being modified) |
6.1 | 16 bits | Current Value #1 | Modified Value |
8.1 | 4 bits | Reserved | 0 |
8.5 | 4 bits | Display Code #1 | Display Code (Decimal Code) for Value ID #1 (if being modified) |
9.1 | 8 bits | Value ID #2 | 0x02 – Value ID #2 (if being modified) |
10.1 | 16 bits | Current Value #2 | Modified Value |
12.1 | 4 bits | Reserved | 0 |
12.5 | 4 bits | Display Code #2 | Display Code (Decimal Code) for Value ID #2 (if being modified) |
13.1 | 8 bits | Value ID #3 | 0x04 – Value ID #3 (if being modified) |
14.1 | 16 bits | Current Value #3 | Modified Value |
16.1 | 4 bits | Reserved | 0 |
16.5 | 4 bits | Display Code #3 | Display Code (Decimal Code) for Value ID #3 (if being modified) |
17.1 | 8 bits | Value ID #4 | 0x08 – Value ID #4 (if being modified) |
18.1 | 16 bits | Current Value #4 | Modified Value |
20.1 | 4 bits | Reserved | 0 |
20.5 | 4 bits | Display Code #4 | Display Code (Decimal Code) for Value ID #4 (if being modified) |
21.1 | 8 bits | Value ID #5 | 0x10 – Value ID #5 (if being modified) |
22.1 | 16 bits | Current Value #5 | Modified Value |
24.1 | 4 bits | Reserved | 0 |
24.5 | 4 bits | Display Code #5 | Display Code (Decimal Code) for Value ID #5 (if being modified) |
25.1 | 8 bits | Value ID #6 | 0x20 – Value ID #6 (if being modified) |
26.1 | 16 bits | Current Value #6 | Modified Value |
28.1 | 4 bits | Reserved | 0 |
28.5 | 4 bits | Display Code #6 | Display Code (Decimal Code) for Value ID #6 (if being modified) |
29.1 | 8 bits | Value ID #7 | 0x40 – Value ID #7 (if being modified) |
30.1 | 16 bits | Current Value #7 | Modified Value |
32.1 | 4 bits | Reserved | 0 |
32.5 | 4 bits | Display Code #7 | Display Code (Decimal Code) for Value ID #7 (if being modified) |
33.1 | 8 bits | Value ID #8 | 0x80 – Value ID #8 (if being modified) |
34.1 | 16 bits | Current Value #8 | Modified Value |
36.1 | 4 bits | Reserved | 0 |
36.5 | 4 bits | Display Code #8 | Display Code (Decimal Code) for Value ID #8 (if being modified) |
2.2.2.1 Display Code and Decimal Code
The Display Code gives the Touch Encoder the ability to display decimal numbers. The Display Code occupies 4 upper bits of the corresponding byte. The value of this field is interpreted as a signed 4-bit integer that specifies the direction and the amount of decimal places to shift the point by. The alternative name for this field is Decimal Code. The table below describes how the decimal code works.
Decimal Code | Value | Display Value | Description |
|---|---|---|---|
0x0 | 1 | 1 | Display value directly |
0x1 | 1 | 10 | value x 10 (shift right one place) |
0x2 | 1 | 100 | value x 100 (shift right two places) |
0xE | 1 | 0.01 | value ÷ 100 (shift left two places) |
0xF | 1 | 0.1 | value ÷ 10 (shift left one place) |
2.2.2.2 Screen Transition Suppression
The Screen Transition Suppressor (STS) enables the Touch Encoder to modify variable data of the target screen without first transitioning to that screen. If the corresponding bit is set, the Touch Encoder will not perform a screen transition prior to applying a data change. This feature is only available for Firmware version 3.1.0 or higher.
2.2.2.3 Update Widget Data Examples
Example 1
The figure below displays an example of updating the gauge widget data.
The ring gauge object is designated as Value ID #1 and set as screen 7.
Example 2
The figure below displays an example of updating the ring gauge widget data to 5 and -5.
Radio Ring Gauge 1 | Radio Ring Gauge 2 |
|---|---|
<img src="ring_gauge_radio_1.jpg" width="320" height="320"/img> | <img src="ring_gauge_radio_2.jpg" width="320" height="320"/img> |
The ring gauge object is designated as Value ID #1 and set as screen 9.
Example 3
The figure below displays an example of updating lighted Icons.
The ring gauge object is designated as Value ID #1 and set as screen 6.
Example 4
The figure below displays an example of a multi-value widget.
The dynamic text object is designated at Value ID #1. The lighted icon object is designated as Value ID #3.
Below is the sequence of messages to turn on the top lighted icon and change the dynamic text to 100 (note that the lighted icon object has an offset of 0x8000).
3. Mouse HID
The Mouse HID interface of the Touch Encoder is designed to interface directly with the mouse driver of the host OS. The interface generates USB reports that contain relative motion, as well as left, and right mouse button click data.
The firmware on the Touch Encoder is responsible for processing the hardware button data and the touch data reported by the touch controller, and converting this data into the mouse data format. This processing includes converting individual touch points (as reported by the touch controller) to relative mouse motion data, smoothing the motion data to reduce noise while keeping the processing latency as low as possible, and calculating the duration of individual touches to determine if a tap or other single-touch gesture occurred.
The supported single-touch gestures are as follows:
Tap – touch did not move significantly and was shorter than approximately 360 milliseconds in duration
Drag Enable – touch did not move significantly and was longer than 1 second in but shorter than 2 seconds in duration
Right-Click – touch did not move significantly and was longer than 2 seconds in duration
The “Tap” gesture is realized by sending a single report with the left-click button active, which also allows the use of a double-tap to generate a double-click.
If the “Drag Enable” gesture mentioned above is followed by (significant) relative motion of the touch on the touch pad surface, then the firmware will send persistent left-click reports for as long as the touch is active on the pad. This allows for items to be “pinned” by performing the gesture and then moving them across the screen. The dragging stops when the touch is lifted off the screen.
The “Right-Click” gesture mentioned above causes the device to send a single report with the right-click button active. This results in a right-click menu being opened. The user can then use simple touch motion to move the mouse cursor to the desired menu selection.
3.1 Mouse HID Interface
3.1.1 Mouse Report (IN)
Start | Length | Field Name | Values |
|---|---|---|---|
1.1 | 8 bits | Report ID | 0x06 – Mouse |
2.1 | 2 bits | Mouse Button Mask | 0x00 – No Button is being pressed |
0x01 – Left button is being pressed* | |||
0x02 – Right button is being pressed* | |||
2.3 | 6 bits | Reserved | 0 |
3.1 | 16 bits | X Relative Position | -32768...+32767 |
5.1 | 16 bits | Y Relative Position | -32768...+32767 |
7.1 | 8 bits | Relative Wheel Data | -128...+127 |
8.1 | 8 bits | Reserved | 0 |
* The button bits reflect the output of the single-touch gesture recognition mentioned above.
While touches are being sensed on the touch surface, this report is generated at a rate of approximately 60 Hz.