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:

  • lv_arduino (LittlevGL library for Arduino) (select the latest 2.X version, NOT a 3.X version!)
  • 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
Install the latest 2.X version of lv_arduino. Version 3 introduced a number of breaking changes. Adafruit_LvGL_Glue has not yet been updated for this, and most existing LittlevGL sketches will require changes to use it.

Configure LittlevGL

By default, lv_arduino is pretty well set up already for our 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/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.

Entirely optional, but if using a PyPortal Titano or large TFT FeatherWing, you can also change these resolution values:

Download: file
#define LV_HOR_RES_MAX          (320)
#define LV_VER_RES_MAX          (240)

These are not hard-set screen size limits, they just affect how screen memory is allocated. If bumped up to 480 and 320, some additional memory is set aside and screen updates might go a little faster and smoother. Or there’s no harm just leaving them as they are.

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:

Download: file
#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 Feb 07, 2021.

Text editor powered by tinymce.