RM67162 SPI Driver for MicroPython

This driver is a modified version of nspsck st7735s_WeAct_Studio_TFT_port driver. Which is again a modified version of russhughes' st7789_mpy driver. All credits goes to russhughes for his amazing drivers and nspck for his support!

I modified the driver to specifically support displays with RM67162 controllers that only have SPI connection. We successfully tested it with this great Display of DWO: DO0200PFS01.

For RM67162 Displays with QSPI (quad SPI) check out this driver:RM67162_Micropython_QSPI

So far I have only tested it on ESP32-S3 variants. I use the hardware SPI 2 for my project.

ESP32S3        -->    RM67162 SPI (in some displays documentation/datasheets this is refered as SPI 4 Wire)
3V3            -->    VCC,VBAT
GND            -->    GND
mosi=Pin40     -->    DIN
sck=Pin39      -->    CLK
cs=Pin45       -->    CS
dc=Pin46       -->    D/C
reset=Pin42    -->    RST
backlight=Pin47-->    Not connected (assign unused GPIO)

This display sets the backlight via SPI but for the driver to work you need to assing a random unused pin for backlight. The reverse_backlight option does therefore nothing.

I added a brightness function, this controls the displays brightness level. It accepts an integer between 0 (=off) to 100 (100% brightness). The driver is still called st7789, I will refactor it in the future.

Hardware Scrolling is not supported by the RM67161 Chip. Therefore the functions vscsad() and vscrdef() do nothing.

This driver supports all the features the original has. Please also read Updates.

How to use:

You have to compile the driver as a usercmodule for your micropython port.

For compile instruction see:

• https://github.com/gampam2000/RM67162_Micropyton_SPI?tab=readme-ov-file#setup-micropython-build-environment-in-ubuntu-20042
• https://github.com/micropython/micropython/tree/master/ports/esp32#building-the-firmware
• https://docs.micropython.org/en/latest/develop/cmodules.html

In general, the screen starts at 0 and goes to 535 x 239, that's a total resolution of 536 x 240. All drawing functions should be called with this in mind.

from machine import Pin, SPI
import st7789
import vga2_16x16 as font
import time

oled = st7789.ST7789(
    SPI(2, baudrate=40000000, sck=Pin(39), mosi=Pin(40), miso=None),
    240,
    536,
    reset=Pin(42, Pin.OUT),
    cs=Pin(45, Pin.OUT),
    dc=Pin(46, Pin.OUT),
    backlight=Pin(47, Pin.OUT),
    rotations=[(0x00, 240, 536, 0, 0), (0x60, 536, 240, 0, 0), (0xc0, 240, 536, 0, 0), (0xa0, 536, 240, 0, 0)],
    rotation=1,
    options=0,
    inversion=False,
    color_order=st7789.RGB,
    use_drawbuffer=True,
    )

oled.init()
oled.fill(st7789.YELLOW)

text="Test OLED"
length = len(text)

oled.text(
    font,
    text,
    0,
    0,
    st7789.BLACK,
    st7789.RED)

oled.fill_circle(400,60,50,st7789.MAGENTA)
oled.fill_circle(400,60,20,st7789.BLACK)

#Test brightness:
for i in range(-1,101):
    oled.brightness(i)
    time.sleep_ms(200)

Updates

• Added brightness function
• Added RM67162 support

Original Documentation

• Added an Option for you to use a static framebuffer for drawing. This can improve the performance in some cases (1 - 60%, i.e. repiditively bitmapping, drawing fucntions for a large area, etc.) at the cost of, as you expect, RAM. You can use it in the constructor like so: The buffer should not be used togather with the buffer_size option. If only the buffer_size option is used and this option is not enabled, you can not profit from the faster drawing functions. If this option is enabled, a buffer of size display->height * display-> width * 2 Bytes will be allocated, hence buffer_size and its related i2c_buffer will not have any effects but eating more RAM. Sometimes, the display's resolution is too high, so if the drawbuffer allocation fails, you can also jump back to the buffer_size option.

Firmware-updates

Note: all firwares are compiled with the most recent micropython build at the time, if you want another version of micropython, please build it yourself following the build instruction provided below.

• add BlackPill (no SPI-Flash version) firmwares. .hex, .dfu and .bin file available. Flashing guide please view here. Building guide (as USER_C_MODULES for the stm32 port) also view above.
• rp2040 only: added the POV module as a built-in module to control core voltage. For details please visit: RP2040_Micropython_voltage_control.
• esp32 and rp2: added a drawbuffer for more stable, sometimes faster drawing. All other buffer related operations will no longer need to collect RAM if this option is enabled, hence improved performance.
• now suppports all display supported by the original driver by default. Set reversed_backlight to True to use "pull down displays".
• minor improvements on circle and fill_circle. (1-5% more performance depending on the situation)
• added firmwares compiled with the newest micropython version. (added 2 new functions: fill_bubble_rect, bubble_rect)

How to use the new firmwares on ESP32

For esp32c3 and esp32s3, the bootloader.bin starts from 0x0.

esptool.py --chip esp32c3 --port PORT_TO_YOUR_DEVICE --baud 460800 write_flash -z 0x0 .\bootloader.bin 0x8000 .\partition-table.bin 0x10000 .\micropython.bin

For esp32 and esp32s2, the bootloader.bin starts from 0x1000.

esptool.py --chip esp32s2 --port PORT_TO_YOUR_DEVICE --baud 460800 write_flash -z 0x1000 .\bootloader.bin 0x8000 .\partition-table.bin 0x10000 .\micropython.bin

Display Configuration

Some displays may use a BGR color order or inverted colors. The cfg_helper.py program located in the examples can be used to determine the color order, inversion_mode, colstart, and rowstart values needed for a display.

Color Modes

You can test for the correct color order needed by a display by filling it with the st7789.RED color and observing the actual color displayed.

• If the displayed color is RED, the settings are correct.
• 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

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 sets the colstart and rowstart values for common 135x240, 240x240, 170x320 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

inversion_mode(False)
color_order = st7789.BGR
for rotation 0 use offset(2, 1)
for rotation 1 use offset(1, 2)
for rotation 2 use offset(2, 3)
for rotation 3 use offset(3, 2)

128x160 st7735 cfg_helper.py example

inversion_mode(False)
color_order = st7789.RGB
for rotation 0 use offset(0, 0)
for rotation 1 use offset(0, 0)
for rotation 2 use offset(0, 0)
for rotation 3 use offset(0, 0)

Pre-compiled firmware files

The firmware directory contains pre-compiled firmware for various devices with the st7789 C driver and frozen python font files. The BLACKPILL firmware is rolled separately than the other versions and has fewer fonts built-in due to limited sotrage space.

MicroPython v1.21.0+ compiled with ESP IDF v5.0.2 using CMake

Directory	File	Device
ESP32_GENERIC	micropython.bin	Generic ESP32 devices
ESP32_GENERIC-SPIRAM	micropython.bin	Generic ESP32 devices with SPI Ram
ESP32_GENERIC_S2	micropython.bin	Generic ESP32S3 devices
ESP32_GENERIC_S3	micropython.bin	Generic ESP32S3 devices
ESP32_GENERIC_S3-SPIRAM	micropython.bin	Generic ESP32S3 devices with SPI Ram
ESP32_GENERIC_S3-SPIRAM_OCT	micropython.bin	Generic ESP32S3 devices with Octal-SPI Ram
ESP32_GENERIC_C3	micropython.bin	Generic ESP32-C3 devices
LOLIN_S2_MINI	micropython.bin	Wemos S2 mini
Arduino_NANO_RP2040	firmware.uf2	Arduino nano RP2040 Connect
RP2	firmware.uf2	Raspberry Pi Pico RP2040
RP2W	firmware.uf2	Raspberry Pi PicoW RP2040
WEACTSTUDIO	firmware.uf2	RP2040 by WEACTSTUDIO (16MB)
BLACKPILL	firmware.hex	BlackPill by WEACTSTUDIO (No SPI-Flash)

Built-in fonts:

For BLACKPILL:

NotoSans_32.py   astrol.py      vga1_16x32.py  vga1_8x8.py         vga1_bold_16x32.py
NotoSerif_32.py  vga1_16x16.py  vga1_8x16.py   vga1_bold_16x16.py

For the others:

NotoSansMono_32.py     vga1_8x8.py       vga2_16x32.py       vga2_bold_16x32.py
NotoSans_32.py         astrol.py         vga1_16x16.py       vga1_bold_16x16.py         
NotoSerif_32.py        vga1_16x32.py     vga1_bold_16x32.py  vga2_8x8.py         
vga2_8x16.py           vga1_8x16.py      vga2_16x16.py       vga2_bold_16x16.py

Additional Modules

Module	Source
axp202c	https://github.com/lewisxhe/AXP202X_Libraries
focaltouch	https://gitlab.com/mooond/t-watch2020-esp32-with-micropython

Video Examples

Example	Video
PYBV11 hello.py	https://youtu.be/OtcERmad5ps
PYBV11 scroll.py	https://youtu.be/ro13rvaLKAc
T-DISPLAY fonts.py	https://youtu.be/2cnAhEucPD4
T-DISPLAY hello.py	https://youtu.be/z41Du4GDMSY
T-DISPLAY scroll.py	https://youtu.be/GQa-RzHLBak
T-DISPLAY roids.py	https://youtu.be/JV5fPactSPU
TWATCH-2020 draw.py	https://youtu.be/O_lDBnvH1Sw
TWATCH-2020 hello.py	https://youtu.be/Bwq39tuMoY4
TWATCH-2020 bitmap.py	https://youtu.be/DgYzgnAW2d8
TWATCH-2020 watch.py	https://youtu.be/NItKb6umMc4

This is a work in progress.

Thanks go out to:

• 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/aleggon for finding the correct offsets for 240x240 displays and for discovering issues compiling STM32 ports.

-- Russ

And am thankful to everyone metioned above and those who contributed to this project in any form!

Overview

This is a driver for MicroPython to handle cheap displays based on the ST7789 chip. 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

See the MicroPython README.md 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.

sudo apt-get -y update
sudo apt-get -y upgrade

Use apt-get to install the required build tools.

sudo apt-get -y install build-essential libffi-dev git pkg-config cmake virtualenv python3-pip python3-virtualenv

Install a compatible esp-idf SDK

Currently, MicroPython supports only v5.0.2 version of esp-idf. Well, at least I had no luck with any other versions. So I suggest you use the v5.0.2 version too.

Clone the esp-idf SDK repo -- this usually takes several minutes.

git clone -b v5.0.2 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf/
git pull

If you already have a copy of the IDF, you can checkout a version compatible with MicroPython and update the submodules using:

$ cd esp-idf
$ git checkout v5.0.2
$ git submodule update --init --recursive

Install the esp-idf SDK.

./install.sh

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.

source export.sh
cd ..

Clone the MicroPython repo.

git clone https://github.com/micropython/micropython.git

Clone the st7789 driver repo.

git clone https://github.com/nspsck/st7735s_WeAct_Studio_TFT_port.git

Update the git submodules and compile the MicroPython cross-compiler

cd micropython/
git submodule update --init
cd mpy-cross/
make
cd ..
cd ports/esp32
make submodules

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:

cp ../../../st7735s_WeAct_Studio_TFT_port/fonts/bitmap/vga1_16x16.py modules
cp ../../../st7735s_WeAct_Studio_TFT_port/fonts/truetype/NotoSans_32.py modules
cp ../../../st7735s_WeAct_Studio_TFT_port/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.

make USER_C_MODULES=../../../../st7735s_WeAct_Studio_TFT_port/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.

make USER_C_MODULES=../../../../st7735s_WeAct_Studio_TFT_port/st7789/micropython.cmake PORT=/dev/ttyUSB0 erase
make USER_C_MODULES=../../../../st7735s_WeAct_Studio_TFT_port/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.

pip3 install esptool

Set PORT= to the ESP32's USB serial port

esptool.py --port COM3 erase_flash
esptool.py --chip esp32 --port COM3 write_flash -z 0x1000 firmware.bin

CMake building instructions for MicroPython 1.14 and later

for ESP32:

$ cd micropython/ports/esp32

And then compile the module with specified USER_C_MODULES dir.

$ make USER_C_MODULES=../../../../st7735s_WeAct_Studio_TFT_port/st7789/micropython.cmake

for Raspberry Pi PICO:

$ cd micropython/ports/rp2

And then compile the module with specified USER_C_MODULES dir.

$ make USER_C_MODULES=../../../st7735s_WeAct_Studio_TFT_port/st7789/micropython.cmake

Working examples

This module was tested on ESP32, STM32 based pyboard v1.1, and the Raspberry Pi Pico. You have to provide an SPI object and the pin to use for the `dc' input of the screen.

# ESP32 Example
# To use baudrates above 26.6MHz you must use my firmware or modify the micropython
# source code to increase the SPI baudrate limit by adding SPI_DEVICE_NO_DUMMY to the
# .flag member of the spi_device_interface_config_t struct in the machine_hw_spi_init_internal.c
# file.  Not doing so will cause the ESP32 to crash if you use a baudrate that is too high.

import machine
import st7789
spi = machine.SPI(2, baudrate=40000000, polarity=1, sck=machine.Pin(18), mosi=machine.Pin(23))
display = st7789.ST7789(spi, 240, 240, reset=machine.Pin(4, machine.Pin.OUT), dc=machine.Pin(2, machine.Pin.OUT))
display.init()

Methods

• st7789.ST7789(spi, width, height, dc, reset, cs, backlight, rotations, rotation, custom_init, color_order, inversion, options, buffer_size)

  Required positional arguments:

  • spi spi device
  • width display width
  • height display height

  Required keyword arguments:

  • dc sets the pin connected to the display data/command selection input. This parameter is always required.

  Optional keyword arguments:

  • 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 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 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 used to set the MADCTL register, display width, display height, start_x, and start_y values.

    Default rotations are included for the following st7789 and st7735 display sizes:

    Display	Default Orientation Tables
    240x320	[(0x00, 240, 320, 0, 0), (0x60, 320, 240, 0, 0), (0xc0, 240, 320, 0, 0), (0xa0, 320, 240, 0, 0)]
    170x320	[(0x00, 170, 320, 35, 0), (0x60, 320, 170, 0, 35), (0xc0, 170, 320, 35, 0), (0xa0, 320, 170, 0, 35)]
    240x240	[(0x00, 240, 240, 0, 0), (0x60, 240, 240, 0, 0), (0xc0, 240, 240, 0, 80), (0xa0, 240, 240, 80, 0)]
    135x240	[(0x00, 135, 240, 52, 40), (0x60, 240, 135, 40, 53), (0xc0, 135, 240, 53, 40), (0xa0, 240, 135, 40, 52)]
    128x160	[(0x00, 128, 160, 0, 0), (0x60, 160, 128, 0, 0), (0xc0, 128, 160, 0, 0), (0xa0, 160, 128, 0, 0)]
    132x162	[(0x00, 132, 162, 0, 0), (0x60, 162, 132, 0, 0), (0xc0, 132, 162, 0, 0), (0xa0, 162, 132, 0, 0)]
    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)]

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

    Index	Rotation
    0	Portrait (0 degrees)
    1	Landscape (90 degrees)
    2	Reverse Portrait (180 degrees)
    3	Reverse Landscape (270 degrees)

  • custom_init List of display configuration commands to send to the display during the display init(). The list contains tuples with a bytes object, optionally followed by a delay specified in ms. The first byte of the bytes object contains the command to send optionally followed by data bytes. See the examples/configs/t_dongle_s3/tft_config.py file or an example.

  • 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.

  • options Sets driver option flags.

    Option	Description
    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_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 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.

• madctl(value) Returns the current value of the MADCTL register or sets the MADCTL register if a value is passed to the method. The MADCTL register is used to set the display rotation and color order.

  MADCTL constants

  Constant Name	Value	Description
  st7789.MADCTL_MY	0x80	Page Address Order
  st7789_MADCTL_MX	0x40	Column Address Order
  st7789_MADCTL_MV	0x20	Page/Column Order
  st7789_MADCTL_ML	0x10	Line Address Order
  st7789_MADCTL_MH	0x04	Display Data Latch Order
  st7789_RGB	0x00	RGB color order
  st7789_BGR	0x08	BGR color order

  MADCTL examples

  Orientation	MADCTL Values for RGB color order, for BGR color order add 0x08 to the value.
  	0x00
  	0x80 ( MADCTL_MY )
  	0x40 ( MADCTL_MX )
  	0xC0 ( MADCTL_MX + MADCTL_MY )
  	0x20 ( MADCTL_MV )
  	0xA0 ( MADCTL_MV + MADCTL_MY )
  	0x60 ( MADCTL_MV + MADCTL_MX )
  	0xE0 ( MADCTL_MV + MADCTL_MX + MADCTL_MY )

• init()

  Must be called to initialize the display.

• on()

  Turn on the backlight pin if one was defined during init.

• off()

  Turn off the backlight pin if one was defined during init.

• sleep_mode(value)

  If value is True, cause the display to enter sleep mode, otherwise wake up if value is False. During sleep display content may not be preserved.

  Changed: backlight will also be turned off and on, if you wish to keep the backlight on or off, please call on() or off() accordingly.

• fill(color)

  Fill the display with the specified color.

• pixel(x, y, color)

  Set the specified pixel to the given color.

• line(x0, y0, x1, y1, color)

  Draws a single line with the provided color from (x0, y0) to (x1, y1).

• hline(x, y, length, color)

  Draws a single horizontal line with the provided color and length in pixels. Along with vline, this is a fast version with fewer SPI calls.

• vline(x, y, length, color)

  Draws a single horizontal line with the provided color and length in pixels.

• rect(x, y, width, height, color)

  Draws a rectangle from (x, y) with corresponding dimensions

• fill_rect(x, y, width, height, color)

  Fill a rectangle starting from (x, y) coordinates

  • bubble_rect(x, y, width, height, color)

  Draw a pop-up message box style box starting from (x, y) coordinates

  • fill_bubble_rect(x, y, width, height, color)

  Fill a a pop-up message box style box starting from (x, y) coordinates

• circle(x, y, r, color)

  Draws a circle with radius r centered at the (x, y) coordinates in the given color.

• fill_circle(x, y, r, 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)

  Copy bytes() or bytearray() content to the screen internal memory. Note: every color requires 2 bytes in the array

• text(font, s, x, y[, fg, bg])

  Write s (integer, string or bytes) to the display using the specified bitmap font with the coordinates as the upper-left corner of the text. The optional arguments fg and bg can set the foreground and background colors of the text; otherwise the foreground color defaults to WHITE, and the background color defaults to BLACK. See the README.md in the fonts/bitmap directory for example fonts.

• write(bitmap_font, s, x, y[, fg, bg, background_tuple, fill_flag])

  Write text to the display using the specified proportional or Monospace bitmap font module with the coordinates as the upper-left corner of the text. The foreground and background colors of the text can be set by the optional arguments fg and bg, otherwise the foreground color defaults to WHITE and the background color defaults to BLACK.

  Transparency can be emulated by providing a background_tuple containing (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.

  See the README.md in the truetype/fonts directory for example fonts. Returns the width of the string as printed in pixels. Accepts UTF8 encoded strings.

  The font2bitmap utility creates compatible 1 bit per pixel bitmap modules from Proportional or Monospaced True Type fonts. The character size, foreground, background colors, and characters in the bitmap 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 enough to hold the widest character (HEIGHT * MAX_WIDTH * 2).

• write_len(bitap_font, s)

  Returns the string's width in pixels if printed in the specified font.

• draw(vector_font, s, x, y[, fg, scale])

  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 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 scale value. The scale value must be larger than 0 and can be a floating-point or an integer value. The scale value defaults to 1.0. See the README.md in the vector/fonts directory, for example fonts and the utils directory for a font conversion program.

• draw_len(vector_font, s[, scale])

  Returns the string's width in pixels if drawn with the specified font.

• jpg(jpg, x, y [, method])

  Draw a jpg on the display with the given x and y coordinates as the upper left corner of the image. jpg may be a string containing a filename or a buffer containing the JPEG image data.

  The memory required to decode and display a JPG can be considerable as a full-screen 320x240 JPG would require at least 3100 bytes for the working area + 320 * 240 * 2 bytes of ram to buffer the image. Jpg images that would require a buffer larger than available memory can be drawn by passing SLOW for the method. The SLOW method will draw the image one piece at a time using the Minimum Coded Unit (MCU, typically a multiple of 8x8) of the image. The default method is FAST.

• jpg_decode(jpg_filename [, x, y, width, height])

  Decode a jpg file and return it or a portion of it as a tuple composed of (buffer, width, height). The buffer is a color565 blit_buffer compatible byte 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 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.

• png(png_filename, x, y [, mask])

  Draw a PNG file on the display with upper left corner of the image at the given x and y coordinates. The PNG will be clipped if it is not able to fit fully on the display. The PNG will be drawn one line at a time. Since the driver does not contain a frame buffer, transparency is not supported. Providing a True value for the mask parameter will prevent pixels with a zero alpha channel value from being displayed. Drawing masked PNG's is slower than non-masked as each visible line segment is drawn separately. For an example of using a mask, see the alien.py program in the examples/png folder.

• polygon_center(polygon)

  Return the center of the polygon as an (x, y) tuple. The polygon should consist of a list of (x, y) tuples forming a closed convex polygon.

• fill_polygon(polygon, x, y, color[, angle, center_x, center_y])

  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 center_y point. The polygon should consist of a list of (x, y) tuples forming a closed convex polygon.

  See the TWATCH-2020 watch.py demo for an example.

• polygon(polygon, x, y, color, angle, center_x, center_y)

  Draw a polygon at the x, and y coordinates in the color given. 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 forming a closed convex polygon.

  See the T-Display roids.py for an example.

• bounding({status, as_rect})

  Bounding enables or disables tracking the display area that has been written to. Initially, tracking is disabled; pass a True value to enable tracking and False to disable it. Passing a True or False parameter will reset the current bounding rectangle to (display_width, display_height, 0, 0).

  Returns a four integer tuple containing (min_x, min_y, max_x, max_y) 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) values.

  See the TWATCH-2020 watch.py demo for an example.

• bitmap(bitmap, x , y [, index])

  Draw bitmap using the specified x, y coordinates as the upper-left corner of the bitmap. The optional index parameter provides a method to select from multiple bitmaps contained a bitmap module. The index is used to calculate the offset to the beginning of the desired bitmap using the modules HEIGHT, WIDTH, and BPP values.

  The imgtobitmap.py utility creates compatible 1 to 8 bit per pixel bitmap modules from image files using the Pillow Python Imaging Library.

  The monofont2bitmap.py utility creates compatible 1 to 8 bit per pixel 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 for sample modules and the mono_font.py program for an example using the generated modules.

  The character sizes, bit per pixel, foreground, background colors, and the characters to include in the bitmap module may be specified as parameters. Use the -h option for details. Bits per pixel settings larger than one may be used to create antialiased characters at the expense of memory use. If you specify a buffer_size during the display initialization, it must be large enough to hold the one character (HEIGHT * WIDTH * 2).

• width()

  Returns the current logical width of the display. (ie a 135x240 display rotated 90 degrees is 240 pixels wide)

• height()

  Returns the current logical height of the display. (ie a 135x240 display rotated 90 degrees is 135 pixels high)

• rotation(r)

  Set the rotates the logical display in a counter-clockwise direction. 0-Portrait (0 degrees), 1-Landscape (90 degrees), 2-Inverse Portrait (180 degrees), 3-Inverse Landscape (270 degrees)

• offset(x_start, y_start) The memory in the ST7789 controller is configured for a 240x320 display. When using a smaller display like a 240x240 or 135x240, an offset needs to be added to the x and y parameters so that the pixels are written to the memory area corresponding to the visible display. The offsets may need to be adjusted when rotating the display.

  For example, the TTGO-TDisplay is 135x240 and uses the following offsets.

  Rotation	x_start	y_start
  0	52	40
  1	40	53
  2	53	40
  3	40	52

  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 values; if so, use the offset method after rotation to set the offset values.

  The values needed for a particular display may not be documented and may 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 to the offsets until the display looks correct. See the cfg_helper.py program in the examples folder for more information.

The module exposes predefined colors: BLACK, BLUE, RED, GREEN, CYAN, MAGENTA, YELLOW, and WHITE

Scrolling

The st7789 display controller contains a 240 by 320-pixel frame buffer used to store the pixels for the display. For scrolling, the frame buffer consists of three separate areas; The (tfa) top fixed area, the (height) scrolling area, and the (bfa) bottom fixed area. The tfa is the upper portion of the frame buffer in pixels not to scroll. The height is the center portion of the 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 entire or a part of the display.

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

Displays less than 320 pixels high, the tfa, height, and bfa will need to 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 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 at the 40th row of the frame buffer, leaving the last 40 rows of the frame buffer undisplayed.

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 value of the vertical scrolling start address is absolute (with reference to the frame memory),
it must not enter the fixed area (defined by Vertical Scrolling Definition, otherwise undesirable
image will be displayed on the panel.

• 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 frame buffer that will not be 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 display frame buffer that will not be scrolled.

• vscsad(vssa) Set the vertical scroll address.

  vssa is the vertical scroll start address in pixels. The vertical scroll start address is the line in the frame buffer will be the first line shown after the TFA.

Helper functions

• color565(r, g, b)

  Pack a color into 2-bytes rgb565 format

• map_bitarray_to_rgb565(bitarray, buffer, width, color=WHITE, bg_color=BLACK)

  Convert a bitarray to the rgb565 color buffer suitable for blitting. Bit 1 in bitarray is a pixel with color and 0 - with bg_color.