andyjusa/hydroshift2-rs
GitHub: andyjusa/hydroshift2-rs
非官方 Rust 库，通过 USB 直接控制联力 HydroShift II LCD-C 散热器的 LCD 显示、RGB 灯效与水泵风扇，无需官方 L-Connect 软件。
Stars: 0 | Forks: 0
# hydroshift2
**非官方的 Lian Li HydroShift II LCD-C Rust 协议与 USB 控制库**
[](https://github.com/andyjusa/hydroshift2-rs/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.rust-lang.org/)
无需 L-Connect 进程、DLL、服务或网络连接。
## 控制功能
| 表面 | 功能 |
|---|---|
| 圆形 LCD | 480×480 JPEG 背景与透明 PNG overlay |
| LCD 控制 | 亮度、0°/90°/180°/270° 旋转、时钟/会话设置 |
| 水泵圆环 | 24 个可寻址 RGB LED，静态帧与上传的动画 |
| 散热 | 1600–2500 RPM 的水泵目标映射以及三个风扇控制字节 |
| 传输 | 直接 USB bulk endpoint `0x01` / `0x81` |
该 crate 同时公开了高级的 [`HydroShiftII`] 控制器和无状态的
[`Protocol`] packet 编码器。USB、图像编码以及内置的 TinyUZ 支持
均由 feature flag 控制。
## 快速入门
```
[dependencies]
hydroshift2 = { git = "https://github.com/andyjusa/hydroshift2-rs" }
```
```
use hydroshift2::{HydroShiftII, Rotation};
fn main() -> hydroshift2::Result<()> {
// Claims the USB interface and clears retained vendor LCD layers.
let mut device = HydroShiftII::open_and_initialize()?;
device.set_lcd_brightness(220)?;
device.set_rotation(Rotation::Degrees0)?;
device.set_pump_speed(2025, [0, 0, 0])?;
// One RGB frame uses the dependency-free Rust TinyUZ encoder.
device.set_static_rgb([0, 232, 255], 0.8)?;
// A 64-frame, 20 FPS loop is compressed once and played by the device.
device.set_rainbow()?;
Ok(())
}
```
打开设备不会改变其状态：
```
use hydroshift2::HydroShiftII;
let device = HydroShiftII::open()?;
// Call initialize_lcd() only when you want to clear the retained LCD layers.
# Ok::<(), hydroshift2::Error>(())
```
### 发送 LCD 图像
```
use hydroshift2::HydroShiftII;
fn main() -> hydroshift2::Result<()> {
let image = image::open("dashboard.png")?;
let mut device = HydroShiftII::open_and_initialize()?;
device.send_image(&image, 90)?;
Ok(())
}
```
硬件显示屏在物理上是圆形的，但其传输的画布是一个
正方形 480×480 图像。请在你的渲染器中对可见的圆进行遮罩或合成。
## RGB 动画模型
水泵圆环不需要为每个动画帧进行一次主机 USB 写入。一批
帧会被 TinyUZ 压缩，通过命令 `0xFC` 上传，然后由控制器按照
提供的间隔进行播放。`set_rainbow()` 会以 50 毫秒的间隔（20 FPS）上传 64 帧。
- 单帧更新使用内置的纯 Rust 编码器。
- 多帧上传在 Windows 上使用锁定的官方 TinyUZ 1.1.1 压缩器，因为已知该表示形式能被 H2
固件接受。
- 该可执行文件采用 MIT 许可证，经过 SHA-256 校验，在构建时嵌入，并在需要时
提取到 `%LOCALAPPDATA%/hydroshift2-rs/tinyuz/1.1.1/`。
- 其他平台可以将 `TinyUzCli::from_path(...)` 传递给
`send_rgb_frames_with(...)`。
## 协议说明
每条控制消息都以一个 500 字节的明文 header 开头。该 header
使用 PKCS#7 padding 进行 DES-CBC 加密，放置在一个 512 字节的信封中，并以
`A1 1A` 结尾。图像和 RGB payload 跟在该信封之后。
| 命令 | 用途 | Payload 详情 |
|---:|---|---|
| `0x65` | JPEG LCD 背景 | header `8..12` 处的大端字节长度 |
| `0x66` | PNG LCD overlay | header `8..12` 处的大端字节长度 |
| `0x0D` | LCD 旋转 | 一个字节，`0..3` |
| `0x0E` | LCD 亮度 | 一个字节，`0..255` |
| `0x33` | 设备时钟 | UTC 日期/时间和显示模式 |
| `0xFB` | 水泵/风扇控制 | 带 CRC-16/CCITT 的 16 字节块 |
| `0xFC` | 24-LED 圆环帧 | TinyUZ 数据 + 帧数 + 间隔 + LED 数量 |
`Protocol::*_at` 变体接受显式的时间戳，用于 packet-capture
比较和确定性测试。
## 功能
| 功能 | 默认 | 描述 |
|---|:---:|---|
| `usb` | ✓ | `rusb` 发现与 bulk 传输 |
| `image` | ✓ | JPEG/PNG 编码与干净的 LCD 初始化 |
| `bundled-tinyuz` | ✓ | 用于多帧 RGB 的锁定版 Windows x64 TinyUZ |
仅使用协议的消费者可以禁用所有功能：
```
hydroshift2 = {
git = "https://github.com/andyjusa/hydroshift2-rs",
default-features = false
}
```
## 安全性
- 在声明 USB 接口之前请关闭 L-Connect。两个控制器同时写入
同一设备将发生竞争，并可能留下陈旧的 LCD 或 RGB 状态。
- 水泵请求被限制在观察到的 1600–2500 RPM 范围内。
- `open()` 仅声明接口；`open_and_initialize()` 会有意
清除两个保留的 LCD 合成层。
- 请将所有逆向工程的硬件控制视为风险自负的操作。
## 示例与验证
```
cargo run --example probe
cargo run --example static_rgb
cargo run --example rainbow
cargo run --example lcd_image -- path\to\dashboard.png
cargo test --all-features
```
最初的实现已在
[SpatialLume](https://github.com/andyjusa/SpatialLume) 中得到应用，其中 LCD 和圆环
独立于 L-Connect 进行驱动。
## 许可证
该 Rust 库基于 [MIT 许可证](LICENSE) 提供内置的。
TinyUZ 二进制文件保留其上游的 MIT 许可证；请参阅
[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。标签：LCD屏幕, RGB灯效, Rust, USB通信, 可视化界面, 散热管理, 硬件控制, 网络流量审计, 通知系统