89 lines
3.4 KiB
Markdown
89 lines
3.4 KiB
Markdown
# Raspberry Pi OS Lite（Debian 13 Trixie）全新安装
|
||
|
||
[English](RASPBERRY_PI_OS_TRIXIE_FRESH_INSTALL.md) | 简体中文
|
||
|
||
## 兼容性结论
|
||
|
||
PIGWay Device 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。
|
||
|
||
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
|
||
git clone https://tea.pigway.com/way/pigway-device-agent.git
|
||
cd pigway-device-agent
|
||
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 独立管理，异常退出自动重启，任一项目停止不会停止另一个项目。
|