ST7789 IPS TFT

The small IPS color TFTs: the square 1.3 inch 240x240 board, the 2 inch 240x320, and the 1.14 inch 135x240 on the TTGO T-Display.

Aliases: 1.3 inch IPS, ST7789V, 240x240 TFT. The controller speaks the same command set as the ILI9341, and the same code in Mokxi runs both.

Pins

Pin	What it does
GND	Ground.
VCC	Supply, 3.3 V.
SCL	The SPI clock. It is not I2C, whatever the name says.
SDA	The SPI data in.
RES	Reset, active low.
DC	Low for a command, high for data.
CS	Chip select, active low. The 1.3 inch board has none; leave it unwired.
BLK	The backlight. Pull it low and the picture goes out.

Properties

size: 240x240 (the default), 240x320 or 135x240. Match it to the numbers the sketch passes to init().

What the model gets right

The offsets. The chip always has 240x320 of memory. The 240x240 glass is the top 240 rows of it, so a rotation that counts rows from the bottom has to start at row 80, which is the 80 in every ST7789 library. The 135x240 glass is a window from column 52 and row 40. The part stores only the glass, so a driver with the wrong offset draws where nobody can see, as it does on the bench.

The inverted glass. IPS panels show the controller's colors inverted, and every ST7789 driver sends INVON (0x21) to put them right. Leave it out and the picture is a photographic negative: white is black. That is modeled.

No chip select. A CS left unwired is taken as tied to ground, the way the 1.3 inch board has it. With nothing to mark where a byte starts, the hardware reset on RES is what lines the bits up, so a driver without a reset pin has to be lucky here as on the bench. The chip samples on the rising clock in either SPI mode, so the mode 3 that the no-CS boards are usually driven in works, and so does mode 0.

MADCTL rotation, the window, 16-bit and 18-bit pixels, sleep and display on and off behave as on the ILI9341.

What it does not model

The color order bit, 12-bit color, register reads, timing (the waits after reset and sleep-out are not enforced), gamma, frame rate, partial mode and scrolling. The 170x320 and 240x280 panels are not in the size list.

Code

#include <SPI.h>
#include <Adafruit_GFX.h>
#include <Adafruit_ST7789.h>

Adafruit_ST7789 tft(-1, 9, 8);   // no CS; DC, RES. SDA on 11, SCL on 13

void setup() {
  tft.init(240, 240, SPI_MODE3);
  tft.setRotation(2);
  tft.fillScreen(ST77XX_BLACK);
  tft.setTextColor(ST77XX_WHITE);
  tft.setTextSize(2);
  tft.setCursor(10, 10);
  tft.print("ST7789");
}

void loop() {}

Adafruit_ST7789.h is Mokxi's own, on the same calls as upstream. It works the offsets out from the geometry for each rotation and sends INVON at start-up, and invertDisplay(true) shows the negative. A TFT_eSPI sketch needs its drawing calls moved to these; they are the same Adafruit_GFX ones under other names.

Common mistakes

A size that does not match init(). A hand-written driver without INVON. Taking SCL and SDA for an I2C bus.

See it in action

Two color screens at /templates drives this panel, with no chip select and on pins of its own, beside an ST7735. Or wire one as the code above says and paste the sketch in. Then change setRotation(2) to setRotation(0): the text is still on the glass, because the header now starts its rows at 80. A driver that did not would draw it off the bottom of the memory the glass shows.