Board_config for the T-Display-S3 Pro

[tdhoward]

Hi @bdbarnett , thanks for your help with getting started on the board_config.py file for the T-Display-S3 Pro. I have a ton of questions, so I apologize in advance! I'm trying to get framebuf_simpletest to run on it, using "mpremote mount ."

Display
The display doesn't show anything, but you can tell that the display backlight comes on. That's encouraging, I think. I have a datasheet for the st7796 driver chip, so I'll take a look at that. Any recommended next steps?

I was looking at the schematics, and noticed that the S3-Pro uses the SPI bus (which you put in the board_config) instead of the i80 bus, like the S3. Just out of curiosity, which of these buses are faster?

Touch driver
The touch chip for the S3-Pro is the CST226SE, not the CST8xx. I'm working on getting a driver going for this, based on the CST8xx code and the info here.

[bdbarnett]

@tdhoward When you get a backlight but nothing else, it's almost always a wrong pin or state (such as reset_high=True) in the board_config. I may have given you wrong data.

While creating the board_config.py for the T-Display-S3 Pro, I saw conflicting information about the interface for the touch controller. The webpage shows the touch controller as SPI, but the schematic shows it as I2C. I trust the schematic more, so that's what I put in the board_config.py. The trouble is, the I2C pins from the schematic are GPIO5 and GPIO6. The webpage shows LCD_CS as GPIO6, but the schematic shows LCD_CS as "MTLK", without a GPIO number. The LCD_CS / MTLK pin on the schematic is between GPIO38 and GPIO40, and MTCK (with a C, not an L) on a google search shows it as GPIO39, so that's what I put in the board_config. I'd try setting cs=6 in the board_config and see what happens. You may have to comment out all of the touchscreen setup in board_config since it is also referencing GPIO6.

Just out of curiosity, which of these buses are faster?

I80 is faster, but, with the bus drivers written in MicroPython, they aren't significantly different. When the drivers are written in C, the I80 is noticeably faster. I wrote some C drivers, mostly modified from russhughes work, back in December, but they no longer work with the project as it is. I'm focusing on the Python code now, and will go back to them later, probably after the first of the year. I'm focused on using stock MicroPython and CircuitPython for now.

[tdhoward]

@bdbarnett I saw that you had changed the SPI frequency from 60MHz to 40MHz to match the TFT_eSPI configuration. I didn't notice any problems at 60MHz, but who knows, maybe it becomes glitchy? I'm guessing either would work fine for speed, since that's not likely the limiting factor for getting the data across.

I've now tried this config with tiny_toasters and alien, and both are working. The drawing is fairly slow, though. Do you know of any way to do profiling in MicroPython to figure out where the bottlenecks are? I'd be happy to help out with that, if possible. The S3-Pro doesn't have a parallel bus, just the SPI bus, so it's never going to be blazing fast. But it seems like there would be room for improvements.

Also, I'm curious what I can do to get some scrolling going. It seems like scrolling uses a special set of LCD commands, unless I'm reading it wrong.

[bdbarnett]

Hi @tdhoward.

I had changed the baudrate to 40Mhz while trying to help you get a display. When you submitted the PR, my recent change overrode that line in your PR. I have changed it back to 60MHz, added contributed by @tdhoward and removed all the comments that were for troubleshooting.

No, I don't know how to profile in MicroPython. I'm a middle-aged IT guy with an electronics degree. I code for fun, so there's a lot I don't know about programming. Here are some bottlenecks that come to mind:

1. Running code from mpremote mount . is super handy and I highly recommend it, but for objects that are repeatedly read from the file system, it will make your code appear to run slower. For instance, binfont (which is used for .text() in framebuf_plus) opens the .bin font file and leaves it open for the lifetime of the instance. When it needs a character, it seeks to the required position in the file, outputs one pixel at a time for all "on" pixels, then returns. It doesn't cache the character in memory in any way, thereby reducing the impact on memory constrained devices, with an expected (small) sacrifice in speed. Reading the .bin files from a remote filesystem will magnify the time impact. So, if you're considering speed, don't use mpremote mount ..
2. Byte swapping - this is the single biggest bottleneck we'll come across. It's because MicroPython on most (if not all) microcontrollers is little endian, while most display controllers are big endian. If a controller requires reverse_bytes_in_word=True to get correct colors, every time something is sent to the display the colors have to be swapped. That slows down display_drv.pixel() and display_drv.blit_rect() significantly. I implemented display_drv.swap_bytes() in viper for MicroPython (on controllers that support viper, including the ESP32) and implemented it in numpy for CircuitPython and big Python. Byte swapping is much faster in C code, but the whole objective is to have a working solution without requiring compiling firmware.
   • As a workaround to the swap bytes bottleneck, I made it so that the user application can request byte swapping be disabled. Then, rather than tell display_drv to send a red pixel as 0xF800, the application has to send it already swapped as 0x00F8. That's also why I created the palettes module. So here's one way to disable byte swapping and still have correct colors. Some of my examples do this or a variation of it, but none of the examples from russhughes do. I wanted to leave his examples as untouched as possible.

from board_config import display_drv
from palettes import get_palette

# If byte swapping is required and the display bus is capable of having byte swapping disabled,
# disable it and set a flag so we can swap the color bytes as they are created.
if display_drv.requires_byte_swap:
    needs_swap = display_drv.disable_auto_byte_swap(True)
else:
    needs_swap = False

palette = get_palette(swapped=needs_swap)

print(hex(palette.RED))

3. I know there are more opportunities for speed gains in buses and busdipslay, but I think the major bottlenecks other than byte swapping come from the way data is written to the display. For instance, if you draw something that uses pixel(), such as an unfilled gfx.shapes.circle() or gfx.shapes.line() (for a diagonal line, not horizontal or vertical), the function ends up calling .pixel() repeatedly. That is slow because SPI and I80 buses require the application to send a .set_window() command for every pixel. Instead, you can build your circle or (diagonal) line in a buffer and then .blit_rect() the buffer, which only calls .set_window() once. You can use a framebuf.Framebuffer (built into MicroPython), a framebuf_plus.Framebuffer or a displaybuf.DisplayBuffer to accomplish this. Even a bmp565.BMP565 acts like a buffer and can be blit_rected (?? awful ??) to the display. To see how these compare, see:
   • binfont_simpletest.py - Creates a FrameBuffer the exact size of the text, renders the text to that buffer, then .blit_rects (?? awful ??) that buffer to the display_drv. Both the foreground and background are written, so all text comes out as rectangular blocks. Faster, but doesn't look so good.
   • binfont_simpletest2.py - Renders the text directly to the display_drv one pixel at a time, so it is slower BUT it only draws the foreground. It appears as if the text has a transparent background. No rectangular blocks. Slower, but looks good.
   • binfont_simpletest3.py - Renders the text to a DisplayBuffer object, then only the area that was changed (dirty) is .blit_rected (?? awful ??) to the display_drv. It also appears as if the text has a transparent background. The best tradeoff of speed versus looks.

The moral of the story: Disable byte swapping and use a DisplayBuffer when you can, but be sure to keep track of the dirty area so you can .blit_rect(dirty).

You asked about scrolling. That's going to take some changes to busdisplay.BusDisplay to make it work for boards where either colstart or rowstart is not 0. That is to say, when the GRAM and the display aren't the same dimensions. Give me this weekend to work on it and I'll start a new thread about scrolling Sunday or Monday. In the meantime, will you please test out on-the-fly screen rotations, such as in the binfont tests above as well as russhughes's rotations.py?

By the way, I know I get long winded with my answers. My intention is to at some point turn these informational posts into documentation, so I'm taking the time to try to clarify each topic as much as possible. You may get a little more information than you were asking for. Please bear with me.

[tdhoward]

@bdbarnett This is really great information. Good idea on the palette solution for byte swapping. Is that the only place where byte-swapping is needed?

I really like the idea of using a buffer and tracking dirty rectangles. I got my start in programming with C++ and the Allegro library in the mid 90's, and I remember that technique from then. I'm a 40-something self-taught programmer with a 2 year degree in electronics, so I also do this stuff for fun (and my job, which is software development). At this point, I'm happy to get all the information you want to put out there.

I try to test these ideas out this weekend, if possible.

[tdhoward]

@bdbarnett Okay, I did some testing with the ST7796 (T-Display-S3 Pro), and here's what I found:

• binfont_simpletest.py: Rotations look good.
• binfont_simpletest2.py: Rotations look good.
• binfont_simpletest3.py: Nothing rotated. The DisplayBuffer doesn't appear to respond to a change in rotation.
• rotations.py: The rotation worked, but the colstart/rowstart appears not to be used.

[tdhoward]

@bdbarnett I now have a working T-Display-S3 Pro device, with a CST226 touch driver that seems to be working beautifully. I tried scroll_touch_test.py, and it works really nicely. I made a few PRs for bugfixes and adding this touch driver.

I might take a look at the non-rotating binfont_simpletest3.py this weekend, but for now I'm feeling pretty happy with how this is all working. We can likely close this discussion thread unless you have any info you want to add to it.

[bdbarnett]

@tdhoward Great work! Thanks for contributing it to the project. It sounds like the "double scrolling" caused by implementing colstart and rowstart in both fill_rect and blit_rect was the problem. I'm glad you found it.

I'm glad you found scroll_touch_test.py. I'm going to start another thread discussing scrolling now. I meant to do it sooner.

[bdbarnett]

@tdhoward The reason binfont_simpletest3 isn't rotating is because I have not implemented the .rotation attribute in displaybuf.DisplayBuffer, largely because it isn't implemented in the underlying framebuf.FrameBuffer. I adapted binfont_simpletest3.py from other tests, and just left the rotations in there in case I do implement rotations. (Most of the examples like this started as my personal code to make sure I implemented something correctly, and I use them after I make design changes to make sure I haven't broken anything. They also serve as howto's since the API isn't documented. I'll definitely weed out lots of the examples after the API is pinned down and documented.) binfont_simpletest3.py doesn't throw an error because it just creates a new .rotation attribute on the fly, which does nothing.

To implement rotations in DisplayBuffer, the object would need to be re-inited with a new buffer that is the correct shape. Whether to copy the current buffer to the new, rotated buffer, is optional. Copying it would give the same results as rotating a BusDisplay object, but isn't necessarily required.

Since DisplayBuffer is a subclass of FrameBuffer, I think rotating would require creating a whole new object, not just the underlying memoryview buffer. If you can think of a better way to do it, please let me know. I'm fine with leaving rotations out of DisplayBuffer, for now at least.

[tdhoward]

@bdbarnett That makes sense to me. The only reason I could think of for rotation would be if someone wanted to place two pieces of text, one horizontal and one vertical. But that could probably be accomplished using other means.