gpiozero
The following recipes demonstrate some of the capabilities of the GPIO Zero library. Please note that all recipes are written assuming Python 3. Recipes may work under Python 2, but no guarantees!
gpiozero
In Python, libraries and functions used in a script must be imported by name at the top of the file, with the exception of the functions built into Python by default.
For example, to use the Button interface from GPIO Zero, it should be explicitly imported:
from gpiozero import ButtonNow ~gpiozero.Button is available directly in your script:
button = Button(2)Alternatively, the whole GPIO Zero library can be imported:
import gpiozeroIn this case, all references to items within GPIO Zero must be prefixed:
button = gpiozero.Button(2)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. However, translation from other schemes can be used by providing prefixes to pin numbers (see below).
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:
If you wish to use physical (BOARD) numbering you can specify the pin number as "BOARD11". If you are familiar with the wiringPi pin numbers (another physical layout) you could use "WPI0" instead. Finally, you can specify pins as "header:number", e.g. "J8:11" meaning physical pin 11 on header J8 (the GPIO header on modern Pis). Hence, the following lines are all equivalent:
>>> led = LED(17)
>>> led = LED("GPIO17")
>>> led = LED("BCM17")
>>> led = LED("BOARD11")
>>> led = LED("WPI0")
>>> led = LED("J8:11")Note that these alternate schemes are merely translations. If you request the state of a device on the command line, the associated pin number will always be reported in the Broadcom (BCM) scheme:
>>> led = LED("BOARD11")
>>> led
<gpiozero.LED object on pin GPIO17, active_high=True, is_active=False>Throughout this manual we will use the default integer pin numbers, in the Broadcom (BCM) layout shown above.
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
See more LEDBoard examples in the advanced LEDBoard recipes
<ledboard-advanced>.
A collection of LEDs can be treated like a bar graph using LEDBarGraph:
examples/led_bargraph_1.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 common 7-segment display can be used to represent a variety of characters using LEDCharDisplay (which actually supports an arbitrary number of segments):
examples/led_char_display.py
Alternatively:
examples/led_char_source.py
See a multi-character example in the advanced recipes
<multichar-display> chapter.
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
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
Note
In the diagram above, the wires leading from the sensor to the breadboard can be omitted; simply plug the sensor directly into the breadboard facing the edge (unfortunately this is difficult to illustrate in the diagram without the sensor's diagram obscuring most of the breadboard!)
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
Note
In this recipe, I've used a common anode RGB LED. Often, Pi projects use common cathode RGB LEDs because they're slightly easier to think about electrically. However, in this case all three components can be found in an illuminated rotary encoder which incorporates a common anode RGB LED, and a momentary push button. This is also the reason for the button being wired active-low, contrary to most other examples in this documentation.
For the sake of clarity, the diagram shows the three separate components, but this same circuit will work equally well with this commonly available illuminated rotary encoder instead.
Have a rotary encoder, an RGB LED, and button act as a color picker.
examples/color_picker.py
Control a servo between its minimum, mid-point and maximum positions in sequence:
examples/servo_1.py
Use a button to control the servo between its minimum and maximum positions:
examples/servo_2.py
Automate the servo to continuously slowly sweep:
examples/servo_sweep.py
Use AngularServo so you can specify an angle:
examples/angular_servo.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_1.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
If you have a pet (e.g. a tortoise) which requires a heat lamp to be switched on for a certain amount of time each day, you can use an Energenie Pi-mote to remotely control the lamp, and the TimeOfDay class to control the timing:
examples/timed_heat_lamp.py
You can use a pair of green and red LEDs to indicate whether or not your internet connection is working. Simply use the PingServer class to identify whether a ping to google.com is successful. If successful, the green LED is lit, and if not, the red LED is lit:
examples/internet_status_indicator.py
You can read the Raspberry Pi's own CPU temperature using the built-in CPUTemperature class, and display this on a "bar graph" of LEDs:
examples/cpu_temperature_bar_graph.py
Continue to:
recipes_advancedrecipes_remote_gpio