One line of code · 08 of 12

First light

Install one library, change one constant, and the panel runs its own self-test: colour bars, a backlight sweep and its identity printed to serial. What each stage of that proves is the part worth knowing.

Four things happen before a picture

Power to picture
4 stages
Stage
Pad in use
Pads needed
7 of 8
A dark screen is not one fault, it is four possible ones. Run it and watch where the picture would have to appear. A panel stuck at stage one is a reset problem, at stage two a DC problem, and a panel that is lit but empty has already survived both — the wiring is right and the sketch simply has not drawn anything yet.

Run it. The panel is dark for the first two stages and that is correct — the backlight does not come on until the third, and there is nothing drawn until the fourth.

Knowing that order is what turns a dead screen into a question you can answer. A panel stuck before stage one has a reset problem. One stuck at stage two has a DC or a data problem. One that is lit and empty has already passed both, and the wiring is fine.

The sketch

Install Lonely Binary Display from the Arduino Library Manager — it pulls in GFX Library for Arduino as a dependency — then pick your board in Tools ▸ Board and upload.

The panel constant is the only line to change between screens. The pins are not in the sketch at all; the library takes them from the board you selected.

Read the serial log before you touch anything

Two calls in that sketch are there for the moment it does not work.

begin() returns false instead of hanging when the controller does not answer, so a failure is a printed message rather than a board that appears to have crashed.

printInfo() then prints what the library thinks it is driving: the panel, the driver chip, the colour order, the backlight polarity, and the GPIO each signal is actually on — marked as custom if you overrode them. A wiring mistake that would otherwise be a blank screen becomes a line of text that is obviously wrong.

What the self-test proves

selfTest() fills the screen with solid colours, sweeps the backlight, and finishes on a labelled colour-bar page with the panel's identity on it.

The labels are the point. Unlabelled colour bars cannot tell you whether red is coming out red — which is exactly how a colour-order mistake survived in this library's own panel table for a long time, and why the colour article is in this book.

If the sweep dims and brightens, the backlight is wired the way the table thinks it is. If it runs backwards, you have found something worth reporting.

The code

tft_self_test.ino

The library's own self-test, with the panel constant on the line it belongs on. Change that one token to run the same sketch on any of the six screens in the kit.

// First light: bring a Lonely Binary SPI TFT panel up and run its self-test.
//
// Wiring, using the ribbon: one 15-way FPC cable from the panel's socket to
// the socket on your expansion board. Contacts down — the board prints
// PINS FACE DOWN beside the connector. Nothing else to connect.
//
// Wiring, using the header instead (8 wires, ESP32-S3 defaults shown):
//   display 3V3  -> ESP32-S3 3V3       (3.3 V only, never 5V)
//   display GND  -> ESP32-S3 GND
//   display SCL  -> ESP32-S3 GPIO12    (SPI clock; the pad says SCL)
//   display MOSI -> ESP32-S3 GPIO11
//   display DC   -> ESP32-S3 GPIO2
//   display RST  -> ESP32-S3 GPIO42
//   display CS   -> ESP32-S3 GPIO10
//   display BL   -> ESP32-S3 GPIO41    (or to 3V3 to leave it lit)
//
// On a classic ESP32 the same eight wires go to GPIO 18, 23, 2, 4, 15 and
// 32 instead, and the library picks that set for you from the board you
// choose below. You do not edit anything.
//
// Arduino IDE: Tools > Board > esp32 > "ESP32S3 Dev Module" for an
// ESP32-S3, or "ESP32 Dev Module" for a classic ESP32. Tools > Port, pick
// the port. On an S3, Tools > USB CDC On Boot > Enabled so Serial reaches
// the monitor. Library: "Lonely Binary Display" from Tools > Manage
// Libraries, which pulls in "GFX Library for Arduino" with it.

#include <LonelyBinaryDisplay.h>

// The only line that changes between the six panels in the kit:
//   LB_TFT_096  LB_TFT_18  LB_TFT_20  LB_TFT_24  LB_TFT_28  LB_TFT_35
LB_Display display(LB_TFT_24);

void setup() {
  Serial.begin(115200);
  delay(500);

  if (!display.begin()) {
    Serial.println("Display did not start.");
    Serial.println("Check the ribbon is contacts-down, then check DC and RST.");
    return;
  }

  // Pins actually in use, panel identity, colour order, backlight polarity.
  display.printInfo();

  // Solid colours, a backlight sweep, and a labelled colour-bar page.
  display.selfTest();

  // Anything after this is yours. The drawing surface is Arduino_GFX.
  auto *gfx = display.gfx();
  gfx->fillScreen(BLACK);
  gfx->setTextColor(WHITE);
  gfx->setTextSize(2);
  gfx->setCursor(10, 10);
  gfx->print("Hello");
}

void loop() {
  delay(1000);
}

begin() returns false rather than hanging when the controller does not answer, which is what makes the serial log worth reading before you touch the wiring. printInfo() then names the pins actually in use — including any you overrode — so a mis-wired board shows up as a line of text rather than as a blank screen.

When it does not work

The sketch will not compile — no LonelyBinaryDisplay.h

The library is not installed. Tools > Manage Libraries, search for Lonely Binary Display, install it, and accept the prompt to install GFX Library for Arduino with it — that is the dependency it draws on. Restart is not needed, but the Examples menu only picks the new entry up after the install finishes.

It compiles, uploads, and the screen stays dark

Open the serial monitor at 115200 first. begin() returns false and prints a message when the controller does not answer, and printInfo() lists the pins it is actually using. A dark screen with a clean serial log is usually the backlight; a dark screen with a failed begin is the ribbon or DC.

Serial prints nothing at all

Either the monitor is at the wrong baud rate — the sketch opens at 115200 — or the board is not the one you selected. On an ESP32-S3 with native USB you may also need Tools > USB CDC On Boot enabled before anything the sketch prints reaches the monitor.

The colours in the self-test look wrong

That is what the self-test is for. The bars are labelled, so you can see whether red is coming out red. If it is not, the fix is one call and the symptom tells you which — see the article on colours in this book rather than rewiring anything.

Where this goes next

Two bytes a pixel at a known clock is a number, and on the 3.5 inch it is a number you can see.

How long a redraw takes

Edit this page — content/books/spi-tft-kit/first-light.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