Skip to content

GitLab

S
st7789_mpy
Commit b4aa060b authored by russhughes's avatar russhughes
Browse files
Options

README.md cleanup

parent f31c12af
Hide whitespace changes
Inline Side-by-side
Showing with 220 additions and 162 deletions
README.md
View file @ b4aa060b
...@@ -7,9 +7,9 @@ I modified the original driver for one of my projects to add: ...@@ -7,9 +7,9 @@ I modified the original driver for one of my projects to add:
- Display Rotation. - Display Rotation.
- Scrolling - Scrolling
- Writing text using bitmaps converted from True Type fonts - Writing text using bitmaps converted from True Type fonts
- Drawing text using 8 and 16 bit wide bitmap fonts - Drawing text using 8 and 16-bit wide bitmap fonts
- Drawing text using Hershey vector fonts - Drawing text using Hershey vector fonts
- Drawing JPG's, including a SLOW mode to draw jpg's larger than available ram - Drawing JPGs, including a SLOW mode to draw jpg's larger than available ram
using the TJpgDec - Tiny JPEG Decompressor R0.01d. from using the TJpgDec - Tiny JPEG Decompressor R0.01d. from
http://elm-chan.org/fsw/tjpgd/00index.html http://elm-chan.org/fsw/tjpgd/00index.html
- Drawing and rotating Polygons and filled Polygons. - Drawing and rotating Polygons and filled Polygons.
...@@ -21,22 +21,33 @@ Hershey vector fonts and several example programs for different devices. ...@@ -21,22 +21,33 @@ Hershey vector fonts and several example programs for different devices.
## Display Configuration ## Display Configuration
Some displays may use a BGR color order or iverted colors. The `cfg_helper.py` program can use used to determine the color order, inversion_mode, colstart, and rowstart values needed for a display. Some displays may use a BGR color order or inverted colors. The `cfg_helper.py`
program can be used to determine the color order, inversion_mode, colstart, and
rowstart values needed for a display.
### Color Modes ### Color Modes
You can test the color order needed by a display by filling the display with the `st7789.RED` color and observing the color displayed. You can test for the correct color order needed by a display by filling it with
- If the display is RED, the settings are correct. the `st7789.RED` color and observing the actual color displayed.
- If the display is BLUE, `color_order` should be `st7789.BGR`.
- If the display is YELLOW, `inversion_mode` should be `True`. - If the displayed color is RED, the settings are correct.
- If the display is CYAN, `color_order` should be `st7789.BGR` and `inversion_mode` should be `True`. - If the displayed color is BLUE, `color_order` should be `st7789.BGR`.
- If the displayed color is YELLOW, `inversion_mode` should be `True.`
- If the displayed color is CYAN, `color_order` should be `st7789.BGR` and
`inversion_mode` should be `True.`
### colstart and rowstart ### colstart and rowstart
Some displays have a frame buffer memory larger than the physical LCD or LED matrix. In these cases the driver must be configured with the position of the first physcial column and row pixels relative to the frame buffer. Each rotation setting of the display may require different colstart and rowstart values. Some displays have a frame buffer memory larger than the physical display
matrix. In these cases, the driver must be configured with the position of the
first physical column and row pixels relative to the frame buffer. Each
rotation setting of the display may require different colstart and rowstart
values.
The driver automatically adjusts the colstart and rowstarts values for common 135x240, 240x240 and The driver automatically sets the `colstart` and `rowstart` values for common
240x320 displays. These values can be overridden using the `offsets` method if the default values do not work for your display. The `offsets` method should be called after any calls of the `rotation` method. 135x240, 240x240 and 240x320 displays. If the default values do not work for
your display, these values can be overridden using the `offsets` method. The
`offsets` method should be called after any `rotation` method calls.
#### 128x128 st7735 cfg_helper.py example #### 128x128 st7735 cfg_helper.py example
...@@ -107,29 +118,32 @@ This is a work in progress. ...@@ -107,29 +118,32 @@ This is a work in progress.
- https://github.com/devbis for the original driver this is based on. - https://github.com/devbis for the original driver this is based on.
- https://github.com/hklang10 for letting me know of the new mp_raise_ValueError(). - https://github.com/hklang10 for letting me know of the new mp_raise_ValueError().
- https://github.com/aleggon for finding the correct offsets for a 240x240 - https://github.com/aleggon for finding the correct offsets for 240x240
display and discovering issues compiling for STM32 based boards. displays and for discovering issues compiling STM32 ports.
-- Russ -- Russ
## Overview ## Overview
This is a driver for MicroPython to handle cheap displays based on the ST7789 This is a driver for MicroPython to handle cheap displays based on the ST7789
chip. chip. The driver is written in C. Firmware is provided for ESP32, ESP32 with SPIRAM,
pyboard1.1, and Raspberry Pi Pico devices.
<p align="center"> <p align="center">
<img src="https://raw.githubusercontent.com/russhughes/st7789_mpy/master/docs/ST7789.jpg" alt="ST7789 display photo"/> <img src="https://raw.githubusercontent.com/russhughes/st7789_mpy/master/docs/ST7789.jpg" alt="ST7789 display photo"/>
</p> </p>
The driver is written in C. Firmware is provided for ESP32, ESP32 with SPIRAM,
pyboard1.1, and Raspberry Pi Pico devices.
# Setup MicroPython Build Environment in Ubuntu 20.04.2 # Setup MicroPython Build Environment in Ubuntu 20.04.2
See the MicroPython [README.md](https://github.com/micropython/micropython/blob/master/ports/esp32/README.md#setting-up-esp-idf-and-the-build-environment) if you run into any build issues not directly related to the st7789 driver. The recommended MicroPython build instructions may have changed. See the MicroPython
[README.md](https://github.com/micropython/micropython/blob/master/ports/esp32/README.md#setting-up-esp-idf-and-the-build-environment)
if you run into any build issues not directly related to the st7789 driver. The
recommended MicroPython build instructions may have changed.
Update and upgrade Ubuntu using apt-get if you are using a new install of Ubuntu or the Windows Subsystem for Linux. Update and upgrade Ubuntu using apt-get if you are using a new install of
Ubuntu or the Windows Subsystem for Linux.
```bash ```bash
sudo apt-get -y update sudo apt-get -y update
...@@ -144,9 +158,12 @@ sudo apt-get -y install build-essential libffi-dev git pkg-config cmake virtuale ...@@ -144,9 +158,12 @@ sudo apt-get -y install build-essential libffi-dev git pkg-config cmake virtuale
### Install a compatible esp-idf SDK ### Install a compatible esp-idf SDK
The MicroPython README.md states: "The ESP-IDF changes quickly and MicroPython only supports certain versions. Currently MicroPython supports v4.0.2, v4.1.1 and v4.2, although other IDF v4 versions may also work." I have had good luck using IDF v4.2. The MicroPython README.md states: "The ESP-IDF changes quickly, and MicroPython
only supports certain versions. Currently, MicroPython supports v4.0.2, v4.1.1,
and v4.2, although other IDF v4 versions may also work." I have had good luck
using IDF v4.2.
Clone the esp-idf SDK repo -- this usually takes several minutes Clone the esp-idf SDK repo -- this usually takes several minutes.
```bash ```bash
git clone -b v4.2 --recursive https://github.com/espressif/esp-idf.git git clone -b v4.2 --recursive https://github.com/espressif/esp-idf.git
...@@ -154,7 +171,8 @@ cd esp-idf/ ...@@ -154,7 +171,8 @@ cd esp-idf/
git pull git pull
``` ```
If you already have a copy of the IDF you can checkout a version compatible with MicroPython and update the submodules using: If you already have a copy of the IDF, you can checkout a version compatible
with MicroPython and update the submodules using:
```bash ```bash
$ cd esp-idf $ cd esp-idf
...@@ -168,7 +186,9 @@ Install the esp-idf SDK. ...@@ -168,7 +186,9 @@ Install the esp-idf SDK.
./install.sh ./install.sh
``` ```
Source the esp-idf export.sh script to set the required environment variables. It's important that you source the file and not run it using ./export.sh. You will need to source this file before compiling MicroPython. Source the esp-idf export.sh script to set the required environment variables.
You must source the file and not run it using ./export.sh. You will need to
source this file before compiling MicroPython.
```bash ```bash
source export.sh source export.sh
...@@ -187,7 +207,7 @@ Clone the st7789 driver repo. ...@@ -187,7 +207,7 @@ Clone the st7789 driver repo.
git clone https://github.com/russhughes/st7789_mpy.git git clone https://github.com/russhughes/st7789_mpy.git
``` ```
Update the git submodules and compile the micropython cross-compiler Update the git submodules and compile the MicroPython cross-compiler
```bash ```bash
cd micropython/ cd micropython/
...@@ -198,7 +218,11 @@ cd .. ...@@ -198,7 +218,11 @@ cd ..
cd ports/esp32 cd ports/esp32
``` ```
Copy any .py files you want to include in the firmware as frozen python modules to the modules subdirectory in ports/esp32. Be aware there is a limit to the flash space available. You will know you have exceeded this limit if you receive an error message saying the code won't fit in the partition or if your firmware continuously reboots with an error. Copy any .py files you want to include in the firmware as frozen python modules
to the modules subdirectory in ports/esp32. Be aware there is a limit to the
flash space available. You will know you have exceeded this limit if you
receive an error message saying the code won't fit in the partition or if your
firmware continuously reboots with an error.
For example: For example:
...@@ -208,26 +232,33 @@ cp ../../../st7789_mpy/fonts/truetype/NotoSans_32.py modules ...@@ -208,26 +232,33 @@ cp ../../../st7789_mpy/fonts/truetype/NotoSans_32.py modules
cp ../../../st7789_mpy/fonts/vector/scripts.py modules cp ../../../st7789_mpy/fonts/vector/scripts.py modules
``` ```
Build the MicroPython firmware with the driver and frozen .py files in the modules directory. If you did not add any .py files to the modules directory you can leave out the FROZEN_MANIFEST and FROZEN_MPY_DIR settings. Build the MicroPython firmware with the driver and frozen .py files in the
modules directory. If you did not add any .py files to the modules directory,
you can leave out the FROZEN_MANIFEST and FROZEN_MPY_DIR settings.
```bash ```bash
make USER_C_MODULES=../../../../st7789_mpy/st7789/micropython.cmake FROZEN_MANIFEST="" FROZEN_MPY_DIR=$UPYDIR/modules make USER_C_MODULES=../../../../st7789_mpy/st7789/micropython.cmake FROZEN_MANIFEST="" FROZEN_MPY_DIR=$UPYDIR/modules
``` ```
Erase and flash the firmware to your device. Set PORT= to the ESP32's usb serial port. I could not get the usb serial port to work under the Windows Subsystem (WSL2) for Linux. If you have the same issue you can copy the firmware.bin file and use the Windows esptool.py to flash your device. Erase and flash the firmware to your device. Set PORT= to the ESP32's usb
serial port. I could not get the USB serial port to work under the Windows
Subsystem (WSL2) for Linux. If you have the same issue, you can copy the
firmware.bin file and use the Windows esptool.py to flash your device.
```bash ```bash
make USER_C_MODULES=../../../../st7789_mpy/st7789/micropython.cmake PORT=/dev/ttyUSB0 erase make USER_C_MODULES=../../../../st7789_mpy/st7789/micropython.cmake PORT=/dev/ttyUSB0 erase
make USER_C_MODULES=../../../../st7789_mpy/st7789/micropython.cmake PORT=/dev/ttyUSB0 deploy make USER_C_MODULES=../../../../st7789_mpy/st7789/micropython.cmake PORT=/dev/ttyUSB0 deploy
``` ```
The firmware.bin file will be in the build-GENERIC directory. To flash using the python esptool.py utility. Use pip3 to install the esptool if it's not already installed. The firmware.bin file will be in the build-GENERIC directory. To flash using
the python esptool.py utility. Use pip3 to install the esptool if it's not
already installed.
```bash ```bash
pip3 install esptool pip3 install esptool
``` ```
Set PORT= to the ESP32's usb serial port Set PORT= to the ESP32's USB serial port
```bash ```bash
esptool.py --port COM3 erase_flash esptool.py --port COM3 erase_flash
...@@ -239,7 +270,7 @@ for ESP32: ...@@ -239,7 +270,7 @@ for ESP32:
$ cd micropython/ports/esp32 $ cd micropython/ports/esp32
And then compile the module with specified USER_C_MODULES dir And then compile the module with specified USER_C_MODULES dir.
$ make USER_C_MODULES=../../../../st7789_mpy/st7789/micropython.cmake $ make USER_C_MODULES=../../../../st7789_mpy/st7789/micropython.cmake
...@@ -247,14 +278,15 @@ for Raspberry Pi PICO: ...@@ -247,14 +278,15 @@ for Raspberry Pi PICO:
$ cd micropython/ports/rp2 $ cd micropython/ports/rp2
And then compile the module with specified USER_C_MODULES dir And then compile the module with specified USER_C_MODULES dir.
$ make USER_C_MODULES=../../../st7789_mpy/st7789/micropython.cmake $ make USER_C_MODULES=../../../st7789_mpy/st7789/micropython.cmake
## Working examples ## Working examples
This module was tested on ESP32, STM32 based pyboard v1.1 and the Raspberry Pi This module was tested on ESP32, STM32 based pyboard v1.1, and the Raspberry Pi
Pico. You have to provide a `SPI` object and the pin to use for the `dc' input of the screen. Pico. You have to provide an `SPI` object and the pin to use for the `dc' input
of the screen.
# ESP32 # ESP32
...@@ -266,7 +298,7 @@ Pico. You have to provide a `SPI` object and the pin to use for the `dc' input o ...@@ -266,7 +298,7 @@ Pico. You have to provide a `SPI` object and the pin to use for the `dc' input o
display.init() display.init()
I was not able to run the display with a baud rate over 40MHZ. I could not run the display with a baud rate over 40MHZ.
## Methods ## Methods
...@@ -278,19 +310,31 @@ I was not able to run the display with a baud rate over 40MHZ. ...@@ -278,19 +310,31 @@ I was not able to run the display with a baud rate over 40MHZ.
- `height` display height - `height` display height
### Required keyword arguments: ### Required keyword arguments:
- `dc` sets the pin connected to the display data/command selection input. This parameter is always required. - `dc` sets the pin connected to the display data/command selection input.
This parameter is always required.
### Optional keyword arguments: ### Optional keyword arguments:
- `reset` sets the pin connected to the displays hardware reset input. If the displays reset pin is tied high the `reset` parameter is not required. - `reset` sets the pin connected to the display's hardware reset input. If
the displays reset pin is tied high, the `reset` parameter is not
required.
- `cs` sets the pin connected to the displays chip select input. If the displays CS pin is tied low, the display must be the only device connected to the SPI port. The display will always be the selected device and the `cs` parameter is not required. - `cs` sets the pin connected to the displays chip select input. If the
display's CS pin is tied low, the display must be the only device
connected to the SPI port. The display will always be the selected
device, and the `cs` parameter is not required.
- `backlight` sets the pin connected to the displays backlight enable input. The displays backlight input can often be left floating or disconnected as the backlight on some displays are always powered on and cannot be turned off. - `backlight` sets the pin connected to the display's backlight enable
input. The display's backlight input can often be left floating or
disconnected as the backlight on some displays is always powered on and
cannot be turned off.
- `rotations` sets the orientation table. The orientation table is a list of tuples for each `rotation` that defines the MADCTL register, width, height, start_x, and start_y values. - `rotations` sets the orientation table. The orientation table is a list
of tuples for each `rotation` that defines the MADCTL register, width,
height, start_x, and start_y values.
Default `rotations` are included for the following st7789 and st7735 display sizes: Default `rotations` are included for the following st7789 and st7735
display sizes:
Display | Default Orientation Tables Display | Default Orientation Tables
------- | -------------------------- ------- | --------------------------
...@@ -301,29 +345,40 @@ I was not able to run the display with a baud rate over 40MHZ. ...@@ -301,29 +345,40 @@ I was not able to run the display with a baud rate over 40MHZ.
128x128 | [(0x00, 128, 128, 2, 1), (0x60, 128, 128, 1, 2), (0xc0, 128, 128, 2, 3), (0xa0, 128, 128, 3, 2)] 128x128 | [(0x00, 128, 128, 2, 1), (0x60, 128, 128, 1, 2), (0xc0, 128, 128, 2, 3), (0xa0, 128, 128, 3, 2)]
other | [(0x00, width, height, 0, 0)] other | [(0x00, width, height, 0, 0)]
You may define as many rotations in the list as you wish. You may define as many rotations as you wish.
- `rotation` sets the display rotation according to the orientation table. The default orientation table defines four counter-clockwise rotations as 0-Portrait (0 degrees), 1- Landscape (90 degrees), 2- Reverse Portrait (180 degrees), and 3- Reverse Landscape (270 degrees) for 240x320, 240x240, 134x240, 128x160 and 128x128 displays with the LCD's ribbon cable at - `rotation` sets the display rotation according to the orientation table.
the bottom of the display. The default rotation being Portrait (0 degrees). The default orientation table defines four counter-clockwise rotations as
0-Portrait (0 degrees), 1- Landscape (90 degrees), 2- Reverse Portrait (180
degrees), and 3- Reverse Landscape (270 degrees) for 240x320, 240x240,
134x240, 128x160 and 128x128 displays with the LCD's ribbon cable at the
bottom of the display. The default rotation is Portrait (0 degrees).
- `color_order` set the color order used by the driver st7789.RGB and st7789.BGR are supported. - `color_order` sets the color order used by the driver (st7789.RGB or st7789.BGR)
- `inversion` Sets the display color inversion mode if True, clears the display color inversion mode if false. - `inversion` Sets the display color inversion mode if True, clears the
display color inversion mode if false.
- `options` Sets driver option flags. - `options` Sets driver option flags.
Option | Description Option | Description
------ | ----------- ------ | -----------
st7789.WRAP | pixels, lines, polygons and Hershey text will wrap around the display both horizontally and vertically. st7789.WRAP | pixels, lines, polygons, and Hershey text will wrap around the display both horizontally and vertically.
st7789.WRAP_H | pixels, lines, polygons and Hershey text will wrap around the display horizontally. st7789.WRAP_H | pixels, lines, polygons, and Hershey text will wrap around the display horizontally.
st7789.WRAP_V | pixels, lines, polygons and Hershey text will wrap around the display vertically. st7789.WRAP_V | pixels, lines, polygons, and Hershey text will wrap around the display vertically.
- `buffer_size` If a buffer_size is not specified a dynamically allocated buffer is created and freed as needed. If a buffer_size is specified it must be large enough to contain the largest bitmap, font character and/or decoded JPG image used (Rows * Columns * 2 bytes, 16bit colors in RGB565 notation). Dynamic allocation is slower and can cause heap fragmentation so garbage collection (GC) should be enabled. - `buffer_size` If a buffer_size is not specified, a dynamically allocated
buffer is created and freed as needed. If a buffer_size is set, it must
be large enough to contain the largest bitmap, font character, and
decoded JPG image used (Rows * Columns * 2 bytes, 16bit colors in RGB565
notation). Dynamic allocation is slower and can cause heap fragmentation,
so garbage collection (GC) should be enabled.
- `inversion_mode(bool)` Sets the display color inversion mode if True, clears the display color inversion mode if False. - `inversion_mode(bool)` Sets the display color inversion mode if True, clears
the display color inversion mode if False.
- `madctl(value)` Returns the current value of the MADCTL register. - `madctl(value)` Returns the current value of the MADCTL register. Optionally
Optionally sets the MADCTL register if a value is passed to the method. sets the MADCTL register if a value is passed to the method.
Constant Name | Value | Description Constant Name | Value | Description
---------------- | ----- | ---------------------- ---------------- | ----- | ----------------------
...@@ -337,7 +392,7 @@ I was not able to run the display with a baud rate over 40MHZ. ...@@ -337,7 +392,7 @@ I was not able to run the display with a baud rate over 40MHZ.
- `init()` - `init()`
Must be called to initalize the display. Must be called to initialize the display.
- `on()` - `on()`
...@@ -363,8 +418,7 @@ I was not able to run the display with a baud rate over 40MHZ. ...@@ -363,8 +418,7 @@ I was not able to run the display with a baud rate over 40MHZ.
- `hline(x, y, length, color)` - `hline(x, y, length, color)`
Draws a single horizontal line with the provided `color` and `length` Draws a single horizontal line with the provided `color` and `length`
in pixels. Along with `vline`, this is a fast version with reduced in pixels. Along with `vline`, this is a fast version with fewer SPI calls.
number of SPI calls.
- `vline(x, y, length, color)` - `vline(x, y, length, color)`
...@@ -386,21 +440,22 @@ I was not able to run the display with a baud rate over 40MHZ. ...@@ -386,21 +440,22 @@ I was not able to run the display with a baud rate over 40MHZ.
- `fill_circle(x, y, r, color)` - `fill_circle(x, y, r, color)`
Draws a filled circle with radius `r` centered at the (`x`, `y`) coordinates in the given `color`. Draws a filled circle with radius `r` centered at the (`x`, `y`) coordinates
in the given `color`.
- `blit_buffer(buffer, x, y, width, height)` - `blit_buffer(buffer, x, y, width, height)`
Copy bytes() or bytearray() content to the screen internal memory. Copy bytes() or bytearray() content to the screen internal memory. Note:
Note: every color requires 2 bytes in the array every color requires 2 bytes in the array
- `text(font, s, x, y[, fg, bg])` - `text(font, s, x, y[, fg, bg])`
Write text to the display using the specified bitmap `font` with the Write text to the display using the specified bitmap `font` with the
coordinates as the upper-left corner of the text. The foreground and coordinates as the upper-left corner of the text. The optional arguments `fg`
background colors of the text can be set by the optional arguments `fg` and and `bg` can set the foreground and background colors of the text; otherwise
`bg`, otherwise the foreground color defaults to `WHITE` and the background the foreground color defaults to `WHITE`, and the background color defaults
color defaults to `BLACK`. See the `README.md` in the `fonts/bitmap` to `BLACK`. See the `README.md` in the `fonts/bitmap` directory for example
directory for example fonts. fonts.
- `write(bitmap_font, s, x, y[, fg, bg, background_tuple, fill_flag])` - `write(bitmap_font, s, x, y[, fg, bg, background_tuple, fill_flag])`
...@@ -411,7 +466,7 @@ I was not able to run the display with a baud rate over 40MHZ. ...@@ -411,7 +466,7 @@ I was not able to run the display with a baud rate over 40MHZ.
and the background color defaults to `BLACK`. and the background color defaults to `BLACK`.
Transparency can be emulated by providing a `background_tuple` containing Transparency can be emulated by providing a `background_tuple` containing
(bitmap_buffer, width, height). This is the same format used by the jpg_decode (bitmap_buffer, width, height). This is the same format used by the jpg_decode
method. See examples/T-DISPLAY/clock/clock.py for an example. method. See examples/T-DISPLAY/clock/clock.py for an example.
See the `README.md` in the `truetype/fonts` directory for example fonts. See the `README.md` in the `truetype/fonts` directory for example fonts.
...@@ -419,40 +474,40 @@ I was not able to run the display with a baud rate over 40MHZ. ...@@ -419,40 +474,40 @@ I was not able to run the display with a baud rate over 40MHZ.
The `font2bitmap` utility creates compatible 1 bit per pixel bitmap modules The `font2bitmap` utility creates compatible 1 bit per pixel bitmap modules
from Proportional or Monospaced True Type fonts. The character size, from Proportional or Monospaced True Type fonts. The character size,
foreground, background colors and the characters to include in the bitmap foreground, background colors, and characters in the bitmap
module may be specified as parameters. Use the -h option for details. If you module may be specified as parameters. Use the -h option for details. If you
specify a buffer_size during the display initialization it must be large specify a buffer_size during the display initialization, it must be large
enough to hold the widest character (HEIGHT * MAX_WIDTH * 2). enough to hold the widest character (HEIGHT * MAX_WIDTH * 2).
- `write_len(bitap_font, s)` - `write_len(bitap_font, s)`
Returns the width of the string in pixels if printed in the specified font. Returns the string's width in pixels if printed in the specified font.
- `draw(vector_font, s, x, y[, fg, scale])` - `draw(vector_font, s, x, y[, fg, scale])`
Draw text to the display using the specified hershey vector font with the Draw text to the display using the specified Hershey vector font with the
coordinates as the lower-left corner of the text. The foreground color of the coordinates as the lower-left corner of the text. The foreground color of the
text can be set by the optional argument `fg`, otherwise the foreground color text can be set by the optional argument `fg`. Otherwise the foreground color
defaults to `WHITE`. The size of the text can be scaled by specifying a defaults to `WHITE`. The size of the text can be scaled by specifying a
`scale` value. The `scale` value must be larger then 0 and can be a floating `scale` value. The `scale` value must be larger than 0 and can be a
point or an integer value. The `scale` value defaults to 1.0. See the floating-point or an integer value. The `scale` value defaults to 1.0. See
README.md in the `vector/fonts` directory for example fonts and the utils the README.md in the `vector/fonts` directory, for example fonts and the
directory for a font conversion program. utils directory for a font conversion program.
- `draw_len(vector_font, s[, scale])` - `draw_len(vector_font, s[, scale])`
Returns the width of the string in pixels if drawn with the specified font. Returns the string's width in pixels if drawn with the specified font.
- `jpg(jpg_filename, x, y [, method])` - `jpg(jpg_filename, x, y [, method])`
Draw JPG file on the display at the given `x` and `y` coordinates as the upper Draw a JPG file on the display at the given `x` and `y` coordinates as the
left corner of the image. There memory required to decode and display a JPG upper left corner of the image. The memory required to decode and display a
can be considerable as a full screen 320x240 JPG would require at least 3100 JPG can be considerable as a full-screen 320x240 JPG would require at least
bytes for the working area + 320 * 240 * 2 bytes of ram to buffer the image. 3100 bytes for the working area + 320 * 240 * 2 bytes of ram to buffer the
Jpg images that would require a buffer larger than available memory can be drawn image. Jpg images that would require a buffer larger than available memory
by passing `SLOW` for method. The `SLOW` method will draw the image a piece can be drawn by passing `SLOW` for the `method`. The `SLOW` `method` will
at a time using the Minimum Coded Unit (MCU, typically a multiple of 8x8) draw the image one piece at a time using the Minimum Coded Unit (MCU,
of the image. typically a multiple of 8x8) of the image.
- `jpg_decode(jpg_filename [, x, y, width, height])` - `jpg_decode(jpg_filename [, x, y, width, height])`
...@@ -460,7 +515,7 @@ I was not able to run the display with a baud rate over 40MHZ. ...@@ -460,7 +515,7 @@ I was not able to run the display with a baud rate over 40MHZ.
(buffer, width, height). The buffer is a color565 blit_buffer compatible byte (buffer, width, height). The buffer is a color565 blit_buffer compatible byte
array. The buffer will require width * height * 2 bytes of memory. array. The buffer will require width * height * 2 bytes of memory.
If the optional x, y, width and height parameters are given the buffer will If the optional x, y, width, and height parameters are given, the buffer will
only contain the specified area of the image. See examples/T-DISPLAY/clock/clock.py only contain the specified area of the image. See examples/T-DISPLAY/clock/clock.py
examples/T-DISPLAY/toasters_jpg/toasters_jpg.py for examples. examples/T-DISPLAY/toasters_jpg/toasters_jpg.py for examples.
...@@ -471,7 +526,7 @@ I was not able to run the display with a baud rate over 40MHZ. ...@@ -471,7 +526,7 @@ I was not able to run the display with a baud rate over 40MHZ.
- `fill_polygon(polygon, x, y, color[, angle, center_x, center_y])` - `fill_polygon(polygon, x, y, color[, angle, center_x, center_y])`
Draw a filled `polygon` at the `x`, `y` coordinates in the `color` given. Draw a filled `polygon` at the `x`, and `y` coordinates in the `color` given.
The polygon may be rotated `angle` radians about the `center_x` and The polygon may be rotated `angle` radians about the `center_x` and
`center_y` point. The polygon should consist of a list of (x, y) tuples `center_y` point. The polygon should consist of a list of (x, y) tuples
forming a closed convex polygon. forming a closed convex polygon.
...@@ -480,51 +535,52 @@ I was not able to run the display with a baud rate over 40MHZ. ...@@ -480,51 +535,52 @@ I was not able to run the display with a baud rate over 40MHZ.
- `polygon(polygon, x, y, color, angle, center_x, center_y)` - `polygon(polygon, x, y, color, angle, center_x, center_y)`
Draw a `polygon` at the `x`, `y` coordinates in the `color` given. The polygon Draw a `polygon` at the `x`, and `y` coordinates in the `color` given. The
may be rotated `angle` radians a bout the `center_x` and `center_y` point. polygon may be rotated `angle` radians about the `center_x` and `center_y`
The polygon should consist of a list of (x, y) tuples forming a closed point. The polygon should consist of a list of (x, y) tuples forming a closed
convex polygon. convex polygon.
See the T-Display `roids.py` for an example. See the T-Display `roids.py` for an example.
- `bounding({status, as_rect})` - `bounding({status, as_rect})`
Bounding turns on and off tracking the area of the display that has been Bounding enables or disables tracking the display area that has been written
written to. Initially tracking is disabled, pass a True value to enable to. Initially, tracking is disabled; pass a True value to enable tracking and
tracking and False to disable. Passing a True or False parameter will reset False to disable it. Passing a True or False parameter will reset the current
the current bounding rectangle to (display_width, display_height, 0, 0). bounding rectangle to (display_width, display_height, 0, 0).
Returns a four integer tuple containing (min_x, min_y, max_x, max_y) indicating Returns a four integer tuple containing (min_x, min_y, max_x, max_y)
the area of the display that has been written to since the last clearing. indicating the area of the display that has been written to since the last
clearing.
If `as_rect` parameter is True, the returned tuple will contain (min_x, min_y, width, height) If `as_rect` parameter is True, the returned tuple will contain (min_x,
values. min_y, width, height) values.
See the TWATCH-2020 `watch.py` demo for an example. See the TWATCH-2020 `watch.py` demo for an example.
- `bitmap(bitmap, x , y [, index])` - `bitmap(bitmap, x , y [, index])`
Draw `bitmap` using the specified `x`, `y` coordinates as the upper-left Draw `bitmap` using the specified `x`, `y` coordinates as the upper-left
corner of the of the `bitmap`. The optional `index` parameter provides a corner of the `bitmap`. The optional `index` parameter provides a method to
method to select from multiple bitmaps contained a `bitmap` module. The select from multiple bitmaps contained a `bitmap` module. The `index` is used
`index` is used to calculate the offset to the beginning of the desired bitmap to calculate the offset to the beginning of the desired bitmap using the
using the modules HEIGHT, WIDTH and BPP values. modules HEIGHT, WIDTH, and BPP values.
The `imgtobitmap.py` utility creates compatible 1 to 8 bit per pixel bitmap modules The `imgtobitmap.py` utility creates compatible 1 to 8 bit per pixel bitmap
from image files using the Pillow Python Imaging Library. modules from image files using the Pillow Python Imaging Library.
The `monofont2bitmap.py` utility creates compatible 1 to 8 bit per pixel The `monofont2bitmap.py` utility creates compatible 1 to 8 bit per pixel
bitmap modules from Monospaced True Type fonts. See the `inconsolata_16.py`, bitmap modules from Monospaced True Type fonts. See the `inconsolata_16.py`,
`inconsolata_32.py` and `inconsolata_64.py` files in the `examples/lib` folder `inconsolata_32.py` and `inconsolata_64.py` files in the `examples/lib`
for sample modules and the `mono_font.py` program for an example using the folder for sample modules and the `mono_font.py` program for an example using
generated modules. the generated modules.
The character sizes, bit per pixel, foreground, background The character sizes, bit per pixel, foreground, background colors, and the
colors and the characters to include in the bitmap module may be specified as characters to include in the bitmap module may be specified as parameters.
parameters. Use the -h option for details. Bits per pixel settings larger than Use the -h option for details. Bits per pixel settings larger than one may be
one may be used to create antialiased characters at the expense of memory use. used to create antialiased characters at the expense of memory use. If you
If you specify a buffer_size during the display initialization it must be specify a buffer_size during the display initialization, it must be large
large enough to hold the one character (HEIGHT * WIDTH * 2). enough to hold the one character (HEIGHT * WIDTH * 2).
- `width()` - `width()`
...@@ -538,18 +594,18 @@ I was not able to run the display with a baud rate over 40MHZ. ...@@ -538,18 +594,18 @@ I was not able to run the display with a baud rate over 40MHZ.
- `rotation(r)` - `rotation(r)`
Set the rotates the logical display in a counter-clockwise direction. 0-Portrait Set the rotates the logical display in a counter-clockwise direction.
(0 degrees), 1-Landscape (90 degrees), 2-Inverse Portrait (180 degrees), 0-Portrait (0 degrees), 1-Landscape (90 degrees), 2-Inverse Portrait (180
3-Inverse Landscape (270 degrees) degrees), 3-Inverse Landscape (270 degrees)
- `offset(x_start, y_start)` The memory in the ST7789 controller is - `offset(x_start, y_start)` The memory in the ST7789 controller is configured
configured for a 240x320 display. When using a smaller display like a for a 240x320 display. When using a smaller display like a 240x240 or
240x240 or 135x240 an offset needs to added to the x and y parameters so 135x240, an offset needs to be added to the x and y parameters so that the
that the pixels are written to the memory area that corresponds to the pixels are written to the memory area corresponding to the visible display.
visible display. The offsets may need to be adjusted when rotating the The offsets may need to be adjusted when rotating the display.
display.
For example, the TTGO-TDisplay is 135x240 and uses the following offsets.
For example the TTGO-TDisplay is 135x240 and uses the following offsets.
| Rotation | x_start | y_start | | Rotation | x_start | y_start |
|----------|---------|---------| |----------|---------|---------|
| 0 | 52 | 40 | | 0 | 52 | 40 |
...@@ -557,15 +613,15 @@ I was not able to run the display with a baud rate over 40MHZ. ...@@ -557,15 +613,15 @@ I was not able to run the display with a baud rate over 40MHZ.
| 2 | 53 | 40 | | 2 | 53 | 40 |
| 3 | 40 | 52 | | 3 | 40 | 52 |
When the rotation method is called the driver will adjust the offsets for a When the rotation method is called, the driver will adjust the offsets for a
135x240 or 240x240 display. Your display may require using different offset 135x240 or 240x240 display. Your display may require using different offset
values, if so, use the `offset` method after `rotation` to set the offset values; if so, use the `offset` method after `rotation` to set the offset
values. values.
The values needed for particular display may not be documented and may The values needed for a particular display may not be documented and may
require some experimentation to determine the correct values. One technique require some experimentation to determine the correct values. One technique
is to draw a box the same size as the display and then make small changes is to draw a box the same size as the display and then make small changes to
to the offsets until the display looks correct. See the `cfg_helper.py` program the offsets until the display looks correct. See the `cfg_helper.py` program
in the examples folder for more information. in the examples folder for more information.
...@@ -574,29 +630,36 @@ The module exposes predefined colors: ...@@ -574,29 +630,36 @@ The module exposes predefined colors:
## Scrolling ## Scrolling
The st7789 display controller contains a 240 by 320-pixel frame buffer used to store the pixels for The st7789 display controller contains a 240 by 320-pixel frame buffer used to
the display. For scrolling, the frame buffer consists of three separate areas; The (`tfa`) top fixed store the pixels for the display. For scrolling, the frame buffer consists of
area, the (`height`) scrolling area, and the (`bfa`) bottom fixed area. The `tfa` is the upper portion of three separate areas; The (`tfa`) top fixed area, the (`height`) scrolling
the frame buffer in pixels not to scroll. The `height` is the center portion of the frame buffer in area, and the (`bfa`) bottom fixed area. The `tfa` is the upper portion of the
pixels to scroll. The `bfa` is the lower portion of the frame buffer in pixels not to scroll. These frame buffer in pixels not to scroll. The `height` is the center portion of the
values control the ability to scroll the entire or a portion of the display. frame buffer in pixels to scroll. The `bfa` is the lower portion of the frame
buffer in pixels not to scroll. These values control the ability to scroll the
Displays that are 320 pixels high, setting the `tfa` to 0, `height` to 320 and `bfa` to 0 will allow entire or a part of the display.
scrolling the entire display. You can set the `tfa` and `bfa` to a non-zero value to scroll a portion of
the display. `tfa` + `height` + `bfa` = should equal 320, otherwise the scrolling mode is undefined. For displays that are 320 pixels high, setting the `tfa` to 0, `height` to 320,
and `bfa` to 0 will allow scrolling of the entire display. You can set the
Displays less than 320 pixels high, the `tfa`, `height`, and `bfa` will need to be adjusted to compensate `tfa` and `bfa` to a non-zero value to scroll a portion of the display. `tfa` +
for the smaller LCD panel. The actual values will vary depending on the configuration of the LCD `height` + `bfa` = should equal 320, otherwise the scrolling mode is undefined.
panel. For example, scrolling the entire 135x240 TTGO T-Display requires a `tfa` value of 40, `height`
value of 240, and `bfa` value of 40 (40+240+40=320) because the T-Display LCD shows 240 rows starting Displays less than 320 pixels high, the `tfa`, `height`, and `bfa` will need to
at the 40th row of the frame buffer, leaving the last 40 rows of the frame buffer undisplayed. be adjusted to compensate for the smaller LCD panel. The actual values will
vary depending on the configuration of the LCD panel. For example, scrolling
Other displays like the Waveshare Pico LCD 1.3 inch 240x240 display require the `tfa` set to 0, `height` the entire 135x240 TTGO T-Display requires a `tfa` value of 40, `height` value
set to 240, and `bfa` set to 80 (0+240+80=320) to scroll the entire display. The Pico LCD 1.3 shows 240 rows of 240, and `bfa` value of 40 (40+240+40=320) because the T-Display LCD shows
starting at the 0th row of the frame buffer, leaving the last 80 rows of the frame buffer undisplayed. 240 rows starting at the 40th row of the frame buffer, leaving the last 40 rows
of the frame buffer undisplayed.
The `vscsad` method sets the (VSSA) Vertical Scroll Start Address. The VSSA sets the line in the
frame buffer that will be the first line after the `tfa`. Other displays like the Waveshare Pico LCD 1.3 inch 240x240 display require the
`tfa` set to 0, `height` set to 240, and `bfa` set to 80 (0+240+80=320) to
scroll the entire display. The Pico LCD 1.3 shows 240 rows starting at the 0th
row of the frame buffer, leaving the last 80 rows of the frame buffer
undisplayed.
The `vscsad` method sets the (VSSA) Vertical Scroll Start Address. The VSSA
sets the line in the frame buffer that will be the first line after the `tfa`.
The ST7789 datasheet warns: The ST7789 datasheet warns:
...@@ -606,18 +669,19 @@ frame buffer that will be the first line after the `tfa`. ...@@ -606,18 +669,19 @@ frame buffer that will be the first line after the `tfa`.
- `vscrdef(tfa, height, bfa)` Set the vertical scrolling parameters. - `vscrdef(tfa, height, bfa)` Set the vertical scrolling parameters.
`tfa` is the top fixed area in pixels. The top fixed area is the upper portion of the display `tfa` is the top fixed area in pixels. The top fixed area is the upper
frame buffer, not scrolled. portion of the display frame buffer that will not be scrolled.
`height` is the total height in pixels of the area scrolled. `height` is the total height in pixels of the area scrolled.
`bfa` is the bottom fixed area in pixels. The bottom fixed area is the lower portion of the `bfa` is the bottom fixed area in pixels. The bottom fixed area is the lower
display frame buffer not scrolled. portion of the display frame buffer that will not be scrolled.
- `vscsad(vssa)` Set the vertical scroll address. - `vscsad(vssa)` Set the vertical scroll address.
`vssa` is the vertical scroll start address in pixels. The vertical scroll start address is the `vssa` is the vertical scroll start address in pixels. The vertical scroll
line in the frame buffer that will be the first line after the TFA. start address is the line in the frame buffer will be the first line shown
after the TFA.
## Helper functions ## Helper functions
...@@ -627,11 +691,5 @@ frame buffer that will be the first line after the `tfa`. ...@@ -627,11 +691,5 @@ frame buffer that will be the first line after the `tfa`.
- `map_bitarray_to_rgb565(bitarray, buffer, width, color=WHITE, bg_color=BLACK)` - `map_bitarray_to_rgb565(bitarray, buffer, width, color=WHITE, bg_color=BLACK)`
Convert a `bitarray` to the rgb565 color `buffer` that is suitable for blitting. Convert a `bitarray` to the rgb565 color `buffer` suitable for blitting. Bit
Bit 1 in `bitarray` is a pixel with `color` and 0 - with `bg_color`. 1 in `bitarray` is a pixel with `color` and 0 - with `bg_color`.
This is a helper with a good performance to print text with a high
resolution font. You can use an awesome tool
https://github.com/peterhinch/micropython-font-to-py
to generate a bitmap fonts from .ttf and use them as a frozen bytecode from
the ROM memory.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment