LovyanGFX for ESP32 displays: setup choices and hardware limits

LovyanGFX's target hardware and display problem

LovyanGFX addresses a specific embedded graphics problem: driving small LCD, OLED, and electronic-paper panels from microcontrollers whose pin counts, buses, RAM, and processing resources vary considerably. It targets ESP32 boards through ESP-IDF and Arduino ESP32, ESP8266 through Arduino ESP8266, and SAMD51 boards through Arduino. The README also describes RP2040 support, including SPI, touch support for several listed microcontroller families, and separate PC and Pico SDK directories in the repository.

The library is intended for developers who already know the physical controller and connection details of their display. Its supported-controller list includes common devices such as ILI9341, ST7789, SSD1306, SH110x, GC9A01, ILI9486, SSD1331, and RA8875. It also covers boards and products including M5Stack, M5StickC, TTGO T-Watch, ODROID-GO, ESP-WROVER-KIT, and WioTerminal. The breadth matters because these products do not all expose the same controller commands, bus width, reset behavior, or pin arrangement.

This is not a generic screen abstraction that can infer hardware from a board name at runtime. Configuration remains an explicit part of using the library. That is a limitation for beginners, but it also gives an engineer control over details that matter on embedded displays, including the command interface and physical connection.

SPI, I2C, parallel buses, and transfer paths

LovyanGFX supports several transport mechanisms. The compatibility table lists SPI, I2C, and 8-bit parallel connections, with different capabilities depending on the microcontroller. Most listed ESP32 variants, ESP8266, and SAMD devices support hardware SPI. I2C is also listed as hardware-supported on several targets, while ESP8266 I2C is marked as software implemented. Parallel support is more uneven: ESP32-S2 and ESP32-S3 have listed hardware paths, ESP32-C3 is marked software implemented, and ESP32-S3 also lists LCD/CAM support.

The intended performance mechanism is DMA transfer. The README says LovyanGFX can execute another process while display communication is in progress through DMA. That matters for applications that must avoid blocking the main control loop during a large transfer. It does not mean every supported bus or platform uses DMA in every mode, so the bus-specific compatibility table is more useful than a broad performance claim.

The library also supports 16-bit and 24-bit color modes, although the README cautions that the actual color count depends on the display. Automatic color reduction for monochrome panels is listed as another feature. Off-screen buffers can be rotated and scaled, and multiple displays can be used at the same time. Those are drawing and architecture capabilities rather than transport guarantees, and each still depends on sufficient memory and a compatible panel implementation.

Board definitions in src/lgfx_user

The configuration examples are located in src/lgfx_user. The README gives a partial list of board selection macros that can be defined before including LovyanGFX.hpp. For example, a project using a recognized M5Stack variant can select LGFX_M5STACK, while M5StickC Plus uses LGFX_M5STICK_C according to the shown list. Other documented selections include LGFX_M5STACK_CORE2, LGFX_M5STACK_COREINK, LGFX_M5PAPER, LGFX_M5TOUGH, LGFX_M5ATOMS3, LGFX_ODROID_GO, LGFX_TTGO_TS, LGFX_TTGO_TWATCH, LGFX_TTGO_TWRISTBAND, LGFX_TTGO_TDISPLAY, LGFX_DDUINO32_XS, LGFX_LOLIN_D32_PRO, LGFX_LOLIN_S3_PRO, and LGFX_ESP_WROVER_KIT.

The important detail is placement. The README says these LGFX_ definitions should appear before the include of LovyanGFX.hpp when the supported board is being used outside Arduino IDE or is not available through the board manager. The complete configuration example should therefore be copied from src/lgfx_user and adjusted for the actual board, rather than reconstructed from the abbreviated README list.

For a custom panel, the controller name and bus protocol are not enough by themselves. The developer still needs the correct bus pins, control pins, reset behavior, initialization sequence, panel dimensions, and touch controller settings. LovyanGFX says that panels with a similar command system may be compatible, but it only officially lists devices that the author obtained and confirmed. That distinction matters when evaluating support for an untested panel.

Installing LovyanGFX and starting a first board project

The README identifies ESP-IDF, Arduino ESP32, Arduino ATSAMD51, and Arduino RP2040 as supported environments and points to examples/ for concrete examples. It does not provide a complete package-manager installation command, IDE menu sequence, or library version to pin. Consequently, there is no installation command that can be reproduced accurately from the README.

For a first project, use the configuration examples in src/lgfx_user and an example from examples/HowToUse/. The README explicitly says that examples/ contains concrete usage examples. Choose the example that matches the target board and transport, then keep the `LGFX_` definition before the `LovyanGFX.hpp` include when the board is not supplied by the selected board manager. The reader should expect to edit the board definition for a custom panel rather than expect automatic detection.

The README does not show a complete initialization and drawing program, including the display object construction, terminal setup, pin assignments, and a draw call. It would be inaccurate to invent those lines. A first real use therefore consists of selecting the matching board configuration, copying one of the repository examples, and using the example's documented drawing flow. If the board or panel is absent from the official examples, src/lgfx_user is the first location to inspect, not a guarantee that an identical configuration will work.

Where LovyanGFX differs from AdafruitGFX and TFT_eSPI

The README says LovyanGFX mimics parts of the AdafruitGFX and TFT_eSPI APIs while aiming for broader functional coverage and faster operation. That gives projects with code already written against either API a possible migration path, but it does not mean complete source compatibility. API similarity is described as partial, so existing code should not be treated as drop-in without checking the functions it uses.

The architectural difference is that LovyanGFX is built around a wider range of target combinations. The project supports ESP-IDF as well as Arduino environments, Arduino ESP8266 and SAMD51, and several ESP32 bus paths. It also documents DMA transfer, off-screen buffer operations, multiple displays, monochrome color reduction, PC drawing destinations through OpenCV or SDL2, and ESP32 CVBS output. Those features are not all part of the same common baseline across the alternatives.

For a project fixed to one familiar Arduino board and one SPI panel, the wider platform matrix may matter less than the simplicity of an existing AdafruitGFX or TFT_eSPI setup. For a project that needs ESP-IDF, a nonstandard bus, multiple displays, or PC-hosted rendering, LovyanGFX offers a more relevant set of integration paths.

Compatibility boundaries, maintenance, and license cost

The clearest limitations are hardware-specific. ESP32-C3 has software I2C in the table, ESP8266 has software I2C, and several boards do not list parallel, RGB, or CVBS support. Touch support is not universal either: RP2040 is marked unsupported for touchscreens in the table. A feature listed for one target should not be generalized to every ESP32, ESP8266, SAMD51, or SAMD21 configuration.

The repository is not archived, and the last push was on 2026-10-16. Releases 1.2.33 and 1.2.32 were published in October 2026, while 1.2.31 was published in September 2026, indicating recent release activity. The README does not define a long-term support policy or a compatibility promise for a particular display revision. Upgrading may therefore require checking the release notes and rechecking the board configuration.

The repository identifies a custom license that GitHub cannot classify, with the license file named license.txt. The project description and compatibility information do not state its exact permissions, redistribution terms, or warranty conditions. Before incorporating LovyanGFX into a product, read license.txt directly and check those terms against the intended distribution model. This is a repository-specific licensing boundary, not a conclusion about legal obligations.

Editorial conclusion

LovyanGFX is a practical choice for embedded display projects that need configurable ESP32, ESP8266, or SAMD51 hardware support and useful Arduino, ESP-IDF, and PC integration. It is a poor match for a user expecting every panel to work from its controller name alone. Check src/lgfx_user first, then verify the bus pins, controller support, touch configuration, and terms in license.txt against the target board.

Frequently asked questions

Official sources

1. Issues
2. lovyan03/LovyanGFX on GitHub
3. README
4. Releases