docs: refine language switch links

README.md

@@ -1,18 +1,21 @@
 # PIGWay Yahboom Cooling HAT
 
-独立运行的本机硬件插件。当前驱动：Yahboom RGB Cooling HAT（MCU 0x0D、OLED 0x3C、128×32）。提供本机状态采集、OLED 展示、风扇温控和 RGB 灯效。无需安装监控主程序即可使用。
+[简体中文](README.zh-CN.md) | 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
 ```
 
-启用 I2C 后安装；需要 python3-smbus2、python3-pil。安装器检查文件及总线占用，不停止其他进程。配置：`/etc/pigway-cooling-hat.conf`。
+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
@@ -21,30 +24,26 @@ 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。
+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
 
-安装时可选择允许接入，默认否；非交互安装默认关闭。关闭时不创建 API socket，本机采集、显示和温控继续运行。也可修改 `/etc/pigway-cooling-hat.conf` 的 `[integration] enabled = true/false` 并重启插件。`--disable-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.
 
-可选接入 [PIGWay Device Agent 监控平台](https://tea.pigway.com/way/pigway-device-agent)，接收服务、进程和系统健康告警。双方独立安装、独立运行；不接入也可正常使用本地功能。
+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.
 
-[独立 Web 管理中心](https://tea.pigway.com/way/pigway-device-console) → 系统配置 → 硬件插件中发现并手动接入。协议是本机 Unix socket 上的 HTTP API，默认不开放 TCP 端口。目录 0750、socket 0660，只有 root 和被明确加入 `pigway-hardware` 组的账户能访问。不要随意授予组成员资格。
+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`.
 
-监控发送完整、带版本和有效期的状态；不发送动画帧或 MCU 指令。插件自己仲裁 OLED 页和 RGB 效果。告警页有页码并轮播主页，相同 RGB 效果不因切页重启。只有一个有效监控来源可以持有显示状态，重复/乱序版本会拒绝。状态超过 10 秒未更新（由客户端声明，允许3–30秒），旧告警失效，OLED 回到本机主页、RGB 回到正常灯效，风扇继续本地温控。主动断开行为相同。监控快照中的 system/network 字段保留 API v1 兼容，但不会覆盖插件的本地数据。采样失败显示 --，不伪装为零。
+### RGB behavior and known limitations
 
-详情：[API v1](docs/HARDWARE_PLUGIN_API.md)。未来其他厂商或 GPIO/PWM 风扇应实现相同能力接口及独立驱动，不复用本板 I2C 寄存器。板上 MCU 的唯一进程所有权通过固定的物理设备文件锁 `/run/lock/pigway-i2c-1-mcu-0d.lock` 保证（不随 API socket 路径变化）；其他不遵守此锁的软件仍需自行避免运行。
+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.
 
-## RGB 与已知限制
+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.
 
-内置呼吸支持为每类告警独立选择红、绿、蓝、黄、紫、青、白，可在 Web 插件配置或 `[rgb]` 的 `<对象>_breathe_color` 中设置。默认 MCU 内置呼吸：CPU红、电源黄、内存紫、存储白、网络蓝、服务青；严重等级使用速度档1/2/3，可配置。速度档不是精确秒数，预置色不支持任意 RGB 或橙色呼吸。相同 effect/speed/color 不重复下发，无周期性“预热”。
+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.
 
-自定义颜色常亮和闪烁仍保留。闪烁是实验性兼容路径：全选→R→全选→G→全选→B，每条间隔5ms；亮灭均完整写三个通道，灭灯写 RGB=0；实际每段至少 `custom_min_hold_ms`（最低1500ms），从指令完成后计时，不追赶延迟边沿。既往实机曾出现异色/漏执行，未证明存在完全稳定的自定义协议，不宣称这些限制能修好 MCU。
+### Uninstall
 
-OLED 与 RGB 各自一个线程，风扇有独立温控线程；访问同一总线时串行，完整 RGB 写入不能被风扇插入。风扇仅写0x08，不补写RGB。OLED 字体随插件提供。
-
-## 卸载
-
-`sudo ./uninstall.sh` 只移除此插件，保留配置，不修改监控项目或其他服务。先在监控 Web 断开插件可避免离线条目。
+`sudo ./uninstall.sh` removes only this plugin, preserves its configuration, and does not modify the Device Agent or any other service.

README.zh-CN.md

@@ -0,0 +1,53 @@
+# PIGWay Yahboom Cooling HAT
+
+简体中文 | [English](README.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 断开插件可避免离线条目。

SHA256SUMS

@@ -1,13 +1,14 @@
-4c7ba2b738c924561a634befd22032830b480d230c11d7f56eee7ddf72911b60  README.md
-93bde984cdce2326601ac808fe55022fe68d9d624b9dcf4ff8b023613418b3c4  install.sh
-cd6bb5137dd5922e48866f6daf4b949a16f8fad321e77addd5b4f75181bc4248  uninstall.sh
+550d29437a0a7642b4e881b4266ce363905fef546736437b6d63ce47fc76229a  README.md
+ee8a07c7f83550fb34ff862d5d63cb499ef94f491177d6321c2bf6bf76a4d17c  README.zh-CN.md
 1c7836f80b0845fbc5c4b8570b12d736e2a3c442b1ceb5d35d48cdd518e4ad50  app/drivers/yahboom.py
+7ca33e7a4361673d153b5e6212447d53091e223ee05ec24411083d6c052f2894  app/local_state.py
 215a62acc0a5c87303d6c52c0a2585b87dfb5cdbafbe9e9e733523d48a6a9812  app/migrate.py
 72c46162c33f9587c6ccb01ad53fbaaf4ecec8cd21014b909e87e8707e253e36  app/oled_font_5x7.bin
-1803eebf7917291587204db85f74e2009e87f3a7b27a194b1aba245aa49b442b  app/runtime.py
+48755a51a15fd6a02098b185d1b17c6746502bd07dc74ac54ac76b4f8581b4db  app/runtime.py
 af4a97339c805b5471149da29699d465cb76b20a8f1da7ad8af8e32d4a2fc827  app/service.py
-413548a4b38ac3ad32712c92df5e7cd4e9ef2603872ca201d3e4df8c50dbad4a  app/settings.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

app/runtime.py

@@ -167,10 +167,11 @@ class Controller:
             self.stop_event.wait(1)
 
     def oled_loop(self):
-        last=None;last_time=0
+        last=None;last_time=0;last_alert_ids=None
         while not self.stop_event.is_set():
             try:
                 v=self.view();page=v['page'];system=v['system'];network=v['network'];home=False
+                alert_ids=tuple(a['id'] for a in v['alerts'])
                 if page=='NORMAL_HOME':
                     home=True
                     ip=network.get('ip','NO IP');label=network.get('ip_label','IP4')
@@ -189,7 +190,18 @@ class Controller:
                     lines=[(a['title'],f"{index}/{len(v['alerts'])}"),(a['l2'],''),(a['l3'],''),(a['l4'],'')]
                 state=(lines,home)
                 if state!=last or self.clock()-last_time>=v['config']['oled']['refresh_seconds']:
-                    self.driver.oled(lines,home);last=state;last_time=self.clock()
+                    self.driver.oled(lines,home)
+                    # Alert recovery changes only a few header pixels (for
+                    # example 1/2 -> 1/1). Confirm that rare topology change
+                    # with a second complete frame: during undervoltage an
+                    # OLED transfer can be only partly applied without an
+                    # I2C exception being reported by the controller.
+                    if last_alert_ids is not None and alert_ids!=last_alert_ids:
+                        self.stop_event.wait(.05)
+                        if not self.stop_event.is_set():self.driver.oled(lines,home)
+                    last=state
+                    last_time=self.clock()
+                    last_alert_ids=alert_ids
                 self.recovered('oled')
             except Exception as exc:self.error('oled',exc)
             self.stop_event.wait(.1)

app/settings.py

@@ -3,7 +3,7 @@ import configparser
 import math
 from pathlib import Path
 
-VERSION = "1.0.0"
+VERSION = "1.0.1"
 PLUGIN_ID = "yahboom-cooling-hat"
 COLORS = {"red":0,"green":1,"blue":2,"yellow":3,"purple":4,"cyan":5,"white":6}
 EFFECTS = {"flow":0,"breathe":1,"marquee":2,"rainbow":3,"colorful":4}