leabergero/k1pro-opendeck-suite

# K1 Pro OpenDeck Suite  为在 Linux 上全面且稳定地使用 **HOTSPOTEK / Mirabox Stream Dock K1 Pro** —— 一款配备 **6 个 LCD 按键**、**3 个旋钮/编码器**和一个 **RGB 环**的 stream-controller 设备（USB `5548:1025`）—— 而创建的 [OpenDeck](https://github.com/nekename/OpenDeck)（Elgato Stream Deck 软件的自由跨平台替代方案）插件套件。 ## 本项目解决的问题 K1 Pro 仅有封闭的 Windows/macOS 官方软件。在 Linux 上，由于缺乏驱动，设备会停留在其“standalone”模式（固件的内部菜单），无法用作可编程控制器。本项目： 1. 将设备的专有 USB/HID 协议（通过逆向工程获取的协议，详见 `CREDITS.md`）作为 OpenDeck 插件实现 —— 即 **真正的驱动程序** (`opendeck-k1pro-plugin`)。 2. 添加了 3 个通用插件，用于解决 OpenDeck 在 Wayland/Linux 上的局限性。这些插件并非 K1 Pro 专属，而是为了完善该控制器在日常使用中的体验而开发的：在按键上播放 GIF 动画、使用旋钮导航配置文件，以及在 Wayland 会话中可靠地分配键盘组合键。 ## 目标硬件 - **驱动程序的必要条件**：HOTSPOTEK / Mirabox Stream Dock K1 Pro（USB `5548:1025`，固件协议 v3，布局为 2×3 LCD + 3 个旋钮）。 - **其他 3 个插件为通用插件**：可在任何 OpenDeck 设备上运行（不依赖于 K1 Pro 协议），但旨在完善其使用体验。 - **操作系统**：Linux（已在 Ubuntu 24.04, Wayland 上测试）。K1 Pro 驱动程序目前仅支持 Linux；其他 3 个插件在清单中也声明支持 Windows/macOS，但仅在 Linux 上进行了验证。 ## 包含的插件 | 插件 | 功能 | 依赖 K1 Pro | |---|---|---| | [`opendeck-k1pro-plugin`](opendeck-k1pro-plugin/) | 驱动程序：检测设备，向 6 个 LCD 发送图像，控制 RGB 环，转发旋钮事件 | 是（即驱动程序） | | [`opendeck-gif-player`](opendeck-gif-player/) | 在任何带 LCD 的按键上循环播放 `.gif` 动画，+ 可选的按下触发动作 | 否（通用） | | [`opendeck-menu-navigator`](opendeck-menu-navigator/) | 通过旋转旋钮来切换 OpenDeck 的配置文件，无需触摸屏幕 | 否（通用） | | [`opendeck-key-macro`](opendeck-key-macro/) | 通过直接输入分配按键/组合键（`ctrl+del`、`ctrl+v` 等），并自动生成图标 | 否（通用） | 每个插件都有自己的 `README.md`，其中包含完整的描述、要求和特定的安装说明。此处仅作概述。 ### `opendeck-k1pro-plugin` —— 驱动程序 实现了设备的“CRT”协议：握手/keepalive、向 6 个 LCD 按键发送 64×64 的 JPEG 图像、控制 RGB 环（颜色、效果、亮度、速度）、将 3 个旋钮（旋转 + 按下）读取为 OpenDeck 的 encoder，以及通过手势（旋钮1三连击）在软件模式和固件原生菜单之间切换，无需拔插设备。 ### `opendeck-gif-player` OpenDeck 不会将指定为静态图标的 `.gif` 制作为动画（仅发送单帧）。此插件会解码 GIF，并按照每一帧的原生速度执行自己的 `setImage` 循环。在按下按键时，可选择打开 URL、执行命令/程序或模拟组合键。 ### `opendeck-menu-navigator` 使用 OpenDeck 的原生 Profiles（而非自定义菜单系统），并通过旋钮进行循环切换：一个用于循环“组”（由 Profile 名称中的前缀定义，即 `" - "` 之前的部分），另一个用于循环该组内的“子菜单”。旨在让您无需触摸屏幕即可切换动作集。 ### `opendeck-key-macro` OpenDeck 原生的“Simulated Input”动作使用 `enigo` crate，该 crate 在 Linux 上默认通过 X11/XTest 模拟按键 —— 这无法到达原生的 Wayland 窗口（仅适用于 XWayland），并且许多 Wayland 合成器出于安全考虑会阻止这些事件。此插件使用 `ydotool`（通过 `/dev/uinput` 进行内核级注入），在 X11 或 Wayland 下均可同等工作，并添加了别名映射器，支持以纯文本形式输入 `ctrl+del`、`pgup`、`pgdn` 等。按键图标会根据组合名称自动生成，并支持自定义背景（自定义图像或纯黑）、字体大小、粗体和斜体。 ## 常规要求 - 已安装并正在运行的 **OpenDeck**（[官方说明](https://github.com/nekename/OpenDeck)）。 - **Rust**（2024 版，最新的稳定版 toolchain）+ 目标平台 `x86_64-unknown-linux-gnu`，用于编译任何插件。 - [`just`](https://just.systems) 和 `zip`，用于打包。 - 对于 `opendeck-key-macro`：需要运行 `ydotool` + `ydotoold`（具体步骤见其 README）。 ## 快速安装（4 个插件） 每个插件的编译和打包方式相同： ``` cd just package ``` 这将生成 `build/com.community..sdPlugin/` 目录和一个可安装的 `.zip` 文件。在 OpenDeck 中：选择 **Plugins → Install from file**，然后选择该 `.zip` 文件。驱动程序 `opendeck-k1pro-plugin` 还需要 udev 规则 —— 完整的分步说明请参阅其 README。 ## 致谢与来源 请参阅 [`CREDITS.md`](CREDITS.md) 获取完整的归属信息：K1 Pro 协议的来源、使用的库/crates，以及每个组件的许可证。 ## 许可证 GPLv3 —— 详见 [`LICENSE`](LICENSE)。驱动程序 `opendeck-k1pro-plugin` 包含一个 vendoreada 的依赖项 (`vendor-mirajazz`)，采用 MPL-2.0 许可证，与 GPLv3 兼容。

标签：Linux桌面工具, OpenDeck插件, USB/HID协议, 可视化界面, 宏键管理, 直播控制台, 硬件驱动, 通知系统