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

# 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).