Using the PicoGraphics library to display text and graphics on an Inky Frame

#

The Inky Frame firmware comes with a library called PicoGraphics that we can use to draw text and graphic images on a number of displays, in a large number of resolutions and bit depths. Since this library is ready to go for our use, lets explore how to use the PicoGraphics library to write some text to the screen.

If you would like to follow along with this article, open Thonny and connect your Inky Frame to your computer. Select the proper interpreter to allow you to send commands to the Pico W on the Inky Frame, and stop the running process. We will be using the MicroPython REPL to play around with the screen. If you need help with any of these steps, please go to the first article in this series.

Working with the MicroPython REPL

#

To ensure that you are in the REPL, just type the help() command.

help()

and you will see output like this.

This means that we are in the REPL and it’s taking our commands, so we are ready to go!

Using the Frame Buffer

#

What is a Frame Buffer? It is a piece of memory that will hold the what we are paining on the screen in memory. It won’t update or change what is on the display until we call the update() method. This allows us to issue a number of commands, each one can be modifying the display in the frame buffer, until we decide to display it to screen.

Hello World with PicoGraphics

#

From within your REPL, issue the following commands.

from picographics import PicoGraphics, DISPLAY_INKY_FRAME
display = PicoGraphics(display=DISPLAY_INKY_FRAME)

These commands are creating our display object and setting it for the proper hardware type. How did we know to set it for DISPLAY_INKY_FRAME? That is in the GitHib documentation for this library.

You can see from the documentation for the PicoGraphics library,the 5.7 inch Inky Frame is called DISPLAY_INKY_FRAME and the 7.3 inch is called DISPLAY_INKY_FRAME_7. This allows the developer to easily specify the hardware they are working with.

Now that we have our display object we can start to use it to setup the frame buffer in the display object. First, let’s clear the screen.

Clearing the Screen

#

To clear the screen, first we need to setup a pen, and set the pen to the color that we would like to display over the entire screen. For example, to clear the screen with white ink, do this.

WIDTH, HEIGHT = display.get_bounds()
display.set_backlight(1.0)
display.set_pen(1)  # 1=white color
display.clear()
# Nothing will have changed on the display to this point, but once you issue
display.update()
# The display will flash and the screen should show a white display

Let’s go over the code line by line.

WIDTH, HEIGHT = display.get_bounds()

Here we are calling the get_bounds method on the display object. This will return a tuple of the width and height of the display hardware.

Getting these values early will allow us to use them to make our code portable across Inky Frame devices.

display.set_backlight(1.0)

next we are calling the set_backlight method on the display object. This allows setting the backlight value from 0.0 to 1.0 or a value of 0.0 is backlight off and 1.0 is the brightest setting.

display.set_pen(1)

Here we are setting the color of the pen that we will use to clear the screen. The possible color values are:

Color values
0=Black 1=White 2=Green 3=Blue 4=Red 5=Yellow 6=Orange 7=Taupe

So setting the pen to 1 will make the screen all white when we clear it.

display.clear()

Again, this won’t actually clear the screen now, but it has in the frame buffer. so let’s write it to the display.

display.update()

Once you press return on this command, you will see that the prompt will not return until the update is complete. The entire time to repaint the display should be around 30 seconds, and then you will see a blank display. What if we wanted to make the screen blue instead?

display.set_pen(3)
display.clear()
display.update()

Copy and paste those commands into the REPL and in around 30 seconds, you will have a blank, blue, display.

Writing text to the screen

#

Now that we have cleared the display, let’s write ‘Hello World!’ to it. First copy and paste this code into the REPL.

display.set_pen(1)
display.set_font("bitmap8")
y = 0
x = 0
display.text("Hello World!", x,y,scale=4)
display.update()

Now you should see a blue background and in white text the words ‘Hello World!’ printed in the upper left corner of the screen, like this.

Let’s walk through the code. First we are setting the pen to white.

display.set_pen(1)
display.set_font("bitmap8")

By calling the set_font method, we have set the font to bitmap8. There are three different bitmap fonts that are available, bitmap6, bitmap8 and bitmap14_outline. The number of the font as in bitmap6 is the point size of that font at a scale of 1. At a scale of two that font will be 12 point or 2 X 6.

y = 0
x = 0
display.text("Hello World!", x,y,scale=4)
display.update()

Next we are setting x and y variables both to 0. Those variables will be used to position the text on the screen. The x and y values will specify the top left corner of the text that is printed to screen.

Then we are calling the text method on the display object to actually create the text in the frame buffer. The call itself, it structured like this.

display.text(text, x, y, wordwrap, scale, angle, spacing, fixed_width)

function arguments:

text - The actual text to be displayed.
x - The X position of the text to display.
y - The Y position of the text to display.
wordwrap - The number of pixels to display before attempting to break text into multiple lines.
scale - size of the text.
angle - rotation of the text. Valid for vector fonts only.
spacing - letter spacing.
fixed_width - monospace characters.

You might have noticed in the description above there is a mention of vector fonts. We have been using bitmap fonts so far, but the issue with bitmap fonts is that the larger you make a bitmap font the larger the jaggies will be on the characters themselves. By moving to a vector font, these fonts are drawn by a series of lines, and are able to scale to any size or font weight. Here is an example of the Sans vector font at scale 3, see how nice the font looks?

My only complaint on this is the font looks a bit thin. The reason for this is that vector fonts are rendered at 1 point thickness. We can add additional thickness to vector fonts like this. Using the set_thickness method we have set it to 3 points.

display.set_thickness(3)
display.text("Hello World!", x,y,scale=3)
display.update()

The other thing you need to keep in mind is that the zero position of the fonts will change depending on if you use a bitmap or vector font. The zero point on the bitmap fonts is at the upper left position of the text. The zero point of a vector font is aligned horizontally (x access) to their left edge. Vertically to their midline excluding descenders.