# 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 独立管理，异常退出自动重启，任一项目停止不会停止另一个项目。