LittlevGL - Open-source Embedded GUI Library

LittlevGL provides everything you need to create a Graphical User Interface (GUI) on embedded systems with easy-to-use graphical elements, beautiful visual effects and low memory footprint.

Website · Live demo · Simulator · Docs · Blog

Features

• Powerful building blocks buttons, charts, lists, sliders, images, etc.
• Advanced graphics with animations, anti-aliasing, opacity, smooth scrolling
• Various input devices touch pad, mouse, keyboard, encoder, buttons, etc.
• Multi-language support with UTF-8 encoding
• Fully customizable graphical elements
• Hardware independent to use with any microcontroller or display
• Scalable to operate with little memory (64 kB Flash, 10 kB RAM)
• OS, External memory and GPU supported but not required
• Single frame buffer operation even with advances graphical effects
• Written in C for maximal compatibility
• Micropython Binding exposes LittlevGL API in Micropython
• Simulator to develop on PC without embedded hardware
• Tutorials, examples, themes for rapid development
• Documentation and API references online

Supported devices

Basically, every modern controller - which is able to drive a display - is suitable to run LittlevGL. The minimal requirements:

• 16, 32 or 64-bit microcontroller or processor
• > 16 MHz clock speed
• > 8 kB RAM for static data and > 2 KB RAM for dynamic data (graphical objects)
• > 64 kB flash program memory
• Optionally ~1/10 screen sized memory for buffered drawing (on 240 × 320, 16-bit colors it's 15 kB)

Just to mention some platforms:

• STM32F1, STM32F3, STM32F4, STM32F7
• Microchip dsPIC33, PIC24, PIC32MX, PIC32MZ
• NXP Kinetis, LPC, iMX
• Linux frame buffer (/dev/fb)
• Raspberry PI
• Espressif ESP32
• Nordic nrf52
• Quectell M66

Quick start in a simulator

The easiest way to get started with LittlevGL is to run it in a simulator on your PC without any embedded hardware.

Choose a project with your favourite IDE:

Eclipse	CodeBlocks	Visual Studio	PlatformIO	Qt Creator
Cross-platform with SDL	Native Windows	Cross-platform with SDL	Cross-platform with SDL	Cross-platform with SDL

Porting to an embedded hardware

In the most simple case you need to do these steps:

1. Copy lv_conf_templ.h as lv_conf.h next to lvgl and set at least LV_HOR_RES, LV_VER_RES and LV_COLOR_DEPTH.
2. Call lv_tick_inc(x) every x milliseconds in a Timer or Task (x should be between 1 and 10). It is required for the internal timing of LittlevGL.
3. Call lv_init()
4. Create a buffer for LittlevGL

static lv_disp_buf_t disp_buf;
static lv_color_t buf[LV_HOR_RES_MAX * 10];                     /*Declare a buffer for 10 lines*/
lv_disp_buf_init(&disp_buf, buf, NULL, LV_HOR_RES_MAX * 10);    /*Initialize the display buffer*/

4. Implement and register a function which can copy a pixel array to an area of your diplay:

lv_disp_drv_t disp_drv;               /*Descriptor of a display driver*/
lv_disp_drv_init(&disp_drv);          /*Basic initialization*/
disp_drv.hor_res = 480;               /*Set the horizontal resolution*/
disp_drv.ver_res = 320;               /*Set the vertical resolution*/
disp_drv.flush_cb = my_disp_flush;    /*Set your driver function*/
disp_drv.buffer = &disp_buf;          /*Assign the buffer to teh display*/
lv_disp_drv_register(&disp_drv);      /*Finally register the driver*/
    
void my_disp_flush(lv_disp_t * disp, const lv_area_t * area, lv_color_t * color_p)
{
    int32_t x, y;
    for(y = area->y1; y <= area->y2; y++) {
        for(x = area->x1; x <= area->x2; x++) {
            set_pixel(x, y, *color_p);  /* Put a pixel to the display.*/
            color_p++;
        }
    }

    lv_disp_flush_ready(disp);                  /* Tell you are ready with the flushing*/
}
    

5. Register a function which can read an input device. E.g. for a touch pad:

lv_indev_drv_init(&indev_drv);             /*Descriptor of a input device driver*/
indev_drv.type = LV_INDEV_TYPE_POINTER;    /*Touch pad is a pointer-like device*/
indev_drv.read_cb = my_touchpad_read;      /*Set your driver function*/
lv_indev_drv_register(&indev_drv);         /*Finally register the driver*/

bool my_touchpad_read(lv_indev_t * indev, lv_indev_data_t * data)
{
    static lv_coord_t last_x = 0;
    static lv_coord_t last_y = 0;

    /*Save the state and save the pressed coordinate*/
    data->state = touchpad_is_pressed() ? LV_INDEV_STATE_PR : LV_INDEV_STATE_REL; 
    if(data->state == LV_INDEV_STATE_PR) touchpad_get_xy(&last_x, &last_y);
   
    /*Set the coordinates (if released use the last pressed coordinates)*/
    data->point.x = last_x;
    data->point.y = last_y;

    return false; /*Return `false` because we are not buffering and no more data to read*/
}

6. Call lv_task_handler() periodically every few milliseconds in the main while(1) loop, in Timer interrupt or in an Operation system task. It will redraw the screen if required, handle input devices etc.

For a detailed description check the Documentation or the Porting examples.

Code examples

Create a button with a label and assign a click callback

lv_obj_t * btn = lv_btn_create(lv_scr_act(), NULL);     /*Add a button the current screen*/
lv_obj_set_pos(btn, 10, 10);                            /*Set its position*/
lv_obj_set_size(btn, 100, 50);                          /*Set its size*/

lv_btn_set_action(btn, LV_BTN_ACTION_CLICK, btn_action);/*Assign a callback to the button*/
lv_obj_t * label = lv_label_create(btn, NULL);          /*Add a label to the button*/
lv_label_set_text(label, "Button");                     /*Set the labels text*/

lv_res_t btn_action(lv_obj_t * btn)
{
    printf("Clicked\n");
    return LV_RES_OK;
}

Modify the styles

static lv_style_t style_btn_rel;                        /*A variable to store the released style*/
lv_style_copy(&style_btn_rel, &lv_style_plain);         /*Initialize from a built-in style*/
style_btn_rel.body.border.color = LV_COLOR_HEX3(0x269);
style_btn_rel.body.border.width = 1;
style_btn_rel.body.main_color = LV_COLOR_HEX3(0xADF);
style_btn_rel.body.grad_color = LV_COLOR_HEX3(0x46B);
style_btn_rel.body.shadow.width = 4;
style_btn_rel.body.shadow.type = LV_SHADOW_BOTTOM;
style_btn_rel.body.radius = LV_RADIUS_CIRCLE;
style_btn_rel.text.color = LV_COLOR_HEX3(0xDEF);

static lv_style_t style_btn_pr;                         /*A variable to store the pressed style*/
lv_style_copy(&style_btn_pr, &style_btn_rel);           /*Initialize from the released style*/
style_btn_pr.body.border.color = LV_COLOR_HEX3(0x46B);
style_btn_pr.body.main_color = LV_COLOR_HEX3(0x8BD);
style_btn_pr.body.grad_color = LV_COLOR_HEX3(0x24A);
style_btn_pr.body.shadow.width = 2;
style_btn_pr.text.color = LV_COLOR_HEX3(0xBCD);

lv_btn_set_style(btn, LV_BTN_STYLE_REL, &style_btn_rel);    /*Set the button's released style*/
lv_btn_set_style(btn, LV_BTN_STYLE_PR, &style_btn_pr);      /*Set the button's pressed style*/

Enable a fancy effect

/*Add some effects when the button is clicked*/
lv_btn_set_ink_in_time(btn, 300);
lv_btn_set_ink_wait_time(btn, 100);
lv_btn_set_ink_out_time(btn, 300);

Use LittlevGL from Micropython

# Create a Button and a Label
scr = lv.obj()
btn = lv.btn(scr)
btn.align(lv.scr_act(), lv.ALIGN.CENTER, 0, 0)
label = lv.label(btn)
label.set_text("Button")

# Load the screen
lv.scr_load(scr)

Check out the Documentation for more!

Contributing

To ask questions please use the Forum. FOr development related things (bug reports, feature suggestions) use GitHub's Issue tracker. You can contribute in several ways:

• Answer other's question in the Forum
• Report and/or fix bugs using the issue tracker and in Pull-request
• Suggest and/or implement new features using the issue tracker and in Pull-request
• Improve and/or translate the documentation learn more here
• Write a blog post about your experiences learn more here
• Upload your project or product as a reference to this site

Before contributing, please read CONTRIBUTING.md.

Donate

If you are pleased with the library, found it useful, or you are happy with the support you got, please help its further development: