Getting Started with Inky pHAT

This tutorial will show you how to install the Inky pHAT Python library, and then walk through its functionality. You'll learn how to run the beautiful included examples: the weather station, calendar, and name badge, and then learn how to display text and images on Inky pHAT.

You'll see that your Inky pHAT already has an image on it, straight out of the bag! This is because e-paper displays, like the one on Inky pHAT, allow you to update them with an image and the image will persist even once you've cut the power supply (i.e. switched off your Pi, or even removed the pHAT altogether)! This means that you can use Inky pHAT as a fancy-pants name badge, completely sans power.

Because Inky pHAT comes fully-assembled, there's no need to solder anything, so you can just pop it onto the GPIO pins on your Pi or Pi Zero and get going!

Installing the software

Note that if you have just received a new Inky pHAT (at the beginning of December 2017), and it doesn't appear to be working after running the one-line-installer below, then you may need to run sudo pip install --upgrade inkyphat in the terminal. It can take a few days for our software to propagate through to the apt repositories used by the one-line-installers.

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 Inky pHAT set up. We'd suggest that you use this method to install the Inky pHAT software.

Open a new terminal, and type the following, making sure to type y or n when prompted:

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

Running the built-in examples

The Inky pHAT Python library comes with a handful of really beautiful examples, including a weather station, a calendar, a name badge, and a QR code display. We'll look at how to run some of those now.

Note that, as of July 2018, Inky pHAT now comes in three different colour schemes: red/black/white, yellow/black/white, and black/white. We've updated the Python library to add support for the different colours, so that each colour looks as good as possible. This means that you have to specify the colour as part of your code - inkyphat.set_colour("red"), inkyphat.set_colour("yellow"), or inkyphat.set_colour("black") - just below the import inkyphat at the top.

For the examples below, they have been updated to allow you to pass the colour straight in as an argument, and we'll assume that you have the red one. If you have yellow or black, then just change red to yellow or black.

Assuming you used the one-line-installer to install the library, the examples will have been downloaded to /home/pi/Pimoroni/inkyphat/examples (if you cloned and installed the library straight from GitHub then they will be in inky-phat/examples). Open a new terminal window, and type the following to navigate to the examples folder:

cd /home/pi/Pimoroni/inkyphat/examples

We'll look first at the calendar example. This example draws a neat little calendar on your Inky pHAT, with days from the current month in white, overhanging days from the previous and next month in red, and the month and year to the side.

In the terminal, type python red to update your Inky pHAT display with the current calendar. It'll take a few seconds (around 15 usually) to update the whole display. e-paper displays work by pulling coloured particles up and down using different voltages, so that's what all the pulsing of the display is (and why the image persists).

Note that if you want to have the calendar always on and updated then you would have to re-run the script periodically using crontab, as follows. In the terminal, type:

crontab -e

And then, at the very bottom of the file, add the following line:

*/30 * * * * python /home/pi/Pimoroni/inkyphat/examples/ red

That will run and update the calendar every 30 minutes, although you can change that number to a smaller or larger number depending on how frequently you'd like it to update.

Next, we'll take a look at the weather example. It displays the time and date at which the weather was last updated, a little icon describing the current weather, and the temperature and pressure at your chosen location.

You can set your chosen location by changing the CITY and COUNTRYCODE variables in the script. The defaults are set to "Sheffield" and "GB", for obvious reasons...

To run the example, type the following in the terminal:

python red

Again, if you want the example to run periodically and keep the weather updated on your Inky pHAT, then you'll need to use crontab, as in the example above. A good frequency at which to run it is probably every ten minutes.

The name badge example uses the red, black, and white inks to evoke one of those "Hello, my name is..." name badges. To run this script, you pass it the name in terminal when running the script, as follows:

python "Inigo Montoya" red

That should display Hello my name is Inigo Montoya on your Inky pHAT.

As we said earlier, you can now completely detach your Inky pHAT and use it as a completely powerless name badge, although it should be noted that the image may fade gradually over the course of a day or so, but you can easily perk it up again by reconnecting it to your Pi and running the script again.

Displaying text on Inky pHAT

A common task that you might want to do is to display text on Inky pHAT. You can use the Python Image Library to display text, using regular TrueType fonts. We've included a handful of nice fonts with the library that are licensed under the Open Font License.

We're going to display a simple Hello, World! on Inky pHAT using the Fredoka One font that's included in the library. It's worth noting that we've found that font sizes greater than 22 point look really crisp, anything above about 16 point is legible, and anything less than 16 starts to look less legible, although this will vary depending on the font.

The Python Image Library (PIL) will have been installed when you ran the installer, so there's no need to worry about installing it. We'll begin by importing ImageFont from PIL, and importing the inkyphat library:

import inkyphat
from PIL import ImageFont

Next, we'll set the colour of your Inky pHAT:


We'll create a variable font that specifies what our font is, and what size it should be, in this case FredokaOne and 22:

font = ImageFont.truetype(inkyphat.fonts.FredokaOne, 22)

There are handy inkyphat.WIDTH and inkyphat.HEIGHT constants that tell us the width and height of the Inky pHAT display, and we can get PIL to tell us the width and height of our Hello, World! text, so that we can perfect centre the text on the display with a little bit of maths!

message = "Hello, World!"
w, h = font.getsize(message)
x = (inkyphat.WIDTH / 2) - (w / 2)
y = (inkyphat.HEIGHT / 2) - (h / 2)

The x and y variables will tell the inkyphat.text() function where to place the top left corner of our text. We'll also have to tell the function what colour we want the text (RED, BLACK, or WHITE), and pass it our font variable. Last of all, we'll call the function to tell Inky pHAT to refresh the display with our text.

inkyphat.text((x, y), message, inkyphat.RED, font)

Try experimenting with different text colours, fonts, and sizes! You can see the other fonts included by typing print(dir(inkyphat.fonts)) in your Python prompt.

If you want to add additional fonts, then you can drop them into both the /usr/lib/python2.7/dist-packages/inkyphat/fonts and /usr/lib/python3/dist-packages/inkyphat/fonts directories. They should be .ttf files, ideally. Or you can simply pass the path to your font into the font = ImageFont.truetype("/path/to/font", 22) line in your code.

Displaying images on Inky pHAT

Displaying images on Inky pHAT requires a little bit of jiggery-pokery to prepare your images properly. They should be PNG-8 images, 212x104 pixels, and in indexed colour mode with a palette of just three colours - black, white, and red - in exactly that order.

We'll run through how to prepare a simple image for Inky pHAT in the free graphics package for Linux, GIMP.

First, in the terminal, we'll install GIMP by typing sudo apt-get install gimp and then open it by typing gimp.

Go to the File menu and click New to create a new file. Make the image width 212 pixels and the image height 104 pixels.

Draw your picture. We went for a simple rectangle and circle in black and red.

Once you've finished drawing your picture, you'll need to change the colour palette of the image to a three colour, indexed colour palette image, with the colours in the order white, black, red.

Go to the Image menu, then Mode, and select Indexed.

We've created an Inky pHAT colour palette that you can use. In the terminal, type git clone to clone the GitHub repo. You'll find the colour palette at inky-phat/tools/Inky-pHAT.gpl.

Select Use custom palette, then click the Palette selection dialogue button. Select Palette file and then select the Inky-pHAT.gpl palette file from the GitHub repo that we just cloned.

The last thing to do is to export the image as a PNG. Go to the File menu and then select Export as. Give your file a filename (we called our inky.png) and save it in your home directory, /home/pi. A dialogue box should pop up with the options for saving it. Make sure that you check the Save background colour checkbox, then click Export.

Now we have to display our image on Inky pHAT. Back in the terminal, type python again to open a Python prompt, assuming you aren't still in one, then type the following:

import inkyphat
from PIL import Image



Your Inky pHAT should now be displaying your glorious art.

Taking it further

There's a bunch of drawing tools included in the Inky pHAT library, inherited from the Python Image Library, that you can use to draw on Inky pHAT using code, and without the need for GIMP and indexed colour palettes.

Why not try to write a script that converts regular coloured images to red, black, and white images using Python Image Library? Inky pHAT is ideal for displaying data on. You could use the Matplotlib library to plot out sensor data from other remote Pis with sensors, for example. Or you could hook it up to IFTTT and use it as a tiny message board on which you could leave messages for you family, attached to your fridge perhaps?

Shopping basket

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

Inky pHAT (ePaper/eInk/EPD)
Red/Black/White £22.00
Inky pHAT (ePaper/eInk/EPD)
Yellow/Black/White £22.00
Inky pHAT (ePaper/eInk/EPD)
Black/White £22.00
Raspberry Pi Zero
Raspberry Pi Zero W
Raspberry Pi 3 Only
Official Raspberry Pi Universal Power Supply
NOOBS 16GB microSD card (2.8)
Antex XS25 Soldering Iron (UK Plug)
Antex Lead Free Solder 2m
GPIO Hammer Header (Solderless)
Male + Female + Installation Jig £6.00
GPIO Hammer Header (Solderless)
Male £2.00
GPIO Hammer Header (Solderless)
Female £3.00
Want to checkout or change something? Click here to view your cart.

Raspberry Pi, Pi Zero

Sandy Macdonald
Formerly, Sandy worked at the University of York, in the biology department, analysing data and telling people that they should have used more replicates. Now a fully-fledged crew member at Pimoroni - head of digital content - working on learning materials and digital chunterings. Find him on Twitter and most everywhere else, as sandyjmacdonald.