Getting Started with Touch pHAT
This tutorial will show you how to install the Touch pHAT Python library, and then walk through its functionality. You'll learn how to control the LEDs, how to link functions to button presses, and then how to turn your Touch pHAT into a timer, with the buttons starting, stopping, and resetting the timer.
If you haven't already soldered the header to your Touch pHAT, then you can follow our guide to soldering pHATs here.
Installing the software
We always recommend using the most up-to-date version of Raspbian, as this is what we test our boards and software against, and it often helps to start with a completely fresh install of Raspbian, although this isn't necessary.
As with most of our boards, we've created a really quick and easy one-line-installer to get your Touch pHAT set up. We'd suggest that you use this method to install the Touch pHAT software.
Open a new terminal, and type the following, making sure to type
curl https://get.pimoroni.com/touchphat | bash
Once that's done, it probably a good idea to reboot your Pi to let the changes propagate, if the installer doesn't prompt you to reboot.
Using the software
Open a new terminal and type
python to open a new Python prompt.
Controlling the LEDs
The LEDs on Touch pHAT are driven by the same chip that drives the capacitive touch buttons, but they can be controlled individually. There are two different methods to control the LEDs - they can be controlled individually or as a group.
Type the following to turn all of the the LEDs on:
import touchphat touchphat.all_on()
You'll notice that we have to
import touchphat to be able to use the functions
in the library. The
touchphat.all_on() function does exactly as it says and,
as you might guess, there's also a
touchphat.all_off() function that... turns
all of them off again. Try that now:
touchphat.led_off() functions allow you to
control the LEDs individually. First, we'll turn the first LED on. Type the
Note that the LEDs are numbered from 1, and from left to right on the pHAT. We pass the number of the pad we want to turn on or off to the function. As well as referring to them by number, we can use their names on the pads. Try the following to turn that LED (the first one) back off again:
The pads' names are
Let's try using a
while True: loop now to loop through the LEDs one at a time
and turn them on for a quarter of a second and then off again:
import time while True: for led in range(1,7): touchphat.led_on(led) time.sleep(0.25) touchphat.led_off(led)
You'll see that we imported the
time library, which lets us introduce that
quarter second delay -
time.sleep(0.25). Then, our loop goes through each LED
in turn with
for led in range(1,7):, and turns the LED on, pauses for a
quarter second, then turns it off again. The
while True: means that this will
run constantly until we type
c to break out of it.
Linking functions to button presses
Button presses on Touch pHAT are linked to functions using decorators.
Decorators in Python are a way of linking a bit of code to a function. They
are always placed immediately before the
def myfunction(): line, and begin
@ symbol, for instance:
@mydecorator def myfunction(): # Do something
Decorators are used to add functionality to functions. In this case, they link
a press of one or more of the buttons on Touch pHAT to a particular function.
Let's look at how it works in practice. We'll use the
decorator and link it to a function called
handle_touch() that will print the
name of the button pressed. Type the following:
@touchphat.on_touch(["Back"`, `"A"`, `"B"`, `"C"`, `"D"`, `"Enter"]) def handle_touch(event): print("Button %s pressed!") % event.name
You'll see that we've passed in a list of all of the button names to the
decorator. This could also be a single button, like
or a subset of the buttons, like
@touchphat.on_touch(["Back", "Enter"]). In
fact, to use all of the buttons we could just have said
and it would implicitly have linked all of the buttons.
event variable that we pass in to our
handle_touch() function is an
object that represents the event that happens, in this case a button press.
event.name will give us the name of the button that has been pressed.
Try pressing the buttons and see what happens. This is the basis of using the buttons on Touch pHAT to trigger events, and they could be used to trigger anything that you could achieve with a Python function, from starting or stopping a timer, to triggering a sound to be played, to switching a remote plug socket or light on.
Creating a timer with Touch pHAT
Now, we're going to use Touch pHAT to create a timer, with the
starting and stopping the timer, and the
"Back" button resetting it.
This is a pretty complex example, but we'll go through what all of the code does, so that you know exactly how it works!
The best way to run this example is to open a new text document and then paste
the code below in. Save it as something like
timer.py and in your home
/home/pi. To run the example, open a terminal and type
python /home/pi/timer.py. To stop it, press
import sys import time import touchphat stopped = True runtime = 0 @touchphat.on_touch("Enter") def start_stop(): global start global stopped global runtime if stopped: start = time.time() stopped = False else: stopped = True runtime += (time.time() - start) @touchphat.on_touch("Back") def reset(): global runtime runtime = 0 blanks = " " * 25 + "\r" try: while True: if stopped and runtime > 0: sys.stdout.write(blanks) sys.stdout.write("Timer stopped: %i seconds\r" % runtime) sys.stdout.flush() elif stopped: sys.stdout.write(blanks) sys.stdout.write("Touch enter to start!\r") sys.stdout.flush() else: sys.stdout.write(blanks) sys.stdout.write("Timer running: %i seconds\r" % (runtime + (time.time() - start))) sys.stdout.flush() time.sleep(0.1) except KeyboardInterrupt(): sys.exit()
Python libraries that you need to import always get imported at the very top of
the program, since a Python program runs in order from top to bottom. We're
touchphat library, the
sys library (we'll use that to display the
output of the program), and the
time library to do the actual timing.
Next, we create a couple of variables that we'll be using.
The first is one called
stopped and it's a Boolean. Booleans can either be
False. In this case, we set our variable
stopped to be
that our timer is stopped initially. We'll be using this variable to keep track
of when our timer is running or stopped.
The other is called
runtime. It'll keep track of the number of seconds that
our program has been running, so that we can display it. It's an integer (a
whole number) and we'll create it with an initial value of
The easiest way to link the press of a button to a function, as we've seen, is
to use the decorator function
@touchphat.on_touch(). Here, we'll be using
"Enter" button to start and stop the timer, and the
"Back" button to reset
Our program will use two functions, one called
start_stop() that starts and
stops the timer, and one called
reset() that resets it. The
is really simple and just sets the
runtime variable back to
0. You'll also
see that it has
global runtime in it. This means that any changes we make to
this variable will have effect throughout our program; normally variables that
are changed within a function have to be passed back out of (or indeed into) the
function to be used elsewhere.
The larger function
start_stop() keeps track of whether the timer is running,
and also updates the
runtime variable. We have to use
global again on the
runtime variables, because they'll be used in our
while loop at the end of the program.
If the timer is currently stopped (the
stopped variable is
True) and the
start_stop function is triggered by a press of the
"Enter" button, then we
want to start the timer. So, we use
if stopped: (this is the same as
if stopped is True:) to then record the time that the timer has started,
start = time.time(). The
time library has a bunch of functions, and the
time.time() function conveniently gives us the current time in seconds. We
stopped = False, since our timer is now
else: statement will apply if the timer is running and the function is
triggered again by another press of the
"Enter" button. It sets
stopped = True, as the timer has now been stopped. We also
get the time that the timer ran for,
(time.time() - start), and add it to our
runtime variable with the handy
+= notation (
a += b is the same as
a = a + b).
The main part of our program, that will run constantly, is a
while True: loop.
We put this inside a
try: block, so that we can add an
except KeyboardInterrupt: that will exit the program cleanly when we press
We have three different cases that could apply: the timer could be stopped with
it not yet having been run, it could be stopped when it has been run one or
more times already, or it could be running. To check for these cases, we'll use
if stopped and runtime > 0: applies when the timer is stopped and it has
previously been running (
runtime > 0). To write the current status of the
timer, we're using the
sys.stdout.write() function rather than the usual
print() function. This is because we can overwrite each time on the same line
rather than printing out hundreds and hundreds of separate lines as the timer is
running. To clear the line each time, we write some blank space with
sys.stdout.write(blanks) before we write the status of our timer with
sys.stdout.write("Timer stopped: %i seconds\r" % runtime). That will print
out the number of seconds that our timer has previously been running. Last, we
flush out the standard output (standard output is what displays messages in the
elif stopped: will apply when the timer hasn't previously been run or has
been reset to
0, so that
runtime is equal to
We simply display a little message saying that the user should press
start the timer:
sys.stdout.write("Touch enter to start!\r"). Again, we write
some blanks before and flush the standard output after.
The last case, the
else:, will apply when the timer is running. If it is, we
(runtime + (time.time() - start)) to get the total time that the timer
has been running for. We display it the same way with
sys.stdout.write("Timer running: %i seconds\r" % (runtime + (time.time() - start))).
At the very end of our
while loop, we introduce a little delay so that it
doesn't run too frequently, with
time.sleep(0.1). After all, our timer is
only updating every second so, in fact, we could probably increase this value
Taking it further
Touch pHAT is great for adding a physical interface to all sorts of projects, far too many to list here. It's perfect for using as a lighting controller, in conjunction with some cheap Wi-Fi-enabled smart lights. You could use it as a controller for a Pi-powered turtle robot, where the buttons are used to program the robot's route. Or why not use it as controls for a Pi-powered camera booth that creates animated GIFs and then tweets them?
Search above to find more great tutorials and guides.