Slow refresh rate and pixel shift on T-Display rp2040

[kreier]

CircuitPython version

Adafruit CircuitPython 8.2.9 on 2023-12-06; LILYGO T-DISPLAY with rp2040

The behaviors was tested with all versions from the first support at 8.1.0 to the latest 9.0.0-alpha6 and is consistent across all versions. It even applies to the similar T-PicoC3. Details below

Code/REPL

# 23 Jun 2022 - @todbot / Tod Kurt
import time, random, board, displayio, vectorio, rainbowio

display = board.DISPLAY
maingroup = displayio.Group()
display.root_group = maingroup

# demo with a bunch of vectorio circles
for i in range(20):
    palette = displayio.Palette(1)
    palette[0] = rainbowio.colorwheel(random.randint(0,255))
    x,y = random.randint(0,display.width), random.randint(0,display.height)
    ball = vectorio.Circle(pixel_shader=palette, radius=20, x=x, y=y)
    maingroup.append(ball)

while True:
    for ball in maingroup:
        ball.x = (ball.x + 1) % display.width
    time.sleep(0.05)

Behavior

The refresh rate of this above code example of 20 moving disks is around 0.9 fps - some 1.2 seconds between each frame. Additionally all the firmware since 8.1.0 to 9.0.0 have one chaos pixel line at the bottom of the screen. A little distracting to be used in a GUI and interactive content.

Description

If I include the respective driver for the ST7789 display chip in the boot.py this problem does not appear. The frame rate is some 20 fps and responsive. Using the same code above in the code.py but having the following content in the boot.py resolves this issue:

import board, busio, displayio, fourwire
from adafruit_st7789 import ST7789

display.release_displays()

tft_dc    = board.LCD_DC
tft_cs    = board.LCD_CS
spi_clk   = board.LCD_CLK
spi_mosi  = board.LCD_MOSI
tft_rst   = board.LCD_RESET
backlight = board.LCD_BACKLIGHT
spi = busio.SPI(spi_clk, spi_mosi)

display_bus = fourwire.FourWire(spi, command=tft_dc, chip_select=tft_cs, reset=tft_rst)

display = ST7789(
    display_bus,
    rotation=270,
    width=240,
    height=135,
    rowstart=40,
    colstart=53,
    backlight_pin=backlight,
)

So even though I call the board.DISPLAY it seems to address the driver loaded in the boot.py instead of the firmware driver. It does not work with my two T-PicoC3, though. But if I include the above code in the respective files and use this display constructor, it is responsive and no bottom pixel shift. Notice the colstart=53 for the additional information.

Additional information

The colstart=53 appears also in the function common_hal_busdisplay_busdisplay_construct() in the board.c of the board description for compiling the firmware as 5th parameter. Changing the number to 52 and recompiling the firmware solved this issue. Note as well that the rotation here (7th parameter) is given as 90 while my constructor above uses rotation=270,. Don't know why. The resulting orientation for both is the same.

One more observation: on one of my 3 T-Display rp2040 boards the firmware produces no output on the display at all. Same firmware on all 3 boards, but one activates only the backlight while the screen stays blank. Yet on all boards (including two additional T-PicoC3 boards) the above mentioned direct call of the adafruit_st7789.mpy library works fast and without issues.

[kreier]

That's how it should look like and it is intended to be used for (thats why a higher refresh rate is needed).

[deshipu]

I can at least tell you why the rotation is different (and I suspect the rotation is at least in part responsible for the slowdown). In the initialization sequence for the display, in the MADCTL register there are some bits that decide how the display is going to be rotated respective to its internal memory – on the side of the display chip. The board.c code has this:

    0x36, 1, 0x08,

and if you glance at the ST7789 driver code, it seeming has the same:

    b"\x36\x01\x08"  # _MADCTL

but then later on it changes it to:

    b"\x36\x01\xC0"  # _MADCTL

(which is, by the way, completely redundant, the first line should be removed)

So the board.c sets it to 0b00001000 while the ST7789 driver sets it to 0b11000000. What are those bits? Let's look at the datasheet:

The first one sets the ML flag to "refresh bottom to top", while the second one leaves the ML at "refresh top to bottom", but sets MX and MY to "right to left" and "bottom to top" respectively. That effectively flips the display 180°, which explains why then the two different initialization sequences require different software rotation.

Now, what I would personally do, is this: I would change the MADCTL register to 0b00010000, and set the software rotation to 0. This way the display will be correctly rotated by its hardware, and no additional code needs to run to rotate it to the right orientation. With less code running, it's faster and possibly avoids that off-by-one bug.

[kreier]

Almost there! Flawless on 2 boards already 😁 And I started to read the 300+ page of the ST7789V documentation ...

First a picture that shows the strange bottom line with pixel noise:

So I followed your suggestion and changed the MADCTL register to 0b00010000 (as 0x10) and changed the rotation in the board.c to zero. It didn't had the intended effect:

So I opened the two init sequences to compare:

• Firmware for T-Display board.c in the circuitpython repository
• Driver in Python https://github.com/adafruit/Adafruit_CircuitPython_ST7789/blob/main/adafruit_st7789.py

The init sequence in the driver is actually very short:

_INIT_SEQUENCE = (
    b"\x01\x80\x96"  # _SWRESET and Delay 150ms
    b"\x11\x80\xFF"  # _SLPOUT and Delay 500ms
    b"\x3A\x81\x55\x0A"  # _COLMOD and Delay 10ms
    b"\x36\x01\x08"  # _MADCTL
    b"\x21\x80\x0A"  # _INVON Hack and Delay 10ms
    b"\x13\x80\x0A"  # _NORON and Delay 10ms
    b"\x36\x01\xC0"  # _MADCTL
    b"\x29\x80\xFF"  # _DISPON and Delay 500ms
)

And it has the mentioned doubled declaration for _MADCTL. After playing a little with different values for MADCTL and rotation I finally did the obvious thing: This little 1.14" 240x135 display is used in so many other boards, why not copy their init sequence? It works without problems for my ESP32 T-Display (after adjusting for the 4M flash chip). Here are some examples:

• https://github.com/adafruit/circuitpython/blob/main/ports/espressif/boards/lilygo_ttgo_tdisplay_esp32_16m/board.c
• https://github.com/adafruit/circuitpython/blob/main/ports/espressif/boards/adafruit_feather_esp32s2_tft/board.c

The second actually uses the rotation of zero! But neither worked. And it seems very few people go into the details of all the different values of the init_sequence. In many board.c files I found this little comment above the init sequences:

// display init sequence according to LilyGO example app
uint8_t display_init_sequence[] = {

Having these different board.c next to one another I compared other parts and looked for differences. And the difference (and error or cause for the stange behaviour) is indeed in the mentioned common_hal_busdisplay_busdisplay_construct() - the version for the T-Display rp2040 uses an additional "parameter" for auto-brightness that the other board.c are missing:

        1.0f,           // brightness (ignored)
        false,          // auto_brightness
        false,          // single_byte_bounds

Source:
https://github.com/adafruit/circuitpython/blob/main/ports/raspberrypi/boards/lilygo_t_display_rp2040/board.c

So I removed the line below the brightness setting (in total one parameter less) and the error is gone! I copied the parameters from Adafruit (with the MADCTL 0x36, 1, 0x68 and rotation=0) and the display is snappy and without pixelnoise around!

Now I probably have to create a pull request for this change. And I can include the missing pins 17, 19, 20, 23, 24, 27, 28 and 29 for the pins.c. And probably create a new T-PicoC3 board with slightly different pins.

Something is still off with the timing parameters. The two T-PicoC3 work without a problem. But now two of my T-Displays don't start correctly with the boot screen. The screen stays blank. But if I call the much simpler init sequence from the boot.py it correctly initializes the display and afterwards I can use it by regularly addressing it as board.DISPLAY. Is the init too short (255 or 0xFF is less than 500 - for 500ms that are needed?) Or bad silicon?

[kreier]

Pull request is created. The different settings for _MADCTL cause the pixel update when drawing to be now from top to bottom (it was left to right or right to left prior to this change). I think this is more pleasing to the eye. The transfer rate of new pixels to the frame buffer of the ST7789V over SPI is still not very high, but probably within the limits of the fourwirebus.

[kreier]

These settings can be replicated directly in Circuitpython. Instead of using the compiled adafruit_st7789.mpy I used the regular adafruit_st7789.py and changed one line with _MADCTL. The additional _MADCTL line can indeed be removed, no change here. And the file has only some 20 lines of code, anyway, so here is the adjusted init sequence from this file:

_INIT_SEQUENCE = (
    b"\x01\x80\x96"  # _SWRESET and Delay 150ms
    b"\x11\x80\xFF"  # _SLPOUT and Delay 500ms
    b"\x3A\x81\x55\x0A"  # _COLMOD and Delay 10ms
    b"\x21\x80\x0A"  # _INVON Hack and Delay 10ms
    b"\x13\x80\x0A"  # _NORON and Delay 10ms
    b"\x36\x01\x68"  # _MADCTL - was C0
    b"\x29\x80\xFF"  # _DISPON and Delay 500ms
)

\C0 is now \x68. My boot.py now got the following sequence:

import board, busio, displayio, fourwire
from adafruit_st7789 import ST7789

displayio.release_displays()

tft_dc    = board.LCD_DC
tft_cs    = board.LCD_CS
spi_clk   = board.LCD_CLK
spi_mosi  = board.LCD_MOSI
tft_rst   = board.LCD_RESET
backlight = board.LCD_BACKLIGHT
spi = busio.SPI(spi_clk, spi_mosi)

display_bus = fourwire.FourWire(spi, command=tft_dc, chip_select=tft_cs, reset=tft_rst)

display = ST7789(
    display_bus,
    rotation=0,
    width=240,
    height=135,
    rowstart=53,
    colstart=40,
    backlight_pin=backlight,
)

Refresh is now top-to-bottom. Rotation is zero. Same as with the new firmware running on the T-PicoC3.

Still no luck with the firmware on T-Display rp2040, display not activated after boot if not using the boot.py. Maybe an extra delay in the sequence for the _INVON Hack and Delay 10ms?

[kreier]

And the story with MADCTL continues. I collected a list of boards with the ST7789 display driver and their combination of MADCTL settings and rotations. The board names link to the respective board.c files. Looks like values are all over the place.

board	MADCTL	_MADCTL	rotation	column start	row start	width	height
T-Display rp2040	0x08	0b00001000	90	53	40	240	135
T-Display ESP32 16M	0x08	0b00001000	270	53	40	240	135
Feather ESP32-S2 with TFT	0x68	0b01101000	0	40	53	240	135
Feather ESP32-S2 reverse TFT	0x68	0b01101000	0	40	53	240	135
TTGO T8 ESP32-S2 ST7789	0x08	0b00001000	90	52	40	240	135
Lilygo T-Embed ESP32-S3	0xC8	0b11001000	90	35	0	320	170
MEMENTO	0xA0	0b10100000	0	80	0	240	240
CLUE NRF52840 Express	0xA0	0b10100000	0	80	0	240	240
Lilygo T-Deck	0x08	0b00001000	270	0	0	320	240
M5StickC PLUS (ST7735R)	0x08	0b00001000	1	40	52	135	240

At least Adafruit knows about the correct combination and gets the rotation to zero.

The pixel noise line seems to have affected other users too. I assume that's the cause for the column/row values of 52 instead of the 53. I guess with correct configuration a 53 value should be correct. This centers the 135 pixel in a 240 pixelbuffer, the same way as the 40 centers the 240 pixel in a 320 pixel wide pixelbuffer of the ST7789.

@RetiredWizard implemented the fix in his pull request for the TTGO T8 ESP32-S2 #8773

I have to review my adjustment for the pixel order in bit D3. With 2 exceptions its set to one and the displays seem to work.

I left the M5StickC Plus in the list even though it has a different display driver (ST7735R) but the same 240x135 1.14" TFT display.

[kreier]

With PR #8772 this problem is now solved!