Introduction
Stream Deck devices communicate with the host via the Human Interface Device (HID) protocol—a standardized USB communication method used by peripherals like mice, keyboards, and game controllers.
Concepts of HID Communication
The host periodically polls the device during operation. When the device has data to send, it assembles a report and returns it in response to the poll.
Each report is defined by a descriptor, which specifies the structure and layout of its data. By parsing this HID descriptor, the host can understand the report format and determine what actions or functionalities the device supports.
Reports themselves are the actual data exchanges between host and device. They are categorized as follows:
- Input Reports: Device to Host
- Output reports: Host to Device
- feature reports: Bidirectional
To communicate effectively with a Stream Deck device, the following information is required:
- Vendor ID
- Product ID
- Report Format (byte layout: input/output)
Understanding what each byte represents is critical. This is where the HID API comes into play.
Workflow Steps
The interaction process can be broken down as follows:
- Detect Device
- Open Device
- Initialize and Configure
- Read input reports / Send output reports
- Close device
Report ID
Every HID report—whether input, output, or feature—begins with a Report ID. This ID allows the host and device to agree on the report's format and the type of information being exchanged.
- Report ID: A single byte indicating the type or purpose of the message
- Payload: The remaining bytes, whose structure depends on the Report ID
At a low level, the report is simply a byte array:
[Report ID, data1, data2, ...] = [Report ID, Payload...]
Note: If a device supports multiple report formats, each begins with a Report ID byte. However, some devices use only a single Report ID.
| Direction | Type of report | Who sends it | Example |
|---|---|---|---|
| Stream Deck → Host | Input Report | Stream Deck | Key press, etc |
| Host → Stream Deck | Output Report | Host | Setting up an icon, etc |
| Host ↔︎ Stream Deck | Feature Report | Optional | Changing brightness, Get firmware version, etc |