<!-- skill: Raspberry Pi | version: 1.0.0 | description: Setup, performance, GPIO and troubleshooting for Raspberry Pi boards | category: System & Productivity -->
## Instructions
- First boot: Raspberry Pi Imager with SSH + WiFi + user preconfigured, quality SD card (A2 rated) or better yet USB SSD boot — SD wear is the #1 killer of Pi projects.
- Performance: 4GB+ models for desktop/agent work; keep swap small (100MB default is fine, big swap on SD = stutter); `arm_boost=1` and honest cooling before any overclock; monitor with `vcgencmd measure_temp` and `get_throttled` (any non-zero throttled value means power/heat problems — fix the PSU first).
- Power: official 5V/3A+ (Pi 4) or 5V/5A (Pi 5) supplies only. Random reboots and lightning bolts = power, always.
- GPIO: use gpiozero (Python) for LEDs/buttons/servos — never drive motors directly from pins (use a driver board); 3.3V logic only, 5V fries pins.
- Headless: SSH + `raspi-config` for interfaces (I2C/SPI/camera), Samba or SFTP for file access, `log2ram` to spare the SD card.
- Updates: `apt update && apt full-upgrade` periodically; pin kernel with `rpi-update` ONLY when you need a specific fix (it installs bleeding-edge firmware).
- Storage hierarchy: USB SSD boot (Pi 4/5) for anything serious — SD for boot-only or disposables; `log2ram` + log caps when stuck on SD; never swap heavily on flash (`vm.swappiness=10`, small swapfile).
- Cooling: passive heatsink minimum, fan above 65°C sustained (`vcgencmd measure_temp`, `vcgencmd get_throttled` — any `throttled=0x...` nonzero means power/heat, fix PSU/cooling before overclock dreams).
- Network: ethernet for servers, WiFi power-save OFF on headless (`iw wlan0 set power_save off` + udev rule or it sleeps mid-SSH); static DHCP reservation in the router, not static IP on the Pi (avoids conflicts).
- Camera/display: `libcamera-hello` smoke test before code, `rpicam-still -o test.jpg` for stills, enable interfaces via `raspi-config nonint do_camera 0` headlessly.
- HATs/bonnets: check pinout (`pinout` command) before stacking — 5V/GND shorts kill Pis; I2C address scan (`i2cdetect -y 1`) before assuming the sensor works.
## Examples
- Slow Pi: check throttled flags, SD health (`dmesg` I/O errors), top memory hogs, disable unused services (`bluetooth`, `cups` if headless).
- Sensor project: DHT22 on GPIO4 + gpiozero + cron logging to CSV, graph later.
- Pi server: SSD boot + static DHCP + Tailscale + systemd user service + log2ram — survives power cuts and SD death.
## Workflows
1. Flash → boot → SSH → updates → enable needed interfaces → deploy code → set up autostart (systemd user service).
2. Anything important gets a backup image (Imager read-back or `dd`) before major changes.
3. Monthly: `apt upgrade`, `vcgencmd get_throttled` check, `df -h` + `dmesg | grep -i "i/o error"`, backup-image refresh quarterly.
4. New peripheral: `pinout` → wire → `i2cdetect`/loopback test → minimal script → systemd service → log check.
## Templates
- systemd user service file for auto-starting Python scripts on boot.
```ini
# ~/.config/systemd/user/sensor.service — GPIO script that survives reboot
[Unit]
Description=Sensor logger
After=network-online.target
[Service]
WorkingDirectory=/home/casper/sensor
ExecStart=/home/casper/sensor/.venv/bin/python logger.py
Restart=on-failure
RestartSec=10
[Install]
WantedBy=default.target
```
```bash
# health snapshot (SSH in, paste when asking for help)
vcgencmd measure_temp; vcgencmd get_throttled; uptime; free -h; df -h /; dmesg | tail -5
```
```python
# gpiozero blink-and-button pattern (never raw RPi.GPIO for beginners)
from gpiozero import LED, Button
from signal import pause
led = LED(17)
btn = Button(27, bounce_time=0.05)
btn.when_pressed = led.toggle
pause()
```
## Tools
- SARAH shell_run for all commands; linux-admin skill for general Debian administration.
- Imager (`rpi-imager`) with SSH/user/WiFi presets saved; `pinout` + `i2cdetect` for wiring truth.
## Advanced
- Boot mastery: EEPROM config (`rpi-eeprom-config`, BOOT_ORDER `0xf41` = SD→USB→repeat) for SSD boot, `cmdline.txt`/`config.txt` edits via the boot FAT partition from any PC when SSH is dead.
- GPIO depth: gpiozero (buttons/LEDs/servos/PWM) → `lgpio` for speed → pigpio daemon for waveforms; NEVER 5V into a GPIO (divider or level-shifter), 16mA/pin budget, relays via opto-isolated boards with separate 5V supply.
- I2C/SPI/UART: enable in raspi-config, `i2cdetect` scan, pull-ups on SDA/SCL for long runs, UART console off (`enable_uart=1` + disable serial-getty) when the port belongs to a sensor.
- Headless fleet: hostname per Pi (`sensor-loft`, `octopi`), mDNS (`.local`) + Tailscale, Ansible or `pssh` for multi-Pi updates, image golden-master + flash per new board.
- Troubleshooting: lightning bolt/reboots → PSU or cable (official supply + short thick cable, USB hubs need their own power); won't boot (ACT LED 4-flashes) → bootloader/SD (re-flash Imager, try another card); WiFi drops → power-save on or weak signal (`iwconfig` link quality, move to 2.4GHz for range); I2C device missing → wiring (SDA GPIO2/SCL GPIO3), address conflict, or 5V sensor on 3.3V bus; SD died → migrate to SSD, restore from last image + recent data backup.
## Documentation
- raspberrypi.com/documentation (configuration + GPIO guides).
- gpiozero docs: https://gpiozero.readthedocs.io
- Boot + EEPROM: https://www.raspberrypi.com/documentation/computers/raspberry-pi.html