API Reference

This document provides a complete API reference for the StreamDock Python SDK.

DeviceManager Class

Device manager for detecting and managing connected StreamDock devices.

Constructor

DeviceManager(transport=None)

Creates a new StreamDock DeviceManager instance.

Parameters:

  • transport (optional): Transport layer instance, defaults to LibUSBHIDAPI

Methods

enumerate()

enumerate()

Detects connected StreamDock devices.

Return Value:

  • list: List containing all connected StreamDock devices

Example:

manager = DeviceManager()
devices = manager.enumerate()
print(f"Found {len(devices)} devices")

listen()

listen()

Listens for device connection and disconnection events. This method blocks the current thread, recommended to run in a separate thread.

Example:

import threading

manager = DeviceManager()
t = threading.Thread(target=manager.listen)
t.start()

StreamDock Base Class

All control classes for specific device models must inherit from the StreamDock base class.

Properties

  • KEY_COUNT: Number of device keys
  • KEY_COLS: Number of key columns
  • KEY_ROWS: Number of key rows
  • KEY_PIXEL_WIDTH: Key image width (pixels)
  • KEY_PIXEL_HEIGHT: Key image height (pixels)
  • KEY_IMAGE_FORMAT: Key image format
  • KEY_FLIP: Key image flip settings (horizontal, vertical)
  • KEY_ROTATION: Key image rotation angle
  • KEY_MAP: Whether to use key mapping
  • TOUCHSCREEN_PIXEL_WIDTH: Touchscreen width (pixels)
  • TOUCHSCREEN_PIXEL_HEIGHT: Touchscreen height (pixels)
  • TOUCHSCREEN_IMAGE_FORMAT: Touchscreen image format
  • TOUCHSCREEN_FLIP: Touchscreen image flip settings
  • TOUCHSCREEN_ROTATION: Touchscreen image rotation angle
  • DIAL_COUNT: Number of dials
  • DECK_TYPE: Device type
  • DECK_VISUAL: Whether visual feedback is supported
  • DECK_TOUCH: Whether touch is supported
  • feature_option: FeatrueOption instance describing device extended features

Methods

Device Control

open()
open()

Opens device connection and starts reading thread.

close()
close()

Closes device connection and clears all display.

init()
init()

Initializes device, including waking screen, setting brightness, clearing all icons and refreshing display.

disconnected()
disconnected()

Disconnects and clears all display.

Screen Control

wakeScreen()
wakeScreen()

Wakes up device screen.

refresh()
refresh()

Refreshes device display.

set_brightness(percent)
set_brightness(percent)

Sets device screen brightness.

Parameters:

  • percent (int): Brightness percentage (0-100)

Return Value:

  • int: Operation result status code

Key Control

set_key_image(key, image)
set_key_image(key, image)

Sets icon for specified key.

Parameters:

  • key (int): Key number
  • image (str): Image file path

Return Value:

  • int: Operation result status code
clearIcon(index)
clearIcon(index)

Clears icon for specified key.

Parameters:

  • index (int): Key number

Return Value:

  • int: Operation result status code
clearAllIcon()
clearAllIcon()

Clears all key icons.

Return Value:

  • int: Operation result status code

LED Control

set_led_brightness(percent)
set_led_brightness(percent)

Sets device LED brightness.

Parameters:

  • percent (int): Brightness percentage (0-100)

Return Value:

  • int: Operation result status code, returns None if device doesn't support LED
set_led_color(r, g, b)
set_led_color(r, g, b)

Sets device LED color.

Parameters:

  • r (int): Red component (0-255)
  • g (int): Green component (0-255)
  • b (int): Blue component (0-255)

Return Value:

  • int: Operation result status code, returns None if device doesn't support LED
reset_led_effect()
reset_led_effect()

Resets device LED effect to default state.

Return Value:

  • int: Operation result status code, returns None if device doesn't support LED

K1 Pro Keyboard Control

K1 Pro device provides the following unique keyboard control methods:

set_keyboard_backlight_brightness(brightness)
set_keyboard_backlight_brightness(brightness)

Sets keyboard backlight brightness.

Parameters:

  • brightness (int): Brightness value (0-6)

Example:

device.set_keyboard_backlight_brightness(3)  # Set medium brightness
set_keyboard_lighting_effects(effect)
set_keyboard_lighting_effects(effect)

Sets keyboard lighting effect.

Parameters:

  • effect (int): Effect mode identifier (0-9), 0 is static lighting

Example:

device.set_keyboard_lighting_effects(0)  # Static lighting
device.set_keyboard_lighting_effects(1)  # Other lighting effects
set_keyboard_lighting_speed(speed)
set_keyboard_lighting_speed(speed)

Sets keyboard lighting effect speed.

Parameters:

  • speed (int): Lighting effect speed value (0-7)

Example:

device.set_keyboard_lighting_speed(3)  # Set medium speed
set_keyboard_rgb_backlight(r, g, b)
set_keyboard_rgb_backlight(r, g, b)

Sets keyboard RGB backlight color.

Parameters:

  • r (int): Red component (0-255)
  • g (int): Green component (0-255)
  • b (int): Blue component (0-255)

Example:

device.set_keyboard_rgb_backlight(255, 128, 0)  # Set to orange
keyboard_os_mode_switch(os_mode)
keyboard_os_mode_switch(os_mode)

Sets keyboard OS mode.

Parameters:

  • os_mode (int): OS mode identifier

Example:

device.keyboard_os_mode_switch(0)  # Switch to specified OS mode

Touchscreen Control

set_touchscreen_image(image)
set_touchscreen_image(image)

Sets touchscreen background image.

Parameters:

  • image (str): Image file path

Return Value:

  • int: Operation result status code

Device Information

getPath()
getPath()

Gets device path.

Return Value:

  • str: Device path
get_serial_number(length)
get_serial_number(length)

Gets device serial number.

Parameters:

  • length (int): Data length to read

Return Value:

  • bytes: Device serial number data
id()
id()

Gets physical identifier of the device.

Return Value:

  • str: Device identifier

Data Reading

read()
read()

Reads device feedback information.

Return Value:

  • bytes: Data returned by device
whileread()
whileread()

Continuously monitors device feedback information, recommended to use in separate thread.

Event Callbacks

set_key_callback(callback)
set_key_callback(callback)

Sets key state change callback function.

Parameters:

  • callback (function): Callback function that receives parameters (device, key, state)

Example:

def key_callback(device, key, state):
    print(f"Key {key} {'pressed' if state else 'released'}")

device.set_key_callback(key_callback)
set_key_callback_async(async_callback, loop=None)
set_key_callback_async(async_callback, loop=None)

Sets async key state change callback function.

Parameters:

  • async_callback (function): Async callback function
  • loop (optional): asyncio event loop
set_touchscreen_callback(callback)
set_touchscreen_callback(callback)

Sets touchscreen interaction callback function.

Parameters:

  • callback (function): Callback function
set_touchscreen_callback_async(async_callback, loop=None)
set_touchscreen_callback_async(async_callback, loop=None)

Sets async touchscreen interaction callback function.

Parameters:

  • async_callback (function): Async callback function
  • loop (optional): asyncio event loop

Image Format

key_image_format()
key_image_format()

Gets key image format information.

Return Value:

  • dict: Dictionary containing image format information
touchscreen_image_format()
touchscreen_image_format()

Gets touchscreen image format information.

Return Value:

  • dict: Dictionary containing image format information

PILHelper Class

Helper class providing image processing and conversion functions.

Methods

create_image(dock, background='black')

create_image(dock, background='black')

Creates blank image in specified device format.

Parameters:

  • dock: StreamDock device instance
  • background (str): Background color, defaults to black

Return Value:

  • PIL.Image: Created image object

create_scaled_image(dock, image, margins=[0, 0, 0, 0], background='black')

create_scaled_image(dock, image, margins=[0, 0, 0, 0], background='black')

Creates scaled image.

Parameters:

  • dock: StreamDock device instance
  • image (PIL.Image): Original image
  • margins (list): Margins [top, right, bottom, left]
  • background (str): Background color

Return Value:

  • PIL.Image: Scaled image object

to_native_key_format(dock, image)

to_native_key_format(dock, image)

Converts image to device native key image format.

Parameters:

  • dock: StreamDock device instance
  • image (PIL.Image): Original image

Return Value:

  • PIL.Image: Converted image object

to_native_touchscreen_format(dock, image)

to_native_touchscreen_format(dock, image)

Converts image to device native touchscreen image format.

Parameters:

  • dock: StreamDock device instance
  • image (PIL.Image): Original image

Return Value:

  • PIL.Image: Converted image object

FeatrueOption Class

The FeatrueOption class is used to describe device extended feature characteristics.

Properties

  • hasRGBLed (bool): Whether RGB LED is supported
  • ledCounts (int): Number of LEDs
  • supportConfig (bool): Whether configuration is supported

Exception Classes

TransportError

Transport error exception class.

class TransportError(Exception):
    def __init__(self, message, code=None):
        super().__init__(message)
        self.code = code

Parameters:

  • message (str): Error message
  • code (optional): Error code

DeviceNotFoundError

Device not found exception class.

class DeviceNotFoundError(TransportError):
    pass

InvalidParameterError

Invalid parameter exception class.

class InvalidParameterError(TransportError):
    pass

Constants

Device Type Constants

class DeviceType:
    STREAMDOCK_293 = "StreamDock293"
    STREAMDOCK_293S = "StreamDock293s"
    STREAMDOCK_N3 = "StreamDockN3"
    STREAMDOCK_N4 = "StreamDockN4"
    STREAMDOCK_M18 = "StreamDockM18"
    STREAMDOCK_XL = "StreamDockXL"
    STREAMDOCK_K1_PRO = "K1Pro"

Status Code Constants

class StatusCode:
    SUCCESS = 0
    DEVICE_NOT_FOUND = -1
    INVALID_PARAMETER = -2
    TRANSPORT_ERROR = -3
    PERMISSION_DENIED = -4

Event Types

Key Event Types

class KeyEvent:
    KEY_PRESS = 1    # Key pressed
    KEY_RELEASE = 0  # Key released

Device Event Types

class DeviceEvent:
    DEVICE_CONNECTED = "connected"
    DEVICE_DISCONNECTED = "disconnected"

Usage Examples

Complete API Usage Flow

from StreamDock.DeviceManager import DeviceManager
from StreamDock.ImageHelpers.PILHelper import create_image
import asyncio

# Create device manager
manager = DeviceManager()

# Enumerate devices
devices = manager.enumerate()

for device in devices:
    # Open device
    device.open()

    # Initialize
    device.init()

    # Set brightness
    device.set_brightness(80)

    # Set key image
    image = create_image(device, background='blue')
    device.set_key_image(1, image)

    # Set callback
    def key_callback(device, key, state):
        print(f"Key {key} {'pressed' if state else 'released'}")

    device.set_key_callback(key_callback)

    # Get device information
    print(f"Device Type: {device.DECK_TYPE}")
    print(f"Key Count: {device.KEY_COUNT}")
    print(f"Serial: {device.get_serial_number(64)}")
Last Updated:
Contributors: JKWTCN