Is there a recommended process for adjusting driver init settings?

[tdhoward]

I'm using a LilyGo T-Display-S3, which uses the ST7789 driver chip. When using this driver, the screen looks rotated 90 degrees, the colors are off, and there are big areas of the screen that don't get erased. I'm not sure what to adjust in the settings.

I was hoping for some helpful tips from @bdbarnett (or anyone else in the community) for how to approach this. I'm fine with reading datasheets and all that, but I was wondering if there is a particular sequence that anyone likes to go through when tuning these things. I'm picturing something like:

1. Fill the screen with white (check for inversion)
2. Fill screen with red, then green, then blue (check for byte swapping, etc.)
3. Draw border around edge of screen (check for going off-screen)
4. Draw rect covering left half of screen (check for rotation, etc.)
5. Draw rect covering top half of screen (check for rotation, etc.)
6. ...

Any thoughts or pointers?

[bdbarnett]

Hi @tdhoward,

I've not tried to come up with a process for this yet, but I'll give it a shot.

It seems to me there are 3 primary areas of concern: getting the display to show anything, dialing in colors, and dialing in the position. The first is by far the most difficult because it depends on starting with a working init string (from st7789.py in your case), getting the correct pin numbers in the right places in the board_config, and getting the polarity correct on the backlight and reset pins. Luckily, it sounds like you've gotten past that point, so we can move on.

Currently, BusDisplay only works at 16-bit color depth, so that will help since we don't have to worry with several different color depths. The three things that affect colors are inversion, color order and byte swapping. Luckily they are all True-False settings, so at most there are 8 combinations to try.

• 1. invert - When False, the display uses the color data as defined. When True it flips each bit to the opposite state. This is easiest to see in black and white. White is normally 0xFFFF, but when inverted, it is 0x0000. Likewise, black is the opposite. Forget about all the other colors. If blacks and whites are reversed, change your invert= line.
• 2. bgr -When False, the display expects the color bits in RGB (red, green, blue) order. In binary, it looks like rrrrrggggggbbbbb. When True, it expects the color bits in BGR order, which looks like bbbbbggggggrrrrr. In both cases, the order of the bits are from most significant on the left to least significant on the right for each color. That is to say, blue is b4, b3, b2, b1, b0 no matter whether blue is first or last in the color order. Assuming all other settings are correct (including byte swapping), if you send a 0xF800 (0b1111100000000000), it will show up as red on your display if your bgr setting is correct, blue if it is wrong. If you see any other color but you know your invert setting is correct, then your revers_bytes_in_word setting must be wrong.
• 3. reverse_bytes_in_word - (The name of this setting is really long, but I made the parameter names for BusDisplay the same as CircuitPython's BusDisplay, and that's what they named it.) In the rest of computer science, this is called endianness. In a nutshell, it defines whether the 2-byte word should have the most significant byte on the left (Big-endian) or right (Little-endian). When the display expects the byte order to be the same as our system uses, we set this setting to False. When they are the opposite, we set it to True. A color in RGB order with bytes swapped will look like gggbbbbb rrrrrggg. A color in BGR order with bytes swapped will look like gggrrrrr bbbbbggg.

Knowing all that, after you have your invert setting correct, you could draw 4 rectangles on the screen with the 4 different representations of red and find your settings based on which block was actually red. The 4 representations are 0xF800, 0x001F, 0x00F8 and 0x1F00. I don't do it this way, so I'll leave it to you to figure out which settings are determined by each representation.

This is getting long. I'll pick up with positioning in the next post.

[bdbarnett]

The settings that affect the image position on our display are width, height, colstart, rowstart, rotation and mirrored. (This assumes the init string in the driver is correct.)

The rotation and mirrored settings depend on your application and easier to set to 0 and False, respectively, until you have the other 4 settings correct. That is to say, ignore the way you plan to use it in your project first, and instead be willing to position your project in the display's "natural" position until you get those 4 settings right. (I'm not sure if natural is the correct word here. I'll probably interchange it with native and normal in the rest of this writeup.) Comparing it to a computer monitor, we'd want to start with the monitor with it's normal "up side up", even if in our final project we're going to rotate it or mirror it.

The width and height are easy as well. Just get them from you board's spec sheet. The only issue is that they may be reversed, but we'll test for that in a bit.

• 1. Draw a 1-pixel high WHITE rectangle on your display like:

display_drv.fill_rect(0, display_drv.height // 2, display_drv.width, 1, 0xFFFF)

This line may be offset in any direction, but it will definitely go either horizontal or vertical. If it is vertical, rotate your project 90 degrees. Now we know we have the portrait / landscape orientation correct, but we don't know if it is 180 degrees off or not.

• 2. Draw a 1-pixel high BLUE rectangle on your display 10 lines below that one like:

display_drv.fill_rect(0, 10 + display_drv.height // 2, display_drv.width, 1, 0x001F)

If the blue line is above the white line, rotate your project 180 degrees. Now we have it in it's "normal" posisition.

• 3. If you had to rotate your screen in step 1 or 2, you may need to swap your width and height values (unless you have a round or square display). For instance, if your display is taller than it is wide in its natural position we just found, make sure to set the height to the larger value.
• 4. Determining the colstart and rowstart values is the toughest part for me, primarily because I just haven't had to do it much. Here's the reason. Displays will have dimensions in pixels, such as your T-Display-S3's 170x320. Display controllers must have the same or greater dimensions. If the display and the display controller have the same dimensions, your colstart and rowstart are 0 and we're done. I have primarily purchased displays with 240x320, 320x480 and 240x240 dimensions, which are typical display controller dimensions, so I haven't had to deal with colstart and rowstart. The ST7789V in your T-Display-S3 has a resolution of 240x320. That means there are 70 columns (or rows, depending on orientation) in the display controller's memory that never make it to the display. You MAY have to shift the image from 1 to 70 pixels to get it centered on the display. If your image isn't already centered with the colstart and rowstart at 0, I'd set the colstart to 35 (because the display width is 170 and display controller width is 240) and run some of the examples. I just updated framebuf_simpletest so it no longer requires anything except board_config and its dependencies since framebuf is built into MicroPython. Run that and see if it looks something like this. Hopefully it will be apparent what you need to do to set the colstart (or rowstart). If not, let me know and we'll keep going.

At this point, everything should be working with your display in its "normal" position. Now you can change the rotation and mirror if you need to, and it should still work. If it doesn't, that is my problem to fix in BusDisplay, not yours in the board_config.

As always, please let me know how it turns out. Now that I've written this out, I plan to put some revision of it in the documentation. Feel free to add or change anything you'd like to see in the docs.

[tdhoward]

@bdbarnett This is great info, very helpful. Here are my thoughts and actions as I stepped through this with the T-Display-S3:
I'm using 'mpremote mount .' which is super convenient for fast changes and tests!

1. Let's start off with framebuf_simpletest. Initially, I'm getting something on the screen that looks shifted and wrong colors.
2. I swapped the values for rowstart and colstart, and now everything lines up. The colors are still off, with blue instead of red, etc.
3. I changed bgr from False to True. The colors look great now, but suddenly the whole display is mirrored. No idea why.
4. I changed mirrored from False to True. Now the picture looks perfect.
5. Cool! Now lets go try one of the other examples, like bmp565_blit. Hmm, that one didn't show anything but a black screen.
6. Let's try bmp565_scroll. This shows a mostly black screen, with a small area at one end that isn't changing, but appears to be from the bmp.
7. Let's try boxlines. Nice, this mostly works, but we appear to be offset in the opposite direction this time.
8. What happens if I revert the changes I made to the board_config? No, that's even worse, as the display also appears to be rotated now.
9. I switch back to my modified board_config, but change colstart and rowstart to their original values. Everything looks great now.

Through these tests, it seems like certain parameters change more things than are expected. The settings I was adjusting didn't seem to result in a display driver that worked consistently across different examples. Any suggestions for what I might be doing wrong?

(Also, I've been trying out the board config for the T-Display-S3 Pro, and I have some feedback and questions on that, but I'll save it for a different discussion post.)

Thanks!

[bdbarnett]

@tdhoward I'm glad to hear you are using mpremote mount .! It's a timesaver for sure!

You said

Any suggestions for what I might be doing wrong?

I don't think you are doing anything wrong. BusDisplay just hasn't been tested (and corrected) to work with displays where colstart and rowstart aren't both 0. I need your help to figure out what must be changed in BusDisplay for these displays.

Refer to lines 54 to 78 and 239 to 243 of src/lib/displays/busdisplay/__init__.py for this discussion.

In the MIPI Display Command Set (DCS), register 0x36 is "set_address_mode", more commonly referred to as MADCTL, which stands for "memory address control". It defines the read and write direction of the frame memory. The 8 bits in this register are:

Bit	Description	Effect	Note
7	MY = Page (Row) Address Order	1 = Bottom to Top
6	MX = Column Address Order	1 = Right to Left
5	MV = Page/Column Addressing Order (Row/Column Exchange)	1 = Reverse Mode
4	ML = Display Device Line Refresh Order (Vertical Refresh Order or Scan Address order)	1 = Bottom to Top	The image shown on the display device is unaffected.
3	BGR = RGB/BGR Order	1 = BGR order
2	MH = Display Data Latch Data Order (Horizontal Refresh Order or Horizontal Order)	1 = Right to Left	The image shown on the display device is unaffected.
1	FH = Flip Horizontal	1 = Flipped	This bit flips the image shown on the display device left to right.
0	FV = Flip Vertical	1 = Flipped	This bit flips the image shown on the display device top to bottom by changing the gate scanning order.

The display controller has "frame memory", also called Graphics RAM or GRAM. Bits 7 to 5 of the MADCTL register specify the order the data bytes are written to the frame memory from the MCU. Bits 4 to 0 specify the order the data bytes are written from the frame memory to the display device. From my research, it is customary to leave Bits 1 and 0 set to 0 and use bits 7 and 6 to flip the display image. Likewise, bits 4 and 2 are usually left alone at 0.

Bit 3 effects the colors displayed, but does not effect the orientation of the image on the display. That means we only need to be concerned with Bits 7, 6 and 5 for orientation. That gives us 2^3 orientations, which is 8. 4 of them show the image as you can read it in rotations of 0, 90, 180 and 270 degrees. The other 4 show the image in those same 4 rotations except mirrored, meaning you'd need to see the image in a mirror to be able to read it. These latter 4 are useful in head-up displays.

In BusDisplay, I created 2 rotation tables to represent the 8 possible orientations: one with the images legible, the other with the images mirrored. If mirrored==False, _DEFAULT_ROTATION_TABLE is used. If mirrored=True, _MIRRORED_ROTATION_TABLE is used. That is to say, the mirrored setting is due to my choice of how to implement rotations, not part of the DCS spec. The rotation tables are tuples (or lists) of four 8-bit integers.

The MADCTL register is written in the .init() method (not .__init__) in the line:

self.send(_MADCTL, self._param_mv[:1])

The .init() method is called by .__init__() when the BusDisplay object is first initialized and then every time .rotation is changed.

This is not a permanent fix, but while you are troubleshooting, you can set display_drv.rotation_table = (M, 0, 0, 0), where M is the MADCTL value you want to try. We leave the other 3 entries in the rotation table at 0 because we'll only troubleshoot with rotation==0. Once that is working, the other 3 rotations will be easier to determine.

I'm hoping this background gives you an idea of how to troubleshoot it. One way that comes to my mind is to do the following:

from time import sleep
from framebuf_simpletest import display_drv, main
# (The display is drawn with the settings from the default rotation table)
for m in range(256):
	print(f"Setting MADCTL to {m:#04x}")
	display_drv.rotation_table = (m, 0, 0, 0)
        display_drv.init()
	main()
	sleep(1)

This would show all 256 possible values of MADCTL without making the assumptions about bits 4, 2, 1 and 0. It will draw the display then wait 1 second.

If you only want to test some of the 8 bits, you could do it this way:

from time import sleep
from framebuf_simpletest import display_drv, main
# (The display is drawn with the settings from the default rotation table)
BGR = 1 << 3 if display_drv.bgr else 0
for MY in [1 << 7, 0]:
    for MX in [1 << 6, 0]:
        for MV in [1 << 5, 0]:
	    for ML in [1 << 4, 0]:
                for MH in [1 << 2, 0]:
		    m = MY | MX | MV | ML | BGR | MH 
	            print(f"Setting MADCTL to {m:#04x}")
	            display_drv.rotation_table = (m, 0, 0, 0)
                    display_drv.init()
	            main()
	            sleep(1)

That would keep the setting of BGR from your board_config, then test all 32 combinations of MY, MX, MV, ML and MH while leaving the last 2 bits set to 0.

---

Let's don't test with any of the BMP565 files yet. BMP565 does some advanced things that we need to ignore until we get rotations working correctly, particularly scrolling! Boxlines is a good test. It was originally written by russhughes and uses tft_config. The first thing it does is set the screen to landscape (WIDE) orientation, so we have to take that into account while we're testing. For instance, if you run framebuf_simpletest, it uses the display in whatever rotation it happens to currently be in. When you run boxlines, if leaves the rotation alone if it's already in a landscape orientation, but rotates it 90 degrees if it's in a portrait orientation. If you run framebuf_simpletest again without resetting the board, it will have the rotation set by boxlines, which will always be landscape. For this reason, it can look like you're running the same test but getting different results, when in actuality, it is a new test with the rotation set differently! In fact, it may be necessary to disable setting the rotation in boxlines.py or tft_config.py and only set it in the board_config.py while troubleshooting. I added this line to BusDiplay so you we can see when a device changes it's rotation:

print(f"{self.__class__.__name__}.rotation():  Setting rotation to {value}")

While writing this up and thinking about the results you saw, I realized that I was using ._colstart and ._rowstart in .blit_rect() without taking into consideration the rotation of the display. I have now added properties for .colstart and .rowstart that return the values of ._colstart and ._rowstart IF the rotation is 0. I need to flesh out what those two properties should return at other rotations. Up to this point, I haven't needed to know the width and height of the display controller, but instead only relied on the width and height of the display itself. If the display controller width is 240 and the display width is 170, we have the 70 pixel window I mentioned before to align the image, so we know colstart is between 0 and 70. When rotation==180, we need to recalculate the colstart from the other side of the display, so the formula is display_controller_width - display_width - _colstart. I really don't want to have to specify the display_controller_width, so I'm trying to figure out how to get that value without it. Can you think of anything?

[tdhoward]

Up to this point, I haven't needed to know the width and height of the display controller, but instead only relied on the width and height of the display itself. If the display controller width is 240 and the display width is 170, we have the 70 pixel window I mentioned before to align the image, so we know colstart is between 0 and 70. When rotation==180, we need to recalculate the colstart from the other side of the display, so the formula is display_controller_width - display_width - _colstart. I really don't want to have to specify the display_controller_width, so I'm trying to figure out how to get that value without it. Can you think of anything?

There may be some display controllers that can be queried for their max width/height capabilities, but I'm not sure how many would do provide that. The st7789 isn't one of them. This doesn't feel like a great solution, but we could hard-code the display controller max width/height into the init function for each driver. At least we know it isn't changing.

[bdbarnett]

@tdhoward I fixed a couple errors in colstart() and .rowstart() that I added today. Also, I referenced these Arduino drivers for ST7789 and see that for an ST7789 connected to a 170-pixel wide display, colstart is 35 for portrait orientations while rowstart is 0, and they are swapped for landscape orientations. I updated BusDisplay to do the same thing.

Hopefully we won't need to specify the display controller dimensions after all. I haven't implemented reading from the display and don't plan to, so that would leave out querying the display even if the display allowed it. I like your idea of putting it in the __init__ of the display driver, but I'm hoping to maintain compatibility with CircuitPython's DisplayIO drivers, so I don't want to require editing them. If something has to be done, I'm leaning toward adding optional cgram_width and cgram_height parameters to BusDisplay and setting them to .width and .height if not specified and colstart and rowstart are 0. If cgram_width is not specified but colstart is, raise an error.

[tdhoward]

@bdbarnett When using the latest code on the T-Display-S3, I'm getting consistent behavior between framebuf_simpletest and boxlines, so that is great. I get this message from boxlines, but not from framebuf_simpletest: "ST7789.rotation(): Setting rotation to 90".

At this point, all my focus is going to be on getting the S3-Pro screen working, since I need that for the class I'm teaching.

[bdbarnett]

@tdhoward If you still have no display on the ST7796 on T-Display-S3 Pro, set the SPI baudrate=40_000_000. I found that setting here. If you still have no display, you can try changing the SPI id= to something from 0 to 5. On ESP32, the ID is usually 1, but I hate to assume it always is. You can also try changing reset_high=False, which is unlikely, but possible.

If none of those work, I just ported the TFT_eSPI ST7796 driver to this driver for you. It shouldn't make a difference, but it's worth a shot if everything else is failing.

[tdhoward]

@bdbarnett Thanks for all your work on this! I was also poking through the TFT_eSPI driver for the ST7796. I only had to make a few adjustments to the board_config, and the display seems to be working! It's giving me the correct colors and orientation, and lines up with the edges perfectly. I'll do a PR for the T-Display-S3 Pro board_config.py, but I'm still working on the touch driver.

[bdbarnett]

@tdhoward Fantastic! You are welcome, and thank you for submitting the PR. Looks like my blunders were swapping colstart with rowstart, and, more importantly, having the polarity of reset wrong.

Let me know if I can help in any way. I'm taking a bit of a break from adding features or changing how things work, but I'd be glad to address any bugs or explain anything you need me to.

[tdhoward]

@bdbarnett Thanks! I so appreciate your help. Maybe I'll ask my ST7796 (S3 Pro) questions on the other thread. I'm really happy with this progress.