Autonomous Raspberry Pi line-following car

The goal, the stack, and what we build

The goal is a small car that drives itself along a black line taped to the floor: it stays centred on the line, slows for curves, hunts for the line if it loses it, and stops cleanly at the end. This is the reactive-autonomy core of the Module 4 capstone — the same sense–think–act loop introduced in Session 1, now running tens of times a second on real hardware. The car is deliberately built from the cheapest reliable parts so the engineering lives in the software and tuning, not the bill of materials.

Sessions this project exercises

The worked example is the integration point for almost every session of the course:

Stack

Hardware list

Everything connects to a single Raspberry Pi using BCM pin numbering. Motor power comes from a separate battery pack — the Pi supplies only logic-level signals (Session 10 safety rule).

Sensors → controller → actuators

The car is a textbook sense–think–act pipeline. Each loop iteration the sense stage reads the IR array (and optionally a camera frame) and reduces it to a single line-position error; the think stage runs that error through a PID controller and a state machine to decide a steering correction and a base speed; the act stage mixes those into left/right motor duty cycles and writes them to the L298N over PWM.

Wiring

The Pi never drives a motor directly — its 3.3 V GPIO can't source the current (Session 9/10). Instead, four direction pins and two PWM "enable" pins command the L298N, which switches the separate motor battery. Sensors share a common ground with the Pi.

Detecting the line

The whole controller acts on one number: the line's offset from centre, in the same units every cycle. We compute it two ways — a fast IR array (primary) and an OpenCV camera fallback (richer, used for the vision extension) — and both return an error e where e = 0 means perfectly centred, positive means the line is to the right, negative to the left.

IR reflectance array

Five IR sensors sit in a row under the nose of the car. Each reads 1 over the dark line and 0 over the light floor (after calibrating the threshold to the real surface — Session 13). We assign each channel a fixed position weight and take the weighted average of the channels that see the line. With weights [-2, -1, 0, +1, +2], an all-centre reading gives 0; the line drifting under the rightmost sensor gives +2.

import RPi.GPIO as GPIO

IR_PINS    = [5, 6, 13, 19, 26]   # left -> right, BCM numbering
IR_WEIGHTS = [-2, -1, 0, 1, 2]    # position of each channel

def setup_ir():
    GPIO.setmode(GPIO.BCM)
    for pin in IR_PINS:
        GPIO.setup(pin, GPIO.IN)

def read_line_error():
    """Return (error, on_line). error in [-2, +2]; 0 = centred."""
    bits = [GPIO.input(pin) for pin in IR_PINS]   # 1 = sees dark line
    active = sum(bits)
    if active == 0:
        return 0.0, False                         # line lost
    weighted = sum(w * b for w, b in zip(IR_WEIGHTS, bits))
    return weighted / active, True             # centre of mass of the line

Camera fallback (OpenCV)

For the vision extension we grab a frame, crop a thin region of interest near the front of the car, threshold it to isolate the dark line, and take the centroid of the line pixels. The error is the centroid's horizontal offset from the frame centre, in pixels — the exact "reduce a rich image to one number" pattern from Session 11. We keep the ROI small so the loop stays fast.

import cv2
import numpy as np
from picamera2 import Picamera2

cam = Picamera2()
cam.configure(cam.create_preview_configuration(main={"size": (320, 240)}))
cam.start()

def read_line_error_cv():
    """Return (error_px, on_line). error_px > 0 means line is to the right."""
    frame = cam.capture_array()                 # RGB, 320x240
    gray  = cv2.cvtColor(frame, cv2.COLOR_RGB2GRAY)
    roi   = gray[180:210, :]                    # thin strip near the front

    # dark line on light floor -> invert so the line is white
    _, mask = cv2.threshold(roi, 70, 255,
                            cv2.THRESH_BINARY_INV)
    M = cv2.moments(mask)
    if M["m00"] == 0:
        return 0.0, False                       # no line pixels -> lost

    cx = M["m10"] / M["m00"]                  # centroid x (px)
    frame_center = roi.shape[1] / 2.0          # 160 px
    return cx - frame_center, True           # offset from centre

The PID steering controller

The line error tells us how wrong we are; the controller decides what to do about it. A PID controller (Session 5) computes a single steering correction u from the error, and we mix that correction into the two motor speeds to turn the car back toward the line.

In software the loop runs at discrete steps of length dt (here ~20 ms, so ~50 Hz), so the integral becomes a running sum and the derivative a finite difference:

Building it step by step

import time

class PID:
    def __init__(self, kp, ki, kd, out_limit=100.0, i_limit=40.0):
        self.kp, self.ki, self.kd = kp, ki, kd
        self.out_limit = out_limit      # clamp on the final output
        self.i_limit   = i_limit        # clamp on the integral (anti-windup)
        self.integral  = 0.0
        self.prev_e    = 0.0
        self.prev_t    = time.monotonic()

    def reset(self):
        self.integral = 0.0
        self.prev_e   = 0.0
        self.prev_t   = time.monotonic()

    def update(self, error):
        now = time.monotonic()
        dt  = max(now - self.prev_t, 1e-3)   # guard against dt = 0

        # proportional
        p = self.kp * error

        # integral, clamped to stop windup
        self.integral += error * dt
        self.integral = max(-self.i_limit, min(self.i_limit, self.integral))
        i = self.ki * self.integral

        # derivative on the error
        d = self.kd * (error - self.prev_e) / dt

        u = p + i + d
        u = max(-self.out_limit, min(self.out_limit, u))   # clamp output

        self.prev_e = error
        self.prev_t = now
        return u

import RPi.GPIO as GPIO

IN1, IN2, ENA = 17, 27, 18      # left motor
IN3, IN4, ENB = 22, 23, 12      # right motor
PWM_HZ        = 1000                # 1 kHz switching
DEADBAND      = 18.0                # min duty that actually turns the wheel

def setup_motors():
    GPIO.setmode(GPIO.BCM)
    for p in (IN1, IN2, IN3, IN4, ENA, ENB):
        GPIO.setup(p, GPIO.OUT)
    left  = GPIO.PWM(ENA, PWM_HZ); left.start(0)
    right = GPIO.PWM(ENB, PWM_HZ); right.start(0)
    return left, right

def _clamp_duty(duty):
    duty = max(0.0, min(100.0, duty))
    # jump over the deadband so a small command still moves the wheel
    return 0.0 if duty < 1.0 else DEADBAND + duty * (100 - DEADBAND) / 100

def drive(left_pwm, right_pwm, base, u):
    """base = forward speed (0-100); u = PID steering correction."""
    duty_l = _clamp_duty(base + u)        # u > 0 -> steer right
    duty_r = _clamp_duty(base - u)

    # both wheels forward (set direction pins once)
    GPIO.output(IN1, GPIO.HIGH); GPIO.output(IN2, GPIO.LOW)
    GPIO.output(IN3, GPIO.HIGH); GPIO.output(IN4, GPIO.LOW)
    left_pwm.ChangeDutyCycle(duty_l)
    right_pwm.ChangeDutyCycle(duty_r)

The state machine & main loop

A pure PID line-follower has one fatal flaw: the moment the line disappears (a gap, a sharp corner, the end of the track) the error reads 0 and the car sails straight off. The fix from Session 12 is to add a little state. We wrap the controller in a three-state machine:

• FOLLOW — line is visible: run the PID and drive at base speed (reduced on tight curves).
• SEARCH — line just lost: stop driving forward and pivot toward the side the line was last seen, for up to a timeout. Find it → back to FOLLOW; timeout → STOP.
• STOP — line gone for good (or an obstacle/end detected): cut the motors and hold.

import time
import RPi.GPIO as GPIO
from pid     import PID
from sensors import setup_ir, read_line_error
from drive   import setup_motors, drive

# --- tuned constants (see the results table) ---
KP, KI, KD   = 22.0, 0.4, 9.0
BASE_SPEED   = 55.0          # forward duty on a straight
CURVE_SLOW   = 0.6           # speed multiplier when |error| is large
LOOP_DT      = 0.02          # 20 ms -> ~50 Hz
SEARCH_TIME  = 1.5           # seconds to hunt before giving up
SEARCH_TURN  = 45.0          # pivot duty while searching

FOLLOW, SEARCH, STOP = "FOLLOW", "SEARCH", "STOP"

def main():
    setup_ir()
    left, right = setup_motors()
    pid = PID(KP, KI, KD)

    state          = FOLLOW
    last_dir       = 1.0     # +1 line was last to the right, -1 to the left
    search_started = 0.0

    try:
        while True:
            t0 = time.monotonic()
            error, on_line = read_line_error()

            # ---- THINK: state transitions ----
            if state == FOLLOW:
                if on_line:
                    last_dir = 1.0 if error >= 0 else -1.0
                else:
                    state, search_started = SEARCH, t0
                    pid.reset()                 # drop stale integral

            elif state == SEARCH:
                if on_line:
                    state = FOLLOW
                elif t0 - search_started > SEARCH_TIME:
                    state = STOP

            # ---- ACT ----
            if state == FOLLOW:
                u     = pid.update(error)
                speed = BASE_SPEED * (CURVE_SLOW if abs(error) > 1.0 else 1.0)
                drive(left, right, speed, u)
            elif state == SEARCH:
                # pivot in place toward where the line vanished
                drive(left, right, 0.0, last_dir * SEARCH_TURN)
            else:  # STOP
                drive(left, right, 0.0, 0.0)
                break

            # ---- keep a steady loop rate ----
            time.sleep(max(0.0, LOOP_DT - (time.monotonic() - t0)))
    finally:
        GPIO.cleanup()                          # always release the pins

if __name__ == "__main__":
    main()

Behaviour & tuning

With the tuned gains above (Kp=22, Ki=0.4, Kd=9) the car tracks a 2 cm line at ≈0.3 m/s, holds the centre to within one sensor width on straights, slows automatically into curves, and recovers from a lost line by pivoting back onto it. The behaviour we observed across runs:

• Straights: near-zero steering output, the car runs at full BASE_SPEED.
• Gentle curves: proportional term steers smoothly; derivative term prevents overshoot at the curve exit.
• Sharp corners: CURVE_SLOW drops the speed so the IR array doesn't skip past the line between samples.
• Gaps / line end: SEARCH pivots toward the last-seen side; re-acquires small gaps, stops cleanly at the real end.

PID tuning table

How we got there — the classic "raise Kp until it oscillates, add Kd to damp, add just enough Ki" procedure from Session 5, recorded run by run:

Mapping to course outcomes

This single build hits the Module 4 learning outcomes and reaches back into Modules 1–2:

• Wire sensors & actuators to GPIO The hardware list and wiring diagram connect an IR array, camera and L298N to specific BCM pins, with the common-ground / no-back-feed safety rules (S9, S10).
• Program motor control in Python drive.py sets direction pins and PWM duty through an H-bridge, including the deadband mapping (S10).
• Apply feedback control A complete discrete PID with anti-windup reduces a measured error toward a setpoint of zero (S5).
• Build a reactive autonomous behaviour The follow/search/stop state machine is reactive navigation with just enough memory to escape the "line lost" trap (S12).
• Test, tune & document The PID tuning table is exactly the kind of run-by-run evidence the 20% report component rewards (S13, S14).
• Reduce perception to one signal Both IR and OpenCV sensing collapse a rich input into a single line-position error — the perception→control pattern (S11).

Extensions

Once the line-follower is solid, every harder behaviour is a variation on the same loop:

References