2.7 KiB
Raspberry Pi OS Lite (Debian 13 Trixie) fresh installation
English | 简体中文
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 OLED0x3C. - 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:
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:
sudo raspi-config nonint do_i2c 0
sudo reboot
Install the Agent first. Its API is opt-in:
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:
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:
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:
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.