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!
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
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
curl https://get.pimoroni.com/inkyphat | 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.
Open a new terminal and type
python to open a new Python prompt.
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.
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:
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 cal.py 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
And then, at the very bottom of the file, add the following line:
*/30 * * * * python /home/pi/Pimoroni/inkyphat/examples/cal.py
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
variables in the
weather.py script. The defaults are set to
"GB", for obvious reasons...
To run the example, type the following in the terminal:
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 hello.py "Inigo Montoya"
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.
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
PIL, and importing the
import inkyphat from PIL import ImageFont
We'll create a variable
font that specifies what our font is, and what size it
should be, in this case
font = ImageFont.truetype(inkyphat.fonts.FredokaOne, 22)
There are handy
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)
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 (
WHITE), and pass it our
font variable. Last of all, we'll call the
inkyphat.show() function to
tell Inky pHAT to refresh the display with our text.
inkyphat.text((x, y), message, inkyphat.RED, font) inkyphat.show()
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
If you want to add additional fonts, then you can drop them into both the
/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
font = ImageFont.truetype("/path/to/font", 22) line in your code.
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
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
We've created an Inky pHAT colour palette that you can use. In the terminal,
git clone https://github.com/pimoroni/inky-phat to clone the GitHub repo.
You'll find the colour palette at
Use custom palette, then click the
Palette selection dialogue button.
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
Export as. Give your file a filename (we called our
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
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 inkyphat.set_image(Image.open("/home/pi/inky.png")) inkyphat.show()
Your Inky pHAT should now be displaying your glorious art.
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?
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)
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)
GPIO Hammer Header (Solderless)