Labs / LVGL / 03 Quick Start Example - Control Section (Based on Web Simulator and LVGL v9.0)

12. Charts and Graphs

Author: Li Zisheng · Source: FreakStudio open documentation, v1.0 · License: CC BY 4.0

Contents

Inner Enum Class:

Class nameDescription
chart.TYPEChart type enumeration, used to specify how the chart is displayed:
- NONE: no chart
- LINE: line chart
- BAR: bar chart
- SCATTER: scatter chart
chart.UPDATE_MODEData update mode enumeration, controls how data is displayed when new data is added:
- SHIFT: data shifts left (new data is added on the right, old data shifts left)
- CIRCULAR: circular overwrite (new data overwrites the oldest data)
chart.AXISAxis enumeration, specifies the axis the data is bound to:
- PRIMARY_Y: primary Y axis (default)
- SECONDARY_Y: secondary Y axis
- PRIMARY_X: primary X axis
- SECONDARY_X: secondary X axis
- LAST: last axis

Core Methodology:

Method nameMeaningInput parameters (actually usable format)Return valueNotes
__init__(parent)Chart constructor, creates a chart instanceparent: lv.obj type
(e.g. the screen object scr)
lv.chart objectNone
set_type(type)Sets the chart display typetype: int enum value
(1=LINE line chart,
2=BAR bar chart,
3=SCATTER scatter chart,
0=NONE)
Nonelv.chart.TYPE.LINE actually corresponds to the int value 1; just pass an int directly
set_point_count(count)Sets the maximum number of data points the chart displayscount: int type (e.g. 10/20)NoneNone
set_update_mode(mode)Sets the update logic when new data is addedmode: int enum value
(0=SHIFT shift left,
1=CIRCULAR circular overwrite)
Nonelv.chart.UPDATE_MODE.SHIFT actually corresponds to the int value 0
set_div_line_count(hdiv, vdiv)Sets the number of chart grid lineshdiv: int type (number of horizontal grid lines, e.g. 3);
vdiv: int type (number of vertical grid lines, e.g. 3)
NoneBoth parameters must be passed together; neither can be omitted
set_range(axis, min, max)Sets the value range of the specified axisaxis: int enum value (
0=PRIMARY_Y primary Y axis,
1=SECONDARY_Y secondary Y axis,
2=PRIMARY_X primary X axis,
3=SECONDARY_X secondary X axis);
min: int type (axis minimum value, e.g. 0);
max: int type (axis maximum value, e.g. 100)
NoneAll three parameters must be passed together; lv.chart.AXIS.PRIMARY_Y corresponds to the int value 0
get_type()Gets the current chart typeNoneint enum value (
1=LINE line chart,
2=BAR bar chart, etc.)
Corresponds one-to-one with the int value passed to set_type
get_point_count()Gets the currently set number of data pointsNoneint type (e.g. 10)Same as the value set by set_point_count
get_x_start_point(ser)Gets the X-axis start point index of the specified data seriesser: lv_chart_series_t struct object (created by add_series)int type (e.g. 0)Depends on the series object created by add_series
get_point_pos_by_id(ser, id, p_out)Gets the coordinates of the point in the specified data series by IDser: lv_chart_series_t struct object; id: int type (data point ID, e.g. 0); p_out: lv_point_t struct object (stores the coordinate result)NoneThe coordinate result is stored in the p_out object; no return value
refresh()Forces a chart refresh to update the data / style displayNoneNoneCall after updating data to refresh the interface immediately
add_series(color, axis)Adds a data series (line / bar) to the chartcolor: lv_color_t struct object (e.g. lv.color_hex(0xFF0000));
axis: int enum value (0=PRIMARY_Y primary Y axis)
lv_chart_series_t struct objectThe color does not need to be converted to int; pass the object generated by lv.color_hex directly
remove_series(series)Removes the specified data series from the chartseries: lv_chart_series_t struct objectNoneDepends on the series object created by add_series
hide_series(series, hide)Hides / shows the specified data seriesseries: lv_chart_series_t struct object;
hide: bool type (True = hide, False = show)
NoneDepends on the series object created by add_series
set_series_color(series, color)Sets the display color of the specified data seriesseries: lv_chart_series_t struct object;
color: lv_color_t struct object
NoneDepends on the series object created by add_series
set_x_start_point(ser, id)Sets the X-axis start point index of the specified data seriesser: lv_chart_series_t struct object;
id: int type (start point index, e.g. 0)
NoneDepends on the series object created by add_series
get_series_next(ser)Gets the next series after the specified data series (used for traversal)ser: lv_chart_series_t struct objectlv_chart_series_t struct object (returns None if there is no next one)Depends on the series object created by add_series
add_cursor(color, dir)Adds a cursor to the chart (marks a data point)color: lv_color_t struct object; dir: int enum value (8=DIR.BOTTOM downward)lv_chart_cursor_t struct objectNone
set_cursor_pos(cursor, pos)Sets the cursor position in the chartcursor: lv_chart_cursor_t struct object (created by add_cursor);
pos: lv_point_t struct object (contains x/y coordinates)
NoneDepends on the cursor object created by add_cursor
set_cursor_point(cursor, ser, point_id)Positions the cursor at the specified data point of the specified seriescursor: lv_chart_cursor_t struct object;
ser: lv_chart_series_t struct object;
point_id: int type (data point ID, e.g. 0)
NoneDepends on objects created by add_cursor and add_series
get_cursor_point(cursor)Gets the coordinate point where the cursor is currently positionedcursor: lv_chart_cursor_t struct objectlv_point_t struct object (contains x/y coordinates)Depends on the cursor object created by add_cursor
set_all_value(series, value)Sets all data points of the specified series to the same valueseries: lv_chart_series_t struct object;
value: int type (e.g. 0)
NoneDepends on the series object created by add_series
set_next_value(ser, value)Adds the next Y-axis data point to the specified seriesser: lv_chart_series_t struct object;
value: int type (e.g. 50)
NoneAutomatically processes data according to the mode set by set_update_mode
set_next_value2(ser, x_value, y_value)Adds the next X/Y-axis data point to the specified seriesser: lv_chart_series_t struct object;
x_value: int type (e.g. 1);
y_value: int (e.g., 60)
NoneSupports a custom X-axis value, unlike set_next_value
set_value_by_id(ser, id, value)Set the Y-axis value of the data point with the specified ID in the specified seriesser: lv_chart_series_t struct object;
id: int (data point ID, e.g., 0);
value: int (e.g., 70)
NoneDepends on the series object created by add_series
set_value_by_id2(ser, id, x_value, y_value)Set the X/Y-axis values of the data point with the specified ID in the specified seriesser: lv_chart_series_t struct object;
id: int (data point ID, e.g., 0);
x_value: int (e.g., 2);
y_value: int (e.g., 80)
NoneDepends on the series object created by add_series
set_ext_y_array(ser, array)Bind an external Y-axis data array to the specified seriesser: lv_chart_series_t struct object;
array: list[int] (e.g., [0,10,20,30,40])
NoneDepends on the series object created by add_series
set_ext_x_array(ser, array)Bind an external X-axis data array to the specified seriesser: lv_chart_series_t struct object;
array: list[int] (e.g., [0,10,20,30,40])
NoneDepends on the series object created by add_series
get_y_array(ser)Get the Y-axis data array of the specified seriesser: lv_chart_series_t struct objectC Array (int32 []) (equivalent to Python list[int])Depends on the series object created by add_series
get_x_array(ser)Get the X-axis data array of the specified seriesser: lv_chart_series_t struct objectC Array (int32 []) (equivalent to Python list[int])Depends on the series object created by add_series
get_pressed_point()Get the ID of the data point hit when the user clicks the chartNoneint (2147483647 = no hit; other values are the data point ID)2147483647 is equivalent to -1 (no hit)
get_first_point_center_offset()Get the center offset of the first data point of the chartNoneint type (e.g. 10)The offset is in pixels, used for precise data point positioning

12.1 Line Chart

In the following code, the following operations are performed:

import display_driver
import lvgl as lv
import random
import time

# Initialize the LVGL core engine
lv.init()

# Screen initialization: white background
scr = lv.screen_active()
scr.set_style_bg_color(lv.color_hex(0xFFFFFF), 0)

# ===================== Create and configure the chart =====================
chart = lv.chart(scr)
chart.set_size(300, 200)  # Chart size
chart.center()            # Center on screen

# Core configuration (strictly matches the APIs that passed testing)
chart.set_type(lv.chart.TYPE.LINE)          # Line chart type
chart.set_point_count(10)                   # Number of data points (shows at most 10)
chart.set_update_mode(lv.chart.UPDATE_MODE.SHIFT)  # Data shifts left on update
chart.set_div_line_count(3, 3)              # Grid lines: 3 horizontal + 3 vertical (2 parameters, passed testing)
chart.set_range(lv.chart.AXIS.PRIMARY_Y, 0, 100)  # Y-axis range: 0~100 (3 parameters, passed testing)

# ===================== Add data series =====================
# Pass the color object + AXIS constant directly (passed testing, no int conversion needed)
# Red line
ser1 = chart.add_series(lv.color_hex(0xFF0000), lv.chart.AXIS.PRIMARY_Y)  
# Blue line
ser2 = chart.add_series(lv.color_hex(0x0000FF), lv.chart.AXIS.PRIMARY_Y)  

# ===================== Initialize data =====================
chart.set_all_value(ser1, 0)  # Initialize the red line to 0 (2 parameters, passed testing)
chart.set_all_value(ser2, 0)  # Initialize the blue line to 0

# ===================== Timer: update data in real time =====================
def update_chart(timer):
    """Timer callback: generate random data and update the chart"""
    val1 = random.randint(20, 80)  # Random value for the red line
    val2 = random.randint(10, 90)  # Random value for the blue line
    
    chart.set_next_value(ser1, val1)  # Update the red line data
    chart.set_next_value(ser2, val2)  # Update the blue line data
    
    print(f"Updated: ser1={val1}, ser2={val2}")  # English log output

# Create a timer: 500ms period, repeatedly runs the update function (regular function callback, passed testing)
lv.timer_create(update_chart, 500, None)

# ===================== Load the screen =====================
lv.screen_load(scr)
ser1 57 ser2 28 12.1
2 3 0 100

12.2 Bar Chart

The code below displays a bar chart with a white background, consisting of 6 sets of red and blue bars, a Y-axis range of 0 to 100,3 horizontal grid lines and 2 vertical grid lines.

import display_driver
import lvgl as lv
import random
import time

# Initialize the LVGL core engine
lv.init()

# Screen initialization: white background
scr = lv.screen_active()
scr.set_style_bg_color(lv.color_hex(0xFFFFFF), 0)

# Create a bar chart
chart = lv.chart(scr)
chart.set_size(300, 220)  # Set the chart size: width 300, height 220
chart.center()            # Center the chart on screen

# Configure the chart as a bar chart type (pass lv.chart.TYPE.BAR directly, passed testing)
chart.set_type(lv.chart.TYPE.BAR)
# Set the number of data points (number of bars): 6
chart.set_point_count(6)
# Set the grid lines: 3 horizontal lines, 2 vertical lines (2 parameters, passed testing)
chart.set_div_line_count(3, 2)
# Y-axis range 0~100
chart.set_range(lv.chart.AXIS.PRIMARY_Y, 0, 100)  

# First group: red bars, using the primary Y axis (pass the color object + AXIS constant directly, passed testing)
ser1 = chart.add_series(lv.color_hex(0xFF5733), lv.chart.AXIS.PRIMARY_Y)
# Second group: blue bars, using the primary Y axis
ser2 = chart.add_series(lv.color_hex(0x3377FF), lv.chart.AXIS.PRIMARY_Y)

# Set the first group of data
data1 = [30, 45, 28, 67, 50, 75]
for idx, value in enumerate(data1):
    # Set the Y-axis values one by one by ID
    chart.set_value_by_id(ser1, idx, value)  
    
# Set the second group of data
data2 = [20, 55, 38, 47, 60, 55]
for idx, value in enumerate(data2):
    chart.set_value_by_id(ser2, idx, value)

# Load the screen
lv.screen_load(scr)
12.1

12.3 Scatter Plot

It should be noted that the SCATTER type of LVGL is not a scatter plot in the traditional sense that only displays independent discrete points. Instead, it automatically connects adjacent Data Points of the same series with broken lines, presenting the effect of a "broken line with Data Points", which is significantly different from the conventional scatter plot without connecting lines that we commonly recognize.This feature makes it more suitable for trajectory update scenarios, such as real-time display of device movement trajectories (e. g., sensor positions, mobile terminal positioning), dynamic change trajectories of multi-dimensional indicators (e. g., XY-axis trend tracking of industrial monitoring data), etc. It can intuitively present the continuous change path of the same type of data on the XY plane, rather than simply displaying the distribution of discrete points.

import display_driver
import lvgl as lv
import time
import random

# ===================== 1. Initialize the LVGL environment =====================
lv.init()
scr = lv.screen_active()
scr.set_style_bg_color(lv.color_hex(0x000000), 0)  # Black background to make the scatter points stand out

# ===================== 2. Core configuration for creating a planar scatter chart =====================
chart = lv.chart(scr)
chart.set_size(400, 300)  # Larger size, suited to XY dual-axis distribution
chart.center()

# Key configuration: dual-axis scatter chart
chart.set_type(lv.chart.TYPE.SCATTER)          # Pure scatter chart type
chart.set_point_count(20)                      # Shows at most 20 scatter points (shift update)
chart.set_update_mode(lv.chart.UPDATE_MODE.CIRCULAR)  # New points added on the right, old points shift left
chart.set_div_line_count(5, 5)                 # 5 horizontal and 5 vertical grid lines, evenly dividing the XY axes

# Set the XY dual-axis ranges (planar coordinate system: X 0-100, Y 0-100)
chart.set_range(lv.chart.AXIS.PRIMARY_X, 0, 100)  # X-axis range
chart.set_range(lv.chart.AXIS.PRIMARY_Y, 0, 100)  # Y-axis range

# ===================== 3. Add three-color scatter series (different XY ranges) =====================
# Red scatter points: upper-left region (X 10-30, Y 70-90)
ser_red = chart.add_series(lv.color_hex(0xFF0000), lv.chart.AXIS.PRIMARY_Y)
# Blue scatter points: middle region (X 40-60, Y 40-60)
ser_blue = chart.add_series(lv.color_hex(0x0000FF), lv.chart.AXIS.PRIMARY_Y)
# Yellow scatter points: lower-right region (X 70-90, Y 10-30)
ser_yellow = chart.add_series(lv.color_hex(0xFFFF00), lv.chart.AXIS.PRIMARY_Y)

# ===================== 4. Initialize scatter data (initially 0) =====================
chart.set_all_value(ser_red, 0)
chart.set_all_value(ser_blue, 0)
chart.set_all_value(ser_yellow, 0)

# ===================== 5. Timer: update the planar scatter in real time (random XY) =====================
def update_scatter(timer):
    """Generate random XY values in different ranges and update the planar scatter points"""
    # Red: upper-left region (X 10-30, Y 70-90)
    x_red = random.randint(10, 30)
    y_red = random.randint(70, 90)
    chart.set_next_value2(ser_red, x_red, y_red)  # Dual-axis update: X+Y

    # Blue: middle region (X 40-60, Y 40-60)
    x_blue = random.randint(40, 60)
    y_blue = random.randint(40, 60)
    chart.set_next_value2(ser_blue, x_blue, y_blue)

    # Yellow: lower-right region (X 70-90, Y 10-30)
    x_yellow = random.randint(70, 90)
    y_yellow = random.randint(10, 30)
    chart.set_next_value2(ser_yellow, x_yellow, y_yellow)

    # Print real-time coordinates (optional, to view the data)
    print(f"Red({x_red},{y_red}) | Blue({x_blue},{y_blue}) | Yellow({x_yellow},{y_yellow})")

# Create a timer: update the scatter points every 600ms
lv.timer_create(update_scatter, 600, None)

# ===================== 6. Load the screen and keep running =====================
lv.screen_load(scr)
5

In the code above, a dynamic scatter plot effect with dual XY axes is implemented based on the LVGL graphics library: first, initialize a chart with a black background, configure the value range of 0-100 for both X and Y axes and 5×5 uniform grid lines, create three data series in red, blue and yellow corresponding to different XY coordinate intervals of upper left, middle and lower right respectively, generate random XY coordinates for the corresponding interval every 600ms via a timer, and use the set_next_value2 method to update the dual-axis Data Point of each series, so as to realize the dynamic refresh of data.

Version Record

Version Number

Modifier

Time

Content

v1.0

Li Zisheng

2026/03/23

Initialize the document.