Setting up the Display

We will be using the board.DISPLAY option so that we have a lot of control over the way our UI is rendered, like screen orientation as well as the ability to turn elements of our UI on or off.

To use board.DISPLAY, you will need the following code in your CircuitPython program.

Download: file
display = board.DISPLAY

For this project we are using board.DISPLAY so that all of the critical display settings are loaded for the CircuitPython device we are using. In this case, we are loading the configuration setup for the PyPortal into displayio.Display().

Aside from the main display setup we have a lot of options that we can now set. The two main options we will look at are rotation and backlight.

Screen Rotation

This will let you change the orientation of the display in increments of 90°. So you can also do a user interface in portrait or landscape mode.

To do this, use the following code.

Download: file
display = board.DISPLAY
display.rotation=270

Rendering the Display

Eventually, we will want to have the screen display the content, and to do that we will use the following command:

board.DISPLAY.show(splash)

This will set a Group named splash as the source of information to be displayed. We will get into Groups on the next section.

The Backlight

You can also adjust the brightness of the display backlight using board.DISPLAY. This simple function will allow you to change the brightness easily.

Download: file
# Backlight function
# Value between 0 and 1 where 0 is OFF, 0.5 is 50% and 1 is 100% brightness.
def set_backlight(val):
    val = max(0, min(1.0, val))
    board.DISPLAY.auto_brightness = False
    board.DISPLAY.brightness = val

Just use set_backlight(0.3) to set the backlight to 30% brightness.

If you want to see more stuff that you can do with displayio.Display() have a look at the Display section of CircuitPython docs.

The Touchscreen

The PyPortal has a built-in recessive touchscreen that we will use for button navigation in our UI. The following code will set up the basic touchscreen.

Download: file
# Touchscreen setup
# ------Rotate 270:
screen_width = 240
screen_height = 320
ts = adafruit_touchscreen.Touchscreen(board.TOUCH_XL, board.TOUCH_XR,
                                      board.TOUCH_YD, board.TOUCH_YU,
                                      calibration=((5200, 59000), (5800, 57000)),
                                      size=(screen_width, screen_height))

Rotating the Touchscreen

One issue that we will run into if we rotate the Display for the PyPortal is that this will change the orientation of the display, but the touchscreen coordinates remain the same. Since we will be using the touch screen to detect button presses this is a big issue. Thankfully, we can change the way the touchscreen reads its coordinates by moving the x1_pin, x2_pin, y1_pin, and y2_pin around in addition to switching the size x and y to go from horizontal to vertical format.

To save you some time, here are the touchscreen settings you will want to use if the screen is rotated 0°, 90°, 180°, or 270°

Download: file
# -------Rotate 0:
ts = adafruit_touchscreen.Touchscreen(board.TOUCH_XL, board.TOUCH_XR,
                                      board.TOUCH_YD, board.TOUCH_YU,
                                      calibration=((5200, 59000), (5800, 57000)),
                                      size=(320, 240))

# -------Rotate 90:
ts = adafruit_touchscreen.Touchscreen(board.TOUCH_YU, board.TOUCH_YD,
                                      board.TOUCH_XL, board.TOUCH_XR, 
                                      calibration=((5200, 59000), (5800, 57000)),
                                      size=(240, 320))

# ------Rotate 180:
ts = adafruit_touchscreen.Touchscreen(board.TOUCH_XR, board.TOUCH_XL,
                                      board.TOUCH_YU, board.TOUCH_YD,
                                      calibration=((5200, 59000), (5800, 57000)),
                                      size=(320, 240))

# ------Rotate 270:
ts = adafruit_touchscreen.Touchscreen(board.TOUCH_YD, board.TOUCH_YU,
                                      board.TOUCH_XR, board.TOUCH_XL,
                                      calibration=((5200, 59000), (5800, 57000)),
                                      size=(240, 320))

Just replace the touchscreen settings with whatever ones you would like to use.

Here is the code you would need to set the PyPortal up in 270° orientation.

Download: file
pyportal = PyPortal()
display = board.DISPLAY
display.rotation = 270
 
# Backlight function
# Value between 0 and 1 where 0 is OFF, 0.5 is 50% and 1 is 100% brightness.
def set_backlight(val):
    val = max(0, min(1.0, val))
    board.DISPLAY.auto_brightness = False
    board.DISPLAY.brightness = val
 
# Set the Backlight
set_backlight(0.3)
 
# Touchscreen setup
# ------Rotate 270:
screen_width = 240
screen_height = 320
ts = adafruit_touchscreen.Touchscreen(board.TOUCH_YD, board.TOUCH_YU,
                                      board.TOUCH_XR, board.TOUCH_XL,
                                      calibration=((5200, 59000),
                                                   (5800, 57000)),
                                      size=(screen_width, screen_height))

Note that we have added PyPortal to the project even though we are not using it for Display, there are some other things that we will use it for later.

For more information about Touchscreen, click the button below.

This guide was first published on Feb 10, 2020. It was last updated on Feb 10, 2020. This page (Display) was last updated on Feb 20, 2020.