gpiozero
The following recipes demonstrate some of the capabilities of the gpiozero library. Please note that all recipes are written assuming Python 3. Recipes may work under Python 2, but no guarantees!
This library uses Broadcom (BCM) pin numbering for the GPIO pins, as opposed to physical (BOARD) numbering. Unlike in the RPi.GPIO library, this is not configurable.
Any pin marked "GPIO" in the diagram below can be used as a pin number. For example, if an LED was attached to "GPIO17" you would specify the pin number as 17 rather than 11:
Turn an LED
on and off repeatedly:
examples/led_1.py
Alternatively:
examples/led_2.py
Note
Reaching the end of a Python script will terminate the process and GPIOs may be reset. Keep your script alive with signal.pause
. See keep-your-script-running
for more information.
Any regular LED can have its brightness value set using PWM (pulse-width-modulation). In GPIO Zero, this can be achieved using PWMLED
using values between 0 and 1:
examples/led_variable_brightness.py
Similarly to blinking on and off continuously, a PWMLED can pulse (fade in and out continuously):
examples/led_pulse.py
Check if a Button
is pressed:
examples/button_1.py
Wait for a button to be pressed before continuing:
examples/button_2.py
Run a function every time the button is pressed:
examples/button_3.py
Note
Note that the line button.when_pressed = say_hello
does not run the function say_hello
, rather it creates a reference to the function to be called when the button is pressed. Accidental use of button.when_pressed = say_hello()
would set the when_pressed
action to None
(the return value of this function) which would mean nothing happens when the button is pressed.
Similarly, functions can be attached to button releases:
examples/button_4.py
Turn on an LED
when a Button
is pressed:
examples/button_led_1.py
Alternatively:
examples/button_led_2.py
Using the button press to trigger ~picamera.PiCamera
to take a picture using button.when_pressed = camera.capture
would not work because the ~picamera.PiCamera.capture
method requires an output
parameter. However, this can be achieved using a custom function which requires no parameters:
examples/button_camera_1.py
Another example could use one button to start and stop the camera preview, and another to capture:
examples/button_camera_2.py
The Button
class also provides the ability to run a function when the button has been held for a given length of time. This example will shut down the Raspberry Pi when the button is held for 2 seconds:
examples/button_shutdown.py
A collection of LEDs can be accessed using LEDBoard
:
examples/led_board_1.py
Using LEDBoard
with pwm=True
allows each LED's brightness to be controlled:
examples/led_board_2.py
A collection of LEDs can be treated like a bar graph using LEDBarGraph
:
examples/led_bargraph_2.py
Note values are essentially rounded to account for the fact LEDs can only be on or off when pwm=False
(the default).
However, using LEDBarGraph
with pwm=True
allows more precise values using LED brightness:
examples/led_bargraph_2.py
A full traffic lights system.
Using a TrafficLights
kit like Pi-Stop:
examples/traffic_lights_1.py
Alternatively:
examples/traffic_lights_2.py
Using LED
components:
examples/traffic_lights_3.py
Use LEDs to indicate the status of a Travis build. A green light means the tests are passing, a red light means the build is broken:
examples/led_travis.py
Note this recipe requires travispy. Install with sudo pip3 install travispy
.
Capture a picture with the camera module every time a button is pressed:
examples/button_stop_motion.py
See Push Button Stop Motion for a full resource.
When you see the light come on, the first person to press their button wins!
examples/reaction_game.py
See Quick Reaction Game for a full resource.
Each button plays a different sound!
examples/music_box.py
See GPIO Music Box for a full resource.
While the button is pressed down, the buzzer and all the lights come on.
FishDish
:
examples/all_on_1.py
Ryanteck TrafficHat
:
examples/all_on_2.py
Using LED
, Buzzer
, and Button
components:
examples/all_on_3.py
Making colours with an RGBLED
:
examples/rgbled.py
Light an LED
when a MotionSensor
detects motion:
examples/motion_sensor.py
Have a LightSensor
detect light and dark:
examples/light_sensor_1.py
Run a function when the light changes:
examples/light_sensor_2.py
Or make a PWMLED
change brightness according to the detected light level:
examples/light_sensor_3.py
Have a DistanceSensor
detect the distance to the nearest object:
examples/distance_sensor_1.py
Run a function when something gets near the sensor:
examples/distance_sensor_2.py
Spin a Motor
around forwards and backwards:
examples/motor.py
Make a Robot
drive around in (roughly) a square:
examples/robot_1.py
Make a robot with a distance sensor that runs away when things get within 20cm of it:
examples/robot_2.py
Use four GPIO buttons as forward/back/left/right controls for a robot:
examples/robot_buttons.py
Use up/down/left/right keys to control a robot:
examples/robot_keyboard_1.py
Note
This recipe uses the standard curses
module. This module requires that Python is running in a terminal in order to work correctly, hence this recipe will not work in environments like IDLE.
If you prefer a version that works under IDLE, the following recipe should suffice:
examples/robot_keyboard_2.py
Note
This recipe uses the third-party evdev
module. Install this library with sudo pip3 install evdev
first. Be aware that evdev
will only work with local input devices; this recipe will not work over SSH.
Make a robot drive forward when it detects motion:
examples/robot_motion_1.py
Alternatively:
examples/robot_motion_2.py
Continually print the value of a potentiometer (values between 0 and 1) connected to a MCP3008
analog to digital converter:
examples/pot_1.py
Present the value of a potentiometer on an LED bar graph using PWM to represent states that won't "fill" an LED:
examples/pot_2.py
Wire a TMP36 temperature sensor to the first channel of an MCP3008
analog to digital converter:
examples/thermometer.py
Wire up three potentiometers (for red, green and blue) and use each of their values to make up the colour of the LED:
examples/rgbled_pot_1.py
Alternatively, the following example is identical, but uses the ~SourceMixin.source
property rather than a while
loop:
examples/rgbled_pot_2.py
Please note the example above requires Python 3. In Python 2, zip
doesn't support lazy evaluation so the script will simply hang.
On certain models of Pi (specifically the model A+, B+, and 2B) it's possible to control the power and activity LEDs. This can be useful for testing GPIO functionality without the need to wire up your own LEDs (also useful because the power and activity LEDs are "known good").
Firstly you need to disable the usual triggers for the built-in LEDs. This can be done from the terminal with the following commands:
$ echo none | sudo tee /sys/class/leds/led0/trigger
$ echo gpio | sudo tee /sys/class/leds/led1/trigger
Now you can control the LEDs with gpiozero like so:
examples/led_builtin.py
To revert the LEDs to their usual purpose you can either reboot your Pi or run the following commands:
$ echo mmc0 | sudo tee /sys/class/leds/led0/trigger
$ echo input | sudo tee /sys/class/leds/led1/trigger
Note
On the Pi Zero you can control the activity LED with this recipe, but there's no separate power LED to control (it's also worth noting the activity LED is active low, so set active_high=False
when constructing your LED component).
On the original Pi 1 (model A or B), the activity LED can be controlled with GPIO16 (after disabling its trigger as above) but the power LED is hard-wired on.
On the Pi 3B the LEDs are controlled by a GPIO expander which is not accessible from gpiozero (yet).