Build Guide 3: Pi ↔ Hardware Integration

Type: Build Guide

You've bench-tested every chip standalone (Guide 1) and the Pi is fully software-bootstrapped (Guide 2). This guide is the bridge: prove the Pi can actually control and read from every piece of hardware, end-to-end through Python, on the workbench. Zero vehicle risk. When you're done, every component on the rover is something you've already commanded — the vehicle wiring in Guide 5 stops being a leap of faith and becomes "plug the same I2C wires into a bigger servo and a bigger battery."

This is also the most fun guide. You're going to make a servo physically move with five lines of Python.

What You Need

Raspberry Pi 4 from Guide 2 (rover-agent or at least SSH access)
PCA9685 + ADS1115 + voltage divider bench-validated in Guide 1
GPS module with antenna (already tested in Guide 1 Step 5)
Pi Camera (optional this guide — RMA-pending modules can skip Step 6)
A spare hobby servo (any cheap micro 9g servo works — SG90, MG90S, etc). Not the TRX-4's steering servo — leave that on the truck.
Breadboard + jumper wires (mostly female-to-female and male-to-female)
A known battery for the ADC test (a fresh 9V or your 2S LiPo)
About 60-90 minutes

Step 1: I2C Handshake with the PCA9685

Goal: confirm the Pi can see the PCA9685 on the I2C bus. No servo yet — just "hello, are you there?"

Wire the logic side

Power down the Pi first (sudo shutdown -h now). Then connect 4 jumper wires from the Pi's 40-pin header to the PCA9685's 6-pin input header:

From Pi	To PCA9685	Notes
Pin 1 (3.3V)	`VCC`	Pin 1, not Pin 2 or 4 — those are 5V and can damage the chip
Pin 6 (GND)	`GND`	Outer row
Pin 3 (SDA)	`SDA`	Inner row, second from corner
Pin 5 (SCL)	`SCL`	Inner row, third from corner

Leave V+ (the big screw terminal, or one of the pins) unconnected for now — that's servo power, which we wire in Step 2.

Color-coding helps: red for VCC, black for GND, two other colors for SDA/SCL. The Adafruit boards have the labels in tiny silkscreen — match by label, not by position.

Power on and scan

Power the Pi back on. The PCA9685's red power LED should light up — first confirmation that VCC + GND are right. If it doesn't light, fix that before going further.

SSH in and scan the bus:

sudo i2cdetect -y 1

You should see:

     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
00:                         -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
40: 40 -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
70: 70 -- -- -- -- -- -- --

0x40 — PCA9685's default address.
0x70 — the "all-call" broadcast address (PCA9685 also responds here; confirms it's a real one).

Pass / Fail

Pass: 0x40 (and usually 0x70) show up in the grid.

Fail:

Empty grid, red LED on — SDA/SCL swapped or loose. Verify Pin 3 → SDA, Pin 5 → SCL. Wiggle and reseat.
No red LED — VCC or GND not making contact. Check Pin 1, not Pin 2.
Could not open file /dev/i2c-1 — I2C interface not enabled. sudo raspi-config → Interface Options → I2C → Enable.

Step 2: Make a Servo Move from Python

This is the one. Up till now you've measured voltages and read NMEA strings — boring numbers. In this step you write a Python script and a physical thing on your desk moves because of it. Don't skip this even if you're confident in the hardware.

What you need for this step

The PCA9685 still wired up from Step 1
A spare hobby servo (SG90 / MG90S / any 9g micro — they're $2 each, the cheap blue ones from a kit are fine)
One more jumper wire (for V+ servo power)

Wire the servo

The SunFounder PCA9685 has 16 rows of 3-pin headers along one long edge — those are the servo outputs, numbered 0–15. Each row has three pins, top to bottom:

Pin	Color (standard)	Function
Top	Yellow/white/orange	PWM signal
Middle	Red	V+ (servo power)
Bottom	Brown/black	GND

Plug your servo cable into channel 0 (the row labeled 0 on the PCB). The servo connector is keyed to one orientation — the brown/black wire goes to the GND side. Don't force it backwards; you can damage the servo if you reverse polarity.

Power the servo (V+)

The PCA9685's V+ rail powers the servos. It's electrically separate from the chip's logic VCC — meaning the chip can be talking happily over I2C while V+ is dead, and your servo just won't move. (This is the #1 reason "the code runs but nothing happens.")

On the SunFounder board, V+ has a dedicated green 2-pin screw terminal block on the same edge as the 6-pin logic header (clearly labeled V+ and GND). Use that — not the V+ pin on the 6-pin header, which sits right next to the 3.3V VCC pin and is easy to mix up.

For one micro servo on the bench, jumper the Pi's 5V rail to V+:

From Pi	To PCA9685
Pin 2 or Pin 4 (5V)	`V+` (green screw terminal — loosen the screw, insert the jumper wire, tighten)
Pin 6 (GND)	already wired from Step 1 — the PCA9685's signal GND and V+ GND are internally tied, you don't need a second ground wire

A 9g micro servo draws ~150-250mA peak, well within what the Pi can supply on its 5V rail. Do not do this with a full-size hobby servo or the TRX-4's steering servo — those can pull 500mA-1A and will brown-out the Pi. For those, we use the TRX-4's BEC in Guide 5.

Write the sweep script

SSH into the Pi, activate the rover venv, and create the file:

source ~/rover/venv/bin/activate
nano ~/rover/test_servo_sweep.py

Paste in:

"""Bench-only servo sweep — proves Pi → I2C → PCA9685 → PWM → physical motion works."""
import time
import board
import busio
from adafruit_pca9685 import PCA9685
from adafruit_motor import servo

i2c = busio.I2C(board.SCL, board.SDA)
pca = PCA9685(i2c)
pca.frequency = 50  # 50 Hz is standard hobby servo PWM frequency

test_servo = servo.Servo(pca.channels[0])

print("Center (90°)...")
test_servo.angle = 90
time.sleep(1.5)

print("Left (45°)...")
test_servo.angle = 45
time.sleep(1.5)

print("Right (135°)...")
test_servo.angle = 135
time.sleep(1.5)

print("Center (90°)...")
test_servo.angle = 90
time.sleep(1.5)

pca.deinit()
print("Done.")

Save (Ctrl+O, Enter, Ctrl+X) and run:

python3 ~/rover/test_servo_sweep.py

The servo should physically rotate to each position with a satisfying little buzz. This is the moment. A line of Python on a Pi just moved a real motor in physical space. Same code path will drive the TRX-4 steering servo in Guide 5 — only the wiring downstream changes.

Pass / Fail

Pass: Servo moves through center → left → right → center.

Fail:

Script runs, prints all the messages, servo doesn't move — V+ isn't powered. Confirm Pi Pin 2 or 4 is jumpered to PCA9685 V+. Multimeter check: V+ to GND should read ~5V.
Servo buzzes but doesn't move (or just twitches) — under-powered, or it's hitting a mechanical end-stop. If you have a 4×AA pack or USB 5V brick, feed V+ from that instead of the Pi.
Servo moves but in jerky/wrong directions — wrong servo wire orientation in the channel header, or the servo is just cheap. Both common, both harmless.
ImportError: No module named adafruit_pca9685 — venv not activated, or libraries not installed. See Guide 2 Step 2.

What you've proved

You have validated the entire steering/throttle control path with $2 of risk:

Python script → adafruit_pca9685 → I2C bus → PCA9685 chip → PWM signal → servo movement

When Guide 5 wires the TRX-4's steering servo into the same PCA9685 (channel 0 again, by convention) and the ESC into channel 1, you're not running an untested code path. You're running this exact code path with bigger actuators.

Agent Assist·Sweep a servo end-to-end

**Tell the agent:** "PCA9685 (SunFounder board) is detected at 0x40. I have a spare SG90/MG90S micro servo plugged into channel 0, with Pi Pin 2 (5V) wired into the green V+ screw terminal. SSH into `tickslayer`, create `~/rover/test_servo_sweep.py` with the script from Build Guide 3 Step 2 (using `adafruit_pca9685` + `adafruit_motor.servo`, sweep center→left→right→center with 1.5s pauses), and run it. Confirm the servo physically moves at each step. If it doesn't, diagnose — usually V+ not powered, wrong channel, or wrong servo cable orientation."

Heads up: activate the rover venv first (source ~/rover/venv/bin/activate) or the Adafruit imports will fail.

Step 3: I2C Handshake with the ADS1115

Same idea as Step 1, different chip. The ADS1115 is a 4-channel 16-bit analog-to-digital converter — it reads analog voltages (like the divided-down LiPo voltage) and reports them as numbers the Pi can use. It shares the same I2C bus as the PCA9685.

Wire it up

You can either:

Disconnect the PCA9685 and wire ADS1115 to the same Pi pins (simplest if you only have one breadboard / one set of jumpers), or
Wire both in parallel on a breadboard — both chips share SCL/SDA/VCC/GND. This is how they live on the rover.

Either way, 4 wires from the Pi:

From Pi	To ADS1115
Pin 1 (3.3V)	`VDD`
Pin 6 (GND)	`GND`
Pin 3 (SDA)	`SDA`
Pin 5 (SCL)	`SCL`

Leave ADDR unconnected (defaults to 0x48) and leave the 4 analog input pins A0–A3 unconnected for now — Step 4 wires A0.

Scan the bus

sudo i2cdetect -y 1

If only ADS1115 is wired: you'll see 0x48. If both PCA9685 and ADS1115 are on the bus: you'll see 0x40, 0x48, and 0x70. All good.

Pass / Fail

Pass: 0x48 appears in the grid.

Fail: same diagnostic flow as Step 1 — check VCC/GND first (red LED on the board), then SDA/SCL.

Step 4: Read a Real Voltage Through the ADS1115

Now we wire the bench-validated voltage divider into the ADS1115's A0 input and read it from Python. This proves the battery-monitoring chain end-to-end: real battery → divider scales it down → ADC digitizes → Python reads the number.

Wire it up

You already validated the divider in Guide 1 Step 2 by probing it with a multimeter. Now we replace the multimeter probes with two wires going to the ADS1115:

From voltage divider output (3-pin header)	To ADS1115
`S` (signal — the divided voltage)	`A0`
`−` (or `GND`)	`GND`

Leave the divider's + output pin unconnected — we don't need it for measurement.

Connect a known battery to the divider's input terminal block (same wiring as Guide 1 Step 2 — VCC to +, GND to −). A fresh 9V battery is ideal (gives a clean ~1.8V at A0, well within the ADS1115's range). Your 2S LiPo also works (~1.5-1.7V at A0).

Write the read script

nano ~/rover/test_adc_read.py

"""Bench-only ADC read — proves the battery monitoring chain works end-to-end."""
import time
import board
import busio
from adafruit_ads1x15.ads1115 import ADS1115
from adafruit_ads1x15.analog_in import AnalogIn

i2c = busio.I2C(board.SCL, board.SDA)
ads = ADS1115(i2c)

# Read channel A0
chan = AnalogIn(ads, 0)

# Your divider's measured ratio (input ÷ output) from Guide 1 Step 2.
# Most 0-25V modules are ~5x.
DIVIDER_RATIO = 5.0

print("Reading A0 — press Ctrl+C to stop")
print(f"{'raw':>8} {'voltage at A0':>15} {'battery voltage':>18}")
while True:
    raw = chan.value
    v_a0 = chan.voltage
    v_battery = v_a0 * DIVIDER_RATIO
    print(f"{raw:>8} {v_a0:>13.3f} V {v_battery:>15.2f} V")
    time.sleep(0.5)

Run it:

python3 ~/rover/test_adc_read.py

You should see a stream of readings. The "battery voltage" column is the ADC reading multiplied back out by your divider ratio — that's the value you'd report up to Convex as the LiPo voltage.

Sanity check against the multimeter

Probe the actual battery terminals with your multimeter. The number on the meter should match the "battery voltage" column on screen, within ±0.1V. If they differ by more than that:

Your DIVIDER_RATIO is off — compute the real one as multimeter_reading ÷ v_a0 from the output above and edit the constant.
The divider isn't a perfect 5×; manufacturing tolerances are ±5%. Pin down your specific board's ratio once and re-use it.

Pass / Fail

Pass: ADC reads a stable voltage, and after applying your divider ratio it matches the multimeter ±0.1V.

Fail:

v_a0 reads 0.000 forever — A0 not connected to the divider's S pin, or no battery on the input side.
v_a0 saturates at ~3.3V — input voltage too high, or you've wired the divider input directly to A0 (skipping the divider). Don't run the rover off a battery monitor configured like this — would fry the ADC.
Readings jump around wildly — loose ground, or noisy power source. Try a fresh 9V battery instead of the LiPo.

What you've proved

Battery → voltage divider → ADS1115 A0 → I2C bus → adafruit_ads1x15 → Python float

That's the same chain that'll wake you up at 11pm with a low_battery alert when the rover's out doing tick runs and the 2S LiPo drops below 6.6V.

Step 5: Read GPS from Python (not raw `cat`)

In Guide 1 Step 5 you confirmed the GPS module streams NMEA over /dev/serial0 by cat-ing it. That proves the hardware works, but the rover-agent needs structured data — lat, lon, satellites_used, etc. as actual numbers. This step parses NMEA in Python.

Approach A: gpsd (recommended for the rover)

gpsd is a daemon that owns the serial port, parses NMEA, and exposes the data over a TCP socket. The rover-agent (and any other client) can subscribe without fighting over /dev/serial0.

Install (if you didn't already in Guide 2 Step 1):

sudo apt install -y gpsd gpsd-clients python3-gps

Configure gpsd to use /dev/serial0:

sudo nano /etc/default/gpsd

Set:

DEVICES="/dev/serial0"
GPSD_OPTIONS="-n"
START_DAEMON="true"

Restart:

sudo systemctl restart gpsd
sudo systemctl enable gpsd

Quick test with the bundled client:

gpsmon

You should see a full live readout — lat/lon/sats/HDOP/altitude. Press q to quit.

Approach B: read serial directly (simpler, no daemon)

If gpsd feels heavy, you can parse NMEA in 30 lines of Python using pynmea2. This is what pi/sensors.py will eventually do — gpsd is optional infrastructure, not required.

nano ~/rover/test_gps_read.py

"""Bench-only GPS read via direct serial — proves Python can parse NMEA into structured data."""
import serial
import pynmea2

PORT = "/dev/serial0"
BAUD = 9600

print(f"Reading from {PORT} @ {BAUD} — press Ctrl+C to stop")
with serial.Serial(PORT, BAUD, timeout=1) as ser:
    while True:
        try:
            line = ser.readline().decode("ascii", errors="replace").strip()
            if not line.startswith("$"):
                continue
            msg = pynmea2.parse(line)
            if isinstance(msg, pynmea2.types.talker.GGA):
                print(f"GGA  fix={msg.gps_qual}  sats={msg.num_sats}  "
                      f"lat={msg.latitude:.6f}  lon={msg.longitude:.6f}  alt={msg.altitude}m")
            elif isinstance(msg, pynmea2.types.talker.RMC):
                if msg.status == "A":
                    print(f"RMC  speed={msg.spd_over_grnd or 0:.2f} kts  "
                          f"date={msg.datestamp}  time={msg.timestamp}")
        except (pynmea2.ParseError, UnicodeDecodeError):
            continue

Note: If you set up gpsd above, stop it first (sudo systemctl stop gpsd) — only one process can own /dev/serial0 at a time.

Run outside (or near a window):

python3 ~/rover/test_gps_read.py

Pass / Fail

Pass: Structured GGA lines with non-zero lat/lon, fix quality 1, sat count ≥4.

Fail:

PermissionError: /dev/serial0 — your user isn't in the dialout group. sudo usermod -a -G dialout $USER then log out and back in.
Nothing prints — gpsd has the port locked. sudo systemctl stop gpsd and re-run.
GGA lines but fix=0 indefinitely — cold-start in progress, or antenna obstructed. See Guide 1 Step 5's "Interpret what you're seeing" — same diagnostic flow.

What about `pi/sensors.py`?

The rover-agent's get_gps() function is still a mock — it returns synthetic lat/lon. Wiring real GPS into sensors.py is its own commit and isn't strictly part of bench validation. We'll do that as part of the broader real-sensor migration (currently planned for after Guide 5). For now, this script proves Python can read the module — that's enough to unblock Guide 4 (Vehicle Prep).

Step 6: Camera Capture from Python

If your camera is currently broken / RMA-pending: skip this step. Come back when the replacement arrives.

The Pi Camera Module 3 talks over CSI, not I2C/UART. Capture is done through libcamera / picamera2.

Quick smoke test

rpicam-hello -t 5000

A preview window should open for 5 seconds. (Over SSH with no display, you won't see the preview, but the camera should still initialize without errors. Add --nopreview to silence the X11 warnings.)

Capture a still:

rpicam-still -o ~/rover/test.jpg --width 1920 --height 1080
ls -lh ~/rover/test.jpg

You should see a JPEG file of a few hundred KB to a couple MB.

Python capture

nano ~/rover/test_camera.py

"""Bench-only camera capture — proves Pi can grab a frame from Python."""
from picamera2 import Picamera2
from datetime import datetime

pc = Picamera2()
config = pc.create_still_configuration(main={"size": (1920, 1080)})
pc.configure(config)
pc.start()

filename = f"/home/todd/rover/captures/test_{datetime.now():%Y%m%d_%H%M%S}.jpg"
pc.capture_file(filename)
pc.stop()
print(f"Saved: {filename}")

python3 ~/rover/test_camera.py

Pass / Fail

Pass: A 1920×1080 JPEG of the camera's view is saved to ~/rover/captures/.

Fail: see Guide 2 Step 4 (the deeper camera test) for the troubleshooting flow.

What You've Validated

After this guide, you've proved end-to-end:

Chain	Validated by
Pi → I2C → PCA9685 (chip responds)	Step 1
Pi → I2C → PCA9685 → PWM → physical servo motion	Step 2
Pi → I2C → ADS1115 (chip responds)	Step 3
Battery → divider → ADS1115 → Python (calibrated reading)	Step 4
GPS → UART → `pynmea2` → structured lat/lon in Python	Step 5
Camera → CSI → `picamera2` → JPEG on disk	Step 6

Every individual building block on the rover is now something you've personally commanded from a Python script. Guide 4 (Vehicle Prep) is purely mechanical. Guide 5 (Wiring) hooks the TRX-4's steering servo into PCA9685 channel 0 and the ESC into channel 1 — using the same adafruit_motor.servo calls you just ran in Step 2.

Checklist

PCA9685 detected at 0x40 (and 0x70)
Spare servo physically sweeps left/center/right under Python control
ADS1115 detected at 0x48
ADC voltage reading matches multimeter ±0.1V after divider ratio applied
GPS NMEA parsed in Python with fix ≥1 and ≥4 satellites
Camera captures 1920×1080 JPEG via picamera2 (or deferred until module arrives)

What's Next

Time to move from the desk to the truck. Guide 4: Vehicle Prep & Mounting preps the TRX-4 chassis, mounts the enclosure, the camera, the GPS antenna, and the battery. No wiring yet — just mechanical layout.