Boards and displays

Every field on the Board, Display, Touch and Inputs tabs, and the tables behind them.

The Hardware tab describes the board the firmware will run on. A preset fills most of it in; this page explains every field so you can fill in a board that is not listed, or fix a preset that does not match the revision in your hand.

Board

The Board tab has the preset list, filterable by brand, and below it the three things a preset decides first: the MCU, whether PSRAM is enabled, and the FQBN - the fully qualified board name the Arduino CLI and PlatformIO use, such as esp32:esp32:esp32s3. Choosing a preset overwrites the Display, Touch and Inputs tabs and the graphics library; it leaves your buses, devices, I/O, variables and automations alone.

Presets

Custom / breadboard wiring starts from an ESP32-S3 with LovyanGFX and nothing assigned, for hardware you wired yourself.

MCUs

The MCU decides which GPIOs exist, which are input-only, which carry warnings (flash, strapping, UART), which have ADC channels, whether PSRAM is possible, and which graphics libraries and buses are available.

Display

The Display tab: the panel Controller, the Bus, the pins for that bus, the Width and Height, Rotation (0, 90, 180 or 270), Colour depth, Colour order (RGB or BGR - the fix for red and blue being swapped), Invert (the fix for a negative image), and the bus options - the SPI clock in MHz, the SPI mode, and 3-wire for a 9-bit serial panel with no DC pin. The validator checks the resolution against what the controller documents and warns when it is not one of them.

Buses and their pins

Set a pin to -1 when the board does not wire it (a display MISO that is not broken out, a CS tied low). The validator treats optional pins as optional and complains about required ones.

Control lines on an I/O expander

On a growing number of boards the panel reset, the backlight enable and the touch reset are not wired to GPIOs at all - they sit behind an I/O expander on I2C. The Waveshare ESP32-S3-Touch-LCD-4.3 puts all three on a CH422G. For those, the RESET pin of the display and of the touch controller, and the backlight pin, can be set to a pin on one of the project's I/O extenders instead of a GPIO: the pin picker gains an On an I/O extender group once an extender exists on the I/O tab. The generated sketch then brings the expander's bus and the expander up first (hw_init_early()), pulses the resets through it, and drives the backlight through it - on or off, since an expander pin cannot PWM. The pin header records where each line went (#define LCD_RST -1 // RESET - on CH422G pin 3) and the README wiring table says CH422G pin 3 rather than a GPIO.

Presets bring their own kit

Some presets add more than pins. Choosing the Waveshare 4.3" adds the I2C bus on GPIO 8/9 and the CH422G on it, with the three control lines already routed; the two Cheap Yellow Displays add their CN1 connector as an I2C bus on GPIO 27/22; the M5Stack Core2 adds Port A on 32/33. These items are tagged with the board they belong to: they survive re-applying the same preset, are dropped when you choose a different board, and never touch buses or devices you added yourself. Add a sensor to a board bus exactly as you would to one of your own.

Backlight

Pin, Active level, and PWM dimming, which on an ESP32 uses an LEDC channel at the PWM frequency you set, starting at the Default %. Without PWM the pin is simply driven to the active level. An AMOLED has no backlight pin; brightness is a controller command, which the driver handles.

Panel controllers

Thirty-six, across SPI, QSPI, 8- and 16-bit parallel, RGB565 and MIPI-DSI. Each entry knows which buses it supports, the resolutions it is sold in, and the driver symbol every graphics library expects for it.

Graphics library

The library that drives the panel and gives LVGL its flush callback. Which ones are offered depends on the MCU and the bus:

TFT_eSPI is configured by a generated User_Setup.h (and the same defines in platformio.ini); LovyanGFX by a generated LGFX_Config.hpp device class; GFX Library for Arduino and esp_lcd in the sketch itself.

Touch

The Touch tab: the Controller, then the pins and options for its bus. An I2C controller takes SDA, SCL, an optional INT and an optional RESET, its I2C address, the I2C clock and whether it shares the display's I2C bus; an SPI controller takes SCK, MOSI, MISO, CS and an optional IRQ, the SPI clock and whether it shares the display's SPI bus (on by default, and right for most boards). Sharing is what lets the validator accept the same SCK on both without flagging a collision.

Below that, Swap X/Y, Invert X and Invert Y fix a touch that lands in the wrong place after rotation, and for a resistive controller a Calibration block holds the raw minimum and maximum in each axis.

Most capacitive controllers are read by generated register code over Wire and need no library; the ones that do list it in LIBRARIES.md.

Inputs

The Inputs tab adds LVGL input devices that are not touch:

• Rotary encoder - phase A and B pins and an optional push switch, with internal pull-ups, a reverse-direction option and the steps per detent. LVGL moves focus through a group of widgets, so an encoder needs widgets added to that group to reach them.
• Button pad - up to six buttons (up, down, left, right, enter, escape), each optional.
• Matrix keypad - row and column pins.

How pins are checked

Every assigned pin is checked against the MCU on every edit, and the result appears in the Check tab, the Errors tab and the export dialog:

• The pin must exist on the MCU.
• An input-only pin cannot drive CS, DC, RST or the backlight.
• Strapping and flash pins produce a warning naming the risk. They often are the right pin - the Cheap Yellow Display uses GPIO 2, 12 and 15 - so a warning is not an error.
• Two signals on one GPIO is an error, unless they are the shared lines of one named bus.
• The controller must support the bus, the MCU must have the bus, and the graphics library must have a driver for the controller on that bus.
• An RGB panel needs PSRAM; MIPI-DSI needs an ESP32-P4; an SPI clock above what the controller usually tolerates is warned about; a draw buffer too large for the MCU is warned about.

Rendering settings

In the export settings (Export > Export UI code > settings): Buffer height is the partial draw buffer in lines - 40 by default, and the first thing to lower on a small MCU; Double buffer allocates two so LVGL can render one while the other flushes; Buffer in PSRAM puts them in external RAM on boards that have it. The sketch reports draw buffer allocation failed - lower DRAW_BUF_LINES on the serial monitor if it cannot get the memory.