rlvgl-playit

A mini-playwright test driver for rlvgl.

rlvgl-playit lets you drive an rlvgl UI from an external host — injecting input events, querying widget state by tag, and inspecting framebuffer pixels — over any byte-oriented transport (serial UART, stdin/stdout, TCP, or in-process).

Features

• Input injection — send any Event variant (tap, pointer, key, tick, multi-touch) through the widget tree, by coordinate or by widget tag.
• Gesture routing — optionally pipe raw events through a gesture recognition pipeline (EventPipeline trait) so PointerDown/Up sequences produce the same PressRelease / DoubleTap events as real hardware.
• Event recording — capture a timed input session with per-tick deltas and dump it for replay. Record from live hardware, replay in CI.
• Widget tagging — address widgets by name instead of pixel coordinates. Tags are Option<&'static str> on WidgetNode, zero-cost when unused.
• Widget queries — ask for bounds, existence, or child count of a tagged widget.
• Framebuffer inspection — dump ARGB8888 pixel windows, synchronised to display present count.
• no_std by default — runs on bare-metal targets (STM32, etc.) with no allocator required.
• Transport-agnostic — implement the PlayitTransport trait (two methods) to plug in any byte stream.
• Text wire protocol — human-readable, backward-compatible with the original serial commands (T, D, ?), and extensible for new input types.

Quick start

Add the dependency:

[dependencies]
rlvgl-playit = "0.2.0"

Embedded (serial transport)

use rlvgl_playit::{PlayitExecutor, PlayitTransport, StatusData, NullPipeline};

struct SerialTransport;

impl PlayitTransport for SerialTransport {
    fn read_byte(&mut self) -> Option<u8> {
        serial::pop_rx()
    }
    fn write_bytes(&mut self, bytes: &[u8]) {
        serial::write_bytes(bytes);
    }
}

let mut executor = PlayitExecutor::new(SerialTransport);
let mut pipeline = NullPipeline;  // or a real GesturePipeline

// In your main loop:
let status = StatusData { tick_count, present_count };
executor.poll(&mut root, &status, Some(&fb_reader), &mut pipeline, |ext| {
    // handle app-specific extension commands
});

Gesture routing

use rlvgl_playit::EventPipeline;
use rlvgl::platform::gesture::TapRecognizer;

struct GesturePipeline { tap: TapRecognizer }

impl EventPipeline for GesturePipeline {
    fn process(&mut self, event: Event) -> (Option<Event>, Option<Event>) {
        (self.tap.process(&event), None)
    }
    fn tick(&mut self) -> (Option<Event>, Option<Event>) {
        (self.tap.tick(), None)
    }
}

Now PD100,200 followed by PU100,200 produces a debounced PressRelease that buttons actually respond to.

Widget tagging

use rlvgl_core::WidgetNode;

let node = WidgetNode::new(my_widget)
    .with_tag("settings_btn");

Then from the test host:

QE:settings_btn        -> EXISTS:1
QB:settings_btn        -> BOUNDS:10,20,80,40
T@settings_btn:40,30   -> OK

Event recording and replay

-> RS                   <- REC:recording
  (user interacts with the screen)
-> RE                   <- REC:START,4
                        <- @0 PD100,200
                        <- @3 PM105,205
                        <- @6 PU110,210
                        <- @12 PD300,150
                        <- REC:END

The @<delta> prefix is the tick count since the previous event. A host replay script converts these to wall-clock delays and sends the commands back.

Wire protocol

Commands are single lines terminated by \n or \r\n.

Feature flags

See OPTIONS.md for the full feature reference.

Test runners

The repository ships ready-to-run playit test suites for every target:

The rlvgl-playit Node.js client is in playit/node/. See playit/node/test/ for the test files driven by the runners above.

License

MIT