For first time LittlevGL users (existing users, see notes later): we’ll assume you already have basic Arduino usage set up for your board — SAMD, nRF and so forth — the corresponding introduction guide for each board explains that part. If you can get the “blink” sketch running, you’re in good shape.

The required software components for LittlevGL usage can then be installed with the Arduino Library Manager

Sketch→Include Library→Manage Libraries…

Search for and install the following libraries:

  • lvgl (not the similar lv_arduino library — that’s now out of date)
  • Adafruit_LvGL_Glue
  • Adafruit_GFX
  • Adafruit_BusIO
  • Adafruit_Touchscreen
  • Adafruit_STMPE610

Even if you’re not using a touchscreen, those latter two libraries are still required for the code to compile.

Recent versions of the Arduino IDE install library dependencies automatically, so you’ll only need to manually request the first two of these and the rest will come along for the ride. But just in case, there’s the whole list.

In addition, you’ll need to install one or more libraries specific to the display you’re using…

  • Adafruit_ILI9341 (320x240 PyPortal, TFT FeatherWing, etc.)
  • Adafruit_HX8357 (480x320 PyPortal Titano, TFT FeatherWing, etc.)
  • Adafruit_ST7735 (includes ST7789 support) (CLUE, TFT Gizmo, HalloWing, PyGamer, etc.)
  • Other color Adafruit displays can usually work, see the “Using” page for further details

Prior Adafruit_LvGL_Glue Users

If you’ve previously used LittlevGL and Adafruit_LvGL_Glue, there are some configuration and code changes you’ll need to make.

First, uninstall the lv_arduino library and install lvgl in its place. lv_arduino was an older release of LittlevGL for Arduino…it’s quite deprecated now and will not be updated. Use lvgl going forward.

Second, LittlevGL has evolved considerably, and code written with the older library won’t compile without changes. A lot of functions and constants have different names, and styles are handled through “setter” functions now. You can look through the Adafruit_LvGL_Glue examples for some insights, but your best reference will be the official LittlevGL documentation.

Additionally, we no longer recommend LittlevGL for SAMD21 (“M0”) boards. Simple code might work, but it’s generally better to use a SAMD51 (“M4”), nRF52 or ESP32 controller with their spacious RAM.

If the Examples Won’t Compile

LittlevGL moves fast, and its developers aren’t shy about making changes, even if that means breaking existing user code. If you find that the Adafruit_LvGL_Glue examples won’t compile, it might be necessary to rewind the lvgl library version to the last known compatible state (8.2.0 when last checked). There’s a “Select version” option for this in the Arduino Library Manager:

LittlevGL Configuration

By default, our glue library already has LittlevGL set up for our boards and displays. But if you’d like to get in there and tune some settings, the LittlevGL configuration file can be found at:

(home directory)/Documents/Arduino/libraries/Adafruit_LvGL_Glue/lv_conf.h

Of possible interest in there, LV_USE_LOG and LV_LOG_LEVEL can be edited if you want to customize LittlevGL’s status logging capabilities (which will print to the Serial Console when using Adafruit_LvGL_Glue). LV_USE_LOG is set to 1 by default, enabling this capability, but to fully activate it you must pass true as an optional extra argument to our library’s begin() function. If not needed, you can set LV_USE_LOG to 0 to free up a little program space. LV_LOG_LEVEL is set to LV_LOG_LEVEL_INFO by default, displaying the most important events only, but you can step this up to LV_LOG_LEVEL_TRACE if you require verbose and detailed information.

Hello Arduino example

To verify that everything’s installed and working properly, you can try the minimal “Hello” program…

File→Examples→Adafruit LittlevGL Glue Library→Hello *

There are different versions for Adafruit CLUE, TFT FeatherWing, TFT Gizmo and PyPortal (all versions). Other Adafruit boards and displays can also work…see the “Using” page. It’s fairly straightforward to “mash up” an existing graphics example with the LittlevGL hello example and verify that it’s working.

Most of these need no modification. Only the hello_featherwing example, where you’ll need to edit this line if using a 3.5" (480x320) TFT FeatherWing:

#define BIG_FEATHERWING 0 // Set this to 1 for 3.5" (480x320) FeatherWing!

Select your board type from the Tools menu, verify the code compiles, and upload. If you get a legible “Hello Arduino!” centered on the screen, everything’s in good shape!

We provide just these basic test examples because of LittlevGL’s fast-paced development…any actual UI “widget” examples tended to break as the library evolved quicker than we could revisit. Instead, have a look at the examples included with the lvgl library, and “mash up” that code with the initialization from our hello examples to produce a working combination. This is detailed a little further on the next page.

This guide was first published on Apr 09, 2020. It was last updated on Mar 08, 2024.

This page (Installing) was last updated on Mar 08, 2024.

Text editor powered by tinymce.