PyRaspThe GPIO header
Every wire in a PyRasp build starts or ends on the Raspberry Pi's 40-pin header: two rows of 20 pins along one edge of the board. Some pins are power, some are ground, and the rest are GPIOs — with a few of them reserved for fixed jobs such as I²C and SPI. Knowing which is which is most of what "wiring" means.
Physical pins and BCM numbers
There are two numbering schemes, and mixing them up is the classic beginner's error:
- Physical (or board) numbers run 1–40 along the header. Pin 1 is a 3V3 pin at one end.
- BCM numbers are the chip's GPIO numbers — 2, 3, 4, … 27 — and are what Python libraries use.
They do not line up: GPIO17 is physical pin 11, and GPIO2 is physical pin 3. gpiozero always uses BCM numbers; RPi.GPIO can be switched with GPIO.setmode(GPIO.BOARD) to use physical ones. In the wiring library, pi.GPIO17, pi.pin(11) and pi.SDA (GPIO2) all address the same pins in different ways.
pinout.xyz is an interactive map of every pin with its alternate functions, and the official Raspberry Pi 4 datasheet covers the electrical details below.
Power and ground
- 3V3 — physical pins 1 and 17. Powers 3.3 V parts. It is not unlimited: the simulator models a 50 mA budget on it and warns when your parts exceed it. On a real Pi, overloading it can reset the board.
- 5V — physical pins 2 and 4. On real hardware this comes straight from the board's supply and is shared with the Pi itself, so it is where servos, relay coils and 5 V sensors belong (the simulator treats it as a steady 5 V).
- GND — pins 6, 9, 14, 20, 25, 30, 34 and 39. All the same electrical point. In
circuit.py, everypi.GNDreturns a fresh ground pin, so you never have to stack wires.
Never connect 5 V to a GPIO, and never wire 5 V to 3V3: the simulator raises a short-circuit warning, and on real hardware both mistakes can destroy the board.
What each GPIO can do
- Any GPIO — 0–27 are on the header — can be a digital input or output at 3.3 V. A pin may safely source or sink about 16 mA (the simulator warns above it), and any voltage above 3.6 V on a pin is overvoltage. Past 50 mA or 3.6 V for half a second, the simulator damages the pin for the rest of the run, like a real one; see electrical mistakes.
- GPIO0 and GPIO1 (physical 27 and 28) are the ID_SD/ID_SC pins used to read a HAT's EEPROM; leave them alone.
- Every pin has a software-selectable internal pull of about 50 kΩ — that is what makes a bare button work. At power-on, GPIO0–8 reset pulled up and GPIO9–27 pulled down, and GPIO2/3 carry fixed 1.8 kΩ I²C pull-ups. Pull-ups and debouncing covers the details.
Pins with a fixed job
| Function | GPIO (BCM) | Physical pins |
|---|---|---|
| I²C1 SDA / SCL | 2 / 3 | 3 / 5 |
| SPI0 MOSI / MISO / SCLK | 10 / 9 / 11 | 19 / 21 / 23 |
| SPI0 CE0 / CE1 | 8 / 7 | 24 / 26 |
| UART TXD / RXD | 14 / 15 | 8 / 10 |
| 1-Wire (default overlay) | 4 | 7 |
| PWM0 | 12 or 18 | 32 or 12 |
| PWM1 | 13 or 19 | 33 or 35 |
The wiring library names them: pi.SDA, pi.SCL, pi.MOSI, pi.MISO, pi.SCLK, pi.CE0, pi.CE1, pi.TXD, pi.RXD. I²C, SPI, UART and 1-Wire explains what each bus does and which library drives it.
The camera connector
The camera ribbon does not plug into the 40-pin header; it has its own connector:
- Pi 4: one 15-pin CSI camera connector.
- Pi 5: two 22-pin CAM/DISP connectors — a standard camera needs the narrower Pi 5 cable.
- Zero 2 W: a mini 22-pin CSI connector.
In the simulator, wire the camera's CSI pin to the Pi's CSI pin and use picamera2; the camera library page walks through it.
The three boards
| Board | Python | GPIO pins | Note |
|---|---|---|---|
| Raspberry Pi 4 Model B | Pi() | 28 | GPIO pins are 3.3 V only. 5 V on any GPIO can permanently damage the SoC. |
| Raspberry Pi 5 | Pi("pi5") | 28 | GPIO now goes through the RP1 chip: RPi.GPIO does not support the Pi 5 on real hardware. Use gpiozero (with lgpio) — the simulator accepts both. |
| Raspberry Pi Zero 2 W | Pi("pi-zero-2w") | 28 | The header holes ship empty: solder a 2×20 header before wiring. |
All three have the same 40-pin header and the same pinout; choose with Pi() (Pi 4 Model B), Pi("pi5") or Pi("pi-zero-2w"). The Zero 2 W's header ships unsoldered, which is worth knowing before you buy one.
Going deeper
- The simulator's electrical model. A GPIO output is 3.3 V behind about 40 Ω. An input reads high at 2.0 V and low at 0.8 V, with hysteresis between so a slowly changing signal does not chatter; above 3.6 V it warns "GPIOx sees N V — GPIO is 3.3 V only". Sourcing more than 16 mA warns, as do the 3V3 rail's 50 mA budget and two different supplies wired together. More than 50 mA, or more than 3.6 V, for 0.5 s damages the pin until the next run.
- Floating inputs. A pin with no pull and nothing connected floats: the simulator flags the net and returns random levels, which is why an unconfigured input can look like a fast-blinking button.
pi.pin(n)orpi.GPIO17? They are the same wire. Use the GPIO name when a program pin matters (LED(17)), and physical numbers when following a diagram. The bus aliases exist so you can wirepi.SDA >> sensor.SDAwithout remembering that SDA is GPIO2.- Power budget. The header's 3V3 pins share one regulator output (the simulator's 50 mA budget); the 5 V pins share the board's input supply with the Pi's own electronics. Hungry parts such as servos and relay coils belong on 5 V, and adding a separate supply is the next step when even that is not enough. The relay primer shows the budgeting in practice.