54 lines
4.5 KiB
Markdown
54 lines
4.5 KiB
Markdown
# PIGWay Yahboom Cooling HAT
|
||
|
||
简体中文 | [English](README.md)
|
||
|
||
|
||
独立运行的本机硬件插件。当前驱动：Yahboom RGB Cooling HAT（MCU 0x0D、OLED 0x3C、128×32）。提供本机状态采集、OLED 展示、风扇温控和 RGB 灯效。无需安装监控主程序即可使用。
|
||
|
||
## 安装与独立运行
|
||
|
||
```bash
|
||
sudo ./install.sh
|
||
# 允许监控接入（默认关闭）：
|
||
sudo ./install.sh --enable-integration
|
||
# 只安装，不启动/启用新服务：
|
||
sudo ./install.sh --no-start
|
||
```
|
||
|
||
启用 I2C 后安装；需要 python3-smbus2、python3-pil。安装器检查文件及总线占用，不停止其他进程。配置：`/etc/pigway-cooling-hat.conf`。
|
||
|
||
```bash
|
||
sudo systemctl start pigway-cooling-hat.service
|
||
sudo journalctl -u pigway-cooling-hat.service -f
|
||
sudo python3 /usr/local/lib/pigway-cooling-hat/service.py --check-config
|
||
curl --unix-socket /run/pigway-plugins/yahboom-cooling-hat/api.sock http://localhost/v1/descriptor
|
||
```
|
||
|
||
无论是否接入监控，插件都自行采集 CPU、内存、温度、磁盘和主网络状态，OLED 主页显示本机数据，风扇执行本地温控，RGB 采用正常灯效配置，默认全灭。
|
||
温度传感器读取失败时请求风扇全速；停止插件时也请求全速并关闭 OLED/RGB，避免因退出显示程序而取消散热。硬件故障时不能保证执行成功，错误会记录日志。风扇无转速反馈，只报告设置档位，不伪造 RPM。
|
||
|
||
## 可选接入监控
|
||
|
||
安装时可选择允许接入，默认否；非交互安装默认关闭。关闭时不创建 API socket，本机采集、显示和温控继续运行。也可修改 `/etc/pigway-cooling-hat.conf` 的 `[integration] enabled = true/false` 并重启插件。`--disable-integration` 显式关闭。
|
||
|
||
|
||
可选接入 [PIGWay Device Agent 监控平台](https://tea.pigway.com/way/pigway-device-agent)，接收服务、进程和系统健康告警。双方独立安装、独立运行；不接入也可正常使用本地功能。
|
||
|
||
[独立 Web 管理中心](https://tea.pigway.com/way/pigway-device-console) → 系统配置 → 硬件插件中发现并手动接入。协议是本机 Unix socket 上的 HTTP API，默认不开放 TCP 端口。目录 0750、socket 0660，只有 root 和被明确加入 `pigway-hardware` 组的账户能访问。不要随意授予组成员资格。
|
||
|
||
监控发送完整、带版本和有效期的状态；不发送动画帧或 MCU 指令。插件自己仲裁 OLED 页和 RGB 效果。告警页有页码并轮播主页，相同 RGB 效果不因切页重启。只有一个有效监控来源可以持有显示状态，重复/乱序版本会拒绝。状态超过 10 秒未更新（由客户端声明，允许3–30秒），旧告警失效，OLED 回到本机主页、RGB 回到正常灯效，风扇继续本地温控。主动断开行为相同。监控快照中的 system/network 字段保留 API v1 兼容，但不会覆盖插件的本地数据。采样失败显示 --，不伪装为零。
|
||
|
||
详情：[API v1](docs/HARDWARE_PLUGIN_API.md)。未来其他厂商或 GPIO/PWM 风扇应实现相同能力接口及独立驱动，不复用本板 I2C 寄存器。板上 MCU 的唯一进程所有权通过固定的物理设备文件锁 `/run/lock/pigway-i2c-1-mcu-0d.lock` 保证（不随 API socket 路径变化）；其他不遵守此锁的软件仍需自行避免运行。
|
||
|
||
## RGB 与已知限制
|
||
|
||
内置呼吸支持为每类告警独立选择红、绿、蓝、黄、紫、青、白，可在 Web 插件配置或 `[rgb]` 的 `<对象>_breathe_color` 中设置。默认 MCU 内置呼吸：CPU红、电源黄、内存紫、存储白、网络蓝、服务青；严重等级使用速度档1/2/3，可配置。速度档不是精确秒数，预置色不支持任意 RGB 或橙色呼吸。相同 effect/speed/color 不重复下发，无周期性“预热”。
|
||
|
||
自定义颜色常亮和闪烁仍保留。闪烁是实验性兼容路径：全选→R→全选→G→全选→B，每条间隔5ms；亮灭均完整写三个通道，灭灯写 RGB=0；实际每段至少 `custom_min_hold_ms`（最低1500ms），从指令完成后计时，不追赶延迟边沿。既往实机曾出现异色/漏执行，未证明存在完全稳定的自定义协议，不宣称这些限制能修好 MCU。
|
||
|
||
OLED 与 RGB 各自一个线程，风扇有独立温控线程；访问同一总线时串行，完整 RGB 写入不能被风扇插入。风扇仅写0x08，不补写RGB。OLED 字体随插件提供。
|
||
|
||
## 卸载
|
||
|
||
`sudo ./uninstall.sh` 只移除此插件，保留配置，不修改监控项目或其他服务。先在监控 Web 断开插件可避免离线条目。
|