docs: add bilingual project documentation
This commit is contained in:
@@ -1,5 +1,7 @@
|
||||
# PIGWay Yahboom Cooling HAT
|
||||
|
||||
## 中文
|
||||
|
||||
独立运行的本机硬件插件。当前驱动：Yahboom RGB Cooling HAT（MCU 0x0D、OLED 0x3C、128×32）。提供本机状态采集、OLED 展示、风扇温控和 RGB 灯效。无需安装监控主程序即可使用。
|
||||
|
||||
## 安装与独立运行
|
||||
@@ -48,3 +50,50 @@ OLED 与 RGB 各自一个线程，风扇有独立温控线程；访问同一总
|
||||
## 卸载
|
||||
|
||||
`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
|
||||
|
||||
```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`.
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
4c7ba2b738c924561a634befd22032830b480d230c11d7f56eee7ddf72911b60 README.md
|
||||
54a8cb9285746eced6900227e999e280bfae58b5974c67f430d45fe389092c55 README.md
|
||||
93bde984cdce2326601ac808fe55022fe68d9d624b9dcf4ff8b023613418b3c4 install.sh
|
||||
cd6bb5137dd5922e48866f6daf4b949a16f8fad321e77addd5b4f75181bc4248 uninstall.sh
|
||||
1c7836f80b0845fbc5c4b8570b12d736e2a3c442b1ceb5d35d48cdd518e4ad50 app/drivers/yahboom.py
|
||||
|
||||
Reference in New Issue
Block a user