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
```bash
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`.
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](https://tea.pigway.com/way/pigway-device-agent) integration delivers service, process, and system-health alerts. Both projects install and run independently. The [PIGWay Device Console](https://tea.pigway.com/way/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](docs/HARDWARE_PLUGIN_API.md). 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.
