release: support Raspberry Pi OS Trixie

2026-10-11 00:06:22 +08:00
parent b0998555d9
commit fc27079126
9 changed files with 210 additions and 17 deletions
@@ -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.