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.

A board sold in two revisions

A few boards are sold under one name in two revisions on the same pins. The Waveshare ESP32-S3-Touch-AMOLED-1.8 (and the ESP32-C6 version) is one: a V1 has an SH8601 panel and an FT3168 touch chip, a V2 a CO5300 panel and a CST820 touch chip, with the picture 16 columns in. V1 has not shipped since 30 May 2026, and the back of the board is not always labelled.

Each revision has a preset of its own, and the export of either one runs on both: at start-up it asks the touch chip which revision answers and drives the panel that board has, as Waveshare's own firmware does. The Serial Monitor (115200) says which it found, for example touch: CST820 answering at 0x15 - this is the V2 board. This needs a design whose hardware is still the preset's own: if you changed its panel or touch settings, choose the preset that matches your board instead. Seen working on a V2 board.

Board

The Board tab has the preset list, filterable by brand, and below it what a preset decides first: the MCU; on an ESP32, the module's Flash and PSRAM and how its flash is divided (Partitions); and the FQBN - the fully qualified board name the Arduino CLI uses, with those settings as options, such as esp32:esp32:esp32s3:FlashSize=16M,PSRAM=opi,PartitionScheme=custom. Choosing a preset overwrites the Display, Touch and Inputs tabs, the graphics library and the module's memory; it leaves the partition layout, your buses, devices, I/O, variables and automations alone.

Flash, PSRAM and partitions

Flash and PSRAM are the code at the end of an ESP32 module's part number: ESP32-S3-WROOM-1-N16R8 has 16 MB of flash and 8 MB of PSRAM. A preset fills in its board's. PSRAM is listed as quad or octal because on an ESP32-S3 they are different builds - R2 and R4 modules are quad, R8 and R16 octal - and firmware built for the wrong kind finds no PSRAM at boot. The WT32-SC01 Plus, for one, is N16R2.

Partitions divides the flash between the firmware and the filesystem your images and the touch calibration live on:

The export writes the table as partitions.csv beside the sketch, which PlatformIO and the Arduino IDE both use, and puts the flash size and PSRAM kind in platformio.ini; its README lists the matching Arduino IDE settings. On 4 MB, Big app is the Arduino core's own Huge APP scheme and Half and half its No OTA (2MB APP/2MB SPIFFS). The image budget on the Assets tab is the filesystem partition. The MicroPython export takes the flash size and PSRAM kind, but sizes its own app partition to the firmware.

A design with a Firmware update widget is given two app partitions in place of one - the firmware running and the one arriving over the network - each half the size the layout would have given one. The filesystem is unchanged. Nothing has to be chosen: it follows from the widget being there, and going back to one is deleting it.

Presets

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

Every preset also has a public page with its full pinout and what to check on your revision - see Boards.

Switching off on a battery: the power key

Some boards keep their battery connected only while the program holds a line high. On those the designer gives the board its maker's power key, on the Board tab under Power key (on to start with):

• Hold PWR to switch the board on, until the screen shows.
• RESET switches it off, as the board's own firmware does. A restart of the program's own - an update, Wi-Fi set up from a phone - keeps it on.
• Hold PWR while it runs (1 to 2 seconds, as the maker's own firmware times it) and it switches off.
• The action Power off switches it off from a button or an automation.

On USB the board stays on whatever it is told. Every export (Arduino, ESP-IDF, MicroPython and ESPHome) writes it, for these Waveshare boards: ESP32-S3-Touch-LCD-3.49, 1.46B, 1.69, 1.85, 2.8 and 2.8 V2; ESP32-S3-LCD-0.85 and 1.54; ESP32-C6-LCD-1.69 and C6-Touch-LCD-1.69; ESP32-S3-Touch-AMOLED-1.32 and both 2.41s; ESP32-C6-Touch-AMOLED-1.32 and 1.43.

Boards with an AXP2101 power chip (Waveshare's AMOLED 1.75, 1.8, 2.06 and 2.16 among them) need none of this: the chip switches the board off itself when PWR is held for about six seconds, and on with a press, whatever program runs.

Testing a board

Test my board, on the Board tab and in the Help menu, opens a known-good test project for the board the design is on: colour squares that name themselves, a frame on the edge of the glass, keys that say which was tapped, the backlight on a ring, and a line for each part the board has. Generate it and flash it like any design, and in a minute you know whether a dark or wrong screen is the board or the design. On a preset it is made from the preset as it ships; on Custom wiring, or a board under My boards, from the design's own wiring. It holds nothing that is part of Pro. What each screen shows is on the troubleshooting page, and in the README of the test's code.

Your own boards

A board you designed yourself is in no preset list, so its pins have to be set by hand. With My boards you set them once. Describe the board on the Hardware tabs as usual, starting from Custom / breadboard wiring or from the preset nearest to it. Then open My boards on the Board tab, choose Save this hardware as a board, and give it a name. The note is for you, for the revision or where the schematic is kept. The board is then a card under My boards, on the Board tab and in the board step of File > New project, and choosing it puts that hardware on a design as a preset does.

A saved board holds the MCU, the module's flash, PSRAM and partition layout, the graphics library, the panel (controller, bus, pins, bus settings, size, rotation, colour order, offsets and corner radius), touch and the backlight. Include the devices on it is ticked to begin with, and adds the buses, I/O extenders, devices, analog and digital I/O, encoders and buttons, and the sound wiring. Sound arrives switched off in a new design, as it does with a preset. Screens, widgets, variables and automations belong to a design and are never part of a board.

Saving runs the checks the Check tab runs. Hardware with an error is not saved, and the dialog lists each error in the Check tab's own words: a pin the chip does not have, a pin wired to the module's flash, two signals on one GPIO. Warnings do not stop a save.

Using a board copies its hardware into the design. Devices you added to the design yourself stay, and the devices of the board it was on before leave, as when you change preset. The line under the list then reads From your board. After that the design and the board are separate, and the Board tab says when they differ:

• Change the hardware in the design and the line offers Update the board, which writes the design's hardware back to the board.
• Update a board and every design already made from it keeps the hardware it has. Each one says the board has been saved again since, and Use the new version brings the change in.

A design made from one of your boards exports exactly the files the same pins set by hand export. Its README and sketch call it custom wiring. The board's name is kept in your account and not in the design, so it does not go with a design you publish to the gallery or attach to a fault report.

The gear beside a card has four entries. Update from this hardware replaces the board with the open design's hardware. Rename, or edit its note changes neither pins nor devices. Export to a file writes <name>.lwboard.json, to keep a copy or to hand the board to a colleague. Delete asks first, and leaves the designs made from the board as they are. Import a board file, under the list, reads an exported file and checks it exactly as a save is checked.

A name is used once per account, whatever its capitals. Saving under a name you already use asks whether to update that board. An account holds up to 30 boards. A board the project's target cannot build for is greyed and says why, as a preset is: an STM32 board in a MicroPython project, for one. Your boards are offered to nobody else and do not appear on the public Boards pages.

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.

A kit can be more than a bus. Waveshare’s 4.3" and 7" boards arrive with their TF card slot, RS485 line, CAN bus and sensor input as well, each with a line on its card saying what is particular to it on that board; those two have a page of their own, which the Board tab links to when either is chosen. A part a target cannot drive is left out of the kit for that target, and the export’s README says which and why.

Backlight

Pin, Active level, and PWM dimming, which on an ESP32 uses an LEDC channel at the PWM frequency you set (analogWrite on RP2040 and STM32, LovyanGFX's own light driver on LovyanGFX boards), starting at the Default %. Without PWM the pin is simply driven to the active level. To let people change the brightness on the device, give a slider or a pair of buttons a Set backlight event; the preview dims the whole screen to match. The level is not saved, so every boot starts at the Default %. The sketch starts the backlight after the panel, because TFT_eSPI's begin() takes a PWM pin back for itself, and exposes backlight_set(percent) and backlight_get() for your own code.

An AMOLED has no backlight pin. The panel is its own light, and how bright it is is a command to its controller. On such a board the section says so and has one setting, Default %, and a Set backlight event works as it does anywhere else: a slider or a pair of buttons changes the panel's brightness, the preview dims with it, and backlight_set(percent) sends the command. That is so in all three exports that drive the board - in ESPHome the panel becomes a light called Backlight. Leave the pin unused unless the board really has a backlight line as well.

A backlight on an I/O extender's own PWM channel (Waveshare's IO extension has one) dims like a pin with PWM; on an ordinary extender pin it switches on and off.

A backlight that is a device on I2C. Some screens set their backlight as a register of a small chip on the I2C bus rather than on a pin: Waveshare's DSI-TOUCH-A screens for the ESP32-P4-NANO use register 0x96 of a chip at 0x45, written 0 to 255. Set Driven by to A device on I2C, and give the bus (the touch panel's own, or one of the design's I2C buses), the address, the register and what is written for 100 %. Start-up writes are sent once, in order, before the panel starts - on those Waveshare screens the same chip switches the panel's supplies and its reset, so their four writes are what bring the panel up at all. The presets for those screens fill all of it in. A Set backlight event dims it as it would a pin, and the serial monitor says if the chip did not answer. Arduino export only.

Screen off when idle

Below the Backlight section, Screen off when idle puts the light out when nothing has happened for a while, the way a watch or a phone does. Tick Switch off and give it Off after, in seconds. Dim first turns it down to Dim to % after Dim after seconds, before it goes off. Nothing happening means no touch, no turn of an encoder and no press of a key, which is LVGL's own count of inactivity. Two more things can count:

• Wake on motion: one of the design's motion sensors (a QMI8658, an MPU6050 or an ADXL345, under Hardware > Devices). A change of acceleration between two readings larger than the Sensitivity (0.05, 0.15 or 0.4 g) wakes the screen and keeps it on while the board moves. The sensor is read at its own Poll, so a slow poll is a slow wake.
• Wake button: a digital input of the design. A press wakes the screen. Whatever else that input is set to do still happens.

The touch that wakes a dark screen presses nothing. It is kept from the screen until the finger lifts, so the button under it is not pressed. A finger already down when the screen went out does not wake it until it has lifted and pressed again. A dimmed screen can still be seen, so a touch on one goes through to what it touches and lights the screen again.

The light comes back at the level it had. A Set backlight while the screen is dark or dimmed sets the level it comes back at. LVGL goes on running while the screen is dark - timers, bindings, drawing - so what lights up is current, and nothing is skipped.

The same works with the timeout off. Wake the screen and Screen off now are actions for any event, a timer or an encoder. Screen went off and Screen woke are triggers for an automation. Screen is on and Seconds with nothing happening are sources for a variable. In Preview the timeout runs: the panel dims and goes dark after its times, a click on a dark panel wakes it without pressing anything, and the data drawer has Move the board and Press the wake button for the motion and the button a browser does not have.

What goes dark. Whatever the board's backlight is: a GPIO with PWM goes to 0 % and back, a pin that only switches is switched (it cannot dim, so Dim first leaves it lit until it goes off), a line of an I/O expander is switched, Waveshare's IO extension's PWM channel goes to 0 %, a register on I2C is written 0, and an AMOLED is sent a brightness of 0. A board whose light cannot be switched - no backlight pin, no power-chip line and no brightness command - greys the section and says why.

Each export. Arduino, MicroPython and ESP-IDF write all of it. On ESP-IDF an AMOLED is greyed: that export does not send an AMOLED its brightness command yet. On Arduino an AMOLED is sent it through GFX Library for Arduino, so choose that library on the Board tab. ESPHome has its own idle handling and the export uses it as ESPHome has it: on_idle puts the light out and lvgl.pause stops drawing, a touch resumes it (ESPHome's resume_on_input, on by default, which also keeps that touch from the widgets), and Screen went off and Screen woke are on_pause and on_resume. ESPHome's own defaults stand: its light fades over a second, and it stops drawing while the screen is dark. Dimming first, motion, the wake button and the two variables have nothing of ESPHome's to be written as, so on ESPHome they are greyed and the export says it leaves them out.

Panel controllers

Forty, 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.

MIPI-DSI is the ESP32-P4's bus, and the Arduino export drives it through GFX Library for Arduino: the JD9365 (800×1280, Waveshare's 10.1" panel among them), the EK79007 (1024×600, Waveshare's ESP32-P4-WIFI6-Touch-LCD-7B and Elecrow's CrowPanel Advanced P4) and the JD9165 (1024×600, VIEWE's 7" ESP32-P4 SmartDisplay and Guition's JC1060P470C, whose panel makers' own start-up tables the export writes into the sketch). Guition's board changed its panel in 2026: one whose label says V2 takes the V2 sequence its preset starts with, an older one the library's table. It needs PSRAM, two data lanes and a start-up sequence that suits the glass, which the Display tab lets you choose. These panels are compiled and have not yet been seen on a board by us; the ILI9881C is listed and is not supported yet, and the designer says so where you would pick it. The MicroPython and ESPHome exports do not write MIPI-DSI panels yet.

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 describe how the touch layer is bonded to the glass, in the panel's own axes; the firmware then turns each press to follow the display's Rotation by itself. For a capacitive controller they are the whole answer - flip them until a press lands where you touch. For a resistive controller a Calibration block follows, with Calibrate touch on the board (on by default) and the raw minimum and maximum in each axis. With calibration on, the range and the three switches are only the starting point: the board measures all of them from your taps, as below.

Calibrating on the board

A resistive panel read with generic numbers lands tens of pixels off, so by default the firmware calibrates itself. The first time the board starts it shows a cross near each corner; touch the centre of each one. The four readings are fitted together, so one slightly off tap nudges the result rather than skewing it.

Nothing about the touch layer is taken on trust. The fit tries both ways of pairing the controller's two channels with the panel's two axes and keeps the one both axes follow, and the direction of each axis falls out of the same fit - so a touch layer bonded swapped or mirrored calibrates correctly whatever the Swap and Invert switches say. Every tap is then pushed back through the same code the running firmware reads touch with, and has to land within 30 pixels of its cross.

The screen says how it went. Touch calibrated shows which way round the axes turned out to be and that the file was saved. Calibration failed says why - the readings did not follow the crosses, or a tap landed too far off - and a tap tries again; if nobody taps for 15 seconds the board carries on with its previous values and tries again next boot. A calibration that worked but could not be written to flash says so too.

The result is kept in /touch_cal.txt on the flash filesystem. That file always exists - the export includes it as data/touch_cal.txt with the numbers from the Calibration block, and the board writes it with those numbers if it is missing - and reads like this:

touch_cal_ran=1
firmware=3f9c1e...
swap_xy=1
x_min=212
x_max=3871
y_min=3702
y_max=355

swap_xy=1 means the controller's X channel runs along the panel's Y axis, and a min above its max - y above - means that axis runs backwards.

It runs again after every new firmware upload. The file records a hash of the firmware it was made with; flashing different firmware changes that hash, so the next boot calibrates afresh. To recalibrate without reflashing, hold a finger on the screen for a second while powering on, or set touch_cal_ran=0 in the file.

Open the serial monitor at 115200 to watch it: why it ran, the raw x and y of every tap, both fits, the one it chose, where each tap lands afterwards, and the file as it was saved.

It is on for every resistive board and can be switched off on the Touch tab, which then fixes the Calibration block's range into the firmware. On LovyanGFX boards the library draws its own corner markers and the file holds its eight calibration values instead. Two limits: the file needs a flash filesystem, which is only set up for the ESP32 family so far - on the RP2040 and STM32 boards the range is used as it stands - and on boards whose image assets already live on flash it shares that filesystem and never formats it.

Most capacitive controllers are read by generated register code over Wire and need no library; the ones that do list it in LIBRARIES.md. All of the touch code - the reads, the recovery below, the calibration and the LVGL input device - is generated into touch.cpp, beside the sketch rather than inside it.

When a touch controller stops answering

A touch controller is not reset when the MCU reboots, so one that has wedged - interrupted mid-transfer by an upload, or browned out - would otherwise stay dead until the power is removed. The firmware resets it on every boot: it pulses RESET (on a GT911 with the INT pin held to pick its I2C address, which it otherwise chooses at random), clocks the bus free if the controller is holding SDA low, and prints whether it answered. While running, twenty failed reads in a row - about half a second - reset it again, at most every three seconds. A CST816S or CST820 is told not to fall asleep, since asleep it stops answering on I2C until touched. On LovyanGFX boards the library does the reset from the same RESET pin.

An XPT2046 has no reset pin and remembers its last mode through a reboot, including one with its pen interrupt switched off - so the firmware always leaves it switched on, sets it again at boot, and re-arms it twice a second while nothing is pressed.

An I2C touch controller owns Wire. A bus on the Buses tab with the same pins shares it; one on other pins - the capacitive CYD's CN1 connector, say - starts at Wire1.

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. It can fire events as well, or instead: an automation runs on Encoder turned and Encoder pressed, and with Navigate the screen with it switched off that is all the knob does - a volume control that sends a Bluetooth media key, say.
• 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.