2026-10-11 00:06:22 +08:00
|
|
|
|
# Raspberry Pi OS Lite（Debian 13 Trixie）全新安装
|
|
|
|
|
|
|
|
|
|
|
|
[English](RASPBERRY_PI_OS_TRIXIE_FRESH_INSTALL.md) | 简体中文
|
|
|
|
|
|
|
|
|
|
|
|
## 兼容性结论
|
|
|
|
|
|
|
2026-10-11 16:29:26 +08:00
|
|
|
|
PIGWay Raspberry Pi Agent v3.7.1 兼容 Raspberry Pi OS Lite 64-bit、Debian 13 Trixie 与 Python 3.13。Agent 只读取 Linux 的 `/proc`、`/sys`、systemd、网络状态和 journal，不依赖 GPIO、I²C、Pillow 或第三方 Python 包，也不需要 venv。
|
2026-10-11 00:06:22 +08:00
|
|
|
|
|
|
|
|
|
|
Yahboom RGB Cooling HAT 已拆分为独立插件。插件使用 Debian 系统包 `python3-smbus2` 与 `python3-pil`，不会通过 pip 修改受 PEP 668 管理的系统 Python。硬件接口保持原实现：
|
|
|
|
|
|
|
|
|
|
|
|
- I²C 总线：`/dev/i2c-1`，需要启用 I²C；不需要 SPI。
|
|
|
|
|
|
- 控制 MCU：`0x0D`；OLED：`0x3C`，SSD1306 兼容 128×32。
|
|
|
|
|
|
- 风扇通过 MCU 寄存器 `0x08` 的六档控制，不使用 Raspberry Pi GPIO PWM 引脚，也没有可验证的 RPM 反馈。
|
|
|
|
|
|
- RGB 由 MCU 寄存器控制；插件是 MCU、OLED、RGB 与风扇的唯一进程所有者。
|
|
|
|
|
|
|
|
|
|
|
|
因此不能把这块散热板当作直连 GPIO 风扇，也不应猜测或修改 GPIO 引脚。其他 GPIO/PWM 风扇需要独立驱动。
|
|
|
|
|
|
|
|
|
|
|
|
## 安装前检查
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
cat /etc/os-release
|
|
|
|
|
|
python3 --version
|
|
|
|
|
|
raspi-config nonint get_i2c
|
|
|
|
|
|
ls -l /dev/i2c-1
|
|
|
|
|
|
ss -ltnp
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
`raspi-config nonint get_i2c` 返回 `0` 才表示 I²C 已启用。启用 I²C 会修改启动配置，并且通常需要重启；远程操作前应确认 SSH 公钥登录与供电稳定。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
sudo raspi-config nonint do_i2c 0
|
|
|
|
|
|
sudo reboot
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
重连后确认 `/dev/i2c-1` 存在。散热板插件安装器会安装诊断工具并检查 `0x0D`、`0x3C`，不会改 SSH、网络或 Wi-Fi。
|
|
|
|
|
|
|
|
|
|
|
|
## 安装顺序
|
|
|
|
|
|
|
|
|
|
|
|
先安装通用监控 Agent：
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-10-11 16:29:26 +08:00
|
|
|
|
git clone https://tea.pigway.com/way/pigway-raspberry-pi-agent.git
|
|
|
|
|
|
cd pigway-raspberry-pi-agent
|
2026-10-11 00:06:22 +08:00
|
|
|
|
sudo ./install.sh --disable-api
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
默认只监控 `ssh.service`，不会假定已安装向日葵或 Tailscale。需要 NAS 上的 Device Console 时，先确认端口未占用，再显式开启 API：
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
sudo ./install.sh --enable-api
|
|
|
|
|
|
sudo ss -ltnp | grep ':6001 '
|
|
|
|
|
|
sudo cat /etc/pigway-pi-control-api.token
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
再安装独立硬件插件：
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
git clone https://tea.pigway.com/way/pigway-yahboom-cooling-hat.git
|
|
|
|
|
|
cd pigway-yahboom-cooling-hat
|
|
|
|
|
|
sudo ./install.sh --enable-integration
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
最后在 `/etc/pigway-pi-control.conf` 的 `[plugins]` 中登记：
|
|
|
|
|
|
|
|
|
|
|
|
```ini
|
|
|
|
|
|
yahboom-cooling-hat = /run/pigway-plugins/yahboom-cooling-hat/api.sock
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
然后仅重启 Agent：
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
sudo systemctl restart pigway-pi-control.service
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 验收
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
systemctl --no-pager --full status pigway-pi-control.service
|
|
|
|
|
|
systemctl --no-pager --full status pigway-cooling-hat.service
|
|
|
|
|
|
sudo /usr/local/sbin/pigway-pi-control --diagnose
|
|
|
|
|
|
sudo journalctl -u pigway-pi-control.service -b --no-pager
|
|
|
|
|
|
sudo journalctl -u pigway-cooling-hat.service -b --no-pager
|
|
|
|
|
|
curl --unix-socket /run/pigway-plugins/yahboom-cooling-hat/api.sock http://localhost/v1/status
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
实机还需肉眼确认 OLED 四行主页与10秒轮播、RGB 告警颜色/效果，并通过温度变化确认风扇档位。停止插件时会请求风扇全速，驱动关闭时不会写风扇 OFF；硬件无转速反馈，因此只能确认请求档位，不能声称测得真实 RPM。
|
|
|
|
|
|
|
|
|
|
|
|
API 默认关闭，不占用 TCP 端口。插件只使用本机 Unix socket，不会与 Tailscale 或 API 网关争用端口。两个服务都由 systemd 独立管理，异常退出自动重启，任一项目停止不会停止另一个项目。
|
