Source: GPIO Zero Basic Recipes

Pin Numbering

GPIO Zero uses BCM (Broadcom) numbering by default — not physical BOARD numbering.

led = LED(17)         # BCM17 = physical pin 11
led = LED("BOARD11")  # equivalent
led = LED("BCM17")    # equivalent

Always reports pin number back in BCM regardless of how you specified it.

Keep Script Alive: signal.pause()

Critical: if you assign callbacks (when_pressed, etc.) and then reach the end of the script, Python exits and GPIOs reset. Use signal.pause() to block forever.

from signal import pause
 
button.when_pressed = led.on
button.when_released = led.off
 
pause()  # blocks here, callbacks fire in background thread

LED

from gpiozero import LED
from time import sleep
 
red = LED(17)
red.on()
red.off()
red.toggle()
red.blink()      # blinks indefinitely in background
 
# Keep alive (required when using blink() or callbacks)
from signal import pause
pause()

PWMLED (variable brightness)

from gpiozero import PWMLED
from signal import pause
 
led = PWMLED(17)
led.value = 0      # off
led.value = 0.5    # half brightness
led.value = 1      # full brightness
led.pulse()        # continuously fade in/out
 
pause()

Button

from gpiozero import Button
from signal import pause
 
button = Button(2)
 
# Poll state
if button.is_pressed:
    print("Pressed")
 
# Blocking wait
button.wait_for_press()
button.wait_for_release()
 
# Callbacks (non-blocking; need signal.pause() to keep alive)
def say_hello():
    print("Hello!")
 
button.when_pressed = say_hello       # NOTE: no () — pass function reference, not return value
button.when_released = say_goodbye
 
# Hold detection
shutdown_btn = Button(17, hold_time=2)
shutdown_btn.when_held = shutdown     # fires after button held for 2 seconds
 
pause()

Button controlled LED

from gpiozero import LED, Button
from signal import pause
 
led = LED(17)
button = Button(2)
 
# Verbose
button.when_pressed = led.on
button.when_released = led.off
 
# Shorthand (source/sink pattern)
led.source = button   # LED mirrors button state directly
 
pause()

LEDBoard

from gpiozero import LEDBoard
from time import sleep
from signal import pause
 
leds = LEDBoard(5, 6, 13, 19, 26)
leds.on()
leds.off()
leds.value = (1, 0, 1, 0, 1)  # tuple of per-LED states
leds.blink()
 
# With PWM
leds = LEDBoard(5, 6, 13, 19, 26, pwm=True)
leds.value = (0.2, 0.4, 0.6, 0.8, 1.0)
 
pause()

Servo

from gpiozero import Servo, AngularServo
from time import sleep
 
servo = Servo(17)
servo.min()    # minimum position (-1)
servo.mid()    # middle position (0)
servo.max()    # maximum position (+1)
 
# Specify angle explicitly
servo = AngularServo(17, min_angle=-90, max_angle=90)
servo.angle = -45

Motor

from gpiozero import Motor
from time import sleep
 
motor = Motor(forward=4, backward=14)
motor.forward()
sleep(5)
motor.backward()
sleep(5)
motor.stop()

ADC via SPI (MCP3008)

Note: MCP3008 uses SPI. This is different from the Grove Base Hat which uses I2C.

from gpiozero import MCP3008
 
pot = MCP3008(channel=0)
 
while True:
    print(pot.value)   # float 0.0–1.0

co-test

Explorer

gpiozero-recipes