Update Pico Explorer function reference
This commit is contained in:
helgibbons
parent
ad7121dbdc
commit
1fedc038f5
|
|
@ -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)
|
||||
```
|
||||
|
||||
|
||||
|
||||
#### 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)
|
||||
```
|
||||
|
||||
|
||||
|
||||
#### 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)
|
||||
```
|
||||
|
||||
|
||||
|
||||
#### 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)
|
||||
```
|
||||
|
||||
|
||||
|
||||
#### 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).
|
||||
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`
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue