Build Guide 2: Raspberry Pi Setup

Type: Build Guide

Now that every component checks out on the bench, we'll set up the Pi as a proper development environment. By the end of this guide you'll have a Pi that's ready to control hardware, capture images, read GPS, and talk to your web app.

What You Need

Raspberry Pi 4 set up headlessly with Raspberry Pi OS Lite 64-bit (from Guide 1, Step 3)
Working ssh tickslayer from your computer (or ssh todd@tickslayer.local)
An internet connection on the Pi (it's going to download a few hundred MB of system packages and Python libraries)

Step 1: System Updates and Essentials

SSH in:

ssh tickslayer

Get everything current. The first apt upgrade after a fresh flash is usually 50–100 packages because the image was built weeks before you flashed it:

sudo apt update && sudo apt upgrade -y

This takes 5–10 minutes on a Pi 4 over WiFi. Go grab water.

Install the system packages we need throughout the build:

sudo apt install -y \
  python3-pip python3-venv \
  i2c-tools \
  git \
  rpicam-apps \
  python3-picamera2 libcap-dev \
  gpsd gpsd-clients

A few notes on the package list, because some of these have non-obvious history:

rpicam-apps is the camera CLI suite (rpicam-still, rpicam-vid, rpicam-hello). On older Raspberry Pi OS releases this was called libcamera-apps; that's now a transitional package — use rpicam-apps directly on current Trixie/Bookworm builds.
python3-picamera2 is the Python binding for libcamera. Always install picamera2 from apt, not pip. The pip path tries to build python-prctl from source and fails on libcap headers, and even if you fix that, you end up with a worse-integrated install. The apt package is what the Raspberry Pi Foundation actually supports.
libcap-dev is here defensively in case anything else later wants to compile against libcap.
gpsd is the GPS daemon. It runs as a system service and brokers GPS data so multiple programs can read the device without fighting over the serial port. We'll configure it in Step 5.

Step 2: Python Environment

We're going to create a Python virtual environment for the rover code, but with one critical twist: it has to be created with --system-site-packages so the venv can see picamera2 (which lives at the system level because it's apt-installed).

mkdir -p ~/rover
cd ~/rover
python3 -m venv --system-site-packages venv
source venv/bin/activate

Verify picamera2 is visible from inside the venv:

python -c "import picamera2; print('picamera2 OK')"

If that fails, the venv was created without --system-site-packages — delete ~/rover/venv and recreate it with the flag.

Now upgrade pip and install the libraries that do belong in pip (everything except picamera2):

pip install --upgrade pip
pip install \
  adafruit-circuitpython-pca9685 \
  adafruit-circuitpython-ads1x15 \
  adafruit-circuitpython-motor \
  pynmea2 \
  pyserial \
  requests

This pulls in Adafruit-Blinka and a small mountain of CircuitPython hardware abstraction layers. Takes 2–4 minutes on a Pi 4.

Library	Source	Purpose
`picamera2`	apt (`python3-picamera2`)	Camera capture (Pi Camera Module 3)
`adafruit-circuitpython-pca9685`	pip	PWM driver control (steering & throttle)
`adafruit-circuitpython-ads1x15`	pip	ADC for battery voltage monitoring
`adafruit-circuitpython-motor`	pip	Servo abstraction layer
`pynmea2`	pip	Parse GPS NMEA sentences
`pyserial`	pip	Serial port communication with GPS
`requests`	pip	HTTP calls to the Convex backend

Verify every library imports cleanly:

python -c "
import board, busio
import adafruit_pca9685
import adafruit_ads1x15.ads1115 as ADS
from adafruit_motor import servo
import picamera2
import pynmea2
import serial
import requests
print('all imports OK')
"

You should see all imports OK. If you get ModuleNotFoundError for picamera2, see the venv note above. If you get it for board, the Adafruit-Blinka install bailed — re-run the pip install and check the output.

Add the venv activation to your .bashrc so every interactive SSH session starts with the venv active:

echo 'source ~/rover/venv/bin/activate' >> ~/.bashrc

Heads up on non-interactive SSH: the .bashrc activation only runs for interactive shells. If you do ssh tickslayer 'one-line-command' in a script, that command runs in a non-interactive shell, which doesn't source .bashrc, which means the venv is not active and python resolves to the system /usr/bin/python instead of the venv. Either source the activate script explicitly in your scripts, or use the full venv python path (~/rover/venv/bin/python).

Agent Assist·Bootstrap the Pi software environment

**Tell the agent:** "I just SSHed into my Pi for the first time. Walk me through Build Guide 2 Steps 1 and 2 — apt update + upgrade, install the system packages (including `rpicam-apps`, `python3-picamera2`, `libcap-dev`, and `gpsd`), create the rover venv with `--system-site-packages`, install all the Adafruit libraries via pip, verify all imports, and wire venv activation into `.bashrc`. Run things in the background where it makes sense and ping me when each phase finishes."

Heads up: apt upgrade + pip install of the full Adafruit stack takes ~10–15 min total on a Pi 4 over WiFi. Plenty of time to get a coffee.

Step 3: Enable Hardware Interfaces

We need to enable I2C (for the ADS1115 and PCA9685) and the UART hardware (for the GPS module). On current Raspberry Pi OS, the camera interface auto-detects via libcamera and doesn't need an explicit enable.

The easiest way is the raspi-config non-interactive subcommands:

sudo raspi-config nonint do_i2c 0          # 0 = enable
sudo raspi-config nonint do_serial_hw 0    # 0 = enable hardware UART
sudo raspi-config nonint do_serial_cons 1  # 1 = disable login shell on serial

If you prefer the menu UI, sudo raspi-config and navigate to:

Interface Options → I2C → Yes
Interface Options → Serial Port → "login shell" No, "serial port hardware" Yes

(Note: older versions of this guide mentioned do_camera and a separate "Camera" interface entry. Those are gone on current Pi OS — do_camera is no longer a function in raspi-config, and the camera is detected automatically by libcamera at boot. Don't go looking for a Camera interface toggle that doesn't exist.)

Reboot for the I2C kernel module to load and the serial UART changes to take effect:

sudo reboot

Wait ~30 seconds, then SSH back in. To verify everything took:

# I2C bus is alive (empty grid is fine — no chips wired yet)
sudo i2cdetect -y 1

# Serial device exists for GPS
ls -l /dev/serial0

i2cdetect should print a 16x16 grid of addresses. With nothing wired, every cell will be --. That's good — it means the bus is up and ready. When you wire the ADS1115 and PCA9685 in Guide 3: Pi ↔ Hardware Integration, addresses will start showing up.

(Side note on i2cdetect: the binary lives at /usr/sbin/i2cdetect, which is in your PATH for interactive shells but not for non-interactive ones. If you ever script around this and get "command not found," use sudo /usr/sbin/i2cdetect -y 1 or the full path.)

Step 4: Project Structure

Set up the directory structure for the rover code:

mkdir -p ~/rover/{config,logs,captures,routes}

Directory	Purpose
`~/rover/config/`	Calibration values, servo limits, settings
`~/rover/logs/`	GPS logs, mission logs, error logs
`~/rover/captures/`	Captured images (before upload)
`~/rover/routes/`	Saved GPS routes for replay

Create a config file for values we'll calibrate later:

# ~/rover/config/rover_config.py

# Steering servo
STEERING_CHANNEL = 0
STEERING_CENTER = 90    # Will calibrate in Guide 6
STEERING_LEFT_MAX = 50  # Will calibrate in Guide 6
STEERING_RIGHT_MAX = 130  # Will calibrate in Guide 6

# Throttle (ESC)
THROTTLE_CHANNEL = 1
THROTTLE_NEUTRAL = 90   # Will calibrate in Guide 6
THROTTLE_FORWARD_MIN = 95  # Will calibrate in Guide 6
THROTTLE_FORWARD_MAX = 110  # Keep low - we're dragging cloth, not racing
THROTTLE_REVERSE = 70   # Will calibrate in Guide 6

# Camera
CAPTURE_RESOLUTION = (4608, 2592)
CAPTURE_INTERVAL_METERS = 15  # Per entomological standard

# GPS
GPS_SERIAL_PORT = "/dev/serial0"
GPS_BAUD_RATE = 9600

# Battery
BATTERY_DIVIDER_RATIO = 5.0
BATTERY_LOW_THRESHOLD = 6.8  # Volts - triggers return-to-home
BATTERY_CRITICAL = 6.4       # Volts - immediate stop

# Network
CONVEX_UPLOAD_URL = ""  # Set after Convex integration

Checklist

System updated, all packages installed
Python venv created with all libraries
Project directories and config file created

The Pi is ready. Next up: Guide 3: Pi ↔ Hardware Integration — bench-validate that the Pi can actually drive each piece of hardware end-to-end through Python, with a $2 spare servo instead of the $400 truck.