SPI TFT kit/One line of code/07. The one line that changes
One line of code · 07 of 12

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

One constant, five answers
LB_TFT_24
Panel
Arduino
LB_TFT_24
MicroPython
TFT_24
Driver
ST7789
Five settings, none of them yours to remember. The ST7789 at 240 × 320 runs at 40 MHz with an active-high backlight and no offsets. Swap to another size and every one of those can change while the rest of the sketch — the wiring, the drawing calls, the loop — does not.

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

Can I use TFT_eSPI or Adafruit_ST7789 instead?

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.

My picture is shifted sideways by a couple of dozen pixels

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.

Are these numbers measured?

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.

Can I run faster than the default clock?

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.

Where this goes next

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

Community

Questions about this product

See what other owners have asked, and read their solutions.

Ask a question ↗

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.

Browse Modules and blocks on the forum