The Pi and its pins

Every circuit starts with one Raspberry Pi. Pi() builds the Raspberry Pi 4 Model B; pass a board slug for one of the other two boards. The board is provided — it never appears on the bill.

from wiring import *

pi = Pi()
pi.pin(11) >> Resistor(330) >> LED("green") >> pi.GND

from gpiozero import LED
from time import sleep

led = LED(17)

while True:
    led.on()
    sleep(1)
    led.off()
    sleep(1)

A board has exactly one Pi: call Pi() once, keep it in a variable, and reuse that variable. A second Pi() raises a CircuitError — the fix is to use the pi you already have.

The three boards

The model is the board's catalogue slug, so Pi() and Pi("pi4b") are the same Raspberry Pi 4 Model B:

pi = Pi("pi5")          # a Raspberry Pi 5; Pi("pi-zero-2w") and Pi() also work

An unknown model raises a CircuitError that lists the three slugs.

GPIO pins

pi.GPIO0 … pi.GPIO27 are the 28 GPIO pins on the header, named by their BCM number — the same number you pass to gpiozero or RPi.GPIO in main.py, so pi.GPIO17 goes with LED(17). There is a method form too:

pi.GPIO17 >> Resistor(330) >> LED("red") >> pi.GND
pi.gpio(22)             # a Pin — the same header pin as pi.GPIO22

pi.GPIO28 and above are not on the header and raise a CircuitError.

Power rails

pi.V3_3 is the 3.3 V rail, pi.V5 the 5 V rail, and pi.GND ground. Each call hands out the next header pin for that rail, so two pi.GND accesses are two different pins — two parts can each end their chain on their own ground pin:

pi.GPIO17 >> Resistor(330) >> LED("red") >> pi.GND
pi.GPIO27 >> Resistor(330) >> LED("green") >> pi.GND   # a different ground pin

The same rotation applies to pi.V3_3 and pi.V5.

Bus pins

The header's usual bus functions have names of their own. Each one is an ordinary GPIO pin, so pi.SDA and pi.GPIO2 reach the same header position:

The camera connector

pi.CSI is the camera ribbon connector, not a 40-pin header pin. Wire the camera module's CSI pin to it:

camera = Camera()
camera.csi >> pi.CSI

Physical pin numbers

pi.pin(n) addresses a header position directly, from 1 to 40:

pi.pin(11)              # physical pin 11 — the same pin as pi.GPIO17
pi.pin(9)               # physical pin 9 — a ground pin

pi.pin("…") also takes a name and resolves it exactly like an attribute: pi.pin("GPIO17"), pi.pin("GND"), pi.pin("3V3"), pi.pin("SDA"). Rail names go through the same rotation as pi.GND, so each call is a fresh pin.

What raises an error

• a second Pi() in one circuit;
• a model slug that is not one of the three boards;
• pi.GPIO28 or higher — only GPIO0–GPIO27 are on the header;
• pi.pin(0) or pi.pin(41) — physical pins are numbered 1–40;
• pi.pin("nonsense") — an unknown name.

Each of them is listed, with its fix, on Circuit errors.

Going deeper

Every spelling above reaches the same Pin objects: one Pin per header position. pi.GPIO17, pi.gpio(17), pi.pin(11) and pi.pin("GPIO17") are four ways to name pin 11, which is useful when you are reading a datasheet that uses a different convention than your code.

• Rails keep their own counters. Each of GND, 3V3 and 5V rotates through its own list of header pins, starting at the first. They advance only when you ask for a pin, not when a wire is drawn.
• The board's pin labels drive wire colours. The library reads the header label (GND, 3V3, 5V, GPIO17, …) when it picks a wire colour; see Wires and chains.
• The buses are only names. pi.SDA does not start I²C — it is the same GPIO as pi.GPIO2. Turning it into an I²C bus is main.py's job; the buses primer explains the wiring behind each one.
• The three boards share the header, so the same circuit.py builds on all of them. The differences — the Pi 5's RP1 GPIO controller, the smaller camera connectors — are in the table above and the GPIO header primer.
• The official Raspberry Pi 4 datasheet covers the header: Raspberry Pi 4 datasheet.