kopia lustrzana https://github.com/pimoroni/pimoroni-pico
303 wiersze
11 KiB
Markdown
303 wiersze
11 KiB
Markdown
# 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](https://www.instructables.com/Raspberry-Pi-Pico-Pico-Explorer-Workout/) for a comprehensive demo and walk-through of the functions!
|
|
|
|
* [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)
|
|
|
|
## 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
|
|
|
|
### 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:
|
|
|
|
```python
|
|
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 .
|
|
|
|
```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.
|
|
|
|
#### 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)
|
|
```
|
|
|
|
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:
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
picoexplorer.get_adc(channel)
|
|
```
|
|
|
|
The three ADC channels are defined as `0`, `1` and `2`, and should be used with `get_adc`, eg:
|
|
|
|
```python
|
|
adc0 = picoexplorer.get_adc(0)
|
|
```
|
|
|
|
This value can be plugged directly into a motor, eg:
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
picoexplorer.set_tone(frequency)
|
|
```
|
|
|
|
`set_tone` will play an audio tone out of your chosen audio pin.
|
|
|
|
```python
|
|
frequency = 440
|
|
picoexplorer.set_tone(frequency)
|
|
```
|
|
|
|
To make the buzzer be quiet, you can:
|
|
|
|
``` python
|
|
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.
|
|
|
|
```python
|
|
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). |