🍓 Raspberry Pi 5 and Linux

A 640 × 480 camera image has more than 900,000 numbers (three colors per pixel), and dozens of images arrive every second. The ESP32 has enough memory to store only a few of these images and cannot run the vision libraries you’ll use. The Raspberry Pi 5 is a complete computer the size of a credit card: a quad-core processor, gigabytes of memory, a Linux system, Python, and OpenCV. It handles seeing and deciding; the ESP32 continues to handle the motors.

How to read this map: the cyan arrow is wide because it carries a lot of data (the whole image); the purple arrow carries just a short sentence. This asymmetry is how almost every robot with vision is designed: the computer processes the image, and the microcontroller receives only the command. You’ll build this connection in module 3.5.

Why learn this

Knowing what each board does well helps you avoid the two classic mistakes at this stage: trying to run vision on the microcontroller (it won’t fit) and connecting a motor directly to the Pi (it vibrates, lags, and can sometimes burn out a pin). The Pi 4 still works for this module’s basics; for camera use with an object detector, choose the Pi 5.

Key concepts

Inside the robot, the Pi won’t have a screen or keyboard. That’s why you prepare it in “headless” mode (without a head): write the system to the card with Raspberry Pi Imager, configuring the name, user, Wi-Fi, and SSH in advance, then access everything over the network from your computer. The system is Raspberry Pi OS 64-bit, currently based on Debian “Trixie.” For a robot, the Lite version (without a desktop environment) is lighter; if you’d rather see a desktop at first, use the full version.

How to read this map: the three purple panels happen with the card and the board; the cyan panel is your computer communicating with the Pi. If step 4 fails, the problem is almost always in step 1 (the Wi-Fi password was typed incorrectly or SSH is turned off).

Step by step

Goal: connect to the Pi over the network and update the system. Replace <seu_usuario> with the user you created in Imager.

# 1) On YOUR computer: connect to the Pi (the first time, answer "yes")
ssh <seu_usuario>@robo.local

# 2) Once inside the Pi: update the package list and system
sudo apt update
sudo apt full-upgrade -y

# 3) Check what is running
cat /etc/os-release | grep PRETTY_NAME   # should mention Debian and "trixie"
uname -m                                # aarch64 = 64-bit system
hostname -I                             # the Pi's IP address on the network

# 4) Restart to apply kernel updates
sudo reboot

Why learn this

A Pi set up the right way connects to the robot and appears on the network automatically. Configuring everything in Imager saves you from needing a monitor and keyboard, and from trying to edit configuration files by hand—which is where many people get stuck at first.

Key concepts

On the robot, you’ll communicate with the Pi almost entirely through the terminal: a text line where each command is a short word followed by options. You don’t need to memorize dozens of them. With about fifteen, you can navigate folders, edit code, install packages, and figure out why something stopped working.

How to read this map: on the left, the root and three system folders; on the right, what you’ll create yourself inside your personal folder. Keep your files in ~: that way, you won’t accidentally touch anything in the system.

Goal: create the course folder, write a file, check available space, and safely shut down the Pi.

mkdir -p ~/robo && cd ~/robo        # create the folder (if it doesn't exist) and enter it
pwd                                 # shows /home/<seu_usuario>/robo
echo "robo pronto" > notas.txt       # creates a file with one line
cat notas.txt                       # shows the contents
ls -l                               # lists files with size and date
df -h /                             # free space on the card
free -h                             # total and used memory

# Shut down safely (wait for the green LED to stop blinking before unplugging the power)
sudo shutdown -h now

Why learn this

Everything else in the learning path (camera, YOLO26, communication with the ESP32) and all of Learning Path 4 (ROS 2) happen in the terminal. Once you know these commands, you can handle “the card is full,” “the program froze,” and “where did I save that file?” on your own.

Key concepts

If you try pip install directly on Raspberry Pi OS, you’ll see the error externally-managed-environment. This isn’t a defect: the system protects the Python it uses. The right solution is to create a virtual environment (venv) for the robot. One important detail on the Pi: create the venv with --system-site-packages, so it can see libraries installed by the system, such as picamera2 (camera) and gpiozero (pins).

How to read this map: the venv (purple) sits on top of System Python (cyan). The arrow shows that with the --system-site-packagesoption, the venv “looks down” and finds the camera and pins; without it, import picamera2 fails inside the venv.

Goal: create the course venv, activate it, install a package, and confirm that it can see the system libraries.

# Create the environment (just once)
python3 -m venv --system-site-packages ~/robo-venv

# Activate (each time you open a new terminal)
source ~/robo-venv/bin/activate      # the prompt gets "(robo-venv)" at the beginning

# Install packages INSIDE the venv (without sudo)
pip install --upgrade pip
pip install numpy

# Test: Python version and visible system libraries
python -c "import sys; print(sys.prefix)"
python -c "import gpiozero, picamera2; print('gpiozero e picamera2 OK')"

# Exit the venv whenever you want
deactivate

Why learn this

OpenCV, Ultralytics, and pyserial, which you’ll use in the next modules, all go in this virtual environment. Doing it right now avoids the most common vision problem on the Pi: “the camera works in the terminal, but my script can’t find the library.”

Key concepts

The Pi 5 has a double row of 40 pins, like the ESP32 has its own. Some provide power (3.3 V, 5 V, and GND); most are GPIO, pins that your program turns on, turns off, or reads. In Python, the library gpiozero turns these into simple objects: LED(17), Button(27). On the robot, the Pi’s GPIO is for status LEDs, a stop button, and serial communication with the ESP32; the ESP32 handles the motors.

How to read this map: the rectangle marks the start of the connector, viewed from above, with pin 1 in the corner (the square pad on the board). Red is power, gray is GND, and purple is the GPIO you’ll use. The button goes to pin 13, just below pin 11, and to GND on pin 14 next to it.

Goal: make a status LED blink and keep it on while the button is pressed. Connect: GPIO17 (pin 11) → 330 Ω resistor → long leg of the LED; short leg → GND (pin 9). Connect the button between GPIO27 (pin 13) and GND (pin 14). With the virtual environment activated, save as ~/robo/led.py.

# Status LED and button on Raspberry Pi 5 with gpiozero
# Run with: python ~/robo/led.py   (Ctrl+C to exit)
from gpiozero import LED, Button
from signal import pause

led = LED(17)                       # BCM number: GPIO17 = physical pin 11
botao = Button(27, bounce_time=0.05) # GPIO27 = pin 13; internal pull-up enabled

def apertou():
    led.on()
    print("button pressed: LED on")

def soltou():
    led.blink(on_time=0.2, off_time=0.8)  # starts blinking in the background again
    print("button released: LED blinking")

botao.when_pressed = apertou
botao.when_released = soltou
soltou()                            # initial state: blinking
print("Ready. Press the button. Ctrl+C to exit.")
pause()                             # keeps the program running and waiting for events

Why learn this

The 3.3 V pin requires the same care as on the ESP32, but a mistake costs more: a burned-out Pi 5 costs much more than an ESP32. And gpiozero, with events like when_pressed, is the simplest way to add a physical stop button to the robot, which you’ll use in project 3.6.

Key concepts

On the workbench, the Pi 5 uses the official 27 W power supply (5 V, 5 A, USB-C). With a weaker power supply, it still works, but limits current to the USB ports and may restart when the camera and AI draw power at the same time. In the robot, there’s no wall outlet: the battery goes through a buck regulator that provides stable 5 V with enough current. And when running vision, the processor heats up: without the active cooler, it slows itself down to protect itself, and your detector gets slower without warning.

How to read this map: power (amber) comes from the battery and splits before reaching any board. The upper branch, with the buck converter highlighted, keeps the Pi stable. The gray dashed line reminds you that the GND connections on all boards must be connected to each other.

Goal: monitor temperature and power alerts while the robot is running. Save as ~/robo/saude.py and leave it running in a second terminal during vision tests.

# Pi 5 health monitor: temperature and power/thermal alerts
import subprocess, time

def temperatura():
    with open("/sys/class/thermal/thermal_zone0/temp") as f:
        return int(f.read()) / 1000          # reported in thousandths of a degree

def alertas():
    saida = subprocess.run(["vcgencmd", "get_throttled"],
                           capture_output=True, text=True).stdout
    valor = int(saida.strip().split("=")[1], 16)
    msgs = []
    if valor & 0x1:     msgs.append("UNDERVOLTAGE NOW")
    if valor & 0x4:     msgs.append("throttled NOW")
    if valor & 0x10000: msgs.append("undervoltage occurred since boot")
    if valor & 0x40000: msgs.append("throttling occurred since boot")
    return msgs or ["power OK"]

while True:
    t = temperatura()
    aviso = "  HOT: check the cooler" if t > 75 else ""
    print(f"{time.strftime('%H:%M:%S')}  {t:.1f} °C  {', '.join(alertas())}{aviso}")
    time.sleep(2)

Why learn this

Most vision “bugs” in robots start here: the Pi restarts when the robot speeds up, or the detector drops to half speed after a few minutes. Measuring temperature and undervoltage helps distinguish a power problem from a code problem and saves you from looking for the error in the wrong place.

Key concepts