# Troubleshooting Guide: Enabling RGB Lighting on Pironman 5 / Pro Max
This guide explains how to configure and fix the RGB LED lighting issues on the **Pironman 5** and **Pironman 5 Pro Max** case expansion boards. If your case’s LED strips are showing 0% brightness, displaying only a few active lights, or not lighting up at all, follow this walkthrough to configure your Raspberry Pi 5.
-–
## 1. Hardware & System Environment Overview
The Pironman 5 case uses an expansion HAT (Hardware Attached on Top) that connects directly to the Raspberry Pi 5. The primary software and hardware components are:
| Component / Metric | Details & Version |
| :— | :— |
| **Raspberry Pi Model** | Raspberry Pi 5 Model B (Rev 1.1) |
| **Operating System** | Raspberry Pi OS (Debian Bookworm) |
| **Linux Kernel** | `6.12.x` (or newer) |
| **RGB LED controller** | WS2812B NeoPixel strips (controlled over SPI) |
| **Core Service Daemon** | `pironman5.service` (Python-based PMAuto stack) |
| **Required Power Input** | Premium 5V, 5A (27W) USB-C Power Supply |
-–
## 2. Official GitHub Software Installation
If you haven’t installed the core software daemon or need to reinstall it, run the following commands:
1. **Prepare dependencies** (highly recommended on “Lite” operating system versions):
```bash
sudo apt-get update
sudo apt-get install git python3 python3-pip python3-setuptools -y
```
2. **Download and run the official SunFounder installation script**:
```bash
curl -sSL “https://raw.githubusercontent.com/sunfounder/sunfounder-installer-scripts/main/pironman5/install.sh” | sudo bash
```
3. **Reboot the system**:
```bash
sudo reboot
```
-–
## 3. Configuration Changes Implemented to Enable RGB
Two key configurations must be written to the system files to enable the RGB lighting:
### A. Boot Firmware Configuration (`/boot/firmware/config.txt`)
The LEDs communicate over the **SPI (Serial Peripheral Interface)** bus. Because the Raspberry Pi OS leaves the SPI interface disabled by default, it must be enabled:
* **File changed**: `/boot/firmware/config.txt`
* **Entry added**:
```text
dtparam=spi=on
```
*(This forces the Linux kernel to load the `spi-bcm2835` driver and expose `/dev/spidev0.0` to the software.)*
### B. Core Pironman Configuration (`/opt/pironman5/config.json`)
The core service reads its settings from a local JSON configuration database. If the board auto-probe fails, the software defaults to controlling only 4 LEDs. We override this to force-enable all 18 LEDs on the Pro Max case.
* **File changed**: `/opt/pironman5/config.json`
* **Entries configured**:
```json
“system”: {
"rgb_enable": true,
"rgb_led_count": 18,
"rgb_style": "breathing"
}
```
-–
## 4. Troubleshooting: What if it’s Still Not Working?
If you followed the instructions above but the LEDs are still dark, perform these additional diagnostic steps:
### A. Verify the Physical 40-Pin GPIO Connection (Common Mistake)
Power off your Pi completely. Inspect the connection between the Raspberry Pi’s pins and the Pironman expansion board.
* **The Trap**: It is very easy to plug the expansion board in slightly shifted (offset by one row of pins left, right, up, or down). If the pins are misaligned, the SPI signals won’t reach the board, and you risk short-circuiting the power lines. Ensure all 40 pins sit perfectly aligned and flush.
### B. Verify Power Delivery & Voltage Throttling
WS2812B LED arrays draw a significant amount of electrical current under load. If your USB-C power supply is weak (e.g., a standard 5V, 3A phone charger instead of the recommended 5V, 5A Raspberry Pi 27W supply), the Pi will choke under load.
* Check if your Pi is throttling or suffering from under-voltage by running:
```bash
vcgencmd get_throttled
```
* If it returns anything other than `throttled=0x0` (like `0x50000` or `0x50005`), the Pi has detected under-voltage. Under load, the Pi’s internal PMIC will drop power lines to the HAT, causing the LEDs to turn off or fail to respond.
### C. Manually Override Daemon Configurations via Command Line
Sometimes the configuration file changes don’t load correctly if the service is running. Force the configuration updates using the Pironman command-line interface:
1. **Turn on the RGB control**:
```bash
sudo pironman5 -re true
```
2. **Force-set the LED Count**:
```bash
sudo pironman5 -rl 18
```
3. **Change the Animation Style**:
```bash
sudo pironman5 -rs breathing
```
4. **Set standard brightness to 100%**:
```bash
sudo pironman5 -rb 100
```
### D. Check the Kernel Log & Service Output
If the daemon is crashing or cannot initialize the SPI bus, check the live logs:
* Open systemd journal logs to inspect startup warnings:
```bash
sudo journalctl -u pironman5.service -n 50 --no-pager
```
* Open the raw Pironman log file:
```bash
cat /var/log/pironman5/pironman5.log
```
*Look for errors containing `SPI`, `NeoPixel`, or `spidev`. If `spidev` errors appear, verify that the active user running the service has permission to write to `/dev/spidev*`.*
-–
## 5. Technical Deep-Dive & Learning Resources
To learn more about the underlying technologies, check out these guides:
* [Official Pironman 5 Documentation](https://pironman5.rtfd.io): SunFounder’s official user guide, assembly steps, and layout diagrams.
* [Raspberry Pi Boot Configuration (config.txt)](https://www.raspberrypi.com/documentation/computers/config_txt.html): Learn how boot options and configuration variables are processed on Raspberry Pi devices.
* [Device Trees & Overlays on Raspberry Pi](https://www.raspberrypi.com/documentation/computers/configuration.html#device-trees-device-tree-blobs-and-overlays): A guide to understanding device trees, overlays, and hardware configurations on Debian-based Pi OS.
* [SPI (Serial Peripheral Interface) Bus](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#serial-peripheral-interface-spi): Learn how SPI master-slave communication functions on Raspberry Pi GPIO pins.
* [WS2812B NeoPixel Protocol & Datasheet](https://www.arrow.com/en/research-and-events/articles/ws2812b-datasheet-and-led-strip-addressable-rgb): A breakdown of how addressable RGB LEDs receive, strip, and forward timing-sensitive serial data packages.
-–
## Appendix: Fixing InfluxDB Startup Failures on Debian Bookworm
Many users running Pironman 5 on newer **Debian Bookworm** releases encounter an issue where the **Web Dashboard** doesn’t load historical graphs and the **OLED screen freezes** or fails to start.
### 1. The Root Cause: Missing `libssl1.1` Dependency
* Pironman 5 installs **InfluxDB v1.8** to store historical telemetry metrics.
* The InfluxDB binary package is compiled against **OpenSSL 1.1** (which uses the shared library `libssl.so.1.1`).
* Debian Bookworm (Raspberry Pi OS 12) has upgraded to **OpenSSL 3** and completely removed the deprecated `libssl1.1` from its repositories.
* As a result, the `influxd` server crashes immediately on launch with a shared library load error:
`libssl.so.1.1: cannot open shared object file: No such file or directory`.
* When InfluxDB fails, the main Pironman service gets stuck trying to connect to the database (repeating `Failed to connect to InfluxDB…`), which crashes or hangs the OLED display addon and halts the dashboard server.
### 2. How to Resolve the InfluxDB Issue
To get InfluxDB and your dashboard running successfully, follow these steps to manually install the legacy SSL library on your Raspberry Pi:
1. **Download the ARM64 build of `libssl1.1`** from the Debian/Ubuntu security ports archive:
```bash
wget http://ports.ubuntu.com/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2.24_arm64.deb
```
2. **Install the package**:
```bash
sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2.24_arm64.deb
```
3. **Clean up the downloaded package**:
```bash
rm libssl1.1_1.1.1f-1ubuntu2.24_arm64.deb
```
4. **Clean up potential corrupted InfluxDB files** (highly recommended if InfluxDB crashed multiple times during startup):
```bash
sudo systemctl stop pironman5.service
sudo rm -rf /var/lib/influxdb/data/pironman5
sudo rm -rf /var/lib/influxdb/wal/pironman5
```
5. **Restart the Pironman 5 service**:
```bash
sudo systemctl start pironman5.service
```
6. **Verify that InfluxDB is running**:
```bash
pgrep influxd
```
*(If it returns a process ID number, InfluxDB has started successfully as a subprocess of the daemon!)*