PIGWay Yahboom Cooling HAT

中文

独立运行的本机硬件插件。当前驱动：Yahboom RGB Cooling HAT（MCU 0x0D、OLED 0x3C、128×32）。提供本机状态采集、OLED 展示、风扇温控和 RGB 灯效。无需安装监控主程序即可使用。

安装与独立运行

sudo ./install.sh
# 允许监控接入（默认关闭）：
sudo ./install.sh --enable-integration
# 只安装，不启动/启用新服务：
sudo ./install.sh --no-start

启用 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

无论是否接入监控，插件都自行采集 CPU、内存、温度、磁盘和主网络状态，OLED 主页显示本机数据，风扇执行本地温控，RGB 采用正常灯效配置，默认全灭。 温度传感器读取失败时请求风扇全速；停止插件时也请求全速并关闭 OLED/RGB，避免因退出显示程序而取消散热。硬件故障时不能保证执行成功，错误会记录日志。风扇无转速反馈，只报告设置档位，不伪造 RPM。

可选接入监控

安装时可选择允许接入，默认否；非交互安装默认关闭。关闭时不创建 API socket，本机采集、显示和温控继续运行。也可修改 /etc/pigway-cooling-hat.conf 的 [integration] enabled = true/false 并重启插件。--disable-integration 显式关闭。

可选接入 PIGWay Device Agent 监控平台，接收服务、进程和系统健康告警。双方独立安装、独立运行；不接入也可正常使用本地功能。

独立 Web 管理中心 → 系统配置 → 硬件插件中发现并手动接入。协议是本机 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。未来其他厂商或 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 断开插件可避免离线条目。

English

An autonomous local hardware plugin for the Yahboom RGB Cooling HAT: MCU 0x0D, OLED 0x3C, 128×32. It provides local telemetry, OLED pages, temperature-based fan control, and RGB effects without requiring the Device Agent or Device Console.

Installation and standalone operation

sudo ./install.sh
# Allow local Agent integration; disabled by default:
sudo ./install.sh --enable-integration
# Install files without starting or enabling a new service:
sudo ./install.sh --no-start

Enable I2C before installation. The plugin requires python3-smbus2 and python3-pil. The installer validates required files and bus ownership without stopping unrelated processes. Configuration is stored in /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

The plugin always samples local CPU, memory, temperature, disk, and primary-network state. Its OLED shows local data, the fan follows local temperature control, and normal RGB lighting defaults to off. A temperature-read failure requests full fan speed. Shutdown also requests full speed and turns off OLED/RGB; hardware failure can still prevent those commands from succeeding. The board exposes no verified tachometer feedback, so the plugin reports only the requested fan level and never invents RPM values.

Optional Agent integration

Integration is disabled by default. When disabled, the API socket is not created, while local telemetry, display, cooling, and lighting continue normally. Enable it during installation or set [integration] enabled = true in /etc/pigway-cooling-hat.conf and restart the plugin. --disable-integration explicitly disables it.

The optional PIGWay Device Agent integration delivers service, process, and system-health alerts. Both projects install and run independently. The PIGWay Device Console can discover the plugin under System Configuration → Hardware Plugins and attach it manually.

The integration uses an HTTP API over a local Unix socket and opens no TCP port by default. The Agent sends complete, versioned, expiring state snapshots rather than MCU commands or animation frames. The plugin remains the sole owner of OLED arbitration, RGB effects, and fan control. Expired or explicitly released state returns the display to the local home page and normal RGB effect while cooling continues.

See Plugin API v1. Other vendors and GPIO/PWM fans should implement separate drivers behind the same capability boundary rather than reuse this board's I2C registers. Exclusive MCU ownership is coordinated with /run/lock/pigway-i2c-1-mcu-0d.lock.

RGB behavior and known limitations

Built-in breathing supports red, green, blue, yellow, purple, cyan, and white per alert category. Defaults are CPU red, power yellow, memory purple, storage white, network blue, and service cyan, with configurable severity speed levels 1–3. Preset colors do not provide arbitrary RGB or orange breathing.

Custom solid and flashing colors remain available as an experimental compatibility path. The calibrated sequence is select-all → R → select-all → G → select-all → B, with a 5 ms gap per command and complete RGB values for both on and off edges. Each edge lasts at least custom_min_hold_ms (minimum 1500 ms). Previous hardware tests observed occasional wrong colors and dropped writes, so the project does not claim that custom RGB behavior is fully reliable on this MCU.

OLED, RGB, and fan control use separate worker threads. Shared bus access is serialized so a complete RGB update cannot be interrupted by a fan write. The fan writes only register 0x08; the tracked OLED font ships with the plugin.

Uninstall

sudo ./uninstall.sh removes only this plugin, preserves its configuration, and does not modify the Device Agent or any other service.