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.

These instructions should also help you get to grips with the updated Scroll HAT Mini - for examples of how to use the buttons on Scroll HAT Mini check out the Python library.

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 on.

Before we start anything, we have to type the following to import the scrollphathd library:

import scrollphathd as sphd

The 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 sphd.

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 0.0 and 1.0. 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:

sphd.clear()
sphd.show()

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 1) at 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:

sphd.clear()
sphd.show()

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 time.

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 while True 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)

Press control and c to break out of that loop.

Displaying text

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 the write_string() function to write a string to the buffer and then repeatedly call show() and 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 21C, and you don't want to scroll and just display it statically, then you can use the write_string() and show() functions without calling scroll().

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 import lines.

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 fair bit.

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 b 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 at once.

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?

That's all folks!

Search above to find more great tutorials and guides.