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.

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 (7.11.0 at the time this was written). 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 set if you want to use LittlevGL’s status logging capabilities (which will print to the Serial Console when using Adafruit_LvGL_Glue). Set the former to 1 and the latter to LV_LOG_LEVEL_INFO or LV_LOG_LEVEL_TRACE. Logging also must be enabled by passing true as an optional extra argument to our library’s begin() function.

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!

From there, you can try one of the widgets examples. These just scratch the surface of what LittlevGL can do, but give a nice hint of what’s in store visually, and you can look through the code to see how a simple application is implemented.

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

This page (Installing) was last updated on Nov 28, 2021.

Text editor powered by tinymce.