From 1fedc038f5cb44415fec661078282b2bc51f9ade Mon Sep 17 00:00:00 2001 From: helgibbons <50950368+helgibbons@users.noreply.github.com> Date: Tue, 19 Jul 2022 14:08:13 +0100 Subject: [PATCH] Update Pico Explorer function reference --- micropython/modules/pico_explorer/README.md | 296 +++++++------------- 1 file changed, 107 insertions(+), 189 deletions(-) diff --git a/micropython/modules/pico_explorer/README.md b/micropython/modules/pico_explorer/README.md index 123189db..f3f9e3c7 100644 --- a/micropython/modules/pico_explorer/README.md +++ b/micropython/modules/pico_explorer/README.md @@ -1,231 +1,115 @@ # 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. +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. It also has a bunch of 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. +[You can buy one here!](https://shop.pimoroni.com/products/pico-explorer-base) -Check out [tonygo2's Explorer Base workout](https://www.instructables.com/Raspberry-Pi-Pico-Pico-Explorer-Workout/) for a comprehensive demo and walk-through of the functions! +The `picoexplorer` module contains constants you can use with our shared libraries to make it easy to draw to the screen and interface with the buttons, piezo buzzer and motor driver. - * [Example Program](#example-program) - * [Function Reference](#function-reference) - + [Display](#display) - - [init](#init) - - [update](#update) - - [set_pen](#set-pen) - - [create_pen](#create-pen) - - [clear](#clear) - - [pixel](#pixel) - - [pixel_span](#pixel-span) - - [rectangle](#rectangle) - - [circle](#circle) - - [character](#character) - - [text](#text) - - [set_clip](#set-clip) - - [remove_clip](#remove-clip) - + [Buttons](#buttons) - - [is_pressed](#is-pressed) - + [ADC](#adc) - - [get_adc](#get-adc) - + [Motors](#motors) - - [set_motor](#set-motor) - + [Audio](#audio) - - [set_audio_pin](#set-audio-pin) - - [set_tone](#set-tone) - + [GPIO](#gpio) +toc goes here -## 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](/micropython/examples/pico_explorer) for more! - -```python -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 +## Board Functions ### 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. +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-ons with a display should be easy to convert to run on Explorer. -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. +- [PicoGraphics MicroPython function reference](https://github.com/pimoroni/pimoroni-pico/tree/main/micropython/modules/picographics) -#### init +Please note that the backlight on Pico Explorer is not dimmable (we needed the pins to hook up other functions) so `set_backlight` won't do anything on this board. -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: +Here's a simple Hello World example that uses PicoGraphics to set up the display and draw some text on the screen. ```python -buf = bytearray(picoexplorer.get_width() * picoexplorer.get_height() * 2) -picoexplorer.init(buf) +from picographics import PicoGraphics, DISPLAY_PICO_EXPLORER + +# Set up the display +display = PicoGraphics(display=DISPLAY_PICO_EXPLORER) + +# Create a pen colour to draw with +WHITE = display.create_pen(255, 255, 255) + +# Choose a font and switch to the white pen +display.set_font("bitmap8") +display.set_pen(WHITE) + +# Display some text +display.text("Hello Explorer", 0, 0, scale=3) + +# Update the screen +display.update() ``` -#### 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 . - -```python -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. - -```python -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. - -```python -pen_colour = picoexplorer.create_pen(r, g, b) -picoexplorer.set_pen(pen_colour) -``` - -#### clear - -Fills the display buffer with the currently set pen colour. - -```python -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. - -```python -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. - -```python -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. - -```python -picoexplorer.rectangle(x, y, w, h) -``` - -![Rectangle function explanation image](/micropython/modules/pico_display/images/rectangle.png) - -#### 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. - -```python -picoexplorer.circle(x, y, r) -``` - -![Circle function explanation image](/micropython/modules/pico_display/images/circle.png) - -#### 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. - -```python -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. - -```python -picoexplorer.text(string, x, y, wrap) -picoexplorer.text(string, x, y, wrap, scale) -``` - -![Text scale explanation image](/micropython/modules/pico_display/images/text_scale.png) - -#### 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. - -```python -picoexplorer.set_clip(x, y, w, h) -``` - -![Clip function explanation image](/micropython/modules/pico_display/images/clip.png) - -#### 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. +The four buttons, A, B, X and Y have corresponding constants set to their respective GPIO pins (12, 13, 14 and 15). They can be read with the shared `pimoroni` module which contains a `Button` class that handles button debounce and auto-repeat. -#### 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. - -```python -picoexplorer.is_pressed(button) +``` +Button(button, invert=True, repeat_time=200, hold_time=1000) ``` -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: +To set up the buttons, first import the `Button` class from the `pimoroni` module and the pin constants from `picoexplorer`: -```python -is_a_button_pressed = picoexplorer.is_pressed(picoexplorer.BUTTON_A) +``` +from pimoroni import Button +import picoexplorer +``` + +Then create instances of `Button` using our constants: + +``` +button_a = Button(picoexplorer.BUTTON_A) +button_b = Button(picoexplorer.BUTTON_B) +button_x = Button(picoexplorer.BUTTON_X) +button_y = Button(picoexplorer.BUTTON_Y) +``` + +To get the button state, call `.read()`. If the button is held down, then this will return `True` at the interval specified by `repeat_time` until `hold_time` is reached, at which point it will return `True` every `repeat_time / 3` milliseconds. This is useful for rapidly increasing/decreasing values: + +``` +state = button_a.read() +``` + +It is also possible to read the raw button state without the repeat feature, if you prefer: + +``` +state = button_a.raw() ``` ### 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`. +Pico Explorer's ADC channels are connected to Pico's ADC-capable pins (26, 27 and 28). You can read the voltages from them using the `Analog` class in the shared `pimoroni` module. -#### get_adc +First import the `Analog` class from the `pimoroni` module and the pin constants from `picoexplorer`: -```python -picoexplorer.get_adc(channel) +``` +from pimoroni import Analog +import pico explorer ``` -The three ADC channels are defined as `0`, `1` and `2`, and should be used with `get_adc`, eg: +Then create instances of `Analog` using our constants: ```python -adc0 = picoexplorer.get_adc(0) + adc0 = Analog(picoexplorer.ADC0) + adc1 = Analog(picoexplorer.ADC1) + adc2 = Analog(picoexplorer.ADC2) ``` -This value can be plugged directly into a motor, eg: +And read them like this ```python -adc0 = picoexplorer.get_adc(0) -picoexplorer.set_motor(1, 1, adc0) +reading = adc0.read_voltage() ``` + + +-- + + + ### Motors -Motors are driven by PWM via an onboard DRV8833. `set_motor` will set the PWM values for the corresponding channel. +Motors are driven by PWM via an onboard DRV8833. We'd recommend using our Motor library to driver them - here's a quick example 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. @@ -300,4 +184,38 @@ 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](https://www.raspberrypi.org/documentation/rp2040/getting-started/#getting-started-with-micropython). \ No newline at end of file +There's lots more info about how to use `machine` in the [Raspberry Pi documentation](https://www.raspberrypi.org/documentation/rp2040/getting-started/#getting-started-with-micropython). + +## Pin Constants + +Here's a list of constants that are available in `picoexplorer`, and the pin numbers that they correspond to on the Pico. + +**Buttons** + +- `BUTTON_A` = `12` +- `BUTTON_B` = `13` +- `BUTTON_X` = `14` +- `BUTTON_Y` = `15` + +**ADC** + +- `ADC0` +- `ADC1` +- `ADC2` + +**Motors** + +- `MOTOR1` +- `MOTOR2` + +**GPIO** + +- `GP0` +- `GP1` +- `GP2` +- `GP3` +- `GP4` +- `GP5` +- `GP6` +- `GP7` +