docs: split English and Chinese readmes
This commit is contained in:
@@ -1,57 +1,7 @@
|
||||
# PIGWay Yahboom Cooling HAT
|
||||
|
||||
## 中文
|
||||
[English](README.md) | [简体中文](README.zh-CN.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 断开插件可避免离线条目。
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
@@ -0,0 +1,53 @@
|
||||
# PIGWay Yahboom Cooling HAT
|
||||
|
||||
[English](README.md) | [简体中文](README.zh-CN.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 断开插件可避免离线条目。
|
||||
+6
-5
@@ -1,13 +1,14 @@
|
||||
54a8cb9285746eced6900227e999e280bfae58b5974c67f430d45fe389092c55 README.md
|
||||
93bde984cdce2326601ac808fe55022fe68d9d624b9dcf4ff8b023613418b3c4 install.sh
|
||||
cd6bb5137dd5922e48866f6daf4b949a16f8fad321e77addd5b4f75181bc4248 uninstall.sh
|
||||
8085388297ce0907ee5b3b1339449200737cf0cb97847815e4902f1a3eae78f8 README.md
|
||||
044ad6ba47ae7baf2a67b7f74c7ff1e89b4e65fcecca56269b7ea28862dd6258 README.zh-CN.md
|
||||
1c7836f80b0845fbc5c4b8570b12d736e2a3c442b1ceb5d35d48cdd518e4ad50 app/drivers/yahboom.py
|
||||
7ca33e7a4361673d153b5e6212447d53091e223ee05ec24411083d6c052f2894 app/local_state.py
|
||||
215a62acc0a5c87303d6c52c0a2585b87dfb5cdbafbe9e9e733523d48a6a9812 app/migrate.py
|
||||
72c46162c33f9587c6ccb01ad53fbaaf4ecec8cd21014b909e87e8707e253e36 app/oled_font_5x7.bin
|
||||
48755a51a15fd6a02098b185d1b17c6746502bd07dc74ac54ac76b4f8581b4db app/runtime.py
|
||||
af4a97339c805b5471149da29699d465cb76b20a8f1da7ad8af8e32d4a2fc827 app/service.py
|
||||
4855303e4cd358635d4ba3877513e98042809f1ca9eaa14885ded8acadd20638 app/settings.py
|
||||
9bcac51c4e3a3d409885a3041ac121a20a48596bc47ee769c7af0b8f3772fa8d config/pigway-cooling-hat.conf
|
||||
c373cdde2b937bbc58d4b227f3a1d2923f0816c13f1e34548ed1f3b26c101ed5 systemd/pigway-cooling-hat.service
|
||||
e3bf3e7070ea62c0526791bed922688c3fb49fee36ca9c375d080119968feb72 docs/HARDWARE_PLUGIN_API.md
|
||||
7ca33e7a4361673d153b5e6212447d53091e223ee05ec24411083d6c052f2894 app/local_state.py
|
||||
93bde984cdce2326601ac808fe55022fe68d9d624b9dcf4ff8b023613418b3c4 install.sh
|
||||
c373cdde2b937bbc58d4b227f3a1d2923f0816c13f1e34548ed1f3b26c101ed5 systemd/pigway-cooling-hat.service
|
||||
cd6bb5137dd5922e48866f6daf4b949a16f8fad321e77addd5b4f75181bc4248 uninstall.sh
|
||||
|
||||
Reference in New Issue
Block a user