██████╗  █████╗ ███████╗██████╗ ██████╗ ███████╗██████╗ ██████╗ ██╗   ██╗    ██████╗ ██╗
██╔══██╗██╔══██╗██╔════╝██╔══██╗██╔══██╗██╔════╝██╔══██╗██╔══██╗╚██╗ ██╔╝    ██╔══██╗██║
██████╔╝███████║███████╗██████╔╝██████╔╝█████╗  ██████╔╝██████╔╝ ╚████╔╝     ██████╔╝██║
██╔══██╗██╔══██║╚════██║██╔═══╝ ██╔══██╗██╔══╝  ██╔══██╗██╔══██╗  ╚██╔╝      ██╔═══╝ ██║
██║  ██║██║  ██║███████║██║     ██████╔╝███████╗██║  ██║██║  ██║   ██║       ██║     ██║
╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝     ╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝       ╚═╝     ╚═╝

Raspberry Pi — Novice-to-Pro Developer Guide

Focus: A complete path from "I just bought a Pi" to shipping production edge workloads — hardware models, headless OS setup, the 40-pin GPIO header and its 3.3V rule, the Python physical-computing stack (gpiozero, picamera2, lgpio), build ideas, experiments to run with Claude Code, and how the Pi compares to Arduino, ESP32, Jetson, and the Pi's own Pico microcontroller. Grounded in raspberrypi.com/documentation + gpiozero.readthedocs.io; reviewed 2026-06-11.

The Raspberry Pi is the rare device that is approachable on day one and still in your rack five years later. The trick is to learn it in the right order: get a headless Linux box running first (no monitor, no keyboard), then reach for the soldering iron. The interactive learn module above this page is a live 40-pin GPIO pinout explorer — start there to build intuition for the header, then use this reference.

Table of Contents

1. What a Raspberry Pi actually is
2. Pick the right board
3. Headless OS setup (the right way)
4. First-boot configuration
5. The 40-pin GPIO header
6. Physical computing with gpiozero
7. The camera & other interfaces (I2C/SPI/UART)
8. Hardware components shopping list
9. Build ideas — novice to pro
10. Experiments with Claude Code
11. Raspberry Pi Pico (the microcontroller)
12. Comparable tech stacks
13. codeAmani notes

Official Documentation

1. What a Raspberry Pi actually is

A single-board computer (SBC): a complete ARM-based Linux computer — CPU, RAM, USB, HDMI, networking, storage (microSD) — on one board, with a 40-pin GPIO header for talking to electronics. That dual nature is the whole point:

Why it matters: because it's real Linux, everything you already know — ssh, systemd, Docker, Python, Node, cron, nginx — works unchanged. And because it has GPIO, the same box that runs a Flask app can also read a temperature sensor or drive a relay. It is the cheapest honest "computer + I/O" you can buy.

Microcontroller vs SBC: A Pi runs a full OS and is great at software (servers, ML, networking). A microcontroller (Arduino, ESP32, the Pi Pico) runs one program on bare metal with precise real-time timing and microamp sleep. Many real projects pair them: Pi for brains + network, Pico/Arduino for the twitchy real-time pins. See §11 and §12.

2. Pick the right board

Don't overbuy. Match the board to the job:

Also buy (these are not optional): a quality USB-C/micro-USB power supply (under-volting causes mysterious crashes — use the official PSU or a known-good 5V/3A+), a decent A2-rated microSD card (16 GB+; cheap cards corrupt), and for the Pi 5 active cooling. For reliability, an NVMe/USB-SSD boot beats microSD.

3. Headless OS setup (the right way)

You do not need a monitor or keyboard. The professional workflow is headless from minute one.

1. Flash with Raspberry Pi Imager. Download from raspberrypi.com/software, pick your board, choose Raspberry Pi OS (Lite = no desktop, perfect for servers; full = desktop). Then — and this is the step beginners skip — click the ⚙ / "Edit settings" (OS customisation) button before writing:

• Set hostname (e.g. amani-pi)
• Enable SSH (password or, better, paste your public key)
• Configure Wi-Fi SSID + password + country
• Set locale / timezone (Africa/Nairobi)
• Set the username + password (the old default pi/raspberry is gone)

2. Boot and SSH in — no screen required:

# From your laptop (mDNS resolves <hostname>.local on the same network)
ssh amani@amani-pi.local
# or by IP if .local doesn't resolve:
ssh amani@192.168.1.42

# First things first
sudo apt update && sudo apt full-upgrade -y
sudo reboot

If *.local doesn't resolve (some Windows/Android setups), find the IP from your router's DHCP table or ping amani-pi.local. On Windows, install Bonjour/iTunes or just use the IP.

4. First-boot configuration

raspi-config is the official text-UI for system settings; everything in it is also scriptable:

sudo raspi-config            # interactive: interfaces, locale, hostname, boot
sudo raspi-config nonint do_i2c 0    # enable I2C non-interactively (0 = enable)
sudo raspi-config nonint do_spi 0    # enable SPI
sudo raspi-config nonint do_ssh 0    # ensure SSH on

Interfaces (I2C, SPI, the camera, UART) can also be toggled directly in /boot/firmware/config.txt via device-tree params — useful in provisioning scripts and Ansible:

# /boot/firmware/config.txt  — enable buses at boot
dtparam=i2c_arm=on
dtparam=spi=on
dtparam=audio=on
# camera autodetect is on by default on current Pi OS:
camera_auto_detect=1

# Sanity checks after enabling
ls /dev/i2c-*          # I2C bus appears
ls /dev/spidev*        # SPI device appears
i2cdetect -y 1         # scan the I2C bus for device addresses (sudo apt install i2c-tools)
vcgencmd measure_temp  # SoC temperature — watch for throttling

5. The 40-pin GPIO header

Every current Pi (and the Zero/Pico, sometimes unpopulated) exposes a 40-pin header on a 0.1in (2.54 mm) pitch. The single rule that saves your board:

⚠️ GPIO is 3.3V logic, not 5V. The pins source/sink 3.3V and are not 5V-tolerant — putting 5V on a GPIO input can permanently damage the SoC. There are two 5V pins (for powering peripherals) and several 3V3 and GND pins, but every signal pin is 3.3V. Use a level shifter for 5V sensors, or hang them off a Pico instead.

The header is a fixed standard across boards. The layout (physical pin → function):

BCM vs physical numbering — the #1 beginner trap. Software (gpiozero, RPi.GPIO) addresses pins by Broadcom (BCM) GPIO number, not by physical position. LED(17) means BCM17, which sits at physical pin 11 — not physical pin 17 (that's a 3V3 power pin). When in doubt, run pinout on the Pi:

pinout       # ASCII diagram of YOUR board's header (ships with gpiozero)

6. Physical computing with gpiozero

gpiozero is the official, beginner-friendly Python library — it wraps pins as devices (LED, Button, Servo, DistanceSensor) so you write intent, not register pokes. It's pre-installed on Raspberry Pi OS; otherwise:

sudo apt install python3-gpiozero      # recommended (also installs the `pinout` tool)
# or in a venv:
pip install gpiozero rpi-lgpio          # rpi-lgpio = modern backend on Pi 5 / Bookworm

Blink an LED (LED on BCM17 = physical pin 11, through a ~330Ω resistor to GND):

from gpiozero import LED
from time import sleep
from signal import pause

led = LED(17)            # BCM17 — NOT physical pin 17
while True:
    led.toggle()
    sleep(0.5)

Button toggles LED — event-driven, no polling loop:

from gpiozero import LED, Button
from signal import pause

led = LED(17)
button = Button(2)       # BCM2, with internal pull-up by default

button.when_pressed = led.on
button.when_released = led.off
pause()                  # sleep forever, let callbacks fire

PWM for brightness / motor speed:

from gpiozero import PWMLED
from time import sleep

led = PWMLED(17)
while True:
    led.value = 0.1      # 10% duty cycle
    sleep(1)
    led.pulse()          # smooth fade in/out
    sleep(3)

gpiozero uses BCM numbering and it is not configurable — but you can pass alternate notations that all resolve to BCM: LED(17), LED("GPIO17"), LED("BOARD11") (physical), or LED("J8:11") (header:pin). For lower-level work, RPi.GPIO (legacy) / rpi-lgpio (its drop-in successor on Pi 5) and pigpio (hardware-timed PWM, remote GPIO over the network) are the steps down toward the metal.

7. The camera & other interfaces (I2C/SPI/UART)

Camera (CSI ribbon → picamera2). Modern Pi OS autodetects official camera modules. picamera2 is the supported Python API (the old picamera is deprecated):

sudo apt install -y python3-picamera2                  # full (with preview GUI deps)
sudo apt install -y python3-picamera2 --no-install-recommends   # Lite OS, no GUI

from picamera2 import Picamera2
from time import sleep

picam2 = Picamera2()
picam2.start()
sleep(2)                       # let auto-exposure settle
picam2.capture_file("shot.jpg")
picam2.stop()

rpicam-still -o test.jpg       # CLI capture (formerly libcamera-still)
rpicam-hello -t 5000           # 5s preview to confirm the camera is detected

The three buses, in one breath:

i2cdetect -y 1        # find I2C device addresses (e.g. 0x3c for an OLED, 0x76 for BME280)

8. Hardware components shopping list

A starter kit that covers 90% of beginner projects:

• Breadboard + jumper wires (M-M, M-F) + a 40-pin GPIO breakout / T-cobbler ribbon (keeps you off the live header)
• Resistors (330Ω for LEDs, 10kΩ for pull-ups), assorted LEDs, tactile push-buttons
• Sensors: DHT22/BME280 (temp/humidity/pressure, I2C), HC-SR04 (ultrasonic distance), PIR (motion), LDR (light), MCP3008 (ADC — the Pi has no analog input, this is how you read analog sensors over SPI)
• Output: SSD1306 OLED (I2C), relay module (mains switching — be careful), small servo (SG90), DC motors + an L298N / motor HAT (never drive motors straight off GPIO)
• Power discipline: a logic level shifter for 5V parts, and a separate supply for motors/servos (back-EMF + current spikes will brown-out your Pi)
• HATs (Hardware Attached on Top): plug-in boards — Sense HAT (sensors + LED matrix), PoE HAT, motor/relay HATs, the AI HAT+ (Hailo NPU on Pi 5)

The cardinal hardware rules: common ground between Pi and any external supply; never source motor/relay current from a GPIO pin; level-shift anything 5V; and double-check polarity before powering on.

9. Build ideas — novice to pro

• Novice: Blink, traffic-light LEDs, reaction-timer button game, GPIO-controlled buzzer; a tiny Flask/Node page on the LAN that turns an LED on/off (your first "IoT").
• Intermediate: Weather station (BME280 → SQLite/Postgres → a dashboard); Pi-hole network ad-blocker + WireGuard VPN to reach home from anywhere; Samba/NAS on a USB SSD; time-lapse camera; magic mirror; print server.
• Advanced: MQTT sensor network (many Picos/ESP32s publishing to a Mosquito broker on the Pi); kiosk digital signage (Chromium in kiosk mode); RetroPie console; Home Assistant hub; doorbell camera with motion detection.
• Pro: Edge ML inference with a Hailo AI HAT+ or Coral USB TPU (object detection on a live camera, offline); a K3s / Docker Swarm cluster of Pis; a Compute Module baked into your own carrier board as a shippable product; a solar-powered remote telemetry node.

10. Experiments with Claude Code

Claude Code runs on the Pi (it's just Linux + Node) or drives it remotely over SSH from your laptop. Both unlock fast hardware iteration: describe the circuit and the behaviour, let Claude write the gpiozero script, run it, read the output, and iterate.

# On the Pi (ARM64 Linux): install Node, then Claude Code
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
npm install -g @anthropic-ai/claude-code     # see the claude-api guide for current install
cd ~/projects/pi-lab && claude

Experiments that play to Claude Code's strengths:

1. Conversational circuit bring-up. "I wired a BME280 to I2C and an SSD1306 OLED — read temp/humidity every 10s and show it on the display." Claude writes it; i2cdetect -y 1 confirms addresses; you run and refine.
2. Hardware-in-the-loop TDD. Have Claude write a fake/mock pin backend (gpiozero supports a mock pin factory, GPIOZERO_PIN_FACTORY=mock) so logic is unit-tested on your laptop, then deployed to real pins on the Pi.
3. Sensor → cloud pipeline. "Publish each reading to MQTT and also POST to a Next.js API route." Pairs with the webhooks and supabase guides.
4. Local LLM on the edge. Run a small quantised model (ollama / llama.cpp) on a Pi 5 and have Claude Code build the glue: a voice-or-text assistant that works offline — relevant where connectivity is intermittent.
5. Vision on the edge. Wire the camera + a Hailo/Coral accelerator; Claude scaffolds a picamera2 capture loop feeding an object detector, writing events to a DB.
6. Remote GPIO from your dev box. pigpio exposes GPIO over the network — Claude Code on your laptop can prototype against the Pi's pins without copying files each iteration.

Run Claude Code over SSH for the tightest loop: edit on the laptop, execute on the Pi, watch real sensor output stream back. Pair with chrome-devtools to verify any web UI the Pi serves.

11. Raspberry Pi Pico (the microcontroller)

The Pico is a different animal: a microcontroller board built on the in-house RP2040 (Pico/Pico W) or RP2350 (Pico 2) chip — not a Linux computer. No OS, no SD card; you flash one program that runs on bare metal. It shines where the Pi is weak: precise real-time timing, microamp sleep, true analog inputs (ADC), and being cheap enough to scatter.

Two ways to program it:

# MicroPython (drag-and-drop firmware, then this is main.py) — blink the onboard LED
from machine import Pin
from time import sleep
led = Pin("LED", Pin.OUT)
while True:
    led.toggle()
    sleep(0.5)

// C/C++ with the Pico SDK — pico-examples style
#include "pico/stdlib.h"
int main() {
    const uint LED = PICO_DEFAULT_LED_PIN;
    gpio_init(LED); gpio_set_dir(LED, GPIO_OUT);
    while (true) { gpio_put(LED, 1); sleep_ms(250); gpio_put(LED, 0); sleep_ms(250); }
}

Pico W adds Wi-Fi/BT, so it can publish to MQTT on its own. The classic architecture: Picos at the edge (sensors, real-time control) talking to a Pi hub (network, storage, dashboard).

12. Comparable tech stacks

What else lives in this space, and when to pick it instead:

The honest summary: the Pi wins on ecosystem — documentation, community answers, library support, and "it just works" software. Rivals win on specific axes (price-per-spec, GPU, battery life, real-time determinism). Most serious builds are hybrids: a Pi for brains + a Pico/ESP32 for the real-time edge.

13. codeAmani notes

• The Pi is our edge node. A Pi Zero 2 W or Pi 4 is a power-frugal, always-on ARM64 Linux box — ideal for an in-shop or rural deployment running on solar/battery. Spec the board to the job (§2) and don't overbuy RAM you won't use.
• Power and SD discipline are reliability, not nitpicking. Brown-outs from a weak PSU and corruption from a cheap microSD are the two most common field failures — exactly the conditions an East-African deployment (unstable mains, dust, heat) amplifies. Use the official PSU, an A2 card (or SSD boot), and vcgencmd measure_temp / get_throttled in your monitoring.
• Secrets stay server-side. A Pi reachable on a LAN is still a server: keep Daraja/M-Pesa keys, tokens, and DB creds in .env//etc/secrets (git-ignored, chmod 600), never baked into a flashed image you might share. Treat a Pi image like any deployable artefact.
• Offline-first fits the market. Pis make local-first sense: a Pi 5 running a small quantised LLM (ollama) or a Hailo vision model keeps working when the link to the cloud drops, syncing when it returns — the right posture for African-market connectivity.
• Pi + Pico is the pattern. When you need real-time pins or battery sensors, don't fight the Pi's Linux scheduler — offload to a Pico/ESP32 over UART/MQTT and let the Pi do networking, storage, and dashboards. See §11–§12.
• Iterate with Claude Code over SSH. Edit on your laptop, run on the Pi, read real sensor output back (§10) — and unit-test pin logic with GPIOZERO_PIN_FACTORY=mock before it ever touches hardware.