PIGWay Cooling HAT

独立运行的本机硬件插件。当前驱动：Yahboom RGB Cooling HAT（MCU 0x0D、OLED 0x3C、128×32）。不需要安装 PIGWay Pi Control；也不会自动启动它。

安装与独立运行

sudo ./install.sh
# 只安装，不启动/启用新服务：
sudo ./install.sh --no-start
# 显式迁移旧集成版的硬件设置：
sudo ./install.sh --import-monitor-config /etc/pigway-pi-control.conf

启用 I2C 后安装；需要 python3-smbus2、python3-pil。安装器检查文件及总线占用，不停止其他进程。配置：/etc/pigway-cooling-hat.conf。

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

未接入监控时，OLED 显示独立运行与本机温度，风扇执行本地温控，RGB 采用正常灯效配置，默认全灭。 温度传感器读取失败时请求风扇全速；停止插件时也请求全速并关闭 OLED/RGB，避免因退出显示程序而取消散热。硬件故障时不能保证执行成功，错误会记录日志。风扇无转速反馈，只报告设置档位，不伪造 RPM。

接入监控

监控 Web → 系统配置 → 硬件插件中发现并手动接入。协议是本机 Unix socket 上的 HTTP API，默认不开放 TCP 端口。目录 0750、socket 0660，只有 root 和被明确加入 pigway-hardware 组的账户能访问。不要随意授予组成员资格。

监控发送完整、带版本和有效期的状态；不发送动画帧或 MCU 指令。插件自己仲裁 OLED 页和 RGB 效果。告警页有页码并轮播主页，相同 RGB 效果不因切页重启。只有一个有效监控来源可以持有显示状态，重复/乱序版本会拒绝。状态超过 10 秒未更新（由客户端声明，允许3–30秒），旧告警失效，OLED 显示连接中断、RGB 请求关闭，风扇继续本地温控。主动断开则回独立运行。

详情：API v1。未来其他厂商或 GPIO/PWM 风扇应实现相同能力接口及独立驱动，不复用本板 I2C 寄存器。板上 MCU 的唯一进程所有权通过固定的物理设备文件锁 /run/lock/pigway-i2c-1-mcu-0d.lock 保证（不随 API socket 路径变化）；其他不遵守此锁的软件仍需自行避免运行。

RGB 与已知限制

默认 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 断开插件可避免离线条目。