系统要求

操作系统支持

• 跨平台支持：
  • Windows: Windows 10/11 (推荐)
  • macOS: macOS 10.5+
  • Linux: Ubuntu 20.04+
• Python: 3.7+ (推荐 3.9+)

硬件要求

• USB 端口（用于连接 StreamDock 设备）
• 足够的内存运行 Python 应用程序

依赖安装

Python 包依赖

Python StreamDock SDK 需要以下 Python 包：

核心依赖

pip install Pillow

pip install pyusb

平台特定依赖

Linux 系统

pip install pyudev

Windows 系统

pip install hidapi

macOS 系统

brew install hidapi

系统内置模块

以下模块是 Python 标准库的一部分，无需额外安装：

• threading - 线程支持
• ctypes - C 语言外部函数库
• time - 时间相关功能
• abc - 抽象基类
• os - 操作系统接口
• io - 输入/输出操作
• asyncio - 异步 I/O（用于异步回调）

系统依赖

Ubuntu/Debian

# 安装 USB 设备访问权限支持
sudo apt-get update
sudo apt-get install libudev-dev libusb-1.0-0-dev libhidapi-libusb0

# 可选：安装 udev 规则以允许非 root 用户访问设备
sudo cp /path/to/sdk/udev-rules/99-streamdock.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

CentOS/RHEL/Fedora

# 安装开发工具和库
sudo yum groupinstall "Development Tools"
sudo yum install libudev-devel libusb1-devel libhidapi-libusb0

# 或者使用 dnf (较新版本)
sudo dnf groupinstall "Development Tools"
sudo dnf install libudev-devel libusb1-devel

Arch Linux

sudo pacman -S libusb libudev libhidapi-libusb0

安装方式

使用 pip 安装（推荐）

# 从 PyPI 安装
pip install streamdock-sdk

# 或从源码安装
git clone https://github.com/MiraboxSpace/StreamDock-Device-SDK.git
cd StreamDock-Device-SDK/Python-SDK
pip install -e .

手动安装

1. 克隆或下载 SDK 源码
2. 安装 Python 依赖
3. 将 src 目录添加到 Python 路径

# 下载 SDK
git clone https://github.com/MiraboxSpace/StreamDock-Device-SDK.git
cd StreamDock-Device-SDK/Python-SDK

# 安装依赖
pip install Pillow pyusb

# Linux 额外依赖
pip install pyudev

# Windows 额外依赖
pip install hidapi

基本使用

导入模块

from StreamDock.DeviceManager import DeviceManager
from StreamDock.ImageHelpers.PILHelper import create_image, to_native_key_format
import threading
import time

基本使用流程

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

# 2. 启动设备监听（用于热插拔检测）
listen_thread = threading.Thread(target=manager.listen)
listen_thread.daemon = True
listen_thread.start()

# 3. 枚举当前连接的设备
devices = manager.enumerate()
print(f"找到 {len(devices)} 个 StreamDock 设备")

# 4. 操作每个设备
for device in devices:
    try:
        # 打开设备
        device.open()
  
        # 初始化设备（唤醒屏幕、设置亮度、清除图标）
        device.init()
  
        # 设置按键事件回调
        def key_callback(device, key, state):
            action = "按下" if state else "释放"
            print(f"设备 {device.getPath()} 按键 {key} {action}")
  
        device.set_key_callback(key_callback)
  
        # 设置设备亮度 (0-100)
        device.set_brightness(80)
  
        # 设置背景图片（确保图片文件存在）
        device.set_touchscreen_image("background.jpg")
  
        # 设置按键图标
        device.set_key_image(1, "icon1.jpg")
        device.set_key_image(2, "icon2.jpg")
  
        # 刷新显示
        device.refresh()
  
        # 等待一段时间
        time.sleep(5)
  
    except Exception as e:
        print(f"操作设备时出错: {e}")
  
    finally:
        # 关闭设备
        device.close()

高级使用示例

使用 PILHelper 创建动态图像

from PIL import Image, ImageDraw, ImageFont
from StreamDock.ImageHelpers.PILHelper import create_image, to_native_key_format

def create_key_image(text, background_color='blue', text_color='white'):
    """创建带文本的按键图像"""
    # 创建空白图像
    image = create_image(device, background=background_color)
    draw = ImageDraw.Draw(image)
  
    # 加载字体
    try:
        font = ImageFont.truetype("arial.ttf", 40)
    except:
        font = ImageFont.load_default()
  
    # 绘制文本
    bbox = draw.textbbox((0, 0), text, font=font)
    text_width = bbox[2] - bbox[0]
    text_height = bbox[3] - bbox[1]
  
    x = (image.width - text_width) // 2
    y = (image.height - text_height) // 2
  
    draw.text((x, y), text, fill=text_color, font=font)
  
    return image

# 使用示例
for key in range(1, min(device.KEY_COUNT + 1, 16)):
    # 创建带数字的图标
    image = create_key_image(str(key))
  
    # 转换为设备原生格式
    native_image = to_native_key_format(device, image)
  
    # 保存临时文件并设置到设备
    temp_file = f"temp_key_{key}.jpg"
    native_image.save(temp_file, "JPEG", quality=100)
    device.set_key_image(key, temp_file)

异步事件处理

import asyncio

async def async_key_handler(device, key, state):
    """异步按键事件处理"""
    if state:  # 按键按下
        print(f"按键 {key} 被按下")
  
        # 模拟异步操作
        await asyncio.sleep(0.5)
  
        # 更新按键图标
        image = create_key_image(f"OK", background_color='green')
        native_image = to_native_key_format(device, image)
        native_image.save(f"async_key_{key}.jpg", "JPEG", quality=100)
        device.set_key_image(key, f"async_key_{key}.jpg")

# 设置异步回调
device.set_key_callback_async(async_key_handler)

# 运行异步事件循环
async def main():
    # 设备初始化代码...
  
    # 保持程序运行
    while True:
        await asyncio.sleep(1)

asyncio.run(main())

故障排除

常见问题

1. 设备无法检测

问题: enumerate() 返回空列表

解决方案:

• 检查设备是否正确连接
• 确认设备驱动程序已安装
• 检查 USB 权限（可能需要 sudo 或配置 udev 规则）
• 使用 lsusb 命令确认设备可见

lsusb | grep -i streamdock

2. 权限错误

问题: Permission denied 错误

解决方案:

• 使用 sudo 运行程序
• 配置 udev 规则允许用户访问设备

创建 /etc/udev/rules.d/99-streamdock.rules 文件：

# StreamDock 设备规则
SUBSYSTEM=="usb", ATTR{idVendor}=="5500", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="5548", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="6603", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="6602", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="EEEF", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="1500", MODE="0666"

然后重新加载规则：

sudo udevadm control --reload-rules
sudo udevadm trigger

3. 图像显示问题

问题: 图像无法正确显示

解决方案:

• 确认图像文件存在且可读
• 检查图像格式（推荐 JPEG）
• 确认图像尺寸符合设备要求
• 检查图像路径是否正确

4. 依赖安装失败

问题: pip 安装依赖时出错

解决方案:

• 更新 pip: pip install --upgrade pip
• 使用系统包管理器安装系统依赖
• 在虚拟环境中安装

# 创建虚拟环境
python3 -m venv streamdock-env
source streamdock-env/bin/activate

# 安装依赖
pip install Pillow pyudev

调试技巧

启用详细日志

import logging

# 设置日志级别
logging.basicConfig(level=logging.DEBUG)

# 在代码中添加日志
logger = logging.getLogger(__name__)
logger.debug("调试信息")

检查设备信息

for device in devices:
    print(f"设备路径: {device.getPath()}")
    print(f"设备类型: {device.DECK_TYPE}")
    print(f"按键数量: {device.KEY_COUNT}")
    print(f"屏幕尺寸: {device.TOUCHSCREEN_PIXEL_WIDTH}x{device.TOUCHSCREEN_PIXEL_HEIGHT}")
    print(f"按键尺寸: {device.KEY_PIXEL_WIDTH}x{device.KEY_PIXEL_HEIGHT}")

性能优化

图像处理优化

1. 预转换图像: 在程序启动时预转换所有图像
2. 使用缓存: 缓存已转换的图像避免重复处理
3. 批量操作: 批量设置多个按键图标
4. 适当的质量设置: JPEG 质量设置为 85-95 以平衡质量和性能

线程管理

1. 使用线程池: 对于大量设备操作，使用线程池管理
2. 避免阻塞: 不要在回调函数中执行耗时操作
3. 合理超时: 为设备操作设置合理的超时时间