Main Protocol: General Reference
This page documents all concepts, data formats, report structures, and commands that are common to all Stream Deck devices in the Expanded family. Device-specific pages reference this document and only describe what is unique to that device.
Data Format
Basic Data Types
array
The sequence of typed elements:
- typename[number-of-elements] for the array of number-of-elements of typename elements
- typename[] for the variable length array of typename elements
CHAR, INT8
Signed 8-bit integer, ASCII
BYTE, UINT8
Unsigned 8-bit integer
INT16
Little-endian signed 16-bit integer
UINT16
Little-endian unsigned 16-bit integer
INT32
Little-endian signed 32-bit integer
UINT32
Little-endian unsigned 32-bit integer
RGB Triplet
The RGB color definition triplet
| Offset | Type | Note |
|---|---|---|
| + 0x00 | UINT8 | Red color component |
| + 0x01 | UINT8 | Green color component |
| + 0x02 | UINT8 | Blue color component |
Report Structures
Input Report
Input reports are used to transmit events from the device to the host (e.g. key state changes, encoder activity, touchscreen interaction). To obtain input reports, the host polls the device with a non-blocking HID READ command. The device forms the structure below with a maximum size of 512 bytes.
If it is important to know whether no new event is pending, a TIMEOUT error is informative.
| Offset | Type | Note |
|---|---|---|
| + 0x00 | UINT8 | Report ID |
| + 0x01 | UINT8 | Command |
| + 0x02 | UINT16 | Payload data length |
| + 0x04 | BYTE[] | Payload |
Output Report
Output reports are used to transmit bulk data from the host to the device (e.g. images, firmware). To send an output report, the host uses HID WRITE. The report has a maximum size of 1024 bytes. The host should pad the remaining part of the report with zeroes up to 1024 bytes.
| Offset | Type | Note |
|---|---|---|
| + 0x00 | UINT8 | Report ID |
| + 0x01 | UINT8 | Command |
| + 0x02 | BYTE[] | Payload |
Feature Report
Feature reports are used to set and retrieve arbitrary information from the device, or to trigger commands. To send a feature report, the host uses HID SEND FEATURE REPORT. To request and read a feature report, the host uses HID GET FEATURE REPORT. The report has a maximum size of 32 bytes. The host should pad the remaining part of the report with zeroes up to 32 bytes.
When the Command is not given in a Feature Report description, the value is ignored.
| Offset | Type | Note |
|---|---|---|
| + 0x00 | UINT8 | Report ID |
| + 0x01 | UINT8 | Command |
| + 0x02 | BYTE[] | Payload |
Command Descriptions
Input Reports
The Report ID of input reports is 0x01. The host obtains these reports by polling the device with HID READ. When no event is pending, HID READ returns TIMEOUT and the payload is undefined.
Key / Button Press State Change
An event is generated on every change of key or button state. The payload contains one byte per input, indicating the state of the corresponding key or button.
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Input Report | Report ID: 0x01, Command: 0x00, Payload data length: number of keys / buttons |
| + 0x04 | UINT8[] | Each byte has value 0x00 when depressed, or 0x01 when pressed |
Setter Feature Reports
The Report ID of setter feature reports is 0x03.
Show Logo
Forcibly triggers the display of the boot logo.
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Feature Report | Report ID: 0x03, Command: 0x02 |
Fill LCD with Color
Fills the entire LCD with a given RGB color.
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Feature Report | Report ID: 0x03, Command: 0x05 |
| + 0x02 | RGB Triplet | Color |
Fill Key / Button with Color
Fills a single key or button with a given RGB color.
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Feature Report | Report ID: 0x03, Command: 0x06 |
| + 0x02 | UINT8 | Key / Button Index |
| + 0x03 | RGB Triplet | Color |
Set Backlight Brightness
Sets the LCD backlight brightness level.
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Feature Report | Report ID: 0x03, Command: 0x08 |
| + 0x02 | UINT8 | Brightness value from 0x00 to 0x64 |
Set Sleep Mode Duration
Sets the duration of idle time in seconds before the device enters Sleep Mode.
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Feature Report | Report ID: 0x03, Command: 0x0D |
| + 0x02 | INT32 | Duration in seconds (set 0 to disable) |
Getter Feature Reports
The device uses dedicated Report IDs for getter feature reports.
Get Firmware Version
Requests the firmware version string of the device.
Request:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Feature Report | Report ID: see below |
Response:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | UINT8 | Report ID: see below |
| + 0x01 | UINT8 | Data Length: 0x0C |
| + 0x02 | UINT32 | Checksum |
| + 0x06 | UINT8[8] | Version String ASCII |
Report IDs by firmware type:
| Report ID | Name | Note |
|---|---|---|
| 0x04 | LD | |
| 0x05 | AP2 | Primary firmware |
| 0x07 | AP1 |
Get Unit Serial Number
Requests the unit's serial number string.
Request:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Feature Report | Report ID: 0x06 |
Response:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | UINT8 | Report ID: 0x06 |
| + 0x01 | UINT8 | Data Length: 0x0C or 0x0E |
| + 0x02 | UINT8[Data Length] | Serial Number String ASCII |
Get Sleep Mode Duration
Requests the configured idle duration before the device enters Sleep Mode.
Request:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Feature Report | Report ID: 0x0A |
Response:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | UINT8 | Report ID: 0x0A |
| + 0x01 | UINT8 | Data Length |
| + 0x02 | INT32 | Duration |
Get Unit Information
Requests hardware information about the device (keypad layout, LCD geometry, etc.).
Request:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Feature Report | Report ID: 0x08 |
Response:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | UINT8 | Report ID: 0x08 |
| + 0x01 | UINT8 | Keypad Matrix rows |
| + 0x02 | UINT8 | Keypad Matrix columns |
| + 0x03 | UINT16 | Key / Button Width |
| + 0x05 | UINT16 | Key / Button Height |
| + 0x07 | UINT16 | LCD Width |
| + 0x09 | UINT16 | LCD Height |
| + 0x0B | UINT8 | Image BPP |
| + 0x0C | UINT8 | Image Color Scheme |
| + 0x0D | UINT8 | Number of key / button images in Gallery |
| + 0x0E | UINT8 | Number of LCD images in Gallery |
| + 0x0F | UINT8 | Number of frames for DEMO |
| + 0x10 | UINT8 | Reserved |
The response format may vary across firmware versions and is not consistently documented. Window-capable devices extend this response — see device-specific pages.
Device Setup & Communication
Setup Connection
Open the device as a USB HID device. Once connected, the host can receive input events, send images, and issue control commands.
Polling Input Controllers
The host should periodically poll the device with HID READ using a timed call. A TIMEOUT indicates that no controller state changed. If the state changed, an Input Report is returned.
Recommended polling period is 50ms.
Uploading Images
When the payload does not fit into a single output report, it must be split into multiple chunks. The final chunk must set the Transfer is Done flag to 0x01. All images must be exported in JPEG format before upload.
The image rotation requirement varies per device model. Always check the device-specific page before uploading images.
Closing Connection
Close the USB HID device handle.
Before closing the connection, it is good practice to use Show Logo to restore the default visual state.
Common Feature Reports Reference
Setter Feature Reports
| Report ID | Command | Description |
|---|---|---|
0x03 | 0x02 | Show Logo |
0x03 | 0x05 | Fill LCD with Color |
0x03 | 0x06 | Fill Key / Button with Color |
0x03 | 0x08 | Set Backlight Brightness |
0x03 | 0x0D | Set Sleep Mode Duration |
Getter Feature Reports
| Report ID | Command | Description |
|---|---|---|
0x04 | Get Firmware Version (LD) | |
0x05 | Get Firmware Version (AP2) | |
0x06 | Get Unit Serial Number | |
0x07 | Get Firmware Version (AP1) | |
0x08 | Get Unit Information | |
0x0A | Get Sleep Mode Duration |