release: support Raspberry Pi OS Trixie
This commit is contained in:
@@ -0,0 +1,71 @@
|
||||
# Raspberry Pi OS Lite (Debian 13 Trixie) fresh installation
|
||||
|
||||
English | [简体中文](RASPBERRY_PI_OS_TRIXIE_FRESH_INSTALL.zh-CN.md)
|
||||
|
||||
## Compatibility
|
||||
|
||||
PIGWay Device Agent v3.7.1 supports Raspberry Pi OS Lite 64-bit based on Debian 13 Trixie and Python 3.13. The Agent reads Linux `/proc`, `/sys`, systemd, network state, and journal data. It has no GPIO, I2C, Pillow, or third-party Python dependency and does not need a virtual environment.
|
||||
|
||||
The Yahboom RGB Cooling HAT is an independent plugin. It uses Debian packages `python3-smbus2` and `python3-pil`, avoiding pip changes to the PEP 668 managed system Python. Its verified interface remains unchanged:
|
||||
|
||||
- I2C bus `/dev/i2c-1`; I2C must be enabled. SPI is not required.
|
||||
- MCU `0x0D`; 128x32 SSD1306-compatible OLED `0x3C`.
|
||||
- The fan uses six levels through MCU register `0x08`. It is not a Raspberry Pi GPIO PWM fan and has no verified RPM feedback.
|
||||
- The plugin is the sole process owner of the MCU, OLED, RGB, and fan.
|
||||
|
||||
Do not guess or change GPIO pins for this board. Other GPIO/PWM fans require their own driver.
|
||||
|
||||
## Fresh installation
|
||||
|
||||
Check the system first:
|
||||
|
||||
```bash
|
||||
cat /etc/os-release
|
||||
python3 --version
|
||||
raspi-config nonint get_i2c
|
||||
ls -l /dev/i2c-1
|
||||
ss -ltnp
|
||||
```
|
||||
|
||||
`raspi-config nonint get_i2c` must return `0`. Enabling I2C changes boot configuration and normally requires a reboot, so confirm SSH key access and stable power first:
|
||||
|
||||
```bash
|
||||
sudo raspi-config nonint do_i2c 0
|
||||
sudo reboot
|
||||
```
|
||||
|
||||
Install the Agent first. Its API is opt-in:
|
||||
|
||||
```bash
|
||||
git clone https://tea.pigway.com/way/pigway-device-agent.git
|
||||
cd pigway-device-agent
|
||||
sudo ./install.sh --disable-api
|
||||
```
|
||||
|
||||
To use Device Console, verify the port and explicitly enable the API:
|
||||
|
||||
```bash
|
||||
sudo ./install.sh --enable-api
|
||||
sudo ss -ltnp | grep ':6001 '
|
||||
sudo cat /etc/pigway-pi-control-api.token
|
||||
```
|
||||
|
||||
Install the hardware plugin after `/dev/i2c-1` is available:
|
||||
|
||||
```bash
|
||||
git clone https://tea.pigway.com/way/pigway-yahboom-cooling-hat.git
|
||||
cd pigway-yahboom-cooling-hat
|
||||
sudo ./install.sh --enable-integration
|
||||
```
|
||||
|
||||
Register its Unix socket under `[plugins]` in `/etc/pigway-pi-control.conf`, then restart only the Agent:
|
||||
|
||||
```ini
|
||||
yahboom-cooling-hat = /run/pigway-plugins/yahboom-cooling-hat/api.sock
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
Validate both systemd services, Agent diagnostics, boot journal, and plugin status. Physically verify the four-line OLED and 10-second rotation, RGB alerts, and temperature-dependent fan levels. Plugin shutdown requests full fan speed and driver close never writes fan OFF. Since the board has no tachometer feedback, requested level is not measured RPM.
|
||||
|
||||
The Agent API is disabled by default and the plugin uses a local Unix socket, so the default installation opens no TCP port and does not conflict with Tailscale or an API gateway.
|
||||
@@ -0,0 +1,88 @@
|
||||
# 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 独立管理，异常退出自动重启，任一项目停止不会停止另一个项目。
|
||||
Reference in New Issue
Block a user