Testing the Adafruit PyPortal touchscreen


The first thing to do is to set up some nice wallpaper on the screen. The PyPortal only supports bitmaps in 8-bit format at 320x240 pixels. For the project, I trimmed a picture of clouds in Gimp accordingly and exported it in BMP format. The code from Listing 1 displays the image.

Listing 1

Displaying an Image

01 import board
02 import displayio
03 from adafruit_bitmap_font import bitmap_font
05 # -------------------------------------------
07 def get_background(filename):
08   bg_file = open(filename, "rb")
09   background = displayio.OnDiskBitmap(bg_file)
10   return displayio.TileGrid(background, pixel_shader=displayio.ColorConverter())
12 # --- main-loop   ---------------------------
14 display = board.DISPLAY
15 group   = displayio.Group()
17 # set background
18 group.append(get_background("clouds.bmp"))
20 display.show(group)
22 while True:
23   time.sleep(60)

The displayio user interface library uses its own nomenclature. Other toolkits build and display trees of widgets, referred to as a group here. The program creates the top-level group in line 15. The get_background() subroutine (lines 7-10) creates a TileGrid (which itself is a group) from the BMP file.

The command in line 18 adds this group as the first subgroup and displays everything in line 20. The display determines the order of the subgroups: The earlier you add a subgroup, the further back it appears in the image, which is why the background needs to come first.

Text Output

The Label class is used for text output. Again, the terminology is confusing – a label is usually a short caption. In the displayio nomenclature, however, Label denotes a multiline text box. The library does all the work transparently in the constructor (Listing 2, line 10). The constructor creates a label from the text that is passed in, evaluates embedded line breaks, and takes care of suitable line spacing.

Listing 2

Creating a Text Box

01 import board
02 import time
03 import displayio
04 from adafruit_bitmap_font import bitmap_font
05 from adafruit_display_text import label
07 # -------------------------------------------
09 def get_label(text,font,color):
10   text_area = label.Label(font, text=text, color=color)
11   (x,y,w,h) = text_area.bounding_box
12   text_area.x = 0
13   text_area.y = -y
14   return text_area
16 # --- main-loop   ---------------------------
18 display = board.DISPLAY
19 group   = displayio.Group()
20 FONT    = bitmap_font.load_font("/DroidSansMono-16.bdf")
23 text="""Row1
24 Row2
25 Row3"""
27 group.append(get_label(text,FONT,COLOR))
28 display.show(group)
30 while True:
31   time.sleep(60)

However, the absolute alignment of the entire text box is not very intuitive. If you simply output the label, you will only see half of the content: The x and y coordinates of the text box refer to the center of its left edge, which would then end up in the upper left corner of the display. Lines 11-13 correct the offset of the label so that the text output ends up where you expect it to.

If you want to output several pieces of text in different colors or sizes, you cannot do this with just one label. The dimensions of the bounding box in line 11 help you achieve the right layout.


The text output always uses bitmap fonts, with all their inherent advantages and disadvantages. Bitmap fonts contain mini-images of all characters, which avoids the time-consuming rendering of letters. Because the character size is fixed, you need a separate font for each size. More powerful systems, where the rendering overhead is not important, therefore use more space-saving character set formats. As a result, hardly any bitmap fonts are available for download on the Internet.

Fortunately, you can get the font conversion program FontForge through your system's package manager, or you can download it from the FontForge homepage. By following the instructions found online [4], in just a few mouse clicks you have created a bitmap font of your choice. To display the ASCII graphics of the weather output correctly, I chose a monospace font.

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy Linux Magazine

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

  • Adafruit IO API

    The Adafruit IO API offers a convenient means for network-ready sensors and other components.

  • CircuitPython

    The CircuitPython run-time environment runs on almost all microcomputers and microcontrollers, making it perfect for cross-platform programming.

  • Digital Spirit Level

    The small MPU6050 sensor contains a gyroscope and an accelerometer, which means that you can build a digital spirit level with it.

  • Font Manager

    Font Manager makes it simpler to find the specific font you're looking for and to compare font options side by side.

  • Web Serial API

    Upgrade your computer with LEDs, buttons, or sensors to control a microcontroller board over USB from your web browser.

comments powered by Disqus
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters

Support Our Work

Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.

Learn More