alexpedrozawd/pichau-aqua-240x-linux-driver

# pichau-aqua-240x-linux-driver [](https://github.com/alexpedrozawd/pichau-aqua-240x-linux-driver/actions/workflows/ci.yml) [](LICENSE) **Pichau Aqua 240X** 一体式水冷散热器水泵屏幕的非官方 Linux 驱动。 目前没有针对该设备的官方 Linux 驱动——制造商只提供了一个 Windows 应用程序 （"PC SmartMonitor LED"）。如果没有它，水泵上的小屏幕会永远卡在显示 **"88"** 的状态。 本项目对官方 Windows 应用程序的通信协议进行了逆向工程，并从零开始将其重新实现为一个 小巧且独立的 Python 驱动，使得该屏幕可以在 Linux 上显示真实的 CPU/GPU 状态信息。 *(葡萄牙语：葡萄牙语版本请参见 [README.pt-BR.md](README.pt-BR.md)。)* ## 这适合我吗？ 本项目是专为 **Pichau Aqua 240X** 构建和测试的。该水泵的显示芯片是 QinHeng/WCH "Temp-DISP"（USB `1a86:484a`）。如果你的散热器使用了完全相同的芯片——这在 贴牌产品中很常见，因为制造商（Guangzhou Haiji Intelligent Technology）作为一家 OEM/ODM 厂商， 会为多个经销商提供这种屏幕的白标产品——那么这款驱动程序很可能对你也适用。 可以使用以下命令检查： ``` lsusb | grep -i 1a86 ``` 如果返回了一行结果，那就可以使用。如果没有，则此驱动无济于事（但如果你正在对 使用同系列芯片的其他设备进行逆向工程，[协议分析文档](docs/PROTOCOL.md) 可能仍会为你节省不少时间）。 ## 测试环境 在此如实说明，而不是仅仅宣称具有广泛的兼容性： | 组件 | 已确认可用 | 已实现，但未亲自验证 | |---|---|---| | 发行版 | Ubuntu 24.04 LTS | Debian, Mint, Pop!_OS, Fedora, RHEL/CentOS Stream, Arch, Manjaro, EndeavourOS, openSUSE, Alpine（任何 `install.sh` 能检测到包管理器的基于 systemd 的发行版） | | CPU | Intel（通过 `coretemp`） | AMD（`k10temp`/`zenpower`） | | GPU | NVIDIA（`nvidia-smi`） | AMD（`amdgpu` sysfs） | “未亲自验证”一列中的内容是作者基于对这些系统工作原理的最佳理解（匹配真实的 hwmon 驱动名称、各个发行版的真实包名等）正确编写的，并且没有已知的不可用理由——只是尚未在那些实际的硬件或发行版上运行过。 **如果你在该列的某个系统上进行了尝试，无论结果如何（成功或失败），在 GitHub issue 中提交一份报告都会非常有帮助**——参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 功能说明 - 自动检测屏幕（通过 USB 供应商/产品 ID，而不是固定的设备路径，因此即使设备以不同名称枚举，也能继续工作）。 - 从 Linux 内核读取**真实的** CPU 温度、频率、利用率和内存（RAM）使用情况。 - 读取**真实的** GPU 温度/利用率/核心时钟/显存（VRAM）/风扇——优先尝试 NVIDIA（`nvidia-smi`）， 自动回退到 AMD（`amdgpu` sysfs）。没有 GPU，或者是不支持的 GPU？驱动程序仍能正常 运行，只是会将 GPU 相关字段发送为 `0`。 - 每秒发送一次更新——这与原始 Windows 应用程序使用的间隔相同（已通过 反编译确认）。 - 作为后台服务运行，开机自启并保持存活。 ## 安装说明 ``` git clone https://github.com/alexpedrozawd/pichau-aqua-240x-linux-driver.git cd pichau-aqua-240x-linux-driver ./install.sh ``` `install.sh` 旨在兼容自 2020 年以来的任何基于 systemd 的发行版（Debian, Ubuntu、 Linux Mint, Pop!_OS, Fedora, RHEL/CentOS Stream, Arch, Manjaro, EndeavourOS, openSUSE 等）。 它会检测你的包管理器（`apt`, `dnf`, `yum`, `pacman`, `zypper` 或 `apk`）并执行以下操作： 1. 如果缺少 `python3` 和 `pyserial`，则进行安装（优先使用原生发行版包，以 `pip3 --user` 作为备选方案）。 2. 安装 `udev` 规则，以便你的用户无需 `sudo` 即可访问设备，无论是现在还是 在未来的重启后。 3. 安装驱动程序以及一个 `systemd --user` 服务来自动启动它。 系统会要求你输入 `sudo` 密码——它仅用于三件事：安装缺失的 系统软件包、编写 `udev` 规则，以及将你的用户添加到 `dialout` 组中。 脚本本身永远不会以 root 身份运行，除了这三个步骤外，它不会触碰任何其他内容。 **不包含也不需要原始 Windows 应用程序中的任何内容。**仅使用了通过分析它（记录在 [docs/PROTOCOL.md](docs/PROTOCOL.md)）得出的协议 知识来编写这个独立的客户端。 ### 卸载说明 ``` ./uninstall.sh ``` 移除服务、已安装的驱动程序文件以及 `udev` 规则。保留 `python3`/`pyserial` 和你的 `dialout` 组成员身份不变（它们是通用组件，不应由本项目移除）。 ## 可靠性：它能承受重启和断电吗？ 是的——这是构建本项目时的硬性要求，而不是事后补救。三件事保证了它的可靠性： 1. **`systemd --user` 服务，`enabled` + `Restart=always`。** 如果驱动程序崩溃或 USB 设备暂时不可用，systemd 会自动每 5 秒重启一次，直到成功为止。 2. **`loginctl enable-linger`**，由 `install.sh` 自动应用。通常，`--user` systemd 服务仅在你登录时运行。Linger 会指示 `systemd` 在开机时启动你的用户服务管理器， 无论你是否曾登录——这在无人值守开启会话的断电情况下非常重要。 3. **不依赖于活动桌面会话的 `udev` 规则。** 授予设备权限的简单方法（仅使用 `TAG+="uaccess"`）仅在真实的登录/会话处于活动状态时适用。在无人登录的冷启动时， 仅靠该规则将导致服务无法打开设备。 `install.sh` 还会将你的用户添加到 `dialout` 组，并设置一个静态的 `GROUP="dialout", MODE="0660"` 规则，该规则完全不依赖于任何活动的会话。 最终效果：拔掉电源，重新插上，机器启动，并且——一旦 Linux 本身完成启动且桌面/USB 子系统准备就绪——屏幕就会在无人触碰键盘的情况下再次开始显示真实状态。 一个注意事项（这也是 Linux 中各组权限到处适用的工作方式）：如果这是你的*首次*安装，`dialout` 组成员身份只有在你的**下次登录**（或重启）后才会完全生效。`install.sh` 通过授予一次性的 ACL 权限，为*当前*会话规避了这个问题，因此该服务在安装后也会立即开始工作——但如果你在首次运行时遇到权限错误，只需注销并重新登录一次，此后权限即会永久生效。 ## 监控原理 运行后，驱动程序会无限循环（直到被停止），每秒执行以下操作一次： 1. 读取 CPU 温度（`/sys/class/hwmon`，依次尝试 Intel `coretemp` 和 AMD `k10temp`/`zenpower`， 如果都未找到则回退到通用的 `acpitz` 传感器）、频率（`/proc/cpuinfo`）、 利用率（`/proc/stat` 增量）和内存（RAM）使用情况（`/proc/meminfo`）——全部直接从 内核读取，无需任何额外的软件包。 2. 如果存在，则通过 `nvidia-smi` 读取 GPU 状态，否则通过 `amdgpu` 内核驱动的 sysfs 文件 读取。 3. 将所有这些打包成屏幕所期望的 23 字节帧（参见 [docs/PROTOCOL.md](docs/PROTOCOL.md)），按照与原始应用程序相同的方式进行混淆，并将其写入 设备的串行端口。 4. 向日志输出一行状态（`journalctl --user -u pichau-display.service -f`）并休眠 1 秒。 如果写入失败（例如你拔掉了线缆），它会关闭端口，等待，并尝试 重新连接——它不会崩溃，也不需要手动重启。 ## 手动测试 / 高级用法 `tools/test_frame.py` 发送一个特定值（或循环发送），而不会干扰正在运行的 服务——这对于确认屏幕是否有响应，或者调试并非 Aqua 240X 但共享相同芯片的设备非常有用： ``` python3 tools/test_frame.py --scan # where is the device? python3 tools/test_frame.py --cpu-temp 42 --gpu-temp 55 # send once python3 tools/test_frame.py --cpu-temp 42 --gpu-temp 55 --loop # send every second until Ctrl+C ``` 如果你不需要 systemd 服务，主驱动程序也可以独立运行： ``` python3 pichau_display_driver.py ``` ## 运行测试套件 ``` pip install pytest # or: sudo apt install python3-pytest / equivalent for your distro python3 -m pytest tests/ ``` 这些测试涵盖了帧构建/限制逻辑以及有状态的传感器读取器，并且不需要 水泵屏幕（或任何特定的硬件）即可运行。它们也会在每次推送时通过 [GitHub Actions](.github/workflows/ci.yml) 自动运行，同时对安装脚本执行 `shellcheck`。 ## 故障排除 - **没有任何反应 / 屏幕一直显示 "88"：** 确认设备是否出现（`lsusb | grep 1a86`） 并且存在 `/dev/ttyACM*`（`ls /dev/ttyACM*`）。如果你只能看到 `/dev/hidraw*` 而没有 `/dev/ttyACM*`，可能是你的内核没有加载 USB CDC-ACM 驱动——请在插入线缆后检查 `dmesg | tail`。 - **权限被拒绝：** 参见上面的可靠性章节——首次 安装后注销/登录一次。 - **服务未运行：** 使用 `systemctl --user status pichau-display.service` 和 `journalctl --user -u pichau-display.service -f` 查看日志。 - **GPU 数值始终显示为 0：** 你要么使用的是不受支持的 GPU 供应商（目前仅实现了 NVIDIA 和 AMD），要么是 `nvidia-smi`/`amdgpu` 驱动在你的环境中不可用。 ## 免责声明 这是一个独立且非官方的项目，不附属于 Pichau、屏幕的 OEM 制造商或原始 Windows 应用程序的作者。它是通过观察合法购买的设备如何通过 USB 进行通信，并对随附软件进行逆向工程以实现互操作性而构建的，这是开源硬件社区中的标准做法（参见 [OpenRGB](https://openrgb.org/)、[liquidctl](https://github.com/liquidctl/liquidctl) 以及类似的项目）。不包含任何专有的代码或二进制文件。 按“原样”提供，不提供任何保证。向 USB 设备发送格式错误的数据极不可能造成任何损坏（此协议仅控制一个小型数字屏幕的显示内容），但你需自行承担使用风险。 ## 许可证 [MIT](LICENSE)

标签：Linux驱动, Python, 云资产清单, 无后门, 硬件交互, 硬件协议, 逆向工具, 逆向工程