API 参考

本文档提供了 StreamDock Python SDK 的完整 API 参考。

DeviceManager 类

设备管理器，用于检测和管理连接的 StreamDock 设备。

构造函数

DeviceManager(transport=None)

创建新的 StreamDock DeviceManager 实例。

参数:

  • transport (可选): 传输层实例，默认使用 LibUSBHIDAPI

方法

enumerate()

enumerate()

检测连接的 StreamDock 设备。

返回值:

  • list: 包含所有连接的 StreamDock 设备的列表

示例:

manager = DeviceManager()
devices = manager.enumerate()
print(f"找到 {len(devices)} 个设备")

listen()

listen()

监听设备连接和断开事件。此方法会阻塞当前线程，建议在单独的线程中运行。

示例:

import threading

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

StreamDock 基类

所有具体型号设备的控制类都需要继承 StreamDock 基类。

属性

  • KEY_COUNT: 设备按键数量
  • KEY_COLS: 按键列数
  • KEY_ROWS: 按键行数
  • KEY_PIXEL_WIDTH: 按键图像宽度（像素）
  • KEY_PIXEL_HEIGHT: 按键图像高度（像素）
  • KEY_IMAGE_FORMAT: 按键图像格式
  • KEY_FLIP: 按键图像翻转设置 (水平, 垂直)
  • KEY_ROTATION: 按键图像旋转角度
  • KEY_MAP: 是否使用按键映射
  • TOUCHSCREEN_PIXEL_WIDTH: 触摸屏宽度（像素）
  • TOUCHSCREEN_PIXEL_HEIGHT: 触摸屏高度（像素）
  • TOUCHSCREEN_IMAGE_FORMAT: 触摸屏图像格式
  • TOUCHSCREEN_FLIP: 触摸屏图像翻转设置
  • TOUCHSCREEN_ROTATION: 触摸屏图像旋转角度
  • DIAL_COUNT: 旋钮数量
  • DECK_TYPE: 设备类型
  • DECK_VISUAL: 是否支持视觉反馈
  • DECK_TOUCH: 是否支持触摸
  • feature_option: FeatrueOption 实例，描述设备扩展功能

方法

设备控制

open()
open()

打开设备连接并启动读取线程。

close()
close()

关闭设备连接并清除所有显示。

init()
init()

初始化设备，包括唤醒屏幕、设置亮度、清除所有图标和刷新显示。

disconnected()
disconnected()

断开连接并清除所有显示。

屏幕控制

wakeScreen()
wakeScreen()

唤醒设备屏幕。

refresh()
refresh()

刷新设备显示。

set_brightness(percent)
set_brightness(percent)

设置设备屏幕亮度。

参数:

  • percent (int): 亮度百分比 (0-100)

返回值:

  • int: 操作结果状态码

按键控制

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

设置指定按键的图标。

参数:

  • key (int): 按键编号
  • image (str): 图像文件路径

返回值:

  • int: 操作结果状态码
clearIcon(index)
clearIcon(index)

清除指定按键的图标。

参数:

  • index (int): 按键编号

返回值:

  • int: 操作结果状态码
clearAllIcon()
clearAllIcon()

清除所有按键的图标。

返回值:

  • int: 操作结果状态码

LED 控制

set_led_brightness(percent)
set_led_brightness(percent)

设置设备 LED 的亮度。

参数:

  • percent (int): 亮度百分比 (0-100)

返回值:

  • int: 操作结果状态码，如果设备不支持 LED 则返回 None
set_led_color(r, g, b)
set_led_color(r, g, b)

设置设备 LED 的颜色。

参数:

  • r (int): 红色分量 (0-255)
  • g (int): 绿色分量 (0-255)
  • b (int): 蓝色分量 (0-255)

返回值:

  • int: 操作结果状态码，如果设备不支持 LED 则返回 None
reset_led_effect()
reset_led_effect()

重置设备的 LED 效果到默认状态。

返回值:

  • int: 操作结果状态码，如果设备不支持 LED 则返回 None

K1 Pro 键盘控制

K1 Pro 设备提供以下特有的键盘控制方法：

set_keyboard_backlight_brightness(brightness)
set_keyboard_backlight_brightness(brightness)

设置键盘背光亮度。

参数:

  • brightness (int): 亮度值 (0-6)

示例:

device.set_keyboard_backlight_brightness(3)  # 设置中等亮度
set_keyboard_lighting_effects(effect)
set_keyboard_lighting_effects(effect)

设置键盘灯光效果。

参数:

  • effect (int): 效果模式标识符 (0-9)，0 为静态灯光

示例:

device.set_keyboard_lighting_effects(0)  # 静态灯光
device.set_keyboard_lighting_effects(1)  # 其他灯光效果
set_keyboard_lighting_speed(speed)
set_keyboard_lighting_speed(speed)

设置键盘灯光效果速度。

参数:

  • speed (int): 灯光效果速度值 (0-7)

示例:

device.set_keyboard_lighting_speed(3)  # 设置中等速度
set_keyboard_rgb_backlight(r, g, b)
set_keyboard_rgb_backlight(r, g, b)

设置键盘 RGB 背光颜色。

参数:

  • r (int): 红色分量 (0-255)
  • g (int): 绿色分量 (0-255)
  • b (int): 蓝色分量 (0-255)

示例:

device.set_keyboard_rgb_backlight(255, 128, 0)  # 设置为橙色
keyboard_os_mode_switch(os_mode)
keyboard_os_mode_switch(os_mode)

设置键盘 OS 模式。

参数:

  • os_mode (int): OS 模式标识符

示例:

device.keyboard_os_mode_switch(0)  # 切换到指定 OS 模式

触摸屏控制

set_touchscreen_image(image)
set_touchscreen_image(image)

设置触摸屏背景图像。

参数:

  • image (str): 图像文件路径

返回值:

  • int: 操作结果状态码

设备信息

getPath()
getPath()

获取设备路径。

返回值:

  • str: 设备路径
get_serial_number(length)
get_serial_number(length)

获取设备序列号。

参数:

  • length (int): 要读取的数据长度

返回值:

  • bytes: 设备序列号数据
id()
id()

获取设备的物理标识符。

返回值:

  • str: 设备标识符

数据读取

read()
read()

读取设备反馈信息。

返回值:

  • bytes: 设备返回的数据
whileread()
whileread()

持续监听设备反馈信息，建议在单独的线程中使用。

事件回调

set_key_callback(callback)
set_key_callback(callback)

设置按键状态变化回调函数。

参数:

  • callback (function): 回调函数，接收参数 (device, key, state)

示例:

def key_callback(device, key, state):
    print(f"按键 {key} {'按下' if state else '释放'}")

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

设置异步按键状态变化回调函数。

参数:

  • async_callback (function): 异步回调函数
  • loop (可选): asyncio 事件循环
set_touchscreen_callback(callback)
set_touchscreen_callback(callback)

设置触摸屏交互回调函数。

参数:

  • callback (function): 回调函数
set_touchscreen_callback_async(async_callback, loop=None)
set_touchscreen_callback_async(async_callback, loop=None)

设置异步触摸屏交互回调函数。

参数:

  • async_callback (function): 异步回调函数
  • loop (可选): asyncio 事件循环

图像格式

key_image_format()
key_image_format()

获取按键图像格式信息。

返回值:

  • dict: 包含图像格式信息的字典
touchscreen_image_format()
touchscreen_image_format()

获取触摸屏图像格式信息。

返回值:

  • dict: 包含图像格式信息的字典

PILHelper 类

提供图像处理和转换功能的辅助类。

方法

create_image(dock, background='black')

create_image(dock, background='black')

创建指定设备格式的空白图像。

参数:

  • dock: StreamDock 设备实例
  • background (str): 背景颜色，默认为黑色

返回值:

  • PIL.Image: 创建的图像对象

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

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

创建缩放后的图像。

参数:

  • dock: StreamDock 设备实例
  • image (PIL.Image): 原始图像
  • margins (list): 边距 [上, 右, 下, 左]
  • background (str): 背景颜色

返回值:

  • PIL.Image: 缩放后的图像对象

to_native_key_format(dock, image)

to_native_key_format(dock, image)

将图像转换为设备原生的按键图像格式。

参数:

  • dock: StreamDock 设备实例
  • image (PIL.Image): 原始图像

返回值:

  • PIL.Image: 转换后的图像对象

to_native_touchscreen_format(dock, image)

to_native_touchscreen_format(dock, image)

将图像转换为设备原生的触摸屏图像格式。

参数:

  • dock: StreamDock 设备实例
  • image (PIL.Image): 原始图像

返回值:

  • PIL.Image: 转换后的图像对象

FeatrueOption 类

FeatrueOption 类用于描述设备的扩展功能特性。

属性

  • hasRGBLed (bool): 是否支持 RGB LED
  • ledCounts (int): LED 数量
  • supportConfig (bool): 是否支持配置

异常类

TransportError

传输错误异常类。

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

参数:

  • message (str): 错误消息
  • code (可选): 错误代码

DeviceNotFoundError

设备未找到异常类。

class DeviceNotFoundError(TransportError):
    pass

InvalidParameterError

参数无效异常类。

class InvalidParameterError(TransportError):
    pass

常量定义

设备类型常量

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

状态码常量

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

事件类型

按键事件类型

class KeyEvent:
    KEY_PRESS = 1    # 按键按下
    KEY_RELEASE = 0  # 按键释放

设备事件类型

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

使用示例

完整的 API 使用流程

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

# 创建设备管理器
manager = DeviceManager()

# 枚举设备
devices = manager.enumerate()

for device in devices:
    # 打开设备
    device.open()

    # 初始化
    device.init()

    # 设置亮度
    device.set_brightness(80)

    # 设置按键图像
    image = create_image(device, background='blue')
    device.set_key_image(1, image)

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

    device.set_key_callback(key_callback)

    # 获取设备信息
    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