The one line that changes
One constant in the sketch resolves the driver chip, the resolution, the SPI clock, the backlight polarity and the memory offsets. Swapping panels changes that token and nothing else — which is only true because somebody wrote the table down.
One token, five answers
LB_TFT_24 is not a resolution and it is not a chip name. It is a row in a
table, and the row holds five things the driver needs before it can put a single
pixel anywhere: which controller is behind the glass, how many pixels there are,
how fast the bus may run, which way round the backlight is wired, and how far
into the controller's memory the visible pixels start.
Change the constant and all five change. Nothing else in the sketch does.
Why the offsets exist at all
A display controller has a fixed amount of pixel memory, and the glass in front of it is sometimes smaller. An ST7735 has room for 132 × 162 pixels; the 0.96 inch panel shows 80 × 160 of them, starting 24 columns in.
Get that wrong and the picture is not missing, it is shifted — text runs off one edge with a band of junk down the other. It is one of the most common symptoms people post about these panels, and it is not a fault. It is a driver that was never told where the window is.
What the table is, and how much to trust it
The constants come from a file called panels.yaml in the
display library, which
is the single source of truth for both the Arduino side and the MicroPython
side — both are generated from it, and the library's own tests fail if the two
ever disagree.
It is worth being honest about how solid each column is. The driver chips and resolutions are firm: they match the product listing's own comparison table for all six panels. The SPI clocks are conservative choices rather than measurements — the old per-panel Arduino sketches ran at 40 MHz and the MicroPython ones at 20, and the library took the lower figure until somebody checks. The colour order and inversion flags have not been measured on a kit panel at all, which the file says in a warning at the top of itself.
That last one matters less than it sounds, because a colour fault announces itself immediately and takes one call to fix. There is an article on reading the symptom.
MicroPython says the same thing
from lb_display import LBDisplay
from lb_panels import TFT_24 # the only line that changes
d = LBDisplay(TFT_24)
d.begin()Same table, same six names without the LB_ prefix, and the pins are picked at
runtime from the chip the script is running on rather than at compile time. One
script runs on a classic ESP32 and an ESP32-S3 unmodified.
When it does not work
Yes, and you will be supplying the table yourself. Those libraries drive these controllers perfectly well, but they do not know that this 0.96 inch panel starts 24 columns into the controller's memory or that its backlight is active low, so you have to find those values and configure them. That is the work the panel constant exists to avoid.
That is a column offset, and on the 0.96 inch it is 24. The glass is smaller than the controller's memory, so the driver has to be told which part of that memory the visible pixels correspond to. The library carries the offsets per panel; a hand-configured driver usually does not.
Mostly not, and the library says so in its own panel file. The resolutions and driver chips are solid and agree with the product listing. Several of the clock speeds are the lower of two figures the old example sketches used, taken as the conservative choice until somebody measures the panels properly, so treat them as safe defaults rather than limits.
Often. setSpiHz before begin overrides it, and on a short ribbon a panel that ships at 20 MHz may be happy at 40. The symptom of too fast is a scrambled or half-drawn picture rather than a crash, so it is a safe thing to experiment with — raise it, look at the screen, and back off if the image breaks up.
The self-test sketch, the Tools settings it needs, and what each stage of the boot proves.
First light →Edit this page — content/books/spi-tft-kit/one-line-changes.mdx
Questions about this product
See what other owners have asked, and read their solutions.
SPI TFT LCD Display Kit, 6-Pack from 0.96 to 3.5 inch
Loading discussions…
Discuss this article
Ask about this page. The answer stays here, on the page it belongs to, for whoever hits the same wall next.