When nothing appears
Seven of the eight holes have to be right before a picture is drawn, and a dark screen is most often the eighth, BL, because the board holds the lamp off until it is driven. Here is how to tell the faults apart with nothing but the screen in front of you.
Pull one wire, see what happens
Step through the seven. Each one disconnects a single hole and shows what that fault usually puts on the glass, which is the only evidence most people have before they own a meter. The pictures are the typical behaviour, not measurements on these boards.
The first one is the one to rule out before any other, and it is the one that looks the worst.
Dark, or white?
Dark means the lamp is off, or there is no power. The lamp is off until BL is driven: the board holds it off with a 10 kΩ resistor, on all six boards, so a BL that is unconnected, never set, or tied the wrong way for that board draws a perfect picture on a dark screen.
So resolve it the free way: tilt the screen towards a lamp and look at it at an angle. If you can see the picture in the reflection, everything works except the lamp. If there is nothing there either, it is power or ground, and the lamp, which runs from the same 3V3, is dark for the same reason.
White means the lamp is on, so 3V3, GND and BL are fine, and the controller has not been given a picture. Most glass of this kind comes up white, or noisy, so white is the resting state of a display that is alive and unaddressed. It clears three holes in one look and leaves the five that carry the signal.
Among the signals, DC first
Of the five signal holes, DC is the one that goes wrong most.
It says whether the byte on the wire is a command or a pixel. With it stuck in one state, every command is written into the picture or every pixel is executed as a command, and the result is white, or noise, or an image assembled out of garbage. It is also easy to mis-wire because it is the hole with the least memorable name.
RST is next. The controller needs a clean reset pulse before its initialisation sequence means anything. Miss it and the commands may land on a chip that was not listening, and the panel stays in whatever state it woke in.
CS has to be held low for the controller to listen, and nothing on the board holds it there for you unless you bridge the CS jumper. A floating CS gives unpredictable results, which is why this one is worth wiring even when it seems to work.
SCL and MOSI fail together and fail totally: nothing arrives, and the panel stays exactly as it powered up.
The order worth working in
- Is it dark or white? Dark is the lamp or the supply; white is the five signal holes.
- If dark: tilt it to a lamp. Picture visible means BL. Nothing means 3V3 or GND.
- If white: is the cable contacts-down? It fits either way up and only one works.
- Still white: DC, then RST, then CS, then SCL and MOSI.
- Open the serial monitor at 115200 and read
printInfo(). It says which pins the library actually used, which is the thingbegin()cannot tell you.
Only after that is it worth suspecting the library. By then the serial log usually says what is wrong.
When it does not work
Tilt it under a bright lamp and look at an angle. If you can read a picture in the reflection, the board is fine and the lamp is off: drive BL (the library does it in begin(), so check the wire goes to the pin printInfo() lists) or bridge the BL jumper. If there is nothing there either, check 3V3 and GND before anything else.
White usually means the lamp is on and the controller has been given nothing it understood. That is better news than dark: it proves 3V3, GND and BL. Check the cable is contacts-down if you use one, then DC, then RST, then CS. A reset pulse that never arrived or a DC wire on the wrong GPIO both look like this.
Suspect the cable before the code. A flat cable that has been folded can break a conductor inside while looking perfect, and the fault moves when you wiggle it. The 6-pack ships three spare cables for exactly this.
That is a signal that is arriving but not cleanly: too long a cable, too fast a clock, or a 5 V host driving a 3.3 V input. Try the shortest cable, then setSpiHz with a lower number before begin, and check the logic levels if the host is not a 3.3 V board.
It does not follow. The board is written to and never read from, so begin() cannot know whether the controller heard anything; it returns false only when the SPI bus will not start. Use printInfo() in the serial log to confirm which GPIO each signal is on, and compare that list with what you wired.
Red arriving as blue, black arriving as white, and the third case that looks exotic and is not.
When the colours are wrong →Edit this page — content/books/lcd/when-nothing-appears.mdx
Questions about this product
See what other owners have asked, and read their solutions.
This page covers several products. Choose yours to see the right 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.