oxivgl

Safe Rust bindings for LVGL on embedded (no_std) and host (std/SDL2) targets. Wraps all unsafe LVGL calls behind type-safe APIs — user code never touches unsafe or raw FFI directly.

Motivation

Embedded no_std Rust has very few compact UI frameworks, leaving Rust developers envying the C ecosystem's broad reliance on LVGL. LVGL itself, however, feels foreign when approached with a Rust mindset — raw pointers, manual memory management, complex ownership model make it easy to make mistakes which are hard to debug.

oxivgl was created to close this gap. It is a safety layer on top of LVGL that enforces correct ownership, makes lifetimes explicit, and eliminates the unsafe FFI surface from application code. The goal is to make building LVGL UIs in Rust not just safer but genuinely easier and less frustrating than writing the equivalent in plain C directly.

Quick Start

use oxivgl::{
    view::{NavAction, View},
    widgets::{Align, Label, Obj, WidgetError},
};

#[derive(Default)]
struct MyView {
    _label: Option<Label<'static>>,
}

impl View for MyView {
    fn create(&mut self, container: &Obj<'static>) -> Result<(), WidgetError> {
        container.bg_color(0x003a57).bg_opa(255);

        let label = Label::new(container)?;
        label.text("Hello world").align(Align::Center, 0, 0);

        self._label = Some(label);
        Ok(())
    }

    fn update(&mut self) -> Result<NavAction, WidgetError> {
        Ok(NavAction::None)
    }
}

oxivgl_examples_common::example_main!(MyView::default());

Add as a git dependency:

[dependencies]
oxivgl = { git = "https://github.com/emobotics-dev/oxivgl" }

Toolchain

Requires Rust nightly. The primary target is ESP32 (Xtensa), which depends on a nightly-based toolchain (cargo +esp), esp-hal unstable features, and embassy-executor nightly. Since every ESP32 user already needs nightly, the host build (used for testing, docs, and development only) uses nightly too — this avoids split toolchain complexity and lets the library use edition 2024 features like #[unsafe(no_mangle)] and #[collapse_debuginfo].

Status

oxivgl is under active development. Even if it has reached some degree of maturity and is used intensively by our own embedded projects, it is not guaranteed to be API-stable yet — expect breaking changes to happen frequently. Currently, oxivgl does not map 100% of LVGL's features but covers a majority of all APIs demonstrated and used by the comprehensive set of LVGL examples. If you miss a feature that is important for you, you are more than welcome to contribute by writing issues and submitting PRs!

Architecture

Key Types

Application framework — implement View to build a screen; run_lvgl drives the render loop.

Widgets — type-safe wrappers, lifetime-tied to parent via 'p.

Observer / reactive — subjects connect state to widgets automatically.

Style system — two-phase: mutable build → frozen Rc-backed handle.

Animation — stack-local builder → LVGL-owned copy.

Input devices — non-owning wrappers for querying LVGL input state.

Draw tasks — custom draw hooks via DRAW_TASK_ADDED events.

Display & buffers — DMA-aligned double-buffering for ESP32.

Enums & constants — newtype wrappers over LVGL C constants.

Prelude — use oxivgl::prelude::* imports all common types including draw primitives, widgets, styles, and animations.

Memory Safety Across the FFI Boundary

LVGL is a C library that stores raw pointers to styles, image descriptors, point arrays, and callback data — with no built-in ownership tracking. The official Rust wrapper (lv_binding_rust) has known soundness gaps — wrong lifetimes on widget constructors that allow dangling pointers (#166), SIGSEGV on basic SDL init (#180), and is stuck on LVGL v8 with no active maintenance (#201).

oxivgl solves this with a compile-time ownership model documented in docs/spec-memory-lifetime.md:

• Two-phase style system — StyleBuilder (mutable, stack-local) → Style (immutable, Rc<StyleInner>). Sub-descriptors (gradients, transitions, color filters) are moved into the style by value and freed in the correct order via Drop.
• 'static enforcement — APIs where LVGL stores a raw pointer (Image::set_src, Line::set_points, Dropdown::set_symbol, StyleBuilder::bg_image_src, TransitionDsc::new) require 'static references. Non-'static data is rejected at compile time.
• Rc-based style sharing — Obj::add_style clones the Rc before passing the pointer to LVGL. The lv_style_t remains valid as long as any widget or user code holds a clone. Obj::drop calls lv_obj_delete (which internally removes all styles) before Rust drops the _styles Vec.
• Lifetime-tied animations — Anim<'w> uses PhantomData<&'w ()> to tie the animation descriptor to the target widget's lifetime. After start(), LVGL owns a copy; the widget's deletion auto-cancels the animation.

These guarantees are verified by integration tests that exercise style-drop-before-widget, widget-drop-with-styles-applied, shared-style-across-widgets, and explicit remove-then-drop sequences.

Examples

171 ported LVGL examples covering getting started, styles, animations, events, layouts, scrolling, gradients, observer/reactive UI, and individual widgets (including canvas). Each is a self-contained View impl — runs on host SDL2 or ESP32 with zero code changes.

Browse the full gallery with screenshots

./run_host.sh getting_started1      # interactive SDL2 window
./run_host.sh -s getting_started1   # headless screenshot
./run_host.sh -s                    # screenshot all 171 examples
./run_fire27.sh event_trickle       # flash to ESP32

Supported Platforms

Testing

624 automated tests across four tiers — all run on host without hardware:

./run_tests.sh all          # unit + integration + leak (< 5 seconds)
./run_tests.sh unit         # unit + doctests
./run_tests.sh int          # integration (headless LVGL)
./run_tests.sh leak         # memory leak detection
./run_host.sh -s            # visual — screenshot all examples

Integration and leak tests run against a real LVGL instance with SDL_VIDEODRIVER=dummy (no display server needed). Sequential execution (--test-threads=1) because LVGL is single-threaded. CI runs both host tests and ESP32 firmware builds on every push.

Specifications

LVGL Configuration (conf/lv_conf.h)

LVGL is compiled from source with a project-specific lv_conf.h. Key settings:

Only widgets actually used are enabled (LV_USE_<WIDGET> 1) to minimize binary size on embedded. Adding a new widget requires enabling it here first.

Features

Build

# Host check:
LIBCLANG_PATH=/usr/lib64 cargo +nightly check --target x86_64-unknown-linux-gnu

# Host tests:
LIBCLANG_PATH=/usr/lib64 cargo +nightly test --target x86_64-unknown-linux-gnu

# Embedded check (requires Xtensa toolchain):
cargo +esp -Zbuild-std=alloc,core check --features esp-hal,log-04

oxivgl-sys/build.rs downloads and compiles LVGL from source via the cc crate. Expects DEP_LV_CONFIG_PATH pointing to lv_conf.h.

AI Statement

This library has been developed using agentic coding, mostly with Claude Code. The DMA/buffer foundations, architecture decisions, wrapper implementations, memory safety reviews, example porting, and documentation were built through human–AI collaboration.

The API is designed to be AI-friendly: discoverable, well-documented, and free of footguns. Architecture and design boundaries are captured in explicit specs. Rust's type system and borrow checker catch mistakes at compile time that would silently corrupt memory in C — when an AI agent generates widget code, the compiler enforces correct lifetimes, valid enum values, and proper ownership.

Contributors are encouraged to use AI tools. The project's specs, CLAUDE.md, and example patterns are structured to give AI agents the context they need to contribute effectively.

License

Licensed under either of MIT or Apache-2.0 at your option.