Getting Started with Scroll pHAT HD
This tutorial will show you how to install the Scroll pHAT HD Python library, and then walk through its functionality - how to light pixels, display text, and so on - finishing with an example of how to make a stripey animation with trigonometric functions.
If you haven't already soldered the header to your Scroll pHAT HD, 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 Scroll pHAT HD set up. We'd suggest that you use this method to install the Scroll pHAT HD Python library.
Open a new terminal, and type the following, making sure to type 'y' or 'n' when prompted:
curl https://get.pimoroni.com/scrollphathd | 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.
Lighting individual pixels
We'll start by looking at how to light up individual pixels. The pixels on
Scroll pHAT HD are addressed by x/y coordinates, so to light the second pixel in
the first row, for example, this pixel would be
0, 1. Remember that in Python
we number things from 0, hence the first pixel is
0, the second is
1, and so
Before we start anything, we have to type the following to import the
import scrollphathd as sphd
import x as y just means that we don't have to type the rather long-winded
scrollphathd each time we want to call a function, just
As well as the x/y coordinate of the pixel, we also have to pass in a brightness
value. Brightness is a floating point (decimal) number between
We'll use the
set_pixel function to light the second pixel in the first row at
50% brightness. Type the following:
sphd.set_pixel(0, 1, 0.5) sphd.show()
You'll notice that as well as using the
set_pixel() function to tell the library
which pixel to light, we have to call
show() to update Scroll pHAT HD and
actually light the pixel.
To clear any set pixels, there's a
clear() function. Just like the
set_pixel() function, you have to also call
show() to update the display.
Type the following to clear the pixel you just set:
Lighting whole rows or columns
Getting a whole row or column to light is basically the same as lighting an
individual pixel, except that we have to repeat it once for every pixel in that
row or column. We can do that using a
for loop. We'll light all of the pixels
in the second column from the left now (remember that it's numbered
25% brightness this time.
Type the following:
for y in range(7): sphd.set_pixel(1, y, 0.25) sphd.show()
We can take this a little further and use another
for loop to loop through
all of the columns and light each one in turn. We'll introduce a new module
here - the
time module - and use it to introduce a small delay between
lighting each column.
Before we begin, we'll clear that column that we just set:
We'll use one
for loop -
for x in range(17) - to loop through all of the
columns, and a second
for loop -
for x in range(7) - as we did before to
loop through all of the pixels in each column.
import time for x in range(17): sphd.clear() for y in range(7): sphd.set_pixel(x, y, 0.25) sphd.show() time.sleep(1/17.0)
Your Scroll pHAT HD should just have scanned across from left to right and lit all of the columns in turn.
Notice that we called
clear() before each iteration of the
for x in range(17) loop, so that any columns lit already would be cleared each
time. If we hadn't done this, then the columns would all have filled up one at a
Also notice that we called
show() outside of the
for y in range(7) loop, so
that all of the pixels in each column were lit at the same time.
To keep that going indefinitely you could wrap the whole thing in a
loop, as follows:
while True: for x in range(17): sphd.clear() for y in range(7): sphd.set_pixel(x, y, 0.25) sphd.show() time.sleep(1/17.0)
c to break out of that loop.
As well as lighting individual pixels or groups of pixels, the Scroll pHAT HD
library provides a handy way to scroll text across its display. You simply use
write_string() function to write a string to the buffer and then
scroll(1) functions to show the text and then tick
it along by one position.
We'll write and scroll the string "Shiver me timbers!":
sphd.write_string('Shiver me timbers!') while True: sphd.show() sphd.scroll(1) time.sleep(0.05)
If you have a shorter string, for instance a temperature string like
you don't want to scroll and just display it statically, then you can use the
show() functions without calling
Note that the default orientation for Scroll pHAT HD is upside-down if
you're using it in a Scroll Bot. To flip it, simply add
scrollphathd.rotate(180) towards the top of your code, just below the
Using trigonometric functions to create a simple animation
We'll take it a little further now and use a couple of simple trigonometric functions to create a dazzling stripey effect. Here's the code, and we'll break down how it works bit-by-bit after:
import time import math while True: t = time.time() * 10 for x in range(17): for y in range(7): b = math.sin(x + y + t) + math.cos(x + y + t) b = (b + 2) / 4 sphd.set_pixel(x, y, b) sphd.show()
Let's look at what all that does.
We use the
time.time() to get a time value to which we'll apply our trig.
functions. We could simply iterate a number and use that, but the drawback of
doing it that way is that we don't know exactly how long each iteration of the
loop will take and our animation might not be as smooth as it could be. The
time is multiplied by 10, which has the effect of speeding the animation up a
Next, we use two
for loops, as we did before, to loop through all of the rows
and columns of pixels, and set each one, passing it a brightness value
between 0.0 and 1.0. This is the important bit!
b = math.sin(x + y + t) + math.cos(x + y + t) applies a sine function to the
x pixel number +
y pixel number + the time value
t, and a cosine function
to the same numbers, and then adds the results together. Each of those functions
will return a result between -1 and +1, meaning that the sum of them will be a
number between -2 and +2. To get back to a number between 0.0 and 1.0 for the
brightness, we add 2 and divide by 4.
Outside of both of the
for loops, we call
show() to update all of the pixels
Taking it further
Try experimenting with different trig. functions to create different patterns. You should be able to create horizontal or vertical stripes, or even a funky plasma-style pattern.
Why not throw in a bit of IoT and use your Scroll pHAT HD to display the news headlines, the current weather, or track a particlar hashtag on Twitter?
Search above to find more great tutorials and guides.