GOG1071/skydimo-linux

# skydimo-linux 适用于 **Skydimo “Rainbow Music LED”** USB LED 适配器（`SKYDIMO'ND RAINBOW MUSIC LED`）的 Linux 驱动、ambilight 和音乐响应引擎。 厂商仅提供 Windows 软件，且该适配器使用的是原版 [Hyperion](https://github.com/hyperion-project/hyperion.ng) 和 [HyperHDR](https://github.com/awawa-dev/HyperHDR) 不支持的协议——其 Windows 应用程序是一个更换了品牌名称的 HyperHDR 分支，带有一个私有的 LED 驱动（`DriverSerialSkydimondUsb`）。本项目重新实现了该协议，因此该灯带可以在 Linux 上运行。 已在配备 3440×1440 显示器的 Bazzite 44（Fedora/KDE Plasma 6, Wayland）上进行了测试。 该设计与发行版无关；屏幕捕获使用标准的 `xdg-desktop-portal` ScreenCast API，因此它可以在任何实现了该 API 的 Wayland 合成器以及 X11 上运行。 ## 功能特性 - **Ambilight（氛围光）** —— 将屏幕边缘画面镜像到灯带上，约 45 fps - **音乐响应** —— 频谱、VU 表（电平表）或脉冲效果，跟随正在播放的音频 - **一个 GTK4/libadwaita GUI** —— 包含所有设置选项，并提供直观的接线检查 - **一个 systemd 用户服务** —— 根据您的配置运行并在登录时启动 - **一个 CLI** —— 用于静态颜色、测试、校准和脚本编写 ## 安装说明 ``` git clone https://github.com/GOG1071/skydimo-linux.git cd skydimo-linux ./install.sh ``` 安装程序会自动识别您的发行版中如何命名它所需的那些系统包，提示您进行安装，然后在 `~/.local/share/skydimo` 下设置一个隔离的虚拟环境。除非您要求安装可选的 udev 规则，否则不会以 root 权限安装任何内容。 ``` ./install.sh --check # just report what is missing ./install.sh --udev # also install the ModemManager udev rule (sudo) ./install.sh --no-deps # skip the system-package step ./install.sh --uninstall # remove it again (your config is kept) ``` 然后设置 LED 数量——这是必须准确无误的一项设置： ``` skydimo gui # or launch "Skydimo" from your app menu # ...或者 headless： skydimo calibrate --leds 96 systemctl --user enable --now skydimo ``` ### 前置条件 Python 3.10+，以及来自您系统发行版的以下内容（安装程序会为您列出它们）：包含 **Gst**、**GstApp**、**Gtk 4.0** 和 **Adw 1** 类型库的 PyGObject、GStreamer 基础插件、GStreamer 的 **PipeWire** 插件（`pipewiresrc`），以及来自 pulseaudio-utils 的 `parec`。 `numpy` 和 `pyserial` 会通过 pip 安装到虚拟环境中。故意*没有*安装 PyGObject——因为它无法通过 pip 可靠地安装，所以虚拟环境在创建时使用了 `--system-site-packages` 参数，以借用系统安装的版本。 在基于镜像的系统（Silverblue、Kinoite、Bazzite）上，安装程序会打印出 `rpm-ostree install` 命令而不是直接执行它，因为层叠安装需要重启才能生效。 ## 命令 | 命令 | 作用 | |---|---| | `skydimo gui` | 打开配置窗口 | | `skydimo info` | 适配器端口、设备 ID、LED 数量、布局、服务状态 | | `skydimo test` | 红/绿/蓝/白扫光，随后进行逐个点亮测试——用于验证接线 | | `skydimo color ` | 静态颜色：名称、`#rrggbb` 或 `r,g,b` | | `skydimo off` | 熄灭灯带 | | `skydimo calibrate` | LED 数量与布局向导（使用 `--leds N` 可跳过提问） | | `skydimo run` | 运行配置中指定的任何模式——即服务在后台执行的内容 | | `skydimo ambilight` | 将屏幕边缘的画面镜像到灯带上 | | `skydimo music` | 对播放的音频作出响应（使用 `--mode spectrum\|vu\|pulse`） | | `skydimo set k=v` | 读取或写入配置值 | `calibrate` 和 `test` 在占用灯带时会自动暂停引擎，随后将其恢复。`color` 和 `off` 则不会——运行中的引擎会在下一帧直接覆盖它们，因此它们会提示您改用停止服务的方式。 ## GUI - **Service（服务）** —— 启动/停止、登录时启动、ambilight/音乐模式 - **Strip（灯带）** —— LED 数量、颜色顺序 - **Layout（布局）** —— 覆盖的边缘、第一个 LED 所在的角落、走线方向、每条边的 LED 数量（根据检测到的显示器宽高比自动拆分，或手动输入）、采样深度 - **Picture（画面）** —— 亮度、gamma、饱和度、平滑度、最低电平、fps - **Music mode（音乐模式）** —— 样式和增益 - **Hands-on checks（直观检查）** —— 定位第一个 LED、逐个点亮测试、颜色扫光、静态颜色、全熄灭 所有编辑操作会在短暂停顿后自动保存。 ## 从终端调校 ``` skydimo set # list everything skydimo set gamma=1.5 # lower = brighter dark scenes (1.0 = off) skydimo set saturation=1.4 # colour punch skydimo set smoothing=0.5 # higher = lazier fades skydimo set brightness=0.7 # global cap skydimo set min_level=8 # faint floor so the strip never goes fully dark skydimo set zone_depth=0.18 # sample further in from the screen edge skydimo set fps=60 skydimo set mode=music ``` 配置文件位于 `~/.config/skydimo/config.json`。 `gamma` 默认为 1.8。屏幕像素本身已经进行了 sRGB 编码，因此完全采用 2.2 会进行过度校正，使暗色调的桌面看起来像关掉了一样；1.8 是通常的折中方案。将其降至 1.2–1.5 可以获得更明亮、更平淡的视觉效果。 ## 配置更改如何作用于运行中的引擎 单个服务单元会运行配置中指定的任意模式，因此切换模式并不意味着要切换服务。 - **Picture 设置** —— 亮度、gamma、饱和度、平滑度、最低电平、音乐增益 —— 会以每秒约两次的频率实时重新读取。无需重启，也没有画面中断。 - **结构设置** —— LED 数量、布局、颜色顺序、模式、帧率、捕获尺寸 —— 需要重新构建引擎。引擎会检测到更改，并在进程内销毁并重新初始化自身；服务将始终保持运行。 修改配置文件始终就足够了。您永远不需要手动重启任何东西。 ``` systemctl --user enable --now skydimo journalctl --user -u skydimo -f ``` ## Wayland 上的屏幕捕获 Wayland 下不存在“读取根窗口”的操作，因此屏幕捕获是通过 `xdg-desktop-portal` ScreenCast API 以及由 GStreamer 处理的 PipeWire 流来实现的。 首次运行时会请求一次权限；该 portal 的恢复令牌（restore token）会被保存到配置文件中，因此之后不会再次询问。要重新选择监视器： ``` skydimo set restore_token=null ``` ## 可选的强化设置 ModemManager 会在插入后的几秒钟内使用 AT 命令探测 CH340 串口桥，这可能会与握手过程发生冲突。驱动程序会进行重试，但直接让 ModemManager 忽略该端口是更干净的解决方案——使用 `./install.sh --udev`，或者手动设置： ``` sudo cp packaging/99-skydimo.rules /etc/udev/rules.d/ sudo udevadm control --reload-rules && sudo udevadm trigger ``` ## 通信协议 逆向工程得出的底层通信协议——包括 1 000 000 波特率、DTR 复位、`r`/`m` 握手、`Tn?` 帧头以及 Fletcher 校验尾部——均记录在 [`docs/PROTOCOL.md`](docs/PROTOCOL.md) 中，并详细说明了逆向恢复的过程。 简而言之，灯带在 Linux 上看似无响应的原因是：**适配器会锁定在数据模式，并且在 MCU 复位之前停止响应命令**，因此驱动程序必须在握手前将 DTR 拉低。Windows 的串口栈在打开端口时恰好会切换 DTR 状态；而 pyserial 和 Hyperion 则不会。 ## 安装目录结构 ``` ~/.local/share/skydimo/venv/ virtualenv (numpy, pyserial, skydimo) ~/.local/bin/skydimo launcher ~/.config/skydimo/config.json settings ~/.config/systemd/user/skydimo.service ~/.local/share/applications/skydimo.desktop ``` ## 故障排除 **未找到适配器** —— 通过 `lsusb` 检查是否存在 `1a86:7523`。使用 `skydimo set port=/dev/ttyUSB0` 显式指定端口。 **“Could not exclusively lock port”（无法独占锁定端口）** —— 引擎已经占用了它。 请使用 `systemctl --user stop skydimo`，或者使用 GUI 中的直观检查按钮，它们会自动为您完成控制权交接。 **握手反复失败** —— 有其他程序占用了该端口。请停止引擎并安装上述 udev 规则。 **点亮的 LED 数量不对，或者图案过早循环** —— LED 数量设置错误。请在 GUI 中修复它（**Strip → LED count**），这会重新构建分区。 **颜色出现在错误的边缘上** —— 使用 GUI 中的 **Identify the first LED** 按钮，设置与其匹配的 **First LED corner** 和 **Winding direction**，然后选择 **Auto-split**。如果每条边的数量仍然不正确，请手动输入到 **LEDs per edge** 中。 **红色显示为绿色** —— 使用 `skydimo set color_order=grb`（有效值包括：`rgb bgr rbg brg gbr grb`）。 **灯带太暗** —— 使用 `skydimo set gamma=1.3`，和/或使用 `skydimo set min_level=6`。 **音乐模式保持暗灭状态** —— 它监听的是默认输出设备的监视器源（monitor source），因此必须有声音正在播放。如果您的输出音量很低，可以尝试使用 `skydimo music --gain 2.0`。 **Ambilight 无法启动 / 没有权限对话框** —— 检查 `gst-inspect-1.0 pipewiresrc` 是否正常工作，并确认已安装 `xdg-desktop-portal` 以及适用于您桌面的后端。`SKYDIMO_DEBUG=1 skydimo ambilight` 会记录 portal 协商过程的每一步。 ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。 本项目与 Skydimo 无任何关联。HyperHDR 版权归其作者所有；此处不包含任何 HyperHDR 代码。

标签：GTK4, Linux驱动, Wayland, 云资产清单, 环境光照明, 逆向工具, 逆向工程, 音乐反应