GPIO Zero v1.4 is out now! It comes with a set of new features, including a handy
pinout command line tool. To start using this newest version of the API, update your Raspbian OS now:
sudo apt update && sudo apt upgrade
Some of the things we’ve added will make it easier for you try your hand on different programming styles. In doing so you’ll build your coding skills, and will improve as a programmer. As a consequence, you’ll learn to write more complex code, which will enable you to take on advanced electronics builds. And on top of that, you can use the skills you’ll acquire in other computing projects.
Developing GPIO Zero
Nearly two years ago, I started the GPIO Zero project as a simple wrapper around the low-level RPi.GPIO library. I wanted to create a simpler way to control GPIO-connected devices in Python, based on three years’ experience of training teachers, running workshops, and building projects. The idea grew over time, and the more we built for our Python library, the more sophisticated and powerful it became.
One of the great things about Python is that it’s a multi-paradigm programming language. You can write code in a number of different styles, according to your needs. You don’t have to write classes, but you can if you need them. There are functional programming tools available, but beginners get by without them. Importantly, the more advanced features of the language are not a barrier to entry.
Become a more advanced programmer
As a beginner to programming, you usually start by writing procedural programs, in which the flow moves from top to bottom. Then you’ll probably add loops and create your own functions. Your next step might be to start using libraries which introduce new patterns that operate in a different manner to what you’ve written before, for example threaded callbacks (event-driven programming). You might move on to object-oriented programming, extending the functionality of classes provided by other libraries, and starting to write your own classes. Occasionally, you may make use of tools created with functional programming techniques.
It’s much the same with GPIO Zero: you can start using it very easily, and we’ve made it simple to progress along the learning curve towards more advanced programming techniques. For example, if you want to make a push button control an LED, the easiest way to do this is via procedural programming using a
from gpiozero import LED, Button led = LED(17) button = Button(2) while True: if button.is_pressed: led.on() else: led.off()
But another way to achieve the same thing is to use events:
from gpiozero import LED, Button from signal import pause led = LED(17) button = Button(2) button.when_pressed = led.on button.when_released = led.off pause()
You could even use a declarative approach, and set the LED’s behaviour in a single line:
from gpiozero import LED, Button from signal import pause led = LED(17) button = Button(2) led.source = button.values pause()
You will find that using the procedural approach is a great start, but at some point you’ll hit a limit, and will have to try a different approach. The example above can be approach in several programming styles. However, if you’d like to control a wider range of devices or a more complex system, you need to carefully consider which style works best for what you want to achieve. Being able to choose the right programming style for a task is a skill in itself.
So how does the
led.source = button.values thing actually work?
Every GPIO Zero device has a
.value property. For example, you can read a button’s state (
False), and read or set an LED’s state (so
led.value = True is the same as
led.on()). Since LEDs and buttons operate with the same value set (
False), you could say
led.value = button.value. However, this only sets the LED to match the button once. If you wanted it to always match the button’s state, you’d have to use a
while loop. To make things easier, we came up with a way of telling devices they’re connected: we added a
.values property to all devices, and a
.source to output devices. Now, a loop is no longer necessary, because this will do the job:
led.source = button.values
This is a simple approach to connecting devices using a declarative style of programming. In one single line, we declare that the LED should get its values from the button, i.e. when the button is pressed, the LED should be on. You can even mix the procedural with the declarative style: at one stage of the program, the LED could be set to match the button, while in the next stage it could just be blinking, and finally it might return back to its original state.
These additions are useful for connecting other devices as well. For example, a PWMLED (LED with variable brightness) has a value between 0 and 1, and so does a potentiometer connected via an ADC (analogue-digital converter) such as the MCP3008. The new GPIO Zero update allows you to say
led.source = pot.values, and then twist the potentiometer to control the brightness of the LED.
But what if you want to do something more complex, like connect two devices with different value sets or combine multiple inputs?
We provide a set of device source tools, which allow you to process values as they flow from one device to another. They also let you send in artificial values such as random data, and you can even write your own functions to generate values to pass to a device’s source. For example, to control a motor’s speed with a potentiometer, you could use this code:
from gpiozero import Motor, MCP3008 from signal import pause motor = Motor(20, 21) pot = MCP3008() motor.source = pot.values pause()
This works, but it will only drive the motor forwards. If you wanted the potentiometer to drive it forwards and backwards, you’d use the
scaled tool to scale its values to a range of -1 to 1:
from gpiozero import Motor, MCP3008 from gpiozero.tools import scaled from signal import pause motor = Motor(20, 21) pot = MCP3008() motor.source = scaled(pot.values, -1, 1) pause()
And to separately control a robot’s left and right motor speeds with two potentiometers, you could do this:
from gpiozero import Robot, MCP3008 from signal import pause robot = Robot(left=(2, 3), right=(4, 5)) left = MCP3008(0) right = MCP3008(1) robot.source = zip(left.values, right.values) pause()
GPIO Zero and Blue Dot
Martin O’Hanlon created a Python library called Blue Dot which allows you to use your Android device to remotely control things on your Raspberry Pi. The API is very similar to GPIO Zero, and it even incorporates the value/values properties, which means you can hook it up to GPIO devices easily:
from bluedot import BlueDot from gpiozero import LED from signal import pause bd = BlueDot() led = LED(17) led.source = bd.values pause()
We even included a couple of Blue Dot examples in our recipes.
Remote GPIO control
GPIO Zero supports multiple low-level GPIO libraries. We use RPi.GPIO by default, but you can choose to use RPIO or pigpio instead. The pigpio library supports remote connections, so you can run GPIO Zero on one Raspberry Pi to control the GPIO pins of another, or run code on a PC (running Windows, Mac, or Linux) to remotely control the pins of a Pi on the same network. You can even control two or more Pis at once!
If you’re using Raspbian on a Raspberry Pi (or a PC running our x86 Raspbian OS), you have everything you need to remotely control GPIO. If you’re on a PC running Windows, Mac, or Linux, you just need to install gpiozero and pigpio using pip. See our guide on configuring remote GPIO.
There are a number of different ways to use remote pins:
- Set the default pin factory and remote IP address with environment variables:
$ GPIOZERO_PIN_FACTORY=pigpio PIGPIO_ADDR=192.168.1.2 python3 blink.py
- Set the default pin factory in your script:
import gpiozero from gpiozero import LED from gpiozero.pins.pigpio import PiGPIOFactory gpiozero.Device.pin_factory = PiGPIOFactory(host='192.168.1.2') led = LED(17)
pin_factorykeyword argument allows you to use multiple Pis in the same script:
from gpiozero import LED from gpiozero.pins.pigpio import PiGPIOFactory factory2 = PiGPIOFactory(host='192.168.1.2') factory3 = PiGPIOFactory(host='192.168.1.3') local_hat = TrafficHat() remote_hat2 = TrafficHat(pin_factory=factory2) remote_hat3 = TrafficHat(pin_factory=factory3)
GPIO Zero on your PC
GPIO Zero doesn’t have any dependencies, so you can install it on your PC using pip. In addition to the API’s remote GPIO control, you can use its ‘mock’ pin factory on your PC. We originally created the mock pin feature for the GPIO Zero test suite, but we found that it’s really useful to be able to test GPIO Zero code works without running it on real hardware:
$ GPIOZERO_PIN_FACTORY=mock python3 >>> from gpiozero import LED >>> led = LED(22) >>> led.blink() >>> led.value True >>> led.value False
You can even tell pins to change state (e.g. to simulate a button being pressed) by accessing an object’s pin property:
>>> from gpiozero import LED >>> led = LED(22) >>> button = Button(23) >>> led.source = button.values >>> led.value False >>> button.pin.drive_low() >>> led.value True
You can also use the pinout command line tool if you set your pin factory to ‘mock’. It gives you a Pi 3 diagram by default, but you can supply a revision code to see information about other Pi models. For example, to use the pinout tool for the original 256MB Model B, just type
pinout -r 2.
GPIO Zero documentation and resources
On the API’s website, we provide beginner recipes and advanced recipes, and we have added remote GPIO configuration including PC/Mac/Linux and Pi Zero OTG, and a section of GPIO recipes. There are also new sections on source/values, command-line tools, FAQs, Pi information and library development.
You’ll find plenty of cool projects using GPIO Zero in our learning resources. For example, you could check out the one that introduces physical computing with Python and get stuck in! We even provide a GPIO Zero cheat sheet you can download and print.
There are great GPIO Zero tutorials and projects in The MagPi magazine every month. Moreover, they also publish Simple Electronics with GPIO Zero, a book which collects a series of tutorials useful for building your knowledge of physical computing. And the best thing is, you can download it, and all magazine issues, for free!
The world of physical computing is at your fingertips! Are you feeling inspired?
If you’ve never tried your hand on physical computing, our Build a robot buggy learning resource is the perfect place to start! It’s your step-by-step guide for building a simple robot controlled with the help of GPIO Zero.
If you have a gee-whizz idea for an electronics project, do share it with us below. And if you’re currently working on a cool build and would like to show us how it’s going, pop a link to it in the comments.