Anyone using the ThingPulse ESP32 Color Kit Grande with micropython-nano-gui

[cpottle9]

Hi, folks I recently bought this kit
ESP32 WiFi Color Display Kit Grande.
The vendor supplies an example application in C++ using the Arduino on VS Code.
It runs fine on the board, so my soldering for the kit should be OK.

I want to code using micropython. The code in repo micropython-nano-gui looks perfect for what I want to do.

The micropython version I'm running is ESP32_GENERIC-SPIRAM-20241129-v1.24.1.bin.
I don't know if that makes a difference.

I have not been able to draw successfully.

My file color_setup.py is:

# ThingPulse Grande Kit setup
#
# Has ILI9488 
# Running on an ESP32-WROVER-E
#
from micropython import const

# WIRING for Grande Kit values from schematic
# https://thingpulse.com/wp-content/uploads/2022/10/Schematic_Color-Kit-Grande_2023-01-14-pdf.jpg

LCD_DC        = const(02)
LCD_CS        = const(15)
LCD_CLK       = const(05)
LCD_MOSI      = const(18)
LCD_MISO      = const(19)
LCD_BackLight = const(32)
LCD_RST       = const(04)

from machine import Pin, SPI
import gc
from drivers.ili94xx.ili9486 import ILI9486 as SSD

SSD.COLOR_INVERT = 0xFFFF  # Fix color inversion

# Screen configuration
# (Create and export an SSD instance)

prst = Pin(LCD_RST, Pin.OUT, value=1)
pdc  = Pin(LCD_DC, Pin.OUT, value=0)
pcs  = Pin(LCD_CS, Pin.OUT, value=1)

# turn on back light
backlight=Pin(LCD_BackLight, Pin.OUT, value=1)

# Use hardSPI (bus 1)
spi = SPI(1, 2_500_000, sck=Pin(LCD_CLK), mosi=Pin(LCD_MOSI), miso=Pin(LCD_MISO))

# Precaution before instantiating framebuf
gc.collect()
ssd = SSD(spi, height=320, width=480, dc=pdc, cs=pcs, rst=prst, usd=True)

In main.py I have:

from gui.core.colors import *
from machine import Pin
from time import sleep_ms

ssd.fill(BLACK)
ssd.line(0, 0, ssd.width - 1, ssd.height - 1, GREEN)  # Green diagonal corner-to-corner
ssd.rect(0, 0, 15, 15, RED)  # Red square at top left
ssd.rect(ssd.width -15, ssd.height -15, 15, 15, BLUE)  # Blue square at bottom right
ssd.show()

All the other files were downloaded from github in the last couple of days.

When I run the code the screen flashes as the back light is turned on.
Nothing else happens. No errors from micropython.

Any suggestions/ideas would be appreciated.

[peterhinch]

I can't see any errors here and your general approach looks spot-on.

I tend to find that a completely blank display (rather than corruption etc.) is usually down to a wiring problem.

[cpottle9]

Peter, thanks for responding.

Not completely sure, but I don't think I have a wiring problem.
As I mentioned the C++/arduino sample application thingpulse provides is able to update the display.
I double checked my solder work and I don't see cold joints or bridges.

I added some debug code to their app to print the SPI and device pin assignments.
I'm pretty sure I got them right, but not 100%.

I'm starting to suspect the display I have is not a genuine ILI9488, but a clone.
So, it works with the TFT_eSPI drivers but not your drivers.
I think I need a deep dive into the TFT_eSPI drivers in order to make progress.
I'm going to park this project for a while.

[cpottle9]

Hi Peter,
I did dig into the sample program and found that the ili9488 differs from the ili9486 slightly.
The difference I've notes so far being the ili9488 requires three bytes per pixel when writing
display data in show.

It seems I misread DISPLAYS.md.
I read entry for Waveshare Pico 3.5 to say use the ili9486 driver for ili9488.

I hacked some changes to ili9486.py and now the display updates as expected.
The rectangles and diagonal line are displayed.

Right now I'm configuring the display to use 18 bits per pixel.

I cloned your repo and will create a proper ili9488.py and and setup_example for the Grande Kit.
I am hoping to have a pull request for your consideration later this week.

I will be able to test both with the esp32 that came with the kit and Raspberry PI Pico and Pico 2.

[peterhinch]

I'm confused :) The Waveshare Pico res touch uses an ILI9488 see reference. It works fine with this setup file.

The ILI9488 datasheet is not a model of clarity, and it's easy to come away with the impression that only 3-bit or 18-bit color is supported, but section 4.7.2 states:

The available display data formats are:
8 colors, RGB 1, 1, 1 bits input (set Standard Command 3Ah, DBI [2:0] as 001)
65K-Colors, RGB 5, 6, 5 bits input data (set Standard Command 3Ah, DBI [2:0] as 101)
262K-Colors, RGB 6, 6, 6 bits input data (set Standard Command 3Ah, DBI [2:0] as 110)

My driver uses RGB565.

[cpottle9]

Peter, apologies for this long message. A character fault of mine ...

I'm confused too.
I don't want to sound like a conspiracy theorist but, I believe some web vendors are advertising the use a particular controller when in fact they use a different one (that may be fully or partially compatible).

Potentially, the Waveshare Pico you refer to is an example.
I followed your [see reference](link https://www.waveshare.com/wiki/Pico-ResTouch-LCD-3.5) link.
Part way down that page they link to a data sheet for the ST7789VW.
Further down the page they provide (incomplete) instructions for using micropython.
This includes a screen dump with:

from nanoguilib.st7789 import *
SSD = ST7789

Not definitive, but this strongly suggests the Waveshare Pico does not use an ILI9488.

The display I bought from Thingpulse does not have ILI9488 printed on it.
It has "SX035HV006FPC" printed on the cable.
I google that and I see a few hits on Chinese sites.
Google translation did not work so I don't have any details about this device.
But, the images do look like my display including "SX035HV006FPC".

When I was trying to debug my display not working I spotted commands "All Pixels OFF" (0x22) and "All Pixels ON" (0x23) in the 9488 specification.
I added a little functions to ili9486.py to send these commands and found they worked.
That is, all pixels go white or black as a result of the commands.
(This and the fact the Arduino/C++ app worked convinced me my wiring was correct).

Just now, I checked the ILI9486 and ST7789 specs I do not see these two commands.
They might be implemented on those devices but un-documented.
This does suggest I may have a real ILI9488 after all.

My next step was to read through the sample Arduino/C++ app provide by my hardware vendor.

I found the driver TFT_eSPI always write 3 bytes via SPI using this macro:

  // Convert 16-bit colour to 18-bit and write in 3 bytes
  #define tft_Write_16(C)  spi.transfer(((C) & 0xF800)>>8); \
                           spi.transfer(((C) & 0x07E0)>>3); \
                           spi.transfer(((C) & 0x001F)<<3)

They do this for both the ILI9486 and ILI9488.
Note the TFT_eSPI driver uses 16 bits per pixel in it's RAM buffer.

I modified your driver to do the same and changed the 0x3a command to have data 0x66.
My display now works.

I really can't tell you anything else. I am happy because I have my display working.
Just to double check I tried your ili9486.py, again and no, the display does not update.

Since I benefit from you providing these drivers, I would like to give back if I can.
That is why I suggested a pull request. Let me know if you would like to proceed.

[peterhinch]

The ST7789 is rated at 240x320 max, wherease the WS display is 480x320 (based on datasheets of both chips). I can therefore categorically state that they are not using ST7789. Alas Waveshare's documentation is frequently, er, sub-optimal. We end up with the following observations:

• I have no means of proving what chip Waveshare are using. However
• They state ILI9488 and it works with my driver. In the absence of contrary evidence I believe them.
• The ILI9488 should definitely accept 16 bit transfers according to the datasheet.
• The fact that your display doesn't accept 16 bit transfers suggests it's not an ILI9488.

In the absence of definitive information on what you are driving, I wouldn't accept a PR. I need a manufacturer's datasheet to validate any driver.

[cpottle9]

Peter, I understand your reasoning.

We have two vendors claiming they are using an ILI9488 yet the behaviors are different.
So one is wrong. We have no way of knowing who it is.

How do you feel about naming the driver thingpulse_grande.py (or similar) and clearly identifying the driver is specific to this kit?

[peterhinch]

So one is wrong. We have no way of knowing who it is.

Well both may be wrong :)
It does seem certain that ThingPulse is wrong because it doesn't handle 16 bit color. The ILI9488 datasheet is gospel.

My problem is that I cannot support a driver when I don't own the hardware; a problem magnified by the fact that the display driver chip is unknown (and demonstrably not what the manufacturer claims).

If you publish your driver I will link to it in DRIVERS.md and DISPLAYS.md as an unsupported (by me) driver.

[cpottle9]

Peter, please be patient with me ;-)
You might consider I've been a pain in the #$%.
I now have a theory/explanation of how both vendors are using ILI9488 but there is different behavior.

I spent quite some time looking at the ILI9488 and ILI9486 specs.
I now believe the text you quoted from section 4.7.2 of the ILI9488 spec is a typo.

The available display data formats are:
8 colors, RGB 1, 1, 1 bits input (set Standard Command 3Ah, DBI [2:0] as 001)
65K-Colors, RGB 5, 6, 5 bits input data (set Standard Command 3Ah, DBI [2:0] as 101)
262K-Colors, RGB 6, 6, 6 bits input data (set Standard Command 3Ah, DBI [2:0] as 110)

The bullet for 565 should not have been included.
Look at the table of contents, for section 4.7 and you can see no interface option supports more than 2 pixel formats.
Section 4.7.1 which describes a 3 wire SPI option does not include a 565 option.

Note that 4.7.2.1 describes a 3 bit per pixel format and 4.7.2.2 an 18 bit per pixel format.
There is no 4.7.2.3 (which might have described the 16 bit per pixel format if it existed).

The Waveshare page says under section Pinout:

The built-in controller used by Pico-ResTouch-LCD-3.5 is ILI9488, which is a 480 x 320 pixels RGB LCD controller. The test demo uses RGB565 color format. The LCD is a 16Bits parallel port screen, and the hardware uses a parallel port to serial chip, which can greatly save the GPIO port, and the maximum SPI writing speed tested is 60MHz.

On the Waveshare page I found the waveshare schematic for their board.
It is clear the SPI pins on the ILI9488 are not connected.
There are four 74XX components doing serial to parallel conversion.
So, the Waveshare is using the ILI9488 16 bit parallel interface which does support 565 format.

The board I have from Thingpulse uses the SPI pins on the ILI9488.
Check the thingpulse.

I believe this explains why 5-6-5 works for Waveshare but not for Thingpulse.

Looking at the ILI9486 spec the same is true.

[peterhinch]

You have clearly gone into this quite deeply - I hadn't seen that schematic. I have encountered the use of SPI to parallel converters on some of their displays. I believe this is done for the Arduino community to achieve high speed and 5V tolerance.

The question at issue is whether a consequence of this design is to provide support for RGB565 which would otherwise be absent. I still have doubts that the ILI9488 does not support RGB565 on SPI. I could expand on my reasons but there is little point: it either does or does not. I'm adopting the empirical approach.

I've ordered a board from eBay. It comes in two versions, a 4.0" board with ILI9486 (which I already have) and a 3.5" with ILI9488. We'll see if the 3.5" version works with my driver. It's evident from the PCBs that neither has chips for parallel conversion.

I'll report back when the board arrives and I've had a chance to test it.

[peterhinch]

Just to keep you posted I'm still waiting for this display. The vendor dispatched it over a week ago, sadly with Evri. I've asked him to chase them.

[peterhinch]

The display has arrived and, as you predicted, it does not work with the ILI9486 driver. Please could you submit a PR with your driver. I suggest we simply name it ili9488.py as it seems clear that this is the correct driver for all normally-connected chips.

[cpottle9]

Hi Peter,

I will have a pull request later in the week.
I need to do a little cleanup first.

In your documentation you should make it clear that someone using an ILI9488 with a parallel interface will be better off using the ili9486 driver.
Three bytes per pixel compared to two slows down the SPI transfer significantly.
I measure portrait ILI9488.show() as about 350 milliseconds (esp32, cpu 160 mhz, SPI 30 mhz).
Running the esp32 cpu at 240 mhz reduces the time to about 300 milliseconds.
Your comments in ili9486.py says 214 milliseconds for a PICO at 120 mhz.

[peterhinch]

Hi Carl,
I will document the issue re 3-byte transfers and parallel interface. I can't understand why the ILI9488 disallows RGB565 when using SPI. It makes no sense when the capability evidently exists on the chip. It's as if the manufacturer was deliberately aiming to hobble the device.

Apologies if you already know what follows, but the frequency of an SPI interface is typically lower than that specified in the code. To find the actual clock rate for speed testing, issue print(spi_instance).

I look forward to trying your driver.

[cpottle9]

I have a theory, but not a good one.
The ILI9488 and ILI9486 specs support at most two pixel data formats per interface type.
For comparison, the ST7789 supports three pixel data formats per interface type.

For example, the ILI9488 and ILI9486 support 16 bit and 18 bit pixels for 8 and 16 bit parallel.
For SPI (3 or 4 wire) they support a 3 bit per pixel (1-1-1) format with two pixels per byte and they support the 18 bit (6-6-6) format with 3 bytes per pixel.
I looked at the ILI9486 spec it does not document 5-6-5 for SPI either.
Do you have a ILI9486 board in you collection that does not do serial to parallel conversion?

By the way, I coded a hack driver using the 3 bit per pixel format in portrait only and no greyscale.
I don't intend to use it for my project.
If you are interested, I could clean it up, add landscape, and do a pull request.
I don't think greyscale has any value for this pixel format because greyscale just black and white.

Regarding SPI speed, I was aware the actual speed may not be what is requested from my pico experience.
But, I did not think to check the actual speed on the esp32.
Turns out it is 24 mhz.

[peterhinch]

Hi Carl,
thanks for the PR, I've tested this with my display and color tests work fine - I've yet to try monochrome image display. I'm busy today but I'll review and test this properly tomorrow.

As a matter of interest did you consider an approach whereby the LUT remained RGB565, with expansion to 18 bit occurring in the Viper code? Although off the top of my head I think your approach is probably cleanest.

[cpottle9]

Peter, I added some comments to the pull request.
One identifies a bug, I think.

[cpottle9]

Answering my own question.

No, it seems I was the first person to try using ThingPulse ESP32 Color Kit Grande.

I worked with Peter to develop a new driver specifically for the ili9488 in SPI mode.
The ili9488 only supports 5-6-5 pixel format (2 bytes per pixel) when using a parallel interface,
When using SPI a 6-6-6 pixel format (3 bytes per pixel) is required.

Some vendors do serial to parallel conversion on their display board.
So even though the microcontroller is using SPI the ILI9488 will support the 5-6-5 pixel format.
In this case the ili9486 driver can be used.
Writing 3 bytes per pixel is slower than 2 bytes per pixel.
So, the il9486 driver is preferred when it works.

Thanks Peter, for helping me get this board working.