Getting Started with Inky wHAT
This tutorial will show you how to install the Inky Python library, and then walk through its functionality. You'll learn how to a couple of the fun Inky wHAT examples, and how to display text and images.
(wHAT stands for wide-HAT, by the way)
You'll see that your Inky wHAT already has an image on it, straight out of the box! This is because e-paper displays, like the one on Inky wHAT, 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 wHAT altogether)! This means that you can use Inky wHAT as a swish conference badge, completely powerlessly.
Inky wHAT comes completely assembled. If you're using it with a full-sized Pi, like a Pi 3 B+, then you can use the included standoffs to mount everything securely.
Installing the software
Note that if you've previously installed the Inky pHAT Python library and you're installing the Inky library they will live happily alongside each other, so there's no need to get rid of the old library.
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 wHAT set up. We'd suggest that you use this method to install the Inky wHAT software.
Open a new terminal, and type the following, making sure to type
curl https://get.pimoroni.com/inky | 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
Running the built-in examples
The Inky Python library comes with a handful of really beautiful examples.
The examples, that live in the
/home/pi/Pimoroni/inky/examples folder, are
divided into universal ones that work with both the pHAT and wHAT in the topmost
folder, and then those that are specific to the pHAT or wHAT in the
what folders respectively.
Let's look at how to run a wHAT-specific example first.
Assuming you used the one-line-installer to install the library, the examples
will have been downloaded to
/home/pi/Pimoroni/inky/examples (if you
cloned and installed the library straight from GitHub then they will be in
inky/examples). Open a new terminal window, and type the following to
navigate to the examples folder:
The larger size of Inky wHAT means that you can fit quite a bit of text on it. This quotes example uses Wikiquote and the wikiquotes Python library to display quotes from some famous scientists and engineers who we admire.
In the terminal, type the following to run the example:
python3 quotes-what.py --colour "red"
Inky wHAT is only available in red/black/white for now, but if and when other colours become available then you'll be able to change that colour to the appropriate one.
It'll take a few seconds to find a quote and update it to the Inky wHAT display.
If you dig into the code (type
nano quotes-what.py), you'll find the list of
famous people, and you can add or remove people as you wish (here's the
list of people on Wikiquote).
You'll also see a handy function called
reflow_quote that's used to reflow the
text line by line to make sure it flows properly. As well as reflowing the text,
the code checks each quote to make sure that it fits on the Inky wHAT display.
Name badge example
We'll look at how to run one of the universal examples on the wHAT now, the name badge example. This example takes some command line arguments that specify the type of display (wHAT, in this case) and colour of display that you're using.
Command line arguments are extra pieces of information that you can pass into programs straight from the command line.
Let's try the name badge example. It takes three arguments -
--name - the names of which should be fairly self-explanatory.
In the terminal, type the following:
python3 name-badge.py --type "phat" --colour "red" --name "Inigo Montoya"
(You can also use
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).
For now, Inky wHAT is just available in red/black/white, but the code allows
for yellow/black/white and black/white displays if and when they become
available, by just changing the colour passed in via
And obviously change your name from "Inigo Montoya", unless that really is your name?!
Like we said earlier, you can now completely detach your Inky wHAT 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.
Building your own code
Let's take a look now at how to build your own code with Inky wHAT. Because of the way that the new universal Inky library works now, there's some boilerplate (yadda yadda code!) that we need at the top of any code we're going to run.
In the terminal, type
python3 to open a Python prompt.
Here's the boilerplate. Type it in line by line.
from inky import InkyWHAT inky_display = InkyWHAT("red") inky_display.set_border(inky_display.WHITE)
That code imports the
InkyWHAT class from the
inky library, creates an
instance of the class that we've called
inky_display and to which we've passed
"red" to tell it what colour our display is, and set the border colour (the thin bit at the very edge of the display) to white.
Now we're ready to start displaying things on Inky wHAT!
Displaying text on Inky wHAT
A common task that you might want to do is to display text on Inky pHAT. You can use the Python Image Library (PIL) to display text, using regular TrueType fonts. In fact, we'll be using PIL to display images and graphics on Inky wHAT too.
We've made a Python fonts library to make it easy to use Open Font License (OFL) fonts with our products that have displays. The ones that the Inky library examples use will have be installed as part of the Inky library install.
You can also use fonts the regular way by downloading or transferring them to your Pi and then using the path to the file.
We're going to display a simple "Hello, World!"" on Inky wHAT using the Fredoka One font. Because the Inky wHAT display is nice and big, we'll make our "Hello, World!" nice and big at 36 points, but you can experiment with different sizes to get a feel for what works well on the display.
The Python Image Library (PIL) will have been installed when you ran the installer, so there's no need to worry about installing it. Our boilerplate code above has already set up what we need to write to the Inky wHAT display itself, but we'll need to import and set up PIL now.
Type the following:
from PIL import Image, ImageFont, ImageDraw img = Image.new("P", (inky_display.WIDTH, inky_display.HEIGHT)) draw = ImageDraw.Draw(img)
This imports three classes from PIL that we'll need, creates a new image,
that is the width and height of the Inky wHAT display, and then creates a
draw, to which we can draw text and graphics.
Next, let's import the font we need, and create a variable called
font that we
can use when we're writing text to the canvas.
from font_fredoka_one import FredokaOne font = ImageFont.truetype(FredokaOne, 36)
If you want to use your own fonts, then simply replace
FredokaOne above with
the path to your font file in quotes.
As we saw above, when we created the new image, there are handy
inky_display.HEIGHT constants that tell us the width
and height of the Inky wHAT display, and we can get PIL to tell us the width
and height of our
Hello, World! text, so that we can perfectly centre the
text on the display with a little bit of maths!
message = "Hello, World!" w, h = font.getsize(message) x = (inky_display.WIDTH / 2) - (w / 2) y = (inky_display.HEIGHT / 2) - (h / 2)
y variables will tell the
draw.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 set the image with
inky_display.set_image(img) and call the
inky_display.show() function to
tell Inky wHAT to refresh the display with our text.
draw.text((x, y), message, inky_display.RED, font) inky_display.set_image(img) inky_display.show()
Try experimenting with different text colours, fonts, and sizes!
Displaying images on Inky wHAT
Displaying images on Inky wHAT requires a little bit of jiggery-pokery to prepare your images properly. They should be PNG-8 images, 400x300 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 wHAT in the free graphics package for Linux, GIMP.
First, in the terminal, we'll install GIMP by typing
sudo apt 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
400 pixels and the image height 300 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 colour palette that you can use. In the terminal,
git clone https://github.com/pimoroni/inky 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-palette.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 ours
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 wHAT. If you haven't made an image, you
can try displaying the Inky pHAT logo file that's in the GitHub repo at
In the terminal, type the following, remembering that you'll have to type the boilerplate for the Inky library and PIL again if you left the Python prompt, and replacing the filename with the name of your own image file if it's different to ours:
img = Image.open("/home/pi/inky.png") inky_display.set_image(img) inky_display.show()
Your Inky wHAT should now be displaying your glorious art.
Let's take it a little further and see how to take something like a photo and convert it to be displayed on Inky wHAT, all within PIL.
Converting images to be displayed on Inky wHAT
Here's what we'll do:
- Open the image
- Resize it to be 300 pixels tall
- Crop the image
- Convert the image to use the 3-colour palette used by Inky wHAT
We found a really nice geometric pattern
that works really nicely with Inky wHAT and this dithering method on Unsplash.
It's below, if you want to use it, or you can find it in the
examples/what/resources/ folder, where it's called
In the terminal, type the following in your Python prompt to load in the image:
img = Image.open("pattern-3.jpg")
We're going to do some rejigging of it to resize, crop, resample, and recolour it. First, we'll get the dimensions of the image we loaded and create some variables that'll be the new sizes we want to resize to.
w, h = img.size h_new = 300 w_new = int((float(w) / h) * h_new) w_cropped = 400
h_new are the width and height that we're going to resize the
image to. We use the aspect ratio of the original image to calculate the width.
Because this image is a bit wider than 4:3, we'll crop the width down to 400
img = img.resize((w_new, h_new), resample=Image.LANCZOS)
We're using Lanczos resampling which should give a really nice resized image.
Next, we're going to crop the image, so we have to work out the top left (x0, y0) and bottom right (x1, y1) pixel coordinates that we'll crop to.
x0 = (w_new - w_cropped) / 2 x1 = x0 + w_cropped y0 = 0 y1 = h_new
And now we can crop it!
img = img.crop((x0, y0, x1, y1))
The final thing we need to do is to convert the image from an RGB palette to a white/black/red one that's compatible with Inky wHAT.
pal_img = Image.new("P", (1, 1)) pal_img.putpalette((255, 255, 255, 0, 0, 0, 255, 0, 0) + (0, 0, 0) * 252) img = img.convert("RGB").quantize(palette=pal_img)
pal_img lines are creating the palette that we use for the conversion,
quantize method takes care of mapping the two palettes.
Finally, let's display the converted image on Inky wHAT!
You can find the whole example in the downloaded examples in
/home/pi/Pimoroni/inky/examples/what/ and run it as follows:
python3 dither-image-what.py --colour "red" --image "resources/pattern-3.jpg"
There are also a couple of other nice images from Unsplash in the resources folder that work really well with Inky wHAT.
Taking it further
The larger size of the display on Inky wHAT really opens up loads of possibilities to do interesting things with it. There's plenty of space to show lots of text, data, graphs, icons, you name it!
Here's a few ideas we thought of:
- a detailed weather display with 5-day forecast
- graphing sensor data from one of our BME680 environmental sensors
- a to-do list
- household chores rota
- news headlines
- a tiny, palm-sized e-reader, using Button SHIM as the controls
Search above to find more great tutorials and guides.