pigway-raspberry-pi-agent/docs/RASPBERRY_PI_OS_TRIXIE_FRESH_INSTALL.md

# Raspberry Pi OS Lite (Debian 13 Trixie) fresh installation

English | [简体中文](RASPBERRY_PI_OS_TRIXIE_FRESH_INSTALL.zh-CN.md)

## Compatibility

PIGWay Raspberry Pi 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-raspberry-pi-agent.git
cd pigway-raspberry-pi-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.