way/pigway-device-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity
51 Commits 17 Branches 5 Tags
9babcfabc1543272e2efdca43c51ea1557a7f001
T
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE

README.md

PIGWay Pi Control v3.7.0

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

v3.7.0 在现有本机硬件监控基础上增加多机状态、日志和配置管理；未登记其他节点时继续作为完整的单机版本运行。

已有核心功能

  • 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.5.0 System Health

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. DisplayController、OLED 与 RGB

每个当前故障都是 DisplayController 中的一个 active request，包含稳定 ID、priority、severity、OLED 显示数据、首次发现时间、最后变化时间和元数据。监控只提交或清除 request，同一轮采样作为一个原子批次，全部更新后只仲裁一次。DisplayController 始终只选一个最高优先级 owner；同一 ID 更新原请求而不重复入队，恢复时删除请求，同优先级新 request 排队而不抢占，owner 恢复后按 priority、first_seen、ID 重新仲裁。OLED 在主页和全部当前告警页之间轮播，告警页右上角显示 当前页/告警总数，新 owner 会立即抢占一次 OLED。告警页显示时 RGB 同步表达该页对象；回到主页时 RGB 保持最高优先级 active owner，全部恢复后才 OFF。历史 power flags 只进入 diagnose 和一次性 Journal 记录。

5. RGB 正常状态与告警引擎

没有 active alert 时，RGB 默认全灭。[led] normal_mode 可改为自定义颜色常亮/闪烁，或 MCU 已确认的流水、呼吸、跑马、彩虹和炫彩效果。常亮与闪烁使用 0..255 的自定义 R/G/B；内置流水/呼吸使用 MCU 固定的红、绿、蓝、黄、紫、青、白七色和慢/中/快三档速度，跑马/彩虹/炫彩由 MCU 自行配色。内置效果只在模式切换时按 speed → color → effect 的实机校准顺序写一次寄存器，不循环刷 I²C。

任何 active alert 都会立即抢占正常效果。RGB 告警模式由当前 OLED 告警页决定；OLED 位于主页时则使用最高优先级 active owner。颜色表示故障对象：CPU负载、频率、throttling、温度与散热相关为红色，供电/欠压为橙色，内存为紫色，存储为白色，网络/Wi-Fi 为蓝色，服务/进程为青色。频率表示严重等级：默认 Warning 为1500ms亮/1500ms灭，Critical 为750ms亮/750ms灭，Emergency 为300ms亮/300ms灭。[led] 可分别配置六类对象的 R/G/B 值，以及三个严重等级的亮灯和灭灯时长，非法颜色值会限制到0..255，间隔最小为50ms。每次点亮使用 v3.2.0 已验证的完整 selector/R/G/B 写入顺序，只在亮/灭边沿写 MCU，不做高频软件 PWM。相邻页面 RGB mode 相同时不关闭、不重启节奏。动画不写循环日志，owner 变化记录 DISPLAY_OWNER，实际模式变化才记录 RGB_MODE。

6. 结构化事件日志

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

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

level=INFO event=START version=3.7.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'

7. 诊断命令

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

输出 Agent 版本、系统 uptime、配置路径、load、CPU 频率、根文件系统、全部当前/历史 power 位、主网络接口、完整 IP 和 Internet 状态，以及所有 service/process watch 状态。

诊断使用与运行时相同的配置和检查函数；仅以 I²C receive-byte 读取探测 MCU 0x0D / OLED 0x3C，失败显示 MISSING/ERROR，不初始化或写入风扇、RGB、OLED。独立诊断进程无法获取正在运行的服务的内存计数，故 loop_errors / i2c_errors 明确标记 UNAVAILABLE；服务退出的 STOP 事件包含该次运行计数。

RGB 保留卖家 MCU 0x0D 寄存器协议。实机校准确认静态自定义颜色配合低频亮灭最稳定；每次点亮完整写入 selector/R/G/B，寄存器间隔默认10ms。旧版 brightness、呼吸周期和颜色选项可以继续留在用户配置中，但频闪引擎会忽略它们。

8. 关机收尾

收到 systemd SIGTERM / 系统关机时：

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

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

v3.7.0 多机监控

每台机器在 [device] 中设置稳定标识和显示名称；保留 auto 时读取本机 hostname。作为 Web 聚合入口的机器可在 [hosts] 中登记其他已安装 PIGWay Pi Control 的节点：

[device]
identifier = living-room
name = 客厅树莓派

[hosts]
study = http://192.168.1.20:6001
nas-room = http://192.168.1.21:6001

未设置 [hosts] 时，API 和 Web 保持单机使用方式。聚合入口通过各节点现有 HTTP API 读取状态、journal 和配置；节点不可达时会在机器卡片上显示离线，不影响其他节点。

新增接口：

GET /api/v1/hosts
PUT /api/v1/hosts
GET /api/v1/fleet/status
GET /api/v1/fleet/logs
PUT /api/v1/fleet/config

运行状态按机器显示独立卡片，包括机器标识、hostname、型号、序列号、板卡版本、操作系统、内核、架构、CPU 核数和 Agent 版本。内存和根分区同时显示百分比、已用量、总量及可用/剩余量；Wi-Fi 以 0–100% 为主值，并保留原始 dBm。OLED 的 Wi-Fi 主值同样使用百分比。

事件日志增加机器列、机器筛选和机器排序。系统配置可选择目标机器；批量同步只发送当前已修改的配置项，并逐台返回成功或失败结果。远端 Bearer Token 只保存在当前浏览器的 localStorage 中，不写入聚合机器配置文件。

v3.6.0 API 与 Web

安装后访问：

http://树莓派IP:6001/

Web 与 JSON API 由独立的 pigway-pi-control-api.service 提供。API 服务不访问 I²C；硬件 Agent 每秒原子更新 /run/pigway-pi-control/status.json，API 只读取该快照。默认监听地址和端口可在 [api] 中修改：

[api]
bind = 0.0.0.0
port = 6001
log_limit = 200

只读接口：

GET /api/v1/health
GET /api/v1/status
GET /api/v1/logs?limit=200
GET /api/v1/config
GET /api/v1/services

日志接口支持 since、until Unix 时间戳，severity、event、search 筛选，timestamp / severity / event / message 排序，以及 limit / offset 分页。Web 提供今天、昨天、本周、本月和全部快捷范围。日志直接读取 systemd journal 的现有保留数据，不建立重复的 SQLite 日志副本。

Web 界面支持中文和 English 切换，并将结构化 journal 事件类型显示为当前界面的语言；journal 内部稳定的事件标识保持不变，便于脚本筛选。外观可选择自动、深色或浅色，自动模式跟随浏览器/操作系统配色。语言和外观偏好只保存在当前浏览器中。

配置写入接口：

PUT /api/v1/config
Authorization: Bearer <token>
Content-Type: application/json

{"updates":{"led":{"service_b":"96"},"api":{"port":"6001"}}}

服务监控页面会列出本机 systemd 服务，并标识“已监控/未监控”。添加、编辑或删除监控使用 PUT /api/v1/services；启动或停止服务使用 PUT /api/v1/services/control，两者均要求 Bearer Token。API 服务不能通过自己的请求停止自身，其他服务由用户自行管理。监控备注保存在配置文件的 [service_notes]，不会参与硬件 Agent 的监控判断。

“暂停监控/恢复监控”只改变 PIGWay 是否检查该服务，不会启动或停止 systemd unit；暂停状态保存在 [service_monitor_disabled]。只有明确标注为“启动服务/停止服务”的按钮才会调用 systemctl。

读取 token：

sudo cat /etc/pigway-pi-control-api.token

配置更新仅允许 [services]、[processes]、[alerts]、[fan]、[led]、[timing]、[dark_mode]、[display] 和 [api]。每次写入先生成时间戳备份，再原地更新目标键并重启硬件 Agent；修改 [api] 时 API 服务也会自动重启。

用户配置

正式配置只有一个：

/etc/pigway-pi-control.conf

编辑：

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

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

安装 / 升级测试分支

sudo ./install.sh

安装器会：

  • 安装必要依赖
  • 检查 I²C，并在安装前检测 /dev/i2c-1 是否被其他 OLED/LED 控制进程占用
  • 发现冲突时列出进程并退出，由用户决定如何处理；安装器不会停止、禁用或杀死其他服务
  • 确认需要多个进程共用 I²C 时，可用 sudo ./install.sh --force-i2c-conflict 强制继续；冲突进程仍由用户自行管理
  • 安装字体、程序、配置和 systemd unit
  • 完整保留用户现有配置（包括所有 section、用户值和注释），仅补入缺失的 [led] 和 [api] 选项，已有用户值优先
  • 生成只读 root token，安装 API/Web 文件
  • 启动硬件 Agent 与 API/Web 服务
  • 执行版本、OLED、UI、P0健康监控和诊断入口自检

常用命令

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

版本路线

  • v3.2.0：主网络接口 / Wi-Fi RSSI / ETH速率 / 双网切换
  • v3.5.0：System Health、显示仲裁与可配置 RGB 告警
  • v3.6.0：轻量状态/日志/配置 API 与同源 Web 管理界面
  • v3.7.0：多机状态卡片、聚合日志、机器配置选择与批量同步
Reference in New Issue View Git Blame Copy Permalink
S
Description
轻量本地设备监控与可选 API / Lightweight local device monitoring with an optional API.
Readme
237 KiB
Releases 3
PIGWay Device Agent v3.7.0
Latest
2026-09-27 23:18:04 +08:00
Languages
Python 92.7%
Shell 7.3%