This uniquely-shaped TFT display features a relatively high 240x240 resolution with a high pixel density, offering crisp visuals on a full-perspective IPS screen that can be viewed from nearly any angle.
It is available in a variety of breakout board shapes:
There are subtile but important differences among the many available breakout boards that feature this display:
- Voltage: some boards have a voltage regulator and can be supplied with 3.3V and 5V. If the board has no voltage regulator, you must supply 3.3V (and cannot use 5V).
- SD Card Reader: some boards feature an SD card reader on the backside.
- Dimmable Backlight: most boards expose a separate backlight pin that you can either connect to VCC (always full brightness), or a GPIO that then can control backlight brightness via PWM. If the board does not expose a backlight pin, then the backlight is internally connected to VCC and not dimmable.
Overview
The display utilizes the GC9A01 driver, which is supported both by ESPHome and widely used Arduino libraries, which are also compatible with ESP32: Adafruit GFX library and TFT_eSPI.
| Item | Description |
|---|---|
| Voltage | 3-5V |
| Interface | SPI |
| LCD Type | IPS |
| Controller | GC9A01 |
| Libraries | Adafruit library for GC9A01 drivers, TFT_eSPI, ESPHome ILI9xxx component |
| Resolution | 240x240 |
| Colors | 262.000 (*18bit) |
| Pixel Size | 0.135x=.135mm |
| Diameter | 35.5mm (Display), 32.5mm (active area) |
| Size | 50x36mm (red), 44x36mm (blue) |
Thanks to its watch-like form factor and high pixel density, this display is ideal for unusual projects, including a home-made “smart watch”:
Pins
These are the pins and pin labels typically used with breakout boards:
| Pin | Remark |
|---|---|
| VCC | 3-5V (may depend on board) |
| GND | ground |
| SCL/SCK/SCK | SPI Clock |
| SDA/DIN | SPI MOSI |
| CS | Chip Select |
| DC/A0 | Data/Command (Data=high, Command=low) |
| BL/BLK/LED | Backlight |
| RES | Reset |
For some reason, different breakout boards use different labels for these pins. The column Pin lists all commonly used labels.
Some cheap generic display boards do not have a voltage regulator. These boards work with 3.3V only and cannot be used with 5V unless you add your own voltage regulator to step down the voltage. If you use 3.3V anyway, you do not need to care. If you plan to use 5V, make sure your display board can handle it.
SPI
The SPI interface typically uses four lines. Displays only use the MOSI (main out, sub in) since there is only data travelling from the microcontroller to the display. The MISO pin (main in, sub out) for the opposite data direction is not exposed or used.
Instead, most displays use a special additional pin called DC: this pin tells the display whether the sent data is supposed to be screen content, or a specific command to control the display.
Optional SD Card Reader
The red board comes with a built-in SD Card reader. The breakout board exposes the pins for the SD card reader on the opposite site of the main pin header.
Wiring up the SD card reader is no different from a regular separate SD card reader breakout board. Here is a description.
Wiring
Here is how you wire the display to a microcontroller, with example pins for ESP32S and ESP32-C3 SuperMini:
| Display | Microcontroller | ESP32S | ESP32-C3 SuperMini |
|---|---|---|---|
| VCC | 3.3V (5V if display has a voltage regulator) | 3V3 | 3.3 |
| GND | Ground | GND | G |
| SCL/SCK/SCK | SPI Clock | 18/P18 | 4 |
| SDA/DIN | SPI MOSI | 23/P23 | 6 |
| CS | Chip Select | 22/P22 | 7 |
| DC/A0 | Data/Command | 16/P16 | 9 |
| RES | Display Reset | 4/P4 | 10 |
| BL/BLK/LED (if present) | Backlight | 3V3 | 3.3 |
Backlight Pin
If the display breakout board has no pin for the backlight, then the backlight power supply is hard-wired to VCC.
When you supply VCC to the backlight pin (or when there is no backlight pin), then the backlight always runs in full brightness.
Dimming the backlight is only possible with display breakout boards that expose a backlight pin. If so, to enable dimming connect this pin to any available GPIO (instead of VCC). In your code, use a PWM signal on this GPIO to control the brightness.
Programming
For programming, you have two options:
1. C++ Libraries
You can use C++ with one of the following libraries for full control over your display:
- Adafruit library for GC9A01 drivers: this library may only work in ArduinoIDE and fail in platformio
- TFT_eSPI: requires manual adjustment of the file User_Setup.h.
Using C++ code gives you full flexibility but requires programming expertise, as you’ll need to implement everything yourself.
Both mentioned libraries are designed for the Arduino framework so they work for Arduino and ESP32 microcontrollers and any others that are compatible with the framework. For other ecosystems, different libraries exist.
2. ESPHome
Alternatively, you can use ESPHome, which simplifies the setup and eliminates the need for extensive coding. The ILI9xxx component supports this display and is also compatible with a variety of other TFT displays, meaning any ESPHome sample configuration using the ILI9xxx component can be used with this display.
The ILI9xxx component began supporting this display in March 2024. Ensure your ESPHome installation is up-to-date.
Materials
- WaveShare Documentation: WaveShare is one vendor of such display boards, but not the only one. While the linked resource may provide helpful information, it may not fully apply to the board you use. Always make sure the boards are compatible.
Slow Website?
This website is very fast, and pages should appear instantly. If this site is slow for you, then your routing may be messed up, and this issue does not only affect done.land, but potentially a few other websites and downloads as well. Here are simple steps to speed up your Internet experience and fix issues with slow websites and downloads..
Comments
Please do leave comments below. I am using utteran.ce, an open-source and ad-free light-weight commenting system.
Here is how your comments are stored
Whenever you leave a comment, a new github issue is created on your behalf.
-
All comments become trackable issues in the Github Issues section, and I (and you) can follow up on them.
-
There is no third-party provider, no disrupting ads, and everything remains transparent inside github.
Github Users Yes, Spammers No
To keep spammers out and comments attributable, all you do is log in using your (free) github account and grant utteranc.es the permission to submit issues on your behalf.
If you don’t have a github account yet, go get yourself one - it’s free and simple.
If for any reason you do not feel comfortable with letting the commenting system submit issues for you, then visit Github Issues directly, i.e. by clicking the red button Submit Issue at the bottom of each page, and submit your issue manually. You control everything.
Discussions
For chit-chat and quick questions, feel free to visit and participate in Discussions. They work much like classic forums or bulletin boards. Just keep in mind: your valued input isn’t equally well trackable there.
(content created Jan 07, 2025)