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 y or n when prompted:

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 phat and 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:

cd /home/pi/Pimoroni/inky/examples/what

Quotes example

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 - --type, --colour, and --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 -t, -c, and -n)

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

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 the argument "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, img, that is the width and height of the Inky wHAT display, and then creates a drawing canvas, 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.WIDTH and 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)

The x and 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 (RED, BLACK, or 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 gimp.

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

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

Select Use custom palette, then click the Palette selection dialogue button. Select 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 then select Export as. Give your file a filename (we called ours 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 wHAT. If you haven't made an image, you can try displaying the Inky pHAT logo file that's in the GitHub repo at inky/examples/what/resources/InkywHAT-400x300.png.

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:

  1. Open the image
  2. Resize it to be 300 pixels tall
  3. Crop the image
  4. 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 pattern-3.jpg.

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

The w_new and 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 later.

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)

The two pal_img lines are creating the palette that we use for the conversion, and the quantize method takes care of mapping the two palettes.

Finally, let's display the converted image on Inky wHAT!

inky_display.set_image(img)
inky_display.show()

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
That's all folks!

Search above to find more great tutorials and guides.

Plasma 2040

Swathe everything in rainbows with this all-in-one, USB-C powered controller for WS2812/Neopixel and APA102/Dotstar addressable LED strip.