Raspberry Pi Projects skill for Codex

Done well means: the project installs on a fresh Raspberry Pi OS image from a script, runs as a supervised systemd service under a non-root user, survives power loss without a corrupted card, and works on both Pi 4 and Pi 5 unless the user said otherwise.

Inspect first

Ask the user to run these on the Pi (Codex usually works on a laptop clone of the repo) and paste the output, or run them yourself if the session is on the Pi:

cat /proc/device-tree/model; echo
cat /etc/os-release | grep VERSION_CODENAME     # bookworm is the current baseline
uname -m                                         # aarch64 vs armv7l
vcgencmd get_throttled                           # 0x0 is healthy
ls /dev/i2c-* /dev/spidev* 2>/dev/null
groups                                           # needs gpio, i2c, spi for non-root access

Read AGENTS.md and any install script before changing dependencies.

Decisions that changed with Bookworm and the Pi 5

Old habit	Current answer
import RPi.GPIO	Does not work on Pi 5. Use gpiozero (default) or lgpio; rpi-lgpio is a drop-in shim for legacy code
/boot/config.txt	/boot/firmware/config.txt
sudo pip install	Refused (PEP 668). Use a venv; apt install python3-xyz for system packages
raspi-gpio	pinctrl get 17, pinctrl set 17 op dh
libcamera-still, picamera	rpicam-still, Picamera2
dhcpcd.conf static IP	NetworkManager: nmcli connection modify ...
Hard-coded /dev/gpiochip0 or gpiochip4	Let gpiozero pick; on the CLI find the chip with gpiodetect and gpioinfo

Python environment

sudo apt install -y python3-venv python3-lgpio python3-gpiozero   # network
python3 -m venv --system-site-packages ~/app/.venv   # sees apt-installed lgpio
~/app/.venv/bin/pip install -r requirements.txt

--system-site-packages lets the venv use the apt builds of hardware libraries, which are compiled for the Pi; installing those through pip often fails without build headers. Package installs need network access; in a Codex sandbox, request approval for that step.

GPIO with gpiozero

from signal import pause
from gpiozero import Button, LED, PWMLED

led = LED(17)                         # BCM numbering, physical pin 11
button = Button(27, pull_up=True, bounce_time=0.05)
fan = PWMLED(18, frequency=25000)

button.when_pressed = led.toggle      # callbacks run on a background thread
fan.value = 0.4
pause()

• BCM numbers, not physical pins. Put a pin map comment next to each assignment.
• 3.3 V logic only. A 5 V signal on a GPIO pin damages the SoC; use a divider or level shifter. GPIO pins source a few mA safely; drive relays and motors through a transistor or driver board with a flyback diode.
• Callback code runs on another thread: guard shared state with a lock or hand events to a queue.Queue.
• Tests on a laptop: GPIOZERO_PIN_FACTORY=mock with from gpiozero import Device; from gpiozero.pins.mock import MockFactory.

I2C and SPI

sudo raspi-config nonint do_i2c 0     # 0 means enable
sudo raspi-config nonint do_spi 0
sudo reboot
i2cdetect -y 1                        # from i2c-tools

Or add to /boot/firmware/config.txt: dtparam=i2c_arm=on, dtparam=spi=on; extra buses and devices come from overlays (dtoverlay=i2c-rtc,ds3231). Read /boot/firmware/overlays/README for the parameters of each overlay; do not guess them.

Run at boot with systemd

# /etc/systemd/system/plant-monitor.service
[Unit]
Description=Plant monitor
After=network-online.target
Wants=network-online.target

[Service]
User=pi
Group=pi
SupplementaryGroups=gpio i2c
WorkingDirectory=/home/pi/app
ExecStart=/home/pi/app/.venv/bin/python -u main.py
Restart=on-failure
RestartSec=5
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now plant-monitor
journalctl -u plant-monitor -f

• Never run the app as root to “fix” GPIO permissions; add the user to the groups.
• Replace the user name with the real account; recent images do not create pi by default.
• Use a systemd timer instead of cron for periodic jobs, so logs land in the journal.
• GUI apps that need the desktop session belong in a user service or autostart entry, not a system unit.

Power, heat and storage

• vcgencmd get_throttled non-zero: bit 0 undervoltage now, bit 16 undervoltage has occurred, bits 2 and 18 throttling. Fix the supply (Pi 5 wants 5 V 5 A for full USB current) before debugging software.
• vcgencmd measure_temp above about 80 C throttles; add a heatsink or the active cooler.
• SD wear: reduce writes. Set Storage=volatile in /etc/systemd/journald.conf for appliances, write data to a database with batched commits, and consider the overlay file system (raspi-config, Performance Options) for read-only deployments.
• For anything important, boot from an SSD (USB or the Pi 5 PCIe) instead of SD.

Exposing it on a network

Change the default password, keep SSH key-only, and do not port-forward the Pi. For remote access use a VPN or tunnel the user already runs. Server hardening detail lives in linux-server-hardening.

Gotchas

• time.sleep polling loops for buttons miss presses; use gpiozero edge callbacks.
• Two processes cannot own the same pin; a leftover service holds it. Check systemctl list-units --type=service before debugging “GPIO busy”.
• The 1-Wire, UART and I2C overlays change pin functions; check pinctrl get when a pin “does nothing”.
• The primary UART on Pi 3/4 is used by Bluetooth; use /dev/serial0 and enable the UART in raspi-config rather than hard-coding ttyAMA0.

Verification

• Fresh-image install script runs end to end without manual steps
• Service starts after sudo reboot and systemctl status shows active
• Killing the process (sudo kill -9 <pid>) results in an automatic restart
• vcgencmd get_throttled returns 0x0 under full load
• Pulling power mid-run and rebooting leaves the app and data intact

Report

**Hardware:** Raspberry Pi 5 4 GB, Bookworm 64-bit, BME280 at 0x76 on I2C-1
**Change:** RPi.GPIO -> gpiozero; venv with system site packages; systemd unit with restart
**Verified:** survives reboot and kill -9; throttled=0x0; user log pasted from journalctl
**Risks:** still on SD card; journald set to volatile, data written once a minute