pimoroni-pico/micropython/modules/pico_explorer

Pico Explorer Base

Pico Explorer Base straps a whole host of physical computing goodies to your Pico - a vibrant 1.14" (240x240) IPS LCD screen, four switches, a piezo buzzer/speaker and a DRV8833 motor driver, as well as handy accessible general purpose inputs and outputs and a built in breadboard.

We've included helper functions to handle drawing to the screen and interfacing with the buttons, piezo and motor driver.

Check out tonygo2's Explorer Base workout for a comprehensive demo and walk-through of the functions!

• Example Program
• Function Reference
  • Display
    • init
    • update
    • set_pen
    • create_pen
    • clear
    • pixel
    • pixel_span
    • rectangle
    • circle
    • character
    • text
    • set_clip
    • remove_clip
  • Buttons
    • is_pressed
  • ADC
    • get_adc
  • Motors
    • set_motor
  • Audio
    • set_audio_pin
    • set_tone
  • GPIO

Example Program

This simple example sets up Pico Explorer, displays some basic demo text and displays a message when the A button is pressed. Check out the examples folder for more!

import utime
import picoexplorer

# Initialise Picoexplorer with a bytearray display buffer
buf = bytearray(picoexplorer.get_width() * picoexplorer.get_height() * 2)
picoexplorer.init(buf)

picoexplorer.set_pen(255, 0, 0)                      # Set a red pen
picoexplorer.clear()                                 # Fill the screen in red
picoexplorer.set_pen(255, 255, 255)                  # Set a white pen
picoexplorer.text("pico explorer", 10, 10, 240, 5)   # Add some text
picoexplorer.update()                                # Update the display with our changes

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

picoexplorer.set_pen(0, 255, 0)                      # Set a green pen
picoexplorer.clear()                                 # Fill the screen in green
picoexplorer.set_pen(0, 0, 0)                        # Set a black pen
picoexplorer.text("button a pushed", 10, 10, 240, 5) # Add some text
picoexplorer.update()                                # Update the display with our changes

Function Reference

Display

Pico Explorer uses a shared Pico Graphics library to draw graphics and text on its screen. As a result, code written for our other Pico add-on boards with a display should be easy to convert to run on Explorer, but make sure to call picoexplorer to get the correct screen dimensions and orientation.

Please note that the backlight on Pico Explorer is not dimmable (we needed the pins to hook up other functions) so there's no set_backlight function for this board.

init

Sets up Pico Explorer. init must be called before any other functions (even if you're not using the screen) 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(picoexplorer.get_width() * picoexplorer.get_height() * 2)
picoexplorer.init(buf)

update

Once you've finished drawing stuff with the functions below, you need to call update to display your changes on Pico Explorer's screen .

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

picoexplorer.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 = picoexplorer.create_pen(r, g, b)
picoexplorer.set_pen(pen_colour)

clear

Fills the display buffer with the currently set pen colour.

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

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

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

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

picoexplorer.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')
picoexplorer.character(char_a, x, y)
picoexplorer.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.

picoexplorer.text(string, x, y, wrap)
picoexplorer.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.

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

remove_clip

This function removes any currently implemented clip.

Buttons

The four buttons, A, B, X and Y have corresponding constants set to their respective GPIO pins.

is_pressed

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

picoexplorer.is_pressed(button)

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

is_a_button_pressed = picoexplorer.is_pressed(picoexplorer.BUTTON_A)

ADC

Pico Explorer's ADC channels are connected to Pico's ADC-capable pins 26, 27 and 28 which correspond to channels 0, 1 and 2 respectively. get_adc will perform a 12-bit ADC read and return the result as a float scaled from 0.0 to 1.0.

get_adc

picoexplorer.get_adc(channel)

The three ADC channels are defined as 0, 1 and 2, and should be used with get_adc, eg:

adc0 = picoexplorer.get_adc(0)

This value can be plugged directly into a motor, eg:

adc0 = picoexplorer.get_adc(0)
picoexplorer.set_motor(1, 1, adc0)

Motors

Motors are driven by PWM via an onboard DRV8833. set_motor will set the PWM values for the corresponding channel.

The red LED next to the motor connectors is part of the motor driver circuit - it will light up if the overvoltage/undervoltage/short circuit auto shutdown functions of the motor driver are triggered. It's not user controllable.

set_motor

picoexplorer.set_motor(channel, action, speed)

Channel should be one of 0 (motor 1) or 1 (motor 2).

Action should be 0 (forwards) or 1 (backwards).

Speed should be given as a number between 0.0 and 1.0, eg:

picoexplorer.set_motor(0, 0, 0.5)    # motor 1 forwards
picoexplorer.set_motor(1, 1, 0.5)    # motor 2 backwards

And to stop the motor:

picoexplorer.set_motor(0, 0, 0)      # motor 1 stop
picoexplorer.set_motor(1, 0, 0)      # motor 2 stop

Audio

To make noise with Explorer, you must first select one of the GP0 to GP7 pins to PWM for audio. You'll then need to connect this pin to AUDIO with a jumper wire.

set_audio_pin

picoexplorer.set_audio_pin(channel)

set_audio_pin configures the PIN that Pico Explorer uses for audio output. It should be one of GP0 through GP7, eg:

picoexplorer.set_audio_pin(0)

This pin must be bridged to the AUDIO pin on the Pico Explorer header in order to drive the onboard Piezo.

set_tone

picoexplorer.set_tone(frequency)

set_tone will play an audio tone out of your chosen audio pin.

frequency = 440
picoexplorer.set_tone(frequency)

To make the buzzer be quiet, you can:

picoexplorer.set_tone(-1)

GPIO

The 8 general purpose IO pins on the lower Pico Explorer are GP0 through GP7. You can use machine to read a pin in the same way as you would if you were using a Pico on its own.

import machine

GP0 = machine.Pin(0, machine.Pin.IN, machine.Pin.PULL_DOWN)

There's lots more info about how to use machine in the Raspberry Pi documentation.