Two numbering schemes
| Scheme | Counts | Example: the same pin |
|---|---|---|
| BCM / GPIO | the SoC's GPIO signal | GPIO17 |
| BOARD / physical | position on the 40-pin header (1–40) | pin 11 |
Tutorials, HAT docs and code mix both. "Connect the LED to pin 17" is ambiguous; wiring to physical pin 17 (a 3.3 V pin!) instead of GPIO17 is a classic mistake.
In code
RPi.GPIO makes you choose: GPIO.setmode(GPIO.BCM) or GPIO.setmode(GPIO.BOARD).
gpiozero always uses BCM numbers and translates other notations:
from gpiozero import LED
LED(17) # GPIO17 (BCM)
LED("GPIO17") # same
LED("BOARD11") # same pin, physical numbering
LED("J8:11") # same pin, header notation
Error messages and repr() always show the BCM number, so write BCM numbers in docs and comments to match what the library reports.
Tips
- Run
pinout(installed with gpiozero) on the Pi to print the header with both numbers for the board you're on. - The 40-pin layout has been the same since the Model B+ (Zero, 2B, 3B, 4B share it). Only the very first Model B boards differ.
- On Raspberry Pi alternatives, neither scheme is guaranteed to match. Check the board's own pinout (see the GPIO compatibility warning for alternatives).
- Label wires by GPIO number, not header position. Header positions don't survive a change of board or HAT.
Sources: Stack Exchange (CC BY-SA 4.0) — see links.