Add MicroPython function reference for Pico Explorer

2021-03-12 11:03:16 +00:00 · 2021-03-12 11:03:16 +00:00 · c61937adba
commit c61937adba
--- a/micropython/modules/pico_explorer/README.md
+++ b/micropython/modules/pico_explorer/README.md
@ -0,0 +1,303 @@
+# 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).