claygorman/aw5d-linux
GitHub: claygorman/aw5d-linux
在 Linux 下原生驱动 iBUYPOWER AW5/AW5D 散热器的圆形 LCD 屏幕显示实时 CPU 状态，无需厂商 Windows 软件。
Stars: 3 | Forks: 0
# aw5d-linux
[](https://github.com/claygorman/aw5d-linux/actions/workflows/ci.yml)
[](LICENSE)
[-8A2BE2)](#作者与-ai-披露)
在 **Linux** 下驱动 **iBUYPOWER AW5 / AW5D** 360 mm AIO 散热器的圆形 LCD 屏幕 — 无需 Windows，无需厂商软件。
AW5D 原厂自带的“数字仪表盘”（巨大的 CPU 温度数值、旋转的风扇、彩色圆弧和进度条）是由散热器自带的固件绘制并生成动画的。主机只需要**每秒推送一个 64 字节的 USB-HID report**，其中包含实时的 CPU 状态数据即可。本项目正是实现了这一功能，直接从 Linux 内核读取温度 / 使用率 / 频率 — 从而让屏幕在原生环境下直接运行。
## 为什么会有这个项目
在 liquidctl、CoolerControl 或任何社区项目中，都**没有**对该散热器的 Linux 支持 — 厂商只提供了一个 Windows 应用程序 (HYTE Nexus)。不过，这款散热器本身只是一个标准的 USB-HID 设备，Linux 可以直接与其进行通信。完整的逆向工程过程和字节级别的协议记录在 [**RESEARCH.md**](RESEARCH.md) 中。
## 工作原理（简述）
驱动程序大约每 1 秒向散热器的 `hidraw` 节点写入 HID **output report `0x10`**（64 字节）：
| 偏移量 | 字段 | 备注 |
|---|---|---|
| 0 | `0x10` | report ID |
| 1 | `0x08` | 常量 (packet type) |
| 2 | **CPU 使用率 %** | `0–100`，同时也驱动风扇旋转动画 |
| 3–4 | **CPU 频率 (MHz)** | 大端序 `uint16` — 精确值，例如 `0x0EA9` = 3753 |
| 5 | **CPU 温度 °C** | 整数 — 屏幕上显示的大号数字 |
| 9 | 蓝色温度圆弧 | 装饰性仪表等级 |
| 10 | 橙色频率条 | 装饰性仪表等级 |
| 11 | 绿色使用率条 | 装饰性仪表等级 |
| 12 | `0xF0` / `0xF9` | 正常 / 高负载样式标志 |
**没有握手、唤醒或初始化包** — 你只需打开设备并进行写入即可。
传感器数据来自 sysfs：`k10temp` (Tctl) 提供温度，`/proc/stat` 提供使用率，`cpufreq` 提供平均核心频率。所有代码均使用 Python 3 标准库 — 没有 pip 依赖。
## 环境要求
- 连接了散热器 USB 接口的 Linux（`lsusb` 会显示 `ID 3402:0407`）
- Python 3.8+
- 开箱即用的 AMD Ryzen 主机，支持温度传感器（`k10temp` / `zenpower`）；系统也会探测 Intel 的 `coretemp`。只要将 `--temp-input` 指向正确的 `hwmonN/tempN_input`，任何 CPU 都可以兼容。
## 安装
```
git clone https://github.com/claygorman/aw5d-linux
cd aw5d-linux
./install.sh
```
`install.sh` 会将驱动程序放置在 `~/.local/share/aw5d-lcd/` 目录下，安装一个 udev 规则以实现免 root 写入设备，并启用带有 lingering 功能的 **systemd 用户服务** — 这样即使在开机时或你从未进行图形界面登录的情况下（或你的合成器崩溃到桌面时），屏幕也能更新并持续工作。
可以使用 `./install.sh --uninstall` 进行卸载。
## 手动 / 测试
直接运行驱动程序（无需安装）：
```
# 显示检测到的设备 + sensors
python3 aw5d_lcd.py --list
# 打印将要发送的内容，而不触碰设备
python3 aw5d_lcd.py --dry-run --verbose
# 发送一帧并退出
python3 aw5d_lcd.py --once --verbose
# 运行 live loop（按 Ctrl-C 停止）
python3 aw5d_lcd.py --verbose
```
实用参数：`--interval SECONDS`, `--device /dev/hidrawN`,
`--temp-input /sys/class/hwmon/hwmonN/tempN_input`。
管理已安装的服务：
```
systemctl --user status aw5d-lcd
systemctl --user restart aw5d-lcd
journalctl --user -u aw5d-lcd -f
```
## 配置
**更新间隔** — 驱动程序向 LCD 推送新 CPU 状态的频率（默认为 **1 秒**）。
可以通过三种方式进行设置（按优先级从高到低排列）：
```
# 1. 直接运行时的 CLI flag：
python3 aw5d_lcd.py --interval 2
# 2. Env var — 已安装的服务会读取 ~/.config/aw5d-lcd.env：
echo 'AW5D_INTERVAL=2' > ~/.config/aw5d-lcd.env
systemctl --user restart aw5d-lcd
# 3. 或者使用完整的 systemd override，如果您愿意：
# systemctl --user edit aw5d-lcd → 添加 [Service] / 空白的 ExecStart= / 新的 ExecStart=…
```
`install.sh` 会为你生成一个带有注释的 `~/.config/aw5d-lcd.env` 文件（参见
[`aw5d-lcd.env.example`](aw5d-lcd.env.example))；在重新安装时该文件永远不会被覆盖。
## 权限
udev 规则 (`udev/99-aw5d-lcd.rules`) 会将 AW5D 的 `hidraw` 节点权限设置为 `0666`，以便非 root（以及无会话的 lingering）服务能够驱动它。它只是一个内部散热器显示屏，并非安全边界；如果你的威胁模型有所不同，请自行调整权限模式/用户组。
## 法律 / 净室声明
这是一个独立的、基于净室（clean-room）原则的重新实现，基于我们自己对硬件行为的**观察**，旨在实现**互操作性**。它**不包含**任何厂商代码：没有反编译的源码，没有捆绑的可执行文件，也没有固件。"iBUYPOWER"、"AW5"、"HYTE" 和 "Nexus" 是其各自所有者的商标；本项目与它们没有任何附属关系或受其认可。
使用风险自负。向 `hidraw` 设备写入数据本质上是底层操作；虽然本项目仅发送上述的小型状态报告，但不提供任何担保（参见 [LICENSE](LICENSE))。
## 作者与 AI 披露
为了保持透明：**本仓库中的代码和文档是由 AI 编写的** — 即 Anthropic 的 Claude (Claude Code, Opus 4.x) — 它与 **Clay Gorman** 进行了交互式协作。Clay 拥有相关硬件，主导了逆向工程过程，从运行中的设备捕获了 USB/HID 协议，并在物理散热器上测试了所有结果。该协议是通过黑盒观察得出的（参见 [RESEARCH.md](RESEARCH.md)）；Claude 基于这一共同调查编写了驱动程序、打包脚本和文档。
如果你正在评估本项目的可信度，坦诚说明的意义正是在于此：这只是一个体积小巧、无依赖、可审计的 Python 脚本，仅向 `hidraw` 设备写入已记录的状态报告。请在运行前自行阅读。
## 许可证
[MIT](LICENSE) © 2026 Clay Gorman
标签：USB-HID, 云资产清单, 散热控制, 硬件监控, 硬件驱动, 逆向工程