Getting Started with Unicorn HAT


If you're here, you've either bought a Unicorn Hat or are thinking of picking one up. No doubt the lure of the searingly-bright LEDs has captivated you, and you're interested in incorporating this easy-to-use display into your project, or just learning a little from it.

We call it Unicorn Hat because it does rainbows, really bright rainbows, but that's not the limit of its ability. Unicorn Hat is a chain of 64 super clever LEDs known as ws2812s which have built-in intelligence. Each ws2812 LED is capable of understanding a signal that's a little like morse-code. This signal tells it what colour to be by giving it Red, Green and Blue values. Once it's got a colour, it'll pass all the other colour commands along to its neighbour. This happens one LED after the other until the whole chain is lit up, and it happens so quickly you can't even see it happening.

All this is done with just one pin from the Raspberry Pi, and we've wrapped up the particulars into an easy-to-use Python module so all you have to worry about is setting the colour you want each pixel to be.

You'll come across Red, Blue and Green colour codes a lot in programming. They're a standard way to represent nearly 17 million colours with three numbers from 0-255. Understanding how they work, and how to find or generate a particular colour, is key to using Unicorn Hat. You'll learn more about this later.

We've created a GitHub repository bundling the Unicorn Hat software with a set of examples to get you started. This guide will walk you through installing the software and examples.

Before we start

Before installing Unicorn Hat, it's good practise to update the software on your Pi. If you already know how to do this, go right ahead, otherwise you can read our guide to "Keeping your Pi Up-to-date".

Setting up Unicorn Hat

Unicorn Hat is easy to set up. We've created a one-liner ( that's one line of text you enter at the Terminal ) to get everything installed.

With Step 2 above in mind, fire up the Terminal and enter the following command:

curl | bash

Installing Unicorn Hat.

This command downloads an install script from the internet, which should then run automatically through all the steps required to get Unicorn Hat installed and working.

Note: Unicorn Paint is only supported in Python 2.x!

During installation, you'll be asked if you want to install Flask for Unicorn Paint. It's up to you, but I'd recommend it! Unicorn Paint is fun.

Once the install is done, the script will ask if you want to download example code, answer yes.

Verify that Unicorn Hat is installed and working

Finally, you should make sure everything has installed properly.

Still in LXTerminal, type:

cd ~/Pimoroni/unicornhat/examples/

And then:

sudo python ./

If everything is working, you should see the UnicornHat fill with pinky-purple pixels. If so, hurrah! You're ready to move on to the next tutorial.

Keep in mind

Unicorn Hat installs for both Python 2 and 3, so you can use what you're comfortable with.

Shopping basket

Need something for this project? You can use the links below to add products to your Pimoroni Shop basket for easy checkout.

Unicorn HAT
Want to checkout or change something? Click here to view your cart.

Unicorn HAT, Raspberry Pi, Python, LEDs

Phil Howard
Phil is Pimoroni's software guru, instantly recognisable by his somewhat pirate-themed moustache growing attempts. Usually found buried neck deep in Python libraries, he's also been known to escape on occasion and turn out crazy new products. If you need a helping hand, he's a prolific Twitter user and rampages around the forums like a T-Rex. Ask him if you need help with Pimoroni's software libraries, or Propeller HAT.