Skip to main content

Stream Deck Module 15 and 32 Keys

Release History

REVISIONDATE
1.0A02.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

NameModelVIDPIDCapabilities
Stream Deck Module 1520GBA99010x0FD90x00B915 Keys Layout
Stream Deck Module 3220GAT99020x0FD90x00BA32 Keys Layout

Capabilities & Physical Characteristics

15 Keys Layout

EntityProperty
LCD image480 × 272 px (low DPI)
Keys matrix5 x 3
Keys image72 × 72 px
Keypad Keys Index Layout
Image showing the 15 keys keypad buttons index layout.
Unit Pixel Layout
Image showing the 15 keys keypad buttons index layout.

32 Keys Layout

EntityProperty
LCD Image1024 × 600 px (high DPI)
Keys matrix8 x 4
Keys Image96 × 96 px
Keypad keys Index Layout
Image showing the 32 keys keypad buttons index layout.
Unit Pixel Layout
Image showing the 32 keys keypad keys index 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
TypeDescription
CHAR, INT8Signed 8-bit integer, ASCII
BYTE, UINT8Unsigned 8-bit integer
INT16Little-endian signed 16-bit integer
UINT16Little-endian unsigned 16-bit integer
INT32Little-endian signed 32-bit integer
UINT32Little-endian unsigned 32-bit integer

RGB Triplet

RGB color definition triplet

OffsetTypeNote
+ 0x00UINT8Red color component
+ 0x01UINT8Green color component
+ 0x02UINT8Blue 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.

OffsetTypeNote
+ 0x00UINT8Report ID
+ 0x01UINT8Command
+ 0x02UINT16Payload data length
+ 0x04BYTE[]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.

OffsetTypeNote
+ 0x00UINT8Report ID
+ 0x01UINT8Command
+ 0x02BYTE[]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.

OffsetTypeNote
+ 0x00UINT8Report ID
+ 0x01UINT8Command
+ 0x02BYTE[]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:

OffsetTypeNote
+ 0x00Input ReportReport ID: 0x01, Command: 0x00, Payload data length: amount of Keys
+ 0x04UINT8[]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:

OffsetTypeNote
+ 0x00Output ReportReport ID: 0x02, Command: 0x07
+ 0x02UINT8Key Index
+ 0x03UINT8Transfer is Done flag (0x01 = last chunk)
+ 0x04UINT16Chunk Contents Size
+ 0x06UINT16Chunk Index (zero-based)
+ 0x08UINT8[]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.

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:

OffsetTypeNote
+ 0x00Output ReportReport ID: 0x02, Command: 0x09
+ 0x02UINT8Reserved
+ 0x03UINT8Transfer is Done flag
+ 0x04UINT16Chunk Index
+ 0x06UINT16Chunk Contents Size
+ 0x08UINT8[]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 0x01 in 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:

OffsetTypeNote
+ 0x00Output ReportReport ID: 0x02, Command: 0x0D
+ 0x02UINT8Background Index
+ 0x03UINT8Transfer is Done flag
+ 0x04UINT16Chunk Index
+ 0x06UINT16Chunk Contents Size
+ 0x08UINT8[]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 0x01 in 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.

This command forcibly triggers the display of the boot logo. Therefore, the Feature Report payload is structured as follows:

OffsetTypeNote
+ 0x00Feature ReportReport 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:

OffsetTypeNote
+ 0x00Feature ReportReport ID: 0x03, Command: 0x05
+ 0x02RGB TripletColor

Fill Key with Color

This command fills a dedicated key with a given RGB color. Therefore, the Feature Report payload is structured as follows:

OffsetTypeNote
+ 0x00Feature ReportReport ID: 0x03, Command: 0x06
+ 0x02UINT8key Index
+ 0x03RGB TripletColor

Set Backlight Brightness

This command sets the LCD backlight brightness. Therefore, the Feature Report payload is structured as follows:

OffsetTypeNote
+ 0x00Feature ReportReport ID: 0x03, Command: 0x08
+ 0x02UINT8Brightness Value
  • The brightness value range is from 0x00 (zero, backlight is off) to 0x64 (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:

OffsetTypeNote
+ 0x00Feature ReportReport ID: 0x03, Command: 0x0D
+ 0x02INT32Idle 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:

OffsetTypeNote
+ 0x00Feature ReportReport ID: 0x03, Command: 0x13
+ 0x02UINT8Background 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:

OffsetTypeNote
+ 0x00Feature ReportReport ID: see below

The response is structured as follows:

OffsetTypeNote
+ 0x00UINT8Report ID: see below
+ 0x01UINT8Data Length: 0x0C
+ 0x02UINT32Checksum
+ 0x06UINT8[8]Version String ASCII

Report IDs by firmware type:

Report IDNameNote
0x04LD
0x05AP2Primary firmware
0x07AP1Backup firmware

Get Unit Serial Number

This command requests the unit's serial number string. Therefore, the Feature Report payload is structured as follows:

OffsetTypeNote
+ 0x00Feature ReportReport ID: 0x06

The response is structured as follows:

OffsetTypeNote
+ 0x00UINT8Report ID: 0x06
+ 0x01UINT8Data Length: 0x0C or 0x0E
+ 0x02UINT8[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:

OffsetTypeNote
+ 0x00Feature ReportReport ID: 0x0A

The response is structured as follows:

OffsetTypeNote
+ 0x00UINT8Report ID: 0x0A
+ 0x01UINT8Data Length
+ 0x02INT32Duration

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:

OffsetTypeNote
+ 0x00Feature ReportReport ID: 0x08

The response is structured as follows:

OffsetTypeNote
+ 0x00UINT8Report ID: 0x08
+ 0x01UINT8Keypad Matrix rows
+ 0x02UINT8Keypad Matrix columns
+ 0x03UINT16key Width
+ 0x05UINT16key Height
+ 0x07UINT16LCD Width
+ 0x09UINT16LCD Height
+ 0x0BUINT8Image BPP
+ 0x0CUINT8Image Color Scheme
+ 0x0DUINT8Number of key images in Gallery
+ 0x0EUINT8Number of LCD images in Gallery
+ 0x0FUINT8Number of frames for DEMO
+ 0x10UINT8Reserved
+ 0x11UINT16Window Width
+ 0x13UINT16Window 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.

tip

Recommended polling period is 50ms

Uploading Images

Key Image

  1. Prepare the key image in a size as specified by the device capabilities.
    warning

    The image must be rotated 180° for all unit models

  2. Export the image in JPEG format.
  3. Use the sequence of Update Key commands.

Full LCD Image

  1. 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

  2. Export the image in JPEG format.
  3. Use the sequence of Update Full Screen Image commands.

Full Window Image

  1. 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

  2. Export the image in JPEG format.
  3. Use the sequence of Update Window Image commands.

Partial Window Image

  1. Prepare the image in the desired size
    warning

    The image must be rotated 180° for all unit models

  2. Export the image in JPEG format
  3. 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

  1. 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

  2. Export the image in JPEG format
  3. 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.

tip

It is good practice to use the Show Logo command before closing, to clean up key images and the LCD.