pimoroni-pico/micropython/modules/pico_display/README.md

Pico Display Pack - MicroPython

Pico Display Pack is a vibrant 1.14", 240 x 135 pixel IPS LCD screen for your Raspberry Pi Pico, with four useful buttons and a RGB LED. Buy one here!

We've included helper functions to handle every aspect of drawing to the screen and interfacing with the buttons and LED. See the function reference for details. Scroll down to the bottom for links to more resources!

• Example Program
• Function Reference
  • init
  • set_backlight
  • set_led
  • is_pressed
  • update
  • set_pen
  • create_pen
  • clear
  • pixel
  • pixel_span
  • rectangle
  • circle
  • character
  • text
  • set_clip
  • remove_clip
• More Resources

Example Program

The following example sets up Pico Display, displays some basic demo text and illuminates the RGB LED green when the A button is pressed.

import utime
import picodisplay

# Initialise Picodisplay with a bytearray display buffer
buf = bytearray(picodisplay.get_width() * picodisplay.get_height() * 2)
picodisplay.init(buf)
picodisplay.set_backlight(1.0)

picodisplay.set_pen(255, 0, 0)                    # Set a red pen
picodisplay.clear()                               # Clear the display buffer
picodisplay.set_pen(255, 255, 255)                # Set a white pen
picodisplay.text("pico display", 10, 10, 240, 6)  # Add some text
picodisplay.update()                              # Update the display with our changes

picodisplay.set_led(255, 0, 0)   # Set the RGB LED to red
utime.sleep(1)                   # Wait for a second
picodisplay.set_led(0, 255, 0)   # Set the RGB LED to green
utime.sleep(1)                   # Wait for a second
picodisplay.set_led(0, 0, 255)   # Set the RGB LED to blue

while picodisplay.is_pressed(picodisplay.BUTTON_A) == False:
    pass

picodisplay.set_led(0, 255, 0)  # Set the RGB LED to green

Function Reference

init

Sets up Pico Display. init must be called before any other functions since it configures the required PWM and GPIO. init() needs a bytearray type display buffer that MicroPython's garbage collection isn't going to eat, make sure you create one and pass it in like so:

buf = bytearray(picodisplay.get_width() * picodisplay.get_height() * 2)
picodisplay.init(buf)

set_backlight

Sets the display backlight from 0.0 to 1.0.

picodisplay.set_backlight(brightness)

Uses hardware PWM to dim the display backlight, dimming values are gamma-corrected to provide smooth brightness transitions across the full range of intensity. This may result in some low values mapping as "off."

set_led

Sets the RGB LED on Pico Display with an RGB triplet.

picodisplay.set_led(r, g, b)

Uses hardware PWM to drive the LED. Values are automatically gamma-corrected to provide smooth brightness transitions and low values may map as "off."

is_pressed

Reads the GPIO pin connected to one of Pico Display's buttons, returning True if it's pressed and False if it is released.

picodisplay.is_pressed(button)

The button value should be a number denoting a pin, and constants picodisplay.BUTTON_A, picodisplay.BUTTON_B, picodisplay.BUTTON_X and picodisplay.BUTTON_Y are supplied to make it easier. e:

is_a_button_pressed = picodisplay.is_pressed(picodisplay.BUTTON_A)

update

To display your changes on Pico Display's screen you need to call update.

picodisplay.update()

set_pen

Sets the colour to be used by subsequent calls to drawing functions. The values for r, g and b should be from 0-255 inclusive.

picodisplay.set_pen(r, g, b)

create_pen

Creates a pen which can be stored as a variable for faster re-use of the same colour through calls to set_pen. The values for r, g and b should be from 0-255 inclusive.

pen_colour = picodisplay.create_pen(r, g, b)
picodisplay.set_pen(penColour)

clear

Fills the display buffer with the currently set pen colour.

picodisplay.clear()

pixel

Sets a single pixel in the display buffer to the current pen colour. The x and y parameters determine the X and Y coordinates of the drawn pixel in the buffer.

picodisplay.pixel(x, y)

pixel_span

Draws a horizontal line of pixels to the buffer. The x and y parameters specify the coordinates of the first pixel of the line. The l parameter describes the length of the line in pixels. This function will only extend the line towards the end of the screen, i.e. the x coordinate should specify the left hand extreme of the line.

picodisplay.pixel_span(x, y, l)

rectangle

Draws a rectangle filled with the current pen colour to the buffer. The x and y parameters specify the upper left corner of the rectangle, w specifies the width in pixels, and h the height.

picodisplay.rectangle(x, y, w, h)

circle

Draws a circle filled with the current pen colour to the buffer. The x and y parameters specify the centre of the circle, r specifies the radius in pixels.

picodisplay.circle(x, y, r)

character

Draws a single character to the display buffer in the current pen colour. The c parameter should be the ASCII numerical representation of the character to be printed, x and y describe the top-left corner of the character's drawing field. The character function can also be given an optional 4th parameter, scale, describing the scale of the character to be drawn. Default value is 2.

char_a = ord('a')
picodisplay.character(char_a, x, y)
picodisplay.character(char_a, x, y, scale)

text

Draws a string of text to the display buffer in the current pen colour. The string parameter is the string of text to be drawn, and x and y specify the upper left corner of the drawing field. The wrap parameter describes the width, in pixels, after which the next word in the string will be drawn on a new line underneath the current text. This will wrap the string over multiple lines if required. This function also has an optional parameter, scale, which describes the size of the characters to be drawn. The default scale is 2.

picodisplay.text(string, x, y, wrap)
picodisplay.text(string, x, y, wrap, scale)

set_clip

This function defines a rectangular area outside which no drawing actions will take effect. If a drawing action crosses the boundary of the clip then only the pixels inside the clip will be drawn. Note that clip does not remove pixels which have already been drawn, it only prevents new pixels being drawn outside the described area. A more visual description of the function of clips can be found below. Only one clip can be active at a time, and defining a new clip replaces any previous clips. The x and y parameters describe the upper-left corner of the clip area, w and h describe the width and height in pixels.

picodisplay.set_clip(x, y, w, h)

remove_clip

This function removes any currently implemented clip.

More Resources

• Display Pack Guide by UnfinishedStuff - more detail on functions and code examples
• Display Pack Workout by tonygo2 - a comprehensive demo
• picofont by Les Wright - implementing custom fonts using pure MicroPython