Pigway Pi Control v3.3.0 P0 System Health

Raspberry Pi 4B + 配套 128×32 OLED / 风扇 / RGB 散热扩展板的本机硬件监控 Agent。

v3.3.0 的目标不是增加 Web/API，而是先把 P0 本地检测、事件状态、日志、诊断和关机收尾补完整，为后续多机 NAS 监控 API 打基础。

已有核心功能

• SSD1306 128×32 OLED，四行固定主页
• CPU / 内存 / 温度 / 磁盘监控
• Wi-Fi RSSI / Ethernet 链路速率
• 当前默认路由与 IP 同步切换
• 风扇自动温控、回差防抖
• RGB：颜色表示故障对象，闪烁速度表示严重程度
• systemd 服务与普通进程监控
• Raspberry Pi PWR / ACT 运行时 Dark Mode

主页示例：

CPU 18.6%   MEM 16.2%
TMP 46.3C   FAN OFF
DSK 22.4%   WIF -32
IP4 192.168.89.130

v3.3.0 P0 新增

1. 供电与降频健康

周期读取：

vcgencmd get_throttled

区分：

• 当前欠压：立即 POWER LOW / UNDERVOLT 告警
• 当前 CPU throttled / frequency capped：立即告警
• 本次启动历史上曾欠压/降频：只写一次历史事件日志，不持续 RGB 告警
• 状态恢复：写 RECOVERED 类事件

注意：这里检测的是 Pi 的供电质量，不是 UPS 电池百分比。

2. 文件系统健康

检测根文件系统 / 是否被内核切成只读。如果出现只读状态，产生严重告警：

FILESYSTEM RO
ROOT READ ONLY
CHECK STORAGE

3. 本机诊断信息

内部维护：

• uptime
• load average
• CPU 当前频率
• 当前/历史 throttled flags
• 当前主网络接口 / IP
• 根文件系统只读状态
• sensor / network / service / health 最近成功时间
• 主循环异常计数
• I²C相关异常计数基础字段

4. 结构化事件日志

日志继续交给 systemd journal，不额外制造长期 .log 文件。

只在 状态发生变化 时记录关键事件，避免每秒刷屏。例如：

level=INFO event=START version=3.3.0
level=INFO event=NET_SWITCH old_if=eth0 new_if=wlan0 ...
level=WARN event=NETWORK_DOWN ...
level=INFO event=NETWORK_RECOVERED ...
level=WARN event=WATCH_DOWN name=AWESUN ...
level=INFO event=WATCH_RECOVERED name=AWESUN ...
level=WARN event=POWER_LOW raw=0x1
level=INFO event=POWER_RECOVERED raw=0x0
level=WARN event=ALERT_ACTIVE alert=TEMP_HIGH ...
level=INFO event=ALERT_RECOVERED ...

实时查看：

journalctl -u pigway-pi-control -f

只看本次启动：

journalctl -u pigway-pi-control -b --no-pager

搜索某类事件：

journalctl -u pigway-pi-control --no-pager | grep 'event=POWER'

5. 诊断命令

sudo /usr/local/sbin/pigway-pi-control --diagnose

用于快速查看 uptime、load、CPU频率、throttled、根文件系统、当前网络和 Internet 状态。后续排障优先使用该命令，不再反复手工拼大量 grep。

6. 关机收尾

收到 systemd SIGTERM / 系统关机时：

1. 写 STOP 日志
2. RGB OFF
3. 风扇 OFF
4. OLED 清屏并 Display OFF
5. 关闭 I²C handle

Pi 红色 PWR 灯关机后恢复硬件默认亮起的行为不强行修改，可作为“系统已关机但 UPS 仍供电”的直观提示。

用户配置

正式配置只有一个：

/etc/pigway-pi-control.conf

编辑：

sudo nano /etc/pigway-pi-control.conf
sudo systemctl restart pigway-pi-control

配置文件内已经写明每项用途、单位和修改方式。

安装 / 升级测试分支

sudo ./install.sh

安装器会：

• 安装必要依赖
• 检查 I²C
• 禁用旧 temp-control.service
• 安装字体、程序、配置和 systemd unit
• 保留用户已有 [services] / [processes]
• 启动服务
• 执行版本、OLED、UI、P0健康监控和诊断入口自检

常用命令

systemctl status pigway-pi-control --no-pager -l
journalctl -u pigway-pi-control -f
sudo systemctl restart pigway-pi-control
sudo /usr/local/sbin/pigway-pi-control --diagnose

版本路线

• v3.2.0：主网络接口 / Wi-Fi RSSI / ETH速率 / 双网切换
• v3.3.0：P0 System Health，本地检测与日志完善
• 后续：只读 /api/v1/... Agent API，再由 NAS 统一汇总多台设备