Ranveo
Sign inStart a trialDownload
LVGL 9Embedded devices, on the simulator and the board

Test the real device, not a screenshot of it.

Object-level testing for LVGL 9 apps, on the desktop simulator and on the firmware running on your board. Ranveo reaches the board over a serial line, USB or the network, and finds widgets by name and role, not by matching images.

Download for freeRead the LVGL docs

Desktop LVGL testing is free, including for commercial use.

How it connects

Your firmware, the agent, your team.

A small C library in your app speaks Ranveo’s protocol. The agent reaches it on the desktop or on the board, and the server keeps every run.

  1. Your LVGL app

    desktop build or firmware

    Links ranveo_lvgl, which hooks five LVGL functions at link time. Without Ranveo, the app runs unchanged.

    ranveo_lvgl · C · MITloopback or serial

  2. Ranveo agent

    ranveowall · your PC or a CI machine

    Starts the desktop build, or connects to the board over UART, USB CDC or tcp:HOST:PORT. Runs the tests and captures the screen.

    results, live view

  3. Ranveo server

    one per team, for every platform

    Runs, history, reports and recordings, and the AI assistant that writes and fixes the tests.

1
CMake line, or the ESP-IDF component
0
changes to your app code
15/17
conformance checks pass
MIT
the licence of ranveo_lvgl
Integration

No changes to your app code.

Add one CMake line or the ESP-IDF component. Widget names come straight from your debug info, so a UI exported from SquareLine Studio can be tested as it is.

  • Names from the PDB, DWARF or the ELF of the flashed build
  • LVGL classes become roles: lv_arc is a slider
  • Optional: describe subjects, screens and commands in a few lines
Timing

Timing that never flakes.

On Ranveo’s virtual clock, time moves only when the test moves it. Animations, timers and timeouts behave the same on every run: no sleeps, no retries.

0
sleeps
0
retries
  1. tapbtn_plus
  2. advance300 ms
  3. expect22.5 °C
  4. advance10 s
  5. expectscreen idle
  • Every run starts from the same point in time
  • Physical input is off while a test runs
  • On a board, virtual time passes as fast as it renders
Checks

Checks a screenshot can’t make.

Clipped and overlapping text in any language, render time and memory per test with limits, and faults you trigger from the test.

  • Layout rules: clipped text, cut off, overlap, small targets
  • Budgets for render time, heap peak and heap growth
  • Faults through app commands, a few lines of C
Hardware

Same test, simulator to board.

Run fast on the desktop build in CI, then on the real embedded device before release. Before every test on a board, Ranveo opens a new session, sets the clock and resets the app.

setpoint.test.json
Desktop simulator
The Aurora thermostat's LVGL screen in the desktop simulator
The same screen on the real embedded device
In CI, on every commit--exe build/aurora
On the embedded device, before release--serial COM5
Also in the box

Made for real boards.

  • ESP-IDF component

    List it in idf_component.yml, then pick UART, USB OTG or USB Serial/JTAG in menuconfig.

  • Any MCU

    The firmware plugs in its own non-blocking UART or USB CDC read and write functions.

  • Reliable on a busy line

    COBS frames with CRC-32. Lost frames are resent, and logging on the same line doesn’t break it.

  • Subjects and screens

    Register state with type, range and unit, so tests can read, wait for and set it.

  • Accessibility checks

    Icon buttons without a name, low contrast, and controls no key can reach.

  • Session tokens

    A shared secret built into the firmware. The UI and the API never show it back.

Set up

From build to first test in three steps.

  1. Add the library

    On a desktop with CMake, your source needs no Ranveo line.

    add_subdirectory(path/to/ranveo_lvgl
  ${CMAKE_BINARY_DIR}/ranveo_lvgl)
ranveo_lvgl_auto(MyApp
  NAME my-app VERSION 1.0.0)

  2. Connect the board

    Or point Ranveo at the desktop build with --exe.

    ranveowall add-profile \
  --profile-id board \
  --platform lvgl \
  --connection serial \
  --set port=COM5

  3. Run the tests

    Or ask the AI assistant to write the first one.

    ranveowall test tests \
  --serial COM5 \
  --token-file board.token \
  --elf build/app.elf
Under the hood

Objects, not pixels.

Ranveo reads the LVGL object tree on the device. A test finds a widget the way you would describe it.

Name
lv_obj_set_name, else the variable that points at the object
Text
A label’s text, a button’s first label, a text area’s content
Role
From the object’s class, or its base class for your own classes
Screen
The active screen’s name, or the identifier you registered

Today

  • LVGL has no hover, mouse buttons, wheel, files or navigation, so those steps don’t appear.
  • A serial line captures slowly (300 KB in about 3.3 s at 921600 baud), so board runs record no trace by default.
  • Time-dependent code must use lv_tick and lv_timer for the virtual clock to see it.

Roles, from the LVGL class

  • lv_buttonbecomesbutton
  • lv_arcbecomesslider
  • lv_sliderbecomesslider
  • lv_textareabecomesinput
  • lv_switchbecomesswitch
  • lv_checkboxbecomescheckbox
  • lv_dropdownbecomesdropdown
  • lv_rollerbecomesdropdown
  • lv_labelbecomestext
  • lv_barbecomesprogress
  • lv_msgboxbecomesdialog
  • lv_imagebecomesimage

In a test

{ "tap": { "name": "ui_BtnPlus" } }
{ "tap": { "role": "button", "text": "Save" } }
{ "expect": { "subject": "heat_setpoint", "value": 22.5 } }
15/17

conformance checks pass on the LVGL reference app. The two that don’t, emulate and route, test what only a web page has.

Compare every platform
  • busy: passes
  • clear: passes
  • clock: passes
  • commands: passes
  • emulate: skipped
  • input: passes
  • keys: passes
  • layout: passes
  • locators: passes
  • platform: passes
  • popup: passes
  • reset: passes
  • roles: passes
  • route: skipped
  • screens: passes
  • subjects: passes
  • visibility: passes
Questions

LVGL, answered.

Do I need SquareLine Studio?

No. Any LVGL 9 app works. A UI exported from SquareLine Studio can be tested as it is, because the names come from your debug info.

Which boards does it run on?

ESP-IDF projects get a ready component. On other MCUs, the firmware creates the transport over its own UART or USB CDC functions.

Does it need a display in CI?

No. Run the simulator offscreen (SDL_VIDEODRIVER=offscreen on Linux, dummy on Windows). Ranveo captures over its own protocol.

What does the free licence cover?

Testing LVGL apps on the desktop, including for commercial use. Boards and the other platforms come with a licence, and the 30-day trial has all of them.

Other platforms · the same tests, the same runner, one server

Your board, tested by tonight.

Desktop LVGL testing is free. Every platform runs during the 30-day trial, real hardware included.

Start free trialDownload for free