pigway-device-agent/README.md

# Pigway Pi Control v3.1.0 — Release

适用于本套 Raspberry Pi 4B 散热扩展板的正式发布版。

本包遵循一个原则：

> **一个程序 + 一个用户配置文件 + 一个说明文档。**

正常使用时，不需要修改源码。

---

## 1. 功能

### OLED

配套 OLED 按卖家原生参数锁定为：

- SSD1306
- 128×32
- I²C `0x3C`
- MUX `0x1F`
- COM Pins `0x02`
- Page `0..3`
- 卖家同源 5×7 点阵字体
- 4行：`0 / 8 / 16 / 24`

主页：

```text
CPU 18.6%   MEM 16.2%
TMP 46.3C   FAN OFF
DSK 22.4%   NET OK
IP4 192.168.89.130
```

IPv6 地址时自动显示 `IP6`。

主页左右两栏都是固定位置、左对齐。数据默认每秒刷新。

有告警时，OLED 会在 HOME 与所有当前告警之间轮播；默认每页停留10秒。

### 风扇

默认：

```text
< 50°C      OFF
50~53°C     L1
53~56°C     L2
56~59°C     L3
59~62°C     L4
>= 62°C     MAX
```

带降档回差，避免临界温度反复升降档。

### RGB 告警

正常状态 RGB 完全熄灭。

颜色表示“什么对象出问题”：

```text
CPU       黄
温度      红
内存      紫
磁盘      橙
网络      蓝
服务/进程 青
```

所有告警都使用闪烁；闪烁速度表示严重程度：

```text
Warning    慢
Critical   中
Emergency  快
```

亮度可配置，默认10%，适合暗环境。

### Dark Mode

默认关闭 Raspberry Pi 自身：

- PWR LED
- ACT LED

散热板 D1/D8 黄色硬件状态灯和独立电源模块绿色灯不属于已确认的软件控制接口，本程序不操作。

---

## 2. 全新 Raspberry Pi OS 安装

### 第一步：启用 I²C

```bash
sudo raspi-config
```

进入：

```text
Interface Options
→ I2C
→ Enable
```

然后：

```bash
sudo reboot
```

### 第二步：解压本安装包

进入解压后的目录：

```bash
cd pigway-pi-control-v3.1.0
```

### 第三步：安装

```bash
sudo ./install.sh
```

安装器会：

1. 检查 `/dev/i2c-1`
2. 等待 APT/DPKG 锁
3. 安装必要的小型系统依赖
4. 检查 I²C 总线
5. 自动停止并禁用卖家旧 `temp-control.service`
6. 安装正式程序
7. 安装用户配置
8. 安装 systemd 服务并开机自启
9. 执行安装后自检

安装成功后查看：

```bash
systemctl status pigway-pi-control --no-pager -l
```

---

## 3. 安装后的文件在哪里

### 用户应该修改

只有：

```text
/etc/pigway-pi-control.conf
```

编辑：

```bash
sudo nano /etc/pigway-pi-control.conf
```

保存后：

```bash
sudo systemctl restart pigway-pi-control
```

### 用户通常不要修改

程序：

```text
/usr/local/sbin/pigway-pi-control
```

systemd：

```text
/etc/systemd/system/pigway-pi-control.service
```

这些由安装包维护。

因此安装成功后，解压出来的 `pigway-pi-control-v3.1.0/` 文件夹可以删除。

建议把 ZIP 保存到 Mac / NAS，供以后重装。

---

## 4. 用户可以自定义什么

全部集中在：

```text
/etc/pigway-pi-control.conf
```

其中包括：

- 数据采样周期
- OLED刷新周期
- 告警页面停留时间
- 网络检查周期
- 服务检查周期
- 风扇温度曲线
- 风扇降档回差
- CPU告警阈值和持续时间
- 内存告警阈值和持续时间
- 温度普通/严重告警
- 磁盘普通/严重告警
- RGB亮度
- Warning/Critical/Emergency 闪烁周期
- Pi PWR/ACT灯
- 要监控的systemd服务
- 要监控的普通进程

**每个参数在配置文件中都已经写有详细中文注释。**

---

## 5. 增加一个服务监控

编辑：

```bash
sudo nano /etc/pigway-pi-control.conf
```

找到：

```ini
[services]
SSH = ssh.service
AWESUN = runawesun.service
```

例如安装了 Tailscale：

```ini
TAILSCALE = tailscaled.service
```

保存后：

```bash
sudo systemctl restart pigway-pi-control
```

先确认服务真实名称：

```bash
systemctl status tailscaled.service
```

暂时不想监控，行首加 `#`：

```ini
# TAILSCALE = tailscaled.service
```

---

## 6. 监控没有 systemd service 的程序

配置：

```ini
[processes]
MYAPP = /opt/myapp/server
```

先测试：

```bash
pgrep -af '/opt/myapp/server'
```

能找到进程再加入监控。

---

## 7. 常用维护

状态：

```bash
systemctl status pigway-pi-control --no-pager -l
```

日志：

```bash
journalctl -u pigway-pi-control -f
```

重启：

```bash
sudo systemctl restart pigway-pi-control
```

停止：

```bash
sudo systemctl stop pigway-pi-control
```

启动：

```bash
sudo systemctl start pigway-pi-control
```

查看配置：

```bash
cat /etc/pigway-pi-control.conf
```

---

## 8. 升级

新版安装包直接：

```bash
sudo ./install.sh
```

安装器会保留用户已有的 `[services]` 和 `[processes]` 监控列表，并备份旧配置。

升级后检查：

```bash
systemctl status pigway-pi-control --no-pager -l
```

---

## 9. 卸载

在安装包目录执行：

```bash
sudo ./uninstall.sh
```

卸载程序默认保留：

```text
/etc/pigway-pi-control.conf
```

避免误删用户自定义配置。

确认以后不再使用时可手工删除：

```bash
sudo rm /etc/pigway-pi-control.conf
```

---

## 10. 重装树莓派时最短流程

以后即使完全忘记之前怎么安装，只需要：

```text
1. 安装 Raspberry Pi OS
2. raspi-config 开启 I²C
3. 重启
4. 解压本 ZIP
5. cd pigway-pi-control-v3.1.0
6. sudo ./install.sh
```

完成。