Stream Deck Module 15 and 32 Keys
Release History
| REVISION | DATE |
|---|---|
| 1.0A | 02.04.2025 |
Introduction
The Elgato Stream Deck Module 15 and 32 are USB 2.0–compliant input devices engineered for efficient interaction with host systems through their USB HID (Human Interface Device) protocol. Each device features a grid of keys situated atop a single LCD screen, allowing for dynamic content display and assignment of custom functions. The devices communicate using a proprietary protocol, enabling the transmission of input events, state changes, and visual feedback to the LCD.
This documentation provides a comprehensive overview of the USB HID API for the Stream Deck Module 15 and Module 32. It outlines available methods and data structures for developers to leverage key event reporting, input handling, and LCD control to build robust applications and enhance device integration.
Devices Overview
Summary
| Name | Model | VID | PID | Capabilities |
|---|---|---|---|---|
| Stream Deck Module 15 | 20GBA9901 | 0x0FD9 | 0x00B9 | 15 Keys Layout |
| Stream Deck Module 32 | 20GAT9902 | 0x0FD9 | 0x00BA | 32 Keys Layout |
Capabilities & Physical Characteristics
15 Keys Layout
| Entity | Property |
|---|---|
| LCD image | 480 × 272 px (low DPI) |
| Keys matrix | 5 x 3 |
| Keys image | 72 × 72 px |
Keypad Keys Index Layout
Unit Pixel Layout
32 Keys Layout
| Entity | Property |
|---|---|
| LCD Image | 1024 × 600 px (high DPI) |
| Keys matrix | 8 x 4 |
| Keys Image | 96 × 96 px |
Keypad keys Index Layout
Unit Pixel Layout
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
| Type | Description |
|---|---|
| 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
RGB color definition triplet
| Offset | Type | Note |
|---|---|---|
| + 0x00 | UINT8 | Red color component |
| + 0x01 | UINT8 | Green color component |
| + 0x02 | UINT8 | Blue color component |
Input Report
Input reports are used to transmit “events” from the device to the host. Events may include key state changes, encoder rotation, or touchscreen activity. To obtain input reports, the host polls the device using a non-blocking HID READ command. Each report has a maximum size of 512 bytes.
| Offset | Type | Note |
|---|---|---|
| + 0x00 | UINT8 | Report ID |
| + 0x01 | UINT8 | Command |
| + 0x02 | UINT16 | Payload data length |
| + 0x04 | BYTE[] | Payload |
Output Report
Used to transmit bulk data from host to device (e.g. images, firmware). The host sends these with HID WRITE. Max size: 1024 bytes. Payload should be zero-padded to the full size.
| Offset | Type | Note |
|---|---|---|
| + 0x00 | UINT8 | Report ID |
| + 0x01 | UINT8 | Command |
| + 0x02 | BYTE[] | Payload |
Feature Report
Used to set or retrieve configuration data or trigger commands.
- HID SEND FEATURE REPORT to send
- HID GET FEATURE REPORT to request response
Max size: 32 bytes, zero-padded if shorter.
| Offset | Type | Note |
|---|---|---|
| + 0x00 | UINT8 | Report ID |
| + 0x01 | UINT8 | Command |
| + 0x02 | BYTE[] | Payload |
Command Descriptions
Input Reports
Report ID: 0x01. Events are triggered on user interaction. If no event is pending, HID READ returns a TIMEOUT.
Key press state change
An “event” is generated on every change in the state of one or more keys. The payload contains an array of bytes, each indicating the state of a corresponding key. Therefore, the Input Report payload is structured as follows:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Input Report | Report ID: 0x01, Command: 0x00, Payload data length: amount of Keys |
| + 0x04 | UINT8[] | 0x00 = released, 0x01 = pressed |
Output Reports
The Report ID of the output report is set to 0x02. Below, you can find the description of the available commands. To send output reports, the host uses the HID WRITE command—optionally multiple times if the data bulk exceeds the maximum payload size.
Update Key Image
This command is used to upload an image file for a dedicated key on the unit. Since it is not possible to upload the entire image file at once, the command supports a splitting mechanism. Please note the following:
- The maximum size of an output report is 1024 bytes.
Based on the above, the image file must be split into chunks defined by the output report's payload. Therefore, the Output Report payload is structured as follows:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Output Report | Report ID: 0x02, Command: 0x07 |
| + 0x02 | UINT8 | Key Index |
| + 0x03 | UINT8 | Transfer is Done flag (0x01 = last chunk) |
| + 0x04 | UINT16 | Chunk Contents Size |
| + 0x06 | UINT16 | Chunk Index (zero-based) |
| + 0x08 | UINT8[] | Chunk Data (fill to end of report) |
Update Full Screen Image
This command is used to upload an image file for the entire LCD on the unit.
Same structure as above, with Command: 0x08.
Update Boot Logo
This command is used to upload an image file for the entire LCD on the unit as a boot logo. Since it is not possible to upload the image file all at once, the command supports a splitting mechanism. Please note the following:
- The maximum size of an output report is 1024 bytes.
Based on this, the image file must be split into chunks defined by the output report's payload. Therefore, the Output Report payload is structured as follows:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Output Report | Report ID: 0x02, Command: 0x09 |
| + 0x02 | UINT8 | Reserved |
| + 0x03 | UINT8 | Transfer is Done flag |
| + 0x04 | UINT16 | Chunk Index |
| + 0x06 | UINT16 | Chunk Contents Size |
| + 0x08 | UINT8[] | Chunk Data |
- The chunk index is zero-based; it corresponds to the sequential number of the sending chunk.
- The output report of the last chunk should be marked with
0x01in the Transfer is Done; otherwise, it must be zero. - The chunk data size is fixed for the remainder of the report.
Update Background
This command is used to upload an image file for the entire LCD background on the unit, to be used as the background for a given index. Since it is not possible to upload the image file all at once, the command supports a splitting mechanism. Please note the following:
- The maximum size of an output report is 1024 bytes.
Based on this, the image file must be split into chunks defined by the output report's payload. Therefore, the Output Report payload is structured as follows:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Output Report | Report ID: 0x02, Command: 0x0D |
| + 0x02 | UINT8 | Background Index |
| + 0x03 | UINT8 | Transfer is Done flag |
| + 0x04 | UINT16 | Chunk Index |
| + 0x06 | UINT16 | Chunk Contents Size |
| + 0x08 | UINT8[] | Chunk Data |
- The chunk index is zero-based; it corresponds to the sequential number of the sending chunk.
- The output report of the last chunk should be marked with
0x01in the Transfer is Done flag; otherwise, it must be zero. - The chunk data size is fixed for the remainder of the report.
Feature Report - Setters
The Report ID of the feature report for setters is set to 0x03. Below, you can find the description of the available commands. To send a feature report, the host uses the HID SEND FEATURE REPORT command.
Show Logo
This command forcibly triggers the display of the boot logo. Therefore, the Feature Report payload is structured as follows:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Feature Report | Report ID: 0x03, Command: 0x02 |
Fill LCD with Color
This command fills the entire LCD with a given RGB color. Therefore, the Feature Report payload is structured as follows:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Feature Report | Report ID: 0x03, Command: 0x05 |
| + 0x02 | RGB Triplet | Color |
Fill Key with Color
This command fills a dedicated key with a given RGB color. Therefore, the Feature Report payload is structured as follows:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Feature Report | Report ID: 0x03, Command: 0x06 |
| + 0x02 | UINT8 | key Index |
| + 0x03 | RGB Triplet | Color |
Set Backlight Brightness
This command sets the LCD backlight brightness. Therefore, the Feature Report payload is structured as follows:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Feature Report | Report ID: 0x03, Command: 0x08 |
| + 0x02 | UINT8 | Brightness Value |
- The brightness value range is from
0x00(zero, backlight is off) to0x64(100, maximum brightness).
Set Idle time before entering Sleep Mode
This command sets the duration, in seconds, of idling before the unit enters Sleep Mode. Therefore, the Feature Report payload is structured as follows:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Feature Report | Report ID: 0x03, Command: 0x0D |
| + 0x02 | INT32 | Idle time before entering Sleep Mode in seconds |
- Set to zero seconds to disable sleep mode.
Show Background by Index
This command shows the stored background of a given index. Therefore, the Feature Report payload is structured as follows:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Feature Report | Report ID: 0x03, Command: 0x13 |
| + 0x02 | UINT8 | Background Index |
Feature Report - Getters
The Report ID of the feature report for getters is assigned unique values. Below, you can find the description of the possible Report IDs. The Command field is usually ignored. To send a feature report and obtain the response, the host uses HID GET FEATURE REPORT command.
Get Firmware Version
This command requests the firmware version string of the unit. Therefore, the Feature Report payload is structured as follows:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Feature Report | Report ID: see below |
The response is structured as follows:
| 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 | Backup firmware |
Get Unit Serial Number
This command requests the unit's serial number string. Therefore, the Feature Report payload is structured as follows:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Feature Report | Report ID: 0x06 |
The response is structured as follows:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | UINT8 | Report ID: 0x06 |
| + 0x01 | UINT8 | Data Length: 0x0C or 0x0E |
| + 0x02 | UINT8[Data Length] | Serial Number String ASCII |
- The serial number consists of 14 characters.
Get Idle time before entering Sleep Mode
This command requests the duration, in seconds, of idling before the unit enters Sleep Mode. Therefore, the Feature Report payload is structured as follows:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Feature Report | Report ID: 0x0A |
The response is structured as follows:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | UINT8 | Report ID: 0x0A |
| + 0x01 | UINT8 | Data Length |
| + 0x02 | INT32 | Duration |
Get Unit Information
This command requests information about the unit, including keypad matrix layout, LCD geometry, and more. Therefore, the Feature Report payload is structured as follows:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | Feature Report | Report ID: 0x08 |
The response is structured as follows:
| Offset | Type | Note |
|---|---|---|
| + 0x00 | UINT8 | Report ID: 0x08 |
| + 0x01 | UINT8 | Keypad Matrix rows |
| + 0x02 | UINT8 | Keypad Matrix columns |
| + 0x03 | UINT16 | key Width |
| + 0x05 | UINT16 | key Height |
| + 0x07 | UINT16 | LCD Width |
| + 0x09 | UINT16 | LCD Height |
| + 0x0B | UINT8 | Image BPP |
| + 0x0C | UINT8 | Image Color Scheme |
| + 0x0D | UINT8 | Number of key images in Gallery |
| + 0x0E | UINT8 | Number of LCD images in Gallery |
| + 0x0F | UINT8 | Number of frames for DEMO |
| + 0x10 | UINT8 | Reserved |
| + 0x11 | UINT16 | Window Width |
| + 0x13 | UINT16 | Window Height |
Device Setup & Communication
Setup Connection
To bring the unit into operational mode, open it as a USB HID device. The unit may then provide input controller events, receive commands to display feedback, and allow tweaking of some internal settings.
Polling Input Controllers
To obtain changes in the state of controllers, the Input Report is used. The host application should periodically poll the unit using the HID READ timed command. A timeout indicates that no state change has occurred. If a state has changed, Input Reports containing the described contents—depending on the controller type—will be received from the unit.
Recommended polling period is 50ms
Uploading Images
Key Image
- Prepare the key image in a size as specified by the device capabilities.
warning
The image must be rotated 180° for all unit models
- Export the image in JPEG format.
- Use the sequence of Update Key commands.
Full LCD Image
- Prepare the full LCD image in a size as specified by the device capabilities.
warning
The image must be rotated 180° for all unit models
- Export the image in JPEG format.
- Use the sequence of Update Full Screen Image commands.
Full Window Image
- Prepare the full window image in a size as specified by the device capabilities.
warning
The image must be rotated 180° for all unit models
- Export the image in JPEG format.
- Use the sequence of Update Window Image commands.
Partial Window Image
- Prepare the image in the desired size
warning
The image must be rotated 180° for all unit models
- Export the image in JPEG format
- Use the sequence of Update part of Window Image at Given Coordinates commands for the desired size and image position in the window
Boot Logo Image
- Prepare the full LCD image in a size as specified by the device capabilities
warning
The image must be rotated 180° for all unit models
- Export the image in JPEG format
- Use the sequence of Update Boot Logo commands
- The unit has a boot logo image file size limit, which depends on the model. Reducing JPEG quality may help fit within the image file size limit.
Closing Connection
Just close the USB HID device.
It is good practice to use the Show Logo command before closing, to clean up key images and the LCD.