StreamDock 基类

所有具体型号设备的控制类都需要继承 StreamDock 基类，StreamDock 基类提供了以下方法：

设备控制方法

打开设备

def open(self):
    """
    打开设备连接并启动读取线程
    """
    self.transport.open(bytes(self.path,'utf-8'))
    self._setup_reader(self._read)

初始化设备

def init(self):
    """
    初始化设备，包括唤醒屏幕、设置亮度、清除所有图标和刷新显示
    """
    self.wakeScreen()
    self.set_brightness(100)
    self.clearAllIcon()
    self.refresh()

关闭设备

def close(self):
    """
    关闭设备连接并清除所有显示
    """
    self.disconnected()
    # self.transport.close()

断开连接清除所有显示

def disconnected(self):
    """
    断开连接并清除所有显示
    """
    self.transport.disconnected()

屏幕控制方法

唤醒屏幕

def wakeScreen(self):
    """
    唤醒设备屏幕
    """
    self.transport.wakeScreen()

刷新设备显示

def refresh(self):
    """
    刷新设备显示
    """
    self.transport.refresh()

设置亮度

@abstractmethod
def set_brightness(self, percent):
    """
    设置设备屏幕亮度
    
    参数:
        percent (int): 亮度百分比 (0-100)
    
    返回:
        int: 操作结果状态码
    """
    pass

按键控制方法

设置按键图标

@abstractmethod
def set_key_image(self, key, image):
    """
    设置指定按键的图标
    
    参数:
        key (int): 按键编号
        image (str): 图像文件路径
    
    返回:
        int: 操作结果状态码
    """
    pass

清除指定按键的图标

def clearIcon(self, index):
    """
    清除指定按键的图标
    
    参数:
        index (int): 按键编号
    
    返回:
        int: 操作结果状态码，如果按键超出范围返回 -1
    """
    origin = index
    index = self.key(index)
    if index not in range(1, 16):
        print(f"key '{origin}' out of range. you should set (1 ~ 15)")
        return -1
    self.transport.clearKey(index)

清除所有按键的图标

def clearAllIcon(self):
    """
    清除所有按键的图标
    
    返回:
        int: 操作结果状态码
    """
    self.transport.clearAllKeys()

触摸屏控制方法

设置触摸屏图像

@abstractmethod
def set_touchscreen_image(self, image):
    """
    设置触摸屏背景图像
    
    参数:
        image (str): 图像文件路径
    
    返回:
        int: 操作结果状态码
    """
    pass

设备信息方法

获取设备路径

def getPath(self):
    """
    获取设备路径
    
    返回:
        str: 设备路径
    """
    return self.path

获取设备序列号

@abstractmethod
def get_serial_number(self, length):
    """
    获取设备序列号
    
    参数:
        length (int): 要读取的数据长度
    
    返回:
        bytes: 设备序列号数据
    """
    pass

获取设备ID

def id(self):
    """
    获取设备的物理标识符
    
    返回:
        str: 设备标识符
    """
    return self.getPath()

数据读取方法

获取设备反馈的信息

def read(self):
    """
    读取设备反馈信息
    
    返回:
        bytes: 设备返回的数据
    """
    data = self.transport.read_(13)
    return data

一直检测设备有无信息反馈，建议另起一个线程使用

def whileread(self):
    """
    持续监听设备反馈信息，建议在单独的线程中使用
    """
    while 1:
        try:
            data = self.read()
            if data != None and len(data) >= 11:
                if (data[:3].decode('utf-8', errors='ignore') == "ACK" and data[5:7].decode('utf-8', errors='ignore')):
                    if data[10] == 0x01 and data[9] > 0x00 and data[9] <= 0x0f:
                        if (self.KEY_MAP):
                            print("按键{}".format(KEY_MAPPING[data[9]]) + "被按下")
                        else:
                            print("按键{}".format(data[9]) + "被按下")
                    elif data[10] == 0x00 and data[9] > 0x00 and data[9] <= 0x0f:
                        if (self.KEY_MAP):
                            print("按键{}".format(KEY_MAPPING[data[9]]) + "抬起")
                        else:
                            print("按键{}".format(data[9]) + "抬起")
        except Exception as e:
            print("发生错误：")
            traceback.print_exc()
            break

事件回调方法

设置按键回调

def set_key_callback(self, callback):
    """
    设置按键状态变化回调函数
    
    参数:
        callback (function): 回调函数，接收参数 (device, key, state)
    """
    self.key_callback = callback

设置异步按键回调

def set_key_callback_async(self, async_callback, loop=None):
    """
    设置异步按键状态变化回调函数
    
    参数:
        async_callback (function): 异步回调函数
        loop (可选): asyncio 事件循环
    """
    import asyncio
    loop = loop or asyncio.get_event_loop()
    
    def callback(*args):
        asyncio.run_coroutine_threadsafe(async_callback(*args), loop)
    
    self.set_key_callback(callback)

设置触摸屏回调

def set_touchscreen_callback(self, callback):
    """
    设置触摸屏交互回调函数
    
    参数:
        callback (function): 回调函数
    """
    self.touchscreen_callback = callback

设置异步触摸屏回调

def set_touchscreen_callback_async(self, async_callback, loop=None):
    """
    设置异步触摸屏交互回调函数
    
    参数:
        async_callback (function): 异步回调函数
        loop (可选): asyncio 事件循环
    """
    import asyncio
    loop = loop or asyncio.get_event_loop()
    
    def callback(*args):
        asyncio.run_coroutine_threadsafe(async_callback(*args), loop)
    
    self.set_touchscreen_callback(callback)

图像格式方法

获取按键图像格式

@abstractmethod
def key_image_format(self):
    """
    获取按键图像格式信息
    
    返回:
        dict: 包含图像格式信息的字典
    """
    pass

获取触摸屏图像格式

@abstractmethod
def touchscreen_image_format(self):
    """
    获取触摸屏图像格式信息
    
    返回:
        dict: 包含图像格式信息的字典
    """
    pass

按键映射

按键映射转换

def key(self, k):
    """
    根据设备配置转换按键编号
    
    参数:
        k (int): 原始按键编号
    
    返回:
        int: 转换后的按键编号
    """
    if (self.KEY_MAP):
        return KEY_MAPPING[k]
    else:
        return k

设备属性

每个 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 实例)

FeatrueOption 类

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

class FeatrueOption:
    def __init__(self):
        self.hasRGBLed = False      # 是否支持 RGB LED
        self.ledCounts = 0          # LED 数量
        self.supportConfig = False  # 是否支持配置

LED 控制方法

设置 LED 亮度

def set_led_brightness(self, percent):
    """
    设置设备 LED 的亮度

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

    返回:
        int: 操作结果状态码，如果设备不支持 LED 则返回 None
    """
    if self.feature_option.hasRGBLed:
        return self.transport.set_led_brightness(percent)

设置 LED 颜色

def set_led_color(self, r, g, b):
    """
    设置设备 LED 的颜色

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

    返回:
        int: 操作结果状态码，如果设备不支持 LED 则返回 None
    """
    if self.feature_option.hasRGBLed:
        return self.transport.set_led_color(self.feature_option.ledCounts, r, g, b)

重置 LED 效果

def reset_led_effect(self):
    """
    重置设备的 LED 效果到默认状态

    返回:
        int: 操作结果状态码，如果设备不支持 LED 则返回 None
    """
    if self.feature_option.hasRGBLed:
        return self.transport.reset_led_color()