72 lines
2.7 KiB
Markdown
72 lines
2.7 KiB
Markdown
|
# 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.
|