Getting Started with Unicorn HAT Mini
This tutorial will show you how to install the Unicorn HAT Mini Python library 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!
Please note the LEDs on Unicorn HAT Mini are not Neopixels/WS2812 addressable LEDs - they are ordinary RGB LEDs made 'smart' with a pair of Holtek matrix driver chips. All this means is that they use a different library to Unicorn HAT and pHAT so you'll need to make sure you download the right one. If you have one of our older boards you can find a tutorial for Unicorn pHAT here.
Unicorn HAT Mini comes with a pre-soldered header so, as long as you've got headers attached to your Pi, you won't need to do any soldering. Woop!
Installing the software
We always recommend using the most up-to-date version of the full desktop version of Raspberry Pi OS, as this is what we test our boards and software against, and starting with a completely fresh install is usually a good idea. We'll assume you've got a monitor, keyboard and mouse plugged into your Pi, although it's also possible to do all the steps in this tutorial 'headlessly' if you prefer (that's connecting to your Pi over SSH from another computer).
First of all, you'll need to enable SPI on your Pi (this is the protocol your Pi uses to communicate with the mini HAT).
Open a new terminal (click on the icon in the taskbar that looks like a little black box) and type the following, followed by enter.
sudo raspi-config nonint do_spi 0
Alternatively, you can also turn on SPI using the Preferences menu if you prefer - you can find the option to turn on SPI under Preferences > Raspberry Pi Configuration > Interfaces.
Next, we'll need to download the library from Github, and run the installer. For this bit your Pi will need to be connected to wifi (there should be a wifi icon in the taskbar at the top right you can click on to do that if you're not connected).
In the terminal, type the following, pressing enter after each line:
git clone https://github.com/pimoroni/unicornhatmini-python cd unicornhatmini-python sudo ./install.sh
The installer will give you the option to copy our examples to your Pi, we'd suggest typing 'y' to do that.
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.
If you'd like to tidy up the installer files, you can now delete the directory you cloned from Github:
sudo rm -r ~/unicornhatmini-python
If you'd like to give our examples a go you can navigate to them by going to:
cd ~/Pimoroni/unicornhatmini/examples ls
and then running them like this:
Using the software
We'll be programming our Pi via REPL (that's typing our Python commands directly into the Python interpreter, one line at a time). If you'd rather have a slightly more friendly interface, the code below should also work in a Python IDE such as Thonny. Open a new terminal and type
sudo python3 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
from unicornhatmini import UnicornHATMini uh = UnicornHATMini()
The second line is assigning Unicorn HAT Mini a shorter, friendlier name and means we don't have to type
UnicornHATMini() each time we want to call a function, just
We'll also set the brightness to 50%, since Unicorn HAT Mini will scorch your retinas at 100% brightness (you were warned!)
To light a pixel on Unicorn HAT Mini 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 HAT Mini and actually display the pixel that we set.
Pixels on Unicorn HAT Mini 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
16, 6. Remember that, in Python, things are numbered 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 HAT Mini, it's just a matter of repeating the
process we just did once for each of the 119 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(17): and then
for y in range(7):,
because we have 17 pixels along the x axis and 7 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 (making sure the indents look the same as below, with four spaces in front of the second line and eight spaces in front of the third line):
for x in range(17): for y in range(7): uh.set_pixel(x, y, 0, 255, 255)
You might need to press enter twice to tell the interpreter you're done with your
for loop and get the >>> prompt back. Then type:
All of the pixels on your Unicorn HAT Mini 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(17): for y in range(7): uh.set_pixel(x, y, 255, 0, 255) uh.show() time.sleep(0.25) uh.clear() uh.show() time.sleep(0.25)
Again, you might need to press enter twice to break out of the loop, if your cursor shows
... instead of
>>>. You can stop your code running by pressing ctrl-c.
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 HAT Mini. 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 / 34.0 hue = 0 while True: hue = int(time.time() * 100) % 360 for x in range(17): 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(7): 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 / 34.0 means that we'll space half of the colour wheel across
the 17 pixel width of Unicorn HAT Mini at any one time. You can reduce the
get more of the colour wheel across your Unicorn HAT Mini 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 HAT Mini to the current Cheerlights colour, or use your Unicorn HAT Mini to display your mood on Twitter based upon the sentiment of your recent tweets. You could also hook up your Pi to Google Calendar, Zoom or Teams APIs to make a busy light for your office door!
Search above to find more great tutorials and guides.