2019-04-11 09:57:04 +00:00
|
|
|
ST7789 Driver for MicroPython
|
|
|
|
=============================
|
|
|
|
|
|
|
|
|
|
|
|
Overview
|
|
|
|
--------
|
2020-02-11 07:00:23 +00:00
|
|
|
This is a driver for MicroPython to handle cheap displays
|
|
|
|
based on ST7789 chip.
|
2019-04-11 09:57:04 +00:00
|
|
|
|
|
|
|
<p align="center">
|
2020-02-11 07:00:23 +00:00
|
|
|
<img src="https://raw.githubusercontent.com/devbis/st7789_mpy/master/docs/ST7789.jpg" alt="ST7789 display photo"/>
|
2019-04-11 09:57:04 +00:00
|
|
|
</p>
|
|
|
|
|
2019-12-27 17:31:24 +00:00
|
|
|
It supports both 240x240 and 135x240 variants of displays.
|
|
|
|
|
2019-04-11 09:57:04 +00:00
|
|
|
It is written in pure C, so you have to build
|
|
|
|
firmware by yourself.
|
2020-06-25 10:32:18 +00:00
|
|
|
ESP8266, ESP32, and STM32 ports are supported for now.
|
2019-04-11 09:57:04 +00:00
|
|
|
|
|
|
|
|
|
|
|
Building instruction
|
|
|
|
---------------------
|
|
|
|
|
|
|
|
Prepare build tools as described in the manual.
|
2020-02-11 07:00:23 +00:00
|
|
|
You should follow the instruction for building MicroPython and
|
2019-04-11 09:57:04 +00:00
|
|
|
ensure that you can build the firmware without this display module.
|
|
|
|
|
|
|
|
Clone this module alongside the MPY sources:
|
|
|
|
|
|
|
|
$ git clone https://github.com/devbis/st7789_mpy.git
|
|
|
|
|
|
|
|
Go to MicroPython ports directory and for ESP8266 run:
|
|
|
|
|
|
|
|
$ cd micropython/ports/esp8266
|
|
|
|
|
2020-02-11 07:00:23 +00:00
|
|
|
for ESP32:
|
2019-04-11 09:57:04 +00:00
|
|
|
|
|
|
|
$ cd micropython/ports/esp32
|
|
|
|
|
|
|
|
And then compile the module with specified USER_C_MODULES dir
|
|
|
|
|
|
|
|
$ make USER_C_MODULES=../../../st7789_mpy/ all
|
2020-02-11 07:00:23 +00:00
|
|
|
|
|
|
|
|
|
|
|
If you have other user modules, copy the st7789_driver/st7789 to
|
2019-04-11 09:57:04 +00:00
|
|
|
the user modules directory
|
|
|
|
|
2020-02-11 07:00:23 +00:00
|
|
|
Upload the resulting firmware to your MCU as usual with esptool.py
|
|
|
|
(See
|
|
|
|
[MicroPython docs](http://docs.micropython.org/en/latest/esp8266/tutorial/intro.html#deploying-the-firmware)
|
2019-04-11 09:57:04 +00:00
|
|
|
for more info)
|
|
|
|
|
2020-02-02 07:40:56 +00:00
|
|
|
$ make deploy
|
2019-04-11 09:57:04 +00:00
|
|
|
|
|
|
|
Working examples
|
|
|
|
----------------
|
|
|
|
|
|
|
|
This module was tested on ESP32 and ESP8266 MCUs.
|
|
|
|
|
2020-02-11 07:00:23 +00:00
|
|
|
You have to provide `machine.SPI` object and at least two pins for RESET and
|
|
|
|
DC pins on the screen for the display object.
|
2019-04-11 09:57:04 +00:00
|
|
|
|
|
|
|
|
|
|
|
# ESP 8266
|
2020-02-11 07:00:23 +00:00
|
|
|
|
2019-04-11 09:57:04 +00:00
|
|
|
import machine
|
|
|
|
import st7789
|
|
|
|
spi = machine.SPI(1, baudrate=40000000, polarity=1)
|
|
|
|
display = st7789.ST7789(spi, 240, 240, reset=machine.Pin(5, machine.Pin.OUT), dc=machine.Pin(4, machine.Pin.OUT))
|
2019-12-27 11:52:38 +00:00
|
|
|
display.init()
|
2019-04-11 09:57:04 +00:00
|
|
|
|
|
|
|
|
|
|
|
For ESP32 modules you have to provide specific pins for SPI.
|
|
|
|
Unfortunately, I was unable to run this display on SPI(1) interface.
|
2020-02-11 07:00:23 +00:00
|
|
|
For machine.SPI(2) == VSPI you have to use
|
2019-04-11 09:57:04 +00:00
|
|
|
|
|
|
|
- CLK: Pin(18)
|
|
|
|
- MOSI: Pin(23)
|
|
|
|
|
|
|
|
Other SPI pins are not used.
|
|
|
|
|
|
|
|
|
|
|
|
# ESP32
|
|
|
|
|
|
|
|
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))
|
2019-12-27 11:52:38 +00:00
|
|
|
display.init()
|
2019-04-11 09:57:04 +00:00
|
|
|
|
|
|
|
|
|
|
|
I couldn't run the display on an SPI with baudrate higher than 40MHZ
|
|
|
|
|
2020-06-25 10:32:18 +00:00
|
|
|
Also, the driver was tested on STM32 board:
|
|
|
|
|
|
|
|
|
|
|
|
# STM32
|
|
|
|
|
|
|
|
import machine
|
|
|
|
import st7789
|
|
|
|
spi = machine.SPI(2, baudrate=12000000, polarity=1)
|
|
|
|
display = st7789.ST7789(spi, 135, 240, reset=machine.Pin('B3', machine.Pin.OUT), dc=machine.Pin('B6', machine.Pin.OUT))
|
|
|
|
display.init()
|
|
|
|
|
|
|
|
|
2019-04-11 09:57:04 +00:00
|
|
|
Methods
|
|
|
|
-------------
|
|
|
|
|
|
|
|
This driver supports only 16bit colors in RGB565 notation.
|
|
|
|
|
|
|
|
|
|
|
|
- `ST7789.fill(color)`
|
|
|
|
|
|
|
|
Fill the entire display with the specified color.
|
|
|
|
|
|
|
|
- `ST7789.pixel(x, y, color)`
|
|
|
|
|
|
|
|
Set the specified pixel to the given color.
|
2020-02-11 07:00:23 +00:00
|
|
|
|
2019-04-11 09:57:04 +00:00
|
|
|
- `ST7789.line(x0, y0, x1, y1, color)`
|
|
|
|
|
2020-02-11 07:00:23 +00:00
|
|
|
Draws a single line with the provided `color` from (`x0`, `y0`) to
|
2019-04-11 09:57:04 +00:00
|
|
|
(`x1`, `y1`).
|
|
|
|
|
|
|
|
- `ST7789.hline(x, y, length, color)`
|
|
|
|
|
2020-02-11 07:00:23 +00:00
|
|
|
Draws a single horizontal line with the provided `color` and `length`
|
|
|
|
in pixels. Along with `vline`, this is a fast version with reduced
|
2019-04-11 09:57:04 +00:00
|
|
|
number of SPI calls.
|
|
|
|
|
|
|
|
- `ST7789.vline(x, y, length, color)`
|
|
|
|
|
2020-02-11 07:00:23 +00:00
|
|
|
Draws a single horizontal line with the provided `color` and `length`
|
2019-04-11 09:57:04 +00:00
|
|
|
in pixels.
|
|
|
|
|
|
|
|
- `ST7789.rect(x, y, width, height, color)`
|
|
|
|
|
|
|
|
Draws a rectangle from (`x`, `y`) with corresponding dimensions
|
2020-02-11 07:00:23 +00:00
|
|
|
|
2019-04-11 09:57:04 +00:00
|
|
|
- `ST7789.fill_rect(x, y, width, height, color)`
|
|
|
|
|
|
|
|
Fill a rectangle starting from (`x`, `y`) coordinates
|
|
|
|
|
|
|
|
- `ST7789.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
|
|
|
|
|
|
|
|
Also, the module exposes predefined colors:
|
|
|
|
`BLACK`, `BLUE`, `RED`, `GREEN`, `CYAN`, `MAGENTA`, `YELLOW`, and `WHITE`
|
|
|
|
|
|
|
|
|
2019-04-26 08:36:08 +00:00
|
|
|
Helper functions
|
|
|
|
----------------
|
|
|
|
|
|
|
|
- `color565(r, g, b)`
|
|
|
|
|
|
|
|
Pack a color into 2-bytes rgb565 format
|
2020-02-11 07:00:23 +00:00
|
|
|
|
2019-04-26 08:36:08 +00:00
|
|
|
- `map_bitarray_to_rgb565(bitarray, buffer, width, color=WHITE, bg_color=BLACK)`
|
|
|
|
|
|
|
|
Convert a bitarray to the rgb565 color buffer which is suitable for blitting.
|
|
|
|
Bit 1 in bitarray is a pixel with `color` and 0 - with `bg_color`.
|
2020-02-11 07:00:23 +00:00
|
|
|
|
|
|
|
This is a helper with a good performance to print text with a high
|
|
|
|
resolution font. You can use an awesome tool
|
2019-04-26 08:36:08 +00:00
|
|
|
https://github.com/peterhinch/micropython-font-to-py
|
2020-02-11 07:00:23 +00:00
|
|
|
to generate a bitmap fonts from .ttf and use them as a frozen bytecode from
|
2019-04-26 08:36:08 +00:00
|
|
|
the ROM memory.
|
|
|
|
|
2019-04-11 09:57:04 +00:00
|
|
|
Performance
|
|
|
|
-----------
|
|
|
|
|
2020-02-11 07:00:23 +00:00
|
|
|
For the comparison I used an excellent library for Arduino
|
2019-04-11 09:57:04 +00:00
|
|
|
that can handle this screen.
|
|
|
|
|
|
|
|
https://github.com/ananevilya/Arduino-ST7789-Library/
|
|
|
|
|
|
|
|
Also, I used my slow driver for this screen, written in pure python.
|
|
|
|
|
|
|
|
https://github.com/devbis/st7789py_mpy/
|
|
|
|
|
|
|
|
I used these modules to draw a line from 0,0 to 239,239
|
|
|
|
The table represents the time in milliseconds for each case
|
|
|
|
|
|
|
|
| | Arduino-ST7789 | st7789py_mpy | st7789_mpy |
|
|
|
|
|---------|----------------|--------------|---------------|
|
|
|
|
| ESP8266 | 26 | 450 | 12 |
|
|
|
|
| ESP32 | 23 | 450 | 47 |
|
|
|
|
|
|
|
|
|
|
|
|
As you can see, the ESP32 module draws a line 4 times slower than
|
|
|
|
the older ESP8266 module.
|
|
|
|
|
|
|
|
|
|
|
|
Troubleshooting
|
|
|
|
---------------
|
|
|
|
|
|
|
|
#### Overflow of iram1_0_seg
|
|
|
|
|
2020-02-11 07:00:23 +00:00
|
|
|
When building a firmware for esp8266 you can see this failure message from
|
2019-04-11 09:57:04 +00:00
|
|
|
the linker:
|
|
|
|
|
|
|
|
LINK build/firmware.elf
|
|
|
|
xtensa-lx106-elf-ld: build/firmware.elf section `.text' will not fit in region `iram1_0_seg'
|
|
|
|
xtensa-lx106-elf-ld: region `iram1_0_seg' overflowed by 292 bytes
|
|
|
|
Makefile:192: recipe for target 'build/firmware.elf' failed
|
|
|
|
|
2020-02-11 07:00:23 +00:00
|
|
|
To fix this issue, you have to put st7789 module to irom0 section.
|
2019-04-11 09:57:04 +00:00
|
|
|
Edit `esp8266_common.ld` file in the `ports/esp8266` dir and add a line
|
|
|
|
|
|
|
|
*st7789/*.o(.literal* .text*)
|
|
|
|
|
|
|
|
in the `.irom0.text : ALIGN(4)` section
|
2019-12-27 17:31:24 +00:00
|
|
|
|
|
|
|
|
|
|
|
#### Unsupported dimensions
|
|
|
|
|
|
|
|
This driver supports only 240x240 and 135x240 pixel displays.
|
2020-02-11 07:00:23 +00:00
|
|
|
If you have a display with an unsupported resolution, you can pass
|
|
|
|
`xstart` and `ystart` parameters to the display constructor to set the
|
2019-12-27 17:31:24 +00:00
|
|
|
required offsets.
|