Unicorn Basics Pi EN

Unicorn Basics Pi EN Titelbild


All of the circuits, programs, and electronic components were tested by us. Unfortunately, we can’t rule out the possibility of defects or mistakes in the electronic components, circuits, or programs. If you have questions or you are experiencing difficulties please contact us.


Coding World UG (haftungsbeschränkt)
Obdrupstr. 23a, 24986 Mittelangeln
Support & Feedback: support@cw42.de

Table of content

Thema Seite
The Shield Page 2
Install the library Page 3
Your first program Page 4
List of all functions Page 5
Working with colors Page 8
Using the Unicorn Inputs Page 9
More cool projects Page 11

The Shield

The Coding Unicorn Shield was designed to be attached to the Raspberry Pi in order to create the basis for many fun and interesting projects. You simply can use Jumper Cables for this. More Information cw42.de/uce. To begin, you need to attach the shield to the GPIO Pins on your Raspberry Pi so that the head is in the direction of the USB Connectors. On the following pages we will show you how to install the Python library and begin utilizing it to create programs and projects on your own. Altogether you have 9 Pixels on the Shield, also called WS2812B (Red), 2 white 5mm LEDs on the eyes (Green), a brightness sensor (blue) on the Nose and a push button on the ear (dark blue). Because the GPIO Pins aren't capable of reading analog values,we used a little hack and added the capacitor (orange) in order to properly utilize the brightness sensor. You can find out more on: cw42.de/adce

Das Shield mit Erklärungungen

Install the library

Before we get started with the Unicorn shield, we first need to install the necessary libraries and change some settings. When using the Pixels/WS2812B it is important that we have PWM functionality configured on our Raspberry Pi. Once you have activated that, you can't use the the build in audio connector anymore. To make sure that this is deactivated we can use the raspi-config. First use the following terminal command: sudo raspi-config then make the following options: 7 Advanced Options -> A4 Audio -> 2 Force HDMI -> Ok.

You will need an internet connection for the following steps:

sudo apt-get install python-dev

And now download the library:

git clone https://github.com/
cd unicorn-shield-python/
cd rpi-ws281x
sudo python setup.py install
cd ..
cd UnicornShield

sudo python setup.py install
cd ..

Your first program

In the next step we will write a simple program which will set the color of all leds to a pink blinking sequence. If it does not work or you obtain error messages, then you should try reinstalling and setting up all of the materials.

import unicornshield as unicorn
from time import sleep

while True:

You need to execute the program with sudo python nameOfYourProgram.py to start it. You can end the program when you wish with Ctrl+C.

Step for step

In the first two lines we included the required python libraries. By using as unicorn we can give the long name of the libary unicornshield a shorter nickname, or alias, and use this to save typing time moving forward. We also need the sleep() function later in the program to create the blinking.

This is all we need to include to get the work with the shield started. In line 4 the main part of the program is already starting with while True:. This is a loop which will be running until the program is closed with Ctrl+C. Inside the loop in line 5 we are using for the first time a function from the unicornshield. With the function .setAll() we can give all the pixels one color. For this the function has 3 parameters corresponding to the colors. This color system is also called RGB. RGB is short for red, green and blue. For each parameter you can use a value between 0 and 255. This enables you to mix most colors of the color wheel and display them with the Pixels. With the values (155,0,155) we are mixing a light pink, like the color of the PCB. If we end the program after this function, nothing would happen, bringing us to what makes the .show() function in line 6 very important. Only after calling this function, will the colors show and the Pixels change. So always keep in mind to call this function in your programs. Both of the functions are inside the Unicorn Shield library which is also the reason why you need to write: unicorn.nameOfTheFunction() to really call the function. Because we do not want to display one single color, but rather create a blinking, we use the sleep(1) function in line 6. This function will halt the program for 1 second. In line 7 are we using the .clear() function to turn off all of the LEDs. For this function we don't need to call the .show() function. The second sleep() function will halt the program again so that you will see for one second a bright pink unicorn and for another second a turned off unicorn. This concludes your first simple program with the unicorn! In the next step we will have a more detailed look into the function and how to mix custom colors.

List of all functions

Function Explanation Parameters
.brightness(b) Sets the brightness for the Pixel/ WS2812B on the Unicorn b=brightness, ranging from 0-1
.getBrightness() Returns the current brightness
.clear() Turns off all the Pixels/ WS2812B
.setPixel(x,r,g,b) Sets the color for one Pixel/ WS2812B x=Position, ranging from 0-8; r=color red, ranging from 0 to 255; g=color green, ranging from 0 to 255; b=color blue, ranging from 0 to 255
.getPixel(x) Gets the current color value x = Position, ranging from 0 - 8
.setAll(r,g,b) Sets one color code for all Pixel/ WS2812B r=color red, ranging from 0 to 255; g=color green, ranging from 0 to 255; b=color blue, ranging from 0 to 255
.show() Displays the values set by .setPixel() and .setAll() on the Shield
.leftEyeOn() Turns the LED on the left eye on
.leftEyeOff() Turns the LED on the left eye off
.rightEyeOn() Turns the LED on the right eye on
.rightEyeOff() Turns the LED on the right eye off
.nose() Returns the value of the current brightness. Around 0.3 in room lightning
Button / Ear
.buttonPressed() Returns False or True if the button on the ear is pressed

Because all of these functions are inside the unicornshield library you always need to call the library and the function:

import unicornshield


You should also keep in mind that you also need to execute your program with root permissions - so with sudo. This is especially important when you create a cronjob for your program or include these functions into another program.

Working with colors

We can use the Pixel LEDs on the Shield to display a huge variety of colors. We use the RGB Parameters for mixing these colors. To give you some help we prepared a list of colors and codes but you can also use what is called a color picker for creating your own colors. (If you google or search on the internet for color pickers you will find many choices). To give you a better introduction we prepared some .setPixel() function with example colors. Remember that you can also utilize the .setAll() function.

.setPixel(0,255,0,0) Red
.setPixel(0,255,180,0) Orange
.setPixel(0,255,255,0) Yellow
setPixel(0,0,255,0) Green
.setPixel(0,0,255,155) Turquoise
setPixel(0,0,0,255) Blue
.setPixel(0,255,0,255) Lila
.setPixel(0,255,255,255) White
.setPixel(0,0,0,0) Black/turned off

It is important that you always use the .show() function after using the .setPixel() and the .setAll() functions. If you forget it, the colors on the shield won't change. You can also use the .clear() function instead of the .setAll(0,0,0) function because black and turned off are the same for our Pixel Leds.

Now it is your turn: Can you create your favorite color on the Pixel LEDs? Observe what happens when you alter the numbers a little bit?

Using the Unicorn Inputs

You have already learned a lot about the Pixel LEDs on the Unicorn Shield but we haven't talked much about the Button and the brightness sensor on the nose. In this little program we will use both input methods.


import unicornshield as unicorn
from time import sleep


while True:
    buttonStatus = unicorn.buttonPressed()
    noseStatus = unicorn.nose()
    if(buttonStatus == True):
    elif(noseStatus > 0.2):

You can start the program with sudo python test-station.py. It will not stop until you enter Ctrl+C or Cmd+C. After starting the program, all of the Pixel LEDs on the Unicorn Shield will have a white color. You should see the status of the button and the brightness sensor (the nose) in your terminal. After pushing the button, all of Pixel LEDs will have a blue color and both LEDs on the eyes will be turned on. If you hold your thumb or hand in front of the nose, the Pixel LEDs color will change to lila and both LEDs on the eyes will be turned off. We will now have a closer look at the code.

If you look at the code again, you will see that we are importing the needed libraries in the first two lines. In lines 4 and 5 we make sure that with every start of the program the Pixel LEDs are turned on with a white color.

In line 7 is the beginning of a forever running while-loop which ends on line 22. In lines 8 and 9 we are collecting and saving the information for the status of the button in the variable buttonStatus and the current brightness in the variable noseStatus. For this we are using the function .buttonPressed() and .nose(). You already know these functions from the function overview. We are also using the print() function to output these values in the console. In the next step we are creating two if conditions. The first if condition is in line 12 and is true when the variable buttonStatus is equal to True. True means in this case that the button was pushed. If the if condition is true the code from lines 13 to 16 is executed. In lines 13 and 14 are where the Pixel LEDs are handled. This means that they are turned on and are set to the color blue. In line 15 and 16 both LEDs on the eyes are turned on. If the condition in line 12 is not true, because the button wasn’t pushed, the second condition in line 17 will be checked. This condition is true, when the variable noseStatus is greater than 0.2. That would mean that the brightness sensor is covered with a thumb or hand. If this is the case, everything from line 18 to 21 is executed. First, on line 18 and 19 all Pixel LEDs turned on to the color lila, and then in line 20 and 21 both LEDs on the eyes are turned off. In the end of the while loop there is a short break in line 22, because it is not unnecessary to check this inputs too frequently. If none of the conditions are true, the program just waits a bit until it checks the inputs again, and again, and again.

Now it is your turn: Can you change the colors inside the conditions to colors you like? What happens when you change the 0.2 value in the second condition?

More cool Projects

E-Mail Notifications Use your unicorn shield to instantly notice new emails. The program will read your email inbox and visualize it on the unicorn. cw42.io/einhorn1
Photobooth With your unicorn shield and the Raspberry Pi Camera, build a photobooth. Use the Nose for taking the picture and the Leds to show when you need to smile. cw42.io/einhorn2
Hashtag Monitor Which hashtag is currently really trending and how does the twitter API work? In this project we will answer this question and have a look at different technologies. cw42.io/einhorn3
People in space How many people are currently in space or on the ISS? With the unicorn shield an an api you can easily visualize this number. You will also learn how to work with a simple API cw42.io/einhorn4

Noch Fragen oder Feedback?

Bevor du eine Frage stellen kannst musst du dich zuerst Anmelden oder Regestrieren!