Getting Started with Unicorn pHAT
This tutorial will show you how to install the Unicorn HAT Python library (Unicorn pHAT uses the same Python library as Unicorn HAT), and then walk through its functionality - how to light pixels, control colour and brightness, and then finish with an example of how to MAKE IT RAINBOW!
If you haven't already soldered the header to your Unicorn 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 Unicorn pHAT set up. We'd suggest that you use this method to install the Unicorn HAT Python library.
Open a new terminal, and type the following, making sure to type 'y' or 'n' when prompted:
curl https://get.pimoroni.com/unicornhat | 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
sudo python to open a new Python prompt.
Lighting individual pixels
We'll begin by doing the simplest thing you can do, lighting a single pixel red. This will show you how the pixels are organised and the commands needed to light them in a particular colour.
Before we start anything, we have to type the following to import the
import unicornhat as uh
import x as y just means that we don't have to type the rather long-winded
unicornhat each time we want to call a function, just
Because the Unicorn HAT library is used by both the HAT and pHAT (which is half the size of the HAT), we need to specify that it's the the pHAT that we're using. To do that, just type:
We'll also set the brightness to 50%, since Unicorn pHAT will scorch your retinas at 100% brightness (you were warned!)
To light a pixel on Unicorn pHAT in a particular colour, we have to do two
things: first, we have to use the
set_pixel() function to specify which pixel
we want to light and in what colour and, second, we have to use the
function to update the Unicorn pHAT and actually display the pixel that we set.
Pixels on Unicorn pHAT are organised by their x/y coordinates from the top left
hand corner, so the top left pixel is
0, 0 and the bottom right pixel is
7, 3. Remember that, in Python, things are number from 0 rather than from 1.
The colours of pixels are specified by an RGB colour value. Each colour can be
represented by mixing a particular amount of Red, Green, and Blue, from 0 to 255,
meaning that you can get over 16 million different colours!! As an example, pure
255, 0, 0 and white is
255, 255, 255.
Let's light the top left pixel red. Type the following:
uh.set_pixel(0, 0, 255, 0, 0) uh.show()
To clear any pixels that you've set, you can use the
Lighting all of the pixels using a for loop
To light all of the pixels on Unicorn pHAT, it's just a matter of repeating the
process we just did once for each of the 32 pixels. We can make this really
quick and easy by using two
for loops: one to loop through each column, and
another to loop through each pixel in each of those columns.
The rough process is:
for x in range(8): and then
for y in range(4):,
because we have 8 pixels along the x axis and 4 along the y axis.
This time, we'll light the pixels cyan, which is a mix of pure blue and pure
green and so can be represented by the RGB colour
0, 255, 255.
Type the following:
for x in range(8): for y in range(4): uh.set_pixel(x, y, 0, 255, 255) uh.show()
All of the pixels on your Unicorn pHAT should just have lit up cyan!
Making it blink!
Now we're going to use a
while loop to make your Unicorn pHAT blink pink. All
we have to do is continuously light all of the pixels pink, using the technique
we just learned, and clear them again, with a short delay, maybe a quarter of a
second in between.
Type the following:
import time while True: for x in range(8): for y in range(4): uh.set_pixel(x, y, 255, 0, 255) uh.show() time.sleep(0.25) uh.clear() uh.show() time.sleep(0.25)
This is just the same as in the example where we made all of the pixels light in
cyan, except we changed the RGB colour to
255, 0, 255 and we added a couple of
lines to sleep for a quarter of a second -
time.sleep(0.25) - and to clear all
of the pixels -
Making it rainbow!
For our last example, we'll get a little more complex and make a rainbow animate across your Unicorn pHAT. As well as representing colours in RGB, we can also use a system called HSV (hue, saturation, value) that uses the colour wheel to determine the hue of a colour. The colour wheel begins and ends at red, and progresses through all of the other colours of the rainbow in order. Each position on the colour wheel is represented by a compass position in degrees, with red being at 0/360 degrees.
Fortunately, there's a Python library called
colorsys that lets you convert
HSV colour values to RGB colour values that we can feed into the
function. So, to animate our rainbow we just have to continuously cycle around
the colour wheel through all of the colours of the rainbow.
Here's all of the code for our animated rainbow. We'll break down what all of it does after. Type the following:
import time import colorsys spacing = 360.0 / 16.0 hue = 0 while True: hue = int(time.time() * 100) % 360 for x in range(8): offset = x * spacing h = ((hue + offset) % 360) / 360.0 r, g, b = [int(c * 255) for c in colorsys.hsv_to_rgb(h, 1.0, 1.0)] for y in range(4): uh.set_pixel(x, y, r, g, b) uh.show() time.sleep(0.05)
First, we import the
colorsys libraries. We'll need the
library to convert our HSV colour into an RGB colour.
spacing = 360.0 / 16.0 means that we'll space half of the colour wheel across
the 8 pixel width of Unicorn pHAT at any one time. You can reduce the
get more of the colour wheel across your Unicorn pHAT or increase it to get less
hue = 0 initialises the
hue variable with a starting value of
0.0. It will
be changed through time inside our
while True: loop, but we have to initialise
it outside our loop.
while True: loop does several things. Most importantly, it sets the hue by
taking the time (in epoch seconds, no need to worry about what that is),
multiplying it by 100 to scale it up a little, and then taking the modulo 360 of
that result (the remainder after dividing the time x 100).
Then, we have two
for loops. The first calculates an
offset from the pixel
x and our 22.5 degree
spacing that we calculated earlier. This
offset is added to the
hue, the modulo
360 is taken again, and the value is
360.0 to get a number between
1.0 that will be accepted
colorsys.hsv_to_rgb() function. The rather complicated line that begins
r, g, b = is a list comprehension that converts the RGB values returned by
colorsys.hsv_to_rgb(), which are values between
1.0 to RGB values
between 0 and 255.
for loop just sets all of the pixels in each column (
y) to the
same colour that we just calculated for each
x pixel, using the
Finally, we call
uh.show() outside of our two
for loops but still inside the
while loop, and then introduce a small delay of 0.05 seconds to set the
animation speed with
Taking it further
Why not try to take our rainbow example further and set a different colour for the pixels in each column too? Or just clamp the range to a portion of the colour wheel that you like?
Try setting the colour of your Unicorn pHAT to the current Cheerlights colour, or use your Unicorn pHAT to display your mood on Twitter based upon the sentiment of your recent tweets.
Search above to find more great tutorials and guides.