Skip to main content

Crate slint_mipidsi_adapter

Crate slint_mipidsi_adapter 

Source
Expand description

§slint-mipidsi-adapter

English | Русская версия

slint-mipidsi-adapter is a small #![no_std] Slint platform adapter for microcontrollers. It connects:

  • a configured, but not yet initialized, mipidsi::Builder;
  • a touch input implementation through TouchInput;
  • a monotonic clock and waiting implementation through McuRuntime;
  • Slint’s software renderer.

After initialization, the adapter returns the generated Slint component without wrapping it. You can use it like a regular Slint application: set properties, register callbacks, and call show() or run().

The crate targets Slint 1.17, mipidsi 0.10, and embedded-hal 1.0.

§What the adapter does

  • Accepts a ready-to-use mipidsi::Builder with the selected display model, interface, orientation, and reset pin.
  • Calls mipidsi::Builder::init.
  • Installs a global slint::platform::Platform implementation.
  • Renders the UI line by line in RGB565 format.
  • Stores only one pixel line, approximately width × 2 bytes, instead of a full-screen framebuffer.
  • Converts one touch contact into Slint pointer events, or up to five contacts into Slint’s native touch/gesture input.
  • Supports both a blocking event loop and a step-based event loop for Embassy or another cooperative executor.

The adapter does not configure SPI/I²C, bus frequencies, power rails, backlight, touch calibration, or the global allocator. These parts depend on the target board and remain the responsibility of the application’s BSP.

§Dependency setup

[dependencies]
slint-mipidsi-adapter = "0.2.2"

slint = { version = "~1.17.1", default-features = false, features = [
    "compat-1-2",
    "unsafe-single-threaded",
    "libm",
    "renderer-software",
] }

[build-dependencies]
slint-build = "~1.17.1"

Slint requires a global allocator on bare metal. Install and initialize it before constructing the Slint component.

Slint permits only one global platform. If the adapter installs the platform successfully and app_factory then returns an error, that platform remains installed. Rebuilding the adapter in the same process will normally fail; on an MCU, treat this initialization failure as terminal or restart the device.

Prepare UI resources for the software renderer:

ⓘ
fn main() {
    slint_build::compile_with_config(
        "ui/app.slint",
        slint_build::CompilerConfiguration::new()
            .embed_resources(
                slint_build::EmbedResourcesKind::EmbedForSoftwareRenderer,
            ),
    )
    .unwrap();
}

§Basic usage

The application first configures the board’s power, GPIO, SPI, I²C, and device controllers. It then passes a configured mipidsi::Builder, touch input, and runtime to AdapterBuilder.

ⓘ
#![no_std]
#![no_main]

extern crate alloc;

use core::time::Duration;
use slint::ComponentHandle;
use slint_mipidsi_adapter::{
    AdapterBuilder, McuRuntime, TouchInput, TouchPoint,
};

slint::include_modules!();

struct BoardTouch {
    // I²C touch driver, calibration state, and so on.
}

impl TouchInput for BoardTouch {
    type Error = TouchError;

    fn read_touch(&mut self) -> Result<Option<TouchPoint>, Self::Error> {
        let sample = self.driver.scan()?;

        Ok(sample.map(|sample| {
            // Apply calibration and orientation conversion here.
            TouchPoint::new(sample.x, sample.y)
        }))
    }
}

struct BoardRuntime {
    // The board's monotonic timer.
}

impl McuRuntime for BoardRuntime {
    fn now(&self) -> Duration {
        Duration::from_micros(self.timer.now_micros())
    }

    fn wait(&mut self, duration: Duration) {
        self.timer.arm(duration);
        cortex_m::asm::wfi();
    }
}

#[entry]
fn main() -> ! {
    // 1. Initialize the allocator, power, GPIO, SPI, and I²C.
    // 2. Enable display power and backlight.
    // 3. Hardware-reset the display and touch controller if required.

    let display_builder = mipidsi::Builder::new(
        mipidsi::models::ST7789,
        display_interface,
    )
    .reset_pin(display_reset)
    .display_size(240, 320)
    .orientation(
        mipidsi::options::Orientation::new()
            .rotate(mipidsi::options::Rotation::Deg90),
    );

    let app = AdapterBuilder::new(display_builder, board_touch, board_runtime)
        .build(&mut delay, AppWindow::new)
        .unwrap();

    // The returned value is the actual generated Slint component.
    app.set_counter(42);
    app.on_increment({
        let app = app.as_weak();
        move || {
            if let Some(app) = app.upgrade() {
                app.set_counter(app.get_counter() + 1);
            }
        }
    });

    app.run().unwrap();

    loop {
        cortex_m::asm::wfi();
    }
}

§Using Embassy

Do not call the blocking app.run() from an Embassy task: it would never yield control back to the executor. Use build_with_event_loop in async applications.

ⓘ
let (app, event_loop) =
    AdapterBuilder::new(display_builder, touch, runtime)
        .frame_interval(core::time::Duration::from_millis(33))
        .touch_poll_interval(core::time::Duration::from_millis(10))
        .build_with_event_loop(&mut delay, AppWindow::new)?;

app.show()?;

while event_loop.is_running() {
    let wait = event_loop.step()?;
    let micros = wait.as_micros().min(u128::from(u64::MAX)) as u64;

    if micros == 0 {
        embassy_time::Timer::after_ticks(1).await;
    } else {
        embassy_time::Timer::after_micros(micros).await;
    }
}

One McuEventLoop::step call processes only work whose deadline is due:

  1. updates due Slint timers and animations;
  2. samples touch when its independent polling deadline is due;
  3. dispatches any resulting pointer event;
  4. renders pending changes on the next due frame;
  5. returns the remaining duration until the nearest relevant deadline.

Time spent inside step() is included in the configured cadence. For example, with a 16 ms frame interval and 4 ms of work, the returned wait is about 12 ms, not another 16 ms. A nearer Slint timer always wins.

A complete ESP32 implementation is available in examples/m5stack-core2.

§Display without touch

Use AdapterBuilderWithoutTouch when the product has no touch controller or when input is handled entirely through another mechanism:

ⓘ
use slint_mipidsi_adapter::AdapterBuilderWithoutTouch;

let app = AdapterBuilderWithoutTouch::new(display_builder, runtime)
    .build(&mut delay, AppWindow::new)?;

app.run()?;

The same builder supports a cooperative event loop:

ⓘ
let (app, event_loop) =
    AdapterBuilderWithoutTouch::new(display_builder, runtime)
        .poll_interval(core::time::Duration::from_millis(50))
        .build_with_event_loop(&mut delay, AppWindow::new)?;

app.show()?;

while event_loop.is_running() {
    let wait = event_loop.step()?;
    embassy_time::Timer::after_micros(wait.as_micros() as u64).await;
}

AdapterBuilderWithoutTouch installs NoTouch internally. The application does not need a dummy TouchInput implementation. Slint timers, animations, property updates, callbacks invoked by application code, and rendering continue to work normally; the platform simply does not generate pointer events.

Without touch, an inactive animation no longer caps a distant Slint timer to the frame interval. A completely idle UI uses a one-second safety poll instead of waking at 60 Hz. McuRuntime::wait(Duration) cannot represent an indefinite event wait; a runtime with interrupt support should return early when external work arrives, and a cooperative caller may invoke step() before the returned deadline after changing application state.

§Touch input in detail

§The TouchInput contract

TouchInput is a synchronous polling interface:

ⓘ
pub trait TouchInput {
    type Error;

    fn read_touch(&mut self)
        -> Result<Option<TouchPoint>, Self::Error>;

    fn read_touches(&mut self, contacts: &mut [TouchContact])
        -> Result<usize, Self::Error>;
}

In the default TouchMode::Single, read_touch must return a snapshot of the current primary contact, not a queue of one-shot events:

  • Ok(Some(point)): a finger is currently touching the screen;
  • Ok(None): there is currently no active contact;
  • Err(error): the controller or bus could not complete the read.

While a finger remains down, the implementation must return Some(point) on every poll. Returning a coordinate only for the initial IRQ and then returning None would be interpreted as an immediate release.

§How states become Slint events

The adapter remembers the previous state and produces events automatically:

Previous stateNew stateSlint event
NoneNoneno event
NoneSome(point)PointerPressed
Some(old)Some(new), coordinates changedPointerMoved
Some(point)the same pointno event
Some(old)NonePointerReleased, then PointerExited

Standard Slint controls such as Button, TouchArea, and Slider therefore work without special code in the .slint file:

import { Button } from "std-widgets.slint";

export component AppWindow inherits Window {
    in-out property <int> counter: 0;

    Button {
        text: "Press";
        clicked => {
            root.counter += 1;
        }
    }
}

§Selecting single-touch or multi-touch

Existing applications remain single-touch by default. Select native Slint multi-touch while constructing the adapter:

ⓘ
use slint_mipidsi_adapter::{AdapterBuilder, TouchMode};

let builder = AdapterBuilder::new(display, touch, runtime)
    .touch_mode(TouchMode::Multi);

In Single mode the adapter calls only read_touch and retains the previous pointer behavior. In Multi mode it calls read_touches with a fixed-capacity buffer. The implementation must:

  • write a complete snapshot of all active contacts on every poll;
  • assign each contact a unique ID that remains stable until release;
  • return the number of entries written, never more than the slice length;
  • omit released contacts from the next snapshot.

Up to MAX_TOUCH_CONTACTS (five) contacts are tracked in fixed arrays without heap allocation. The default read_touches implementation adapts read_touch() as contact ID zero, so enabling Multi does not break a single-contact driver.

Slint forwards one contact as ordinary pointer input. With two contacts it recognizes pinch and rotation gestures for ScaleRotateGestureHandler. Multiple fingers are not treated as independent simultaneous mouse clicks on different buttons; this follows Slint’s native touch model.

export component GestureView inherits Window {
    in-out property<float> preview-scale: 1;
    in-out property<angle> preview-rotation: 0deg;

    gesture := ScaleRotateGestureHandler {
        updated => {
            root.preview-scale = self.scale;
            root.preview-rotation = self.rotation;
        }
    }
}

Slint 1.17 does not expose contact IDs through public WindowEvent, so the adapter enters Slint’s backend touch API directly. i-slint-core is already a dependency of Slint and adds no second runtime or extra heap use, but this API is internal. The dependency is therefore restricted to Slint 1.17.x; moving to a new Slint minor version requires passing the multi-touch integration test.

§Minimal implementation

If the driver already provides calibrated screen coordinates, the adapter can be as small as:

ⓘ
struct MyTouch<DRIVER> {
    driver: DRIVER,
}

impl<DRIVER> TouchInput for MyTouch<DRIVER>
where
    DRIVER: TouchDriver,
{
    type Error = DRIVER::Error;

    fn read_touch(&mut self) -> Result<Option<TouchPoint>, Self::Error> {
        let data = self.driver.read_primary_touch()?;

        Ok(data.map(|point| TouchPoint::new(point.x, point.y)))
    }
}

For devices without a touch panel, prefer AdapterBuilderWithoutTouch. The lower-level NoTouch implementation remains available when generic code needs to construct AdapterBuilder directly.

§FT6336U example

ft6336u-driver reports up to two points. Implement read_touch for the default single-touch mode and read_touches for TouchMode::Multi:

ⓘ
use embedded_hal::i2c::I2c;
use ft6336u_driver::{
    Error, FT6336U, GestureMode, TouchStatus,
};
use slint_mipidsi_adapter::{TouchContact, TouchInput, TouchPoint};

struct Ft6336Touch<I2C> {
    controller: FT6336U<I2C>,
}

impl<I2C> Ft6336Touch<I2C>
where
    I2C: I2c,
{
    fn new(i2c: I2C) -> Result<Self, Error<I2C::Error>> {
        let mut controller = FT6336U::new(i2c);

        // The adapter polls regularly, making polling mode the simplest and
        // most reliable option.
        controller.write_g_mode(GestureMode::Polling)?;

        Ok(Self { controller })
    }
}

impl<I2C> TouchInput for Ft6336Touch<I2C>
where
    I2C: I2c,
{
    type Error = Error<I2C::Error>;

    fn read_touch(&mut self) -> Result<Option<TouchPoint>, Self::Error> {
        let data = self.controller.scan()?;

        Ok(data
            .points
            .iter()
            .find(|point| point.status != TouchStatus::Release)
            .map(|point| TouchPoint::new(point.x, point.y)))
    }

    fn read_touches(
        &mut self,
        contacts: &mut [TouchContact],
    ) -> Result<usize, Self::Error> {
        let data = self.controller.scan()?;
        let mut count = 0;

        for (slot_id, point) in data.points.iter().enumerate() {
            if point.status == TouchStatus::Release || count == contacts.len() {
                continue;
            }

            contacts[count] = TouchContact::new(
                slot_id as u8,
                TouchPoint::new(point.x, point.y),
            );
            count += 1;
        }

        Ok(count)
    }
}

ft6336u-driver 1.0 stores each scanned point at the array index selected by the FT6336U hardware touch ID. The example therefore uses that array index as the stable ID.

If the PMIC, touch controller, RTC, and other devices share one I²C bus, give each driver a virtual device from embedded-hal-bus:

ⓘ
use core::cell::RefCell;
use embedded_hal_bus::i2c::RefCellDevice;

let bus = RefCell::new(i2c);

let touch_i2c = RefCellDevice::new(&bus);
let pmic_i2c = RefCellDevice::new(&bus);

let touch = Ft6336Touch::new(touch_i2c)?;
let power = Axp192::new(pmic_i2c);

RefCellDevice is suitable only for single-threaded access. This matches Slint’s unsafe-single-threaded mode when all access occurs in one task and never from an interrupt handler.

§Coordinates, rotation, and mirroring

TouchPoint must use the logical display coordinate system after applying the mipidsi::Builder configuration:

  • (0, 0) is the top-left corner of the Slint window;
  • x increases to the right;
  • y increases downwards;
  • maximum values are normally width - 1 and height - 1.

Rotating the LCD with mipidsi::Builder::orientation does not necessarily rotate the touch controller’s raw coordinates. The BSP or TouchInput implementation must apply the same transform.

For a raw panel of size W × H, typical transforms are:

OrientationLogical coordinate
0°(x, y)
90° clockwise(H - 1 - y, x)
180°(W - 1 - x, H - 1 - y)
270° clockwise(y, W - 1 - x)

A particular controller may already swap axes or invert one of them. Verify the conversion against all four corners of the physical display.

By default, the adapter clamps final coordinates to the display bounds. This preserves the behavior of versions before 0.2.1 and protects against isolated outliers, but does not replace calibration.

For a digitizer whose active area is physically larger than the LCD, select OutOfBoundsTouch::Ignore:

ⓘ
use slint_mipidsi_adapter::OutOfBoundsTouch;

let builder = AdapterBuilder::new(display, touch, runtime)
    .out_of_bounds_touch(OutOfBoundsTouch::Ignore);

An outside sample with no active contact produces no event. If a contact began inside and then moves outside, the adapter emits PointerReleased at the last valid position followed by PointerExited; a later re-entry begins a new press. This prevents both false edge presses and a permanently pressed Slint pointer.

In multi-touch mode the same policy is applied independently to every contact. An active contact that leaves the viewport receives Ended at its last valid position, while the remaining contacts continue normally.

§Calibrating raw coordinates

If a controller reports values in a raw_min..raw_max range, scale them to the Slint window size:

ⓘ
fn scale_axis(raw: u16, raw_min: u16, raw_max: u16, screen_size: u16) -> u16 {
    let raw = raw.clamp(raw_min, raw_max);
    let input = u32::from(raw - raw_min);
    let input_range = u32::from(raw_max - raw_min).max(1);
    let output_range = u32::from(screen_size.saturating_sub(1));

    (input * output_range / input_range) as u16
}

For a more accurate resistive or non-linear panel, apply an affine transform before creating the TouchPoint.

Some panels have an active area larger than the LCD. For example, the M5Stack Core2 FT6336U reports a 320×280 area: the bottom 40 rows belong to three capacitive zones below the display. Use OutOfBoundsTouch::Ignore, or discard such samples in the driver:

ⓘ
if raw_y >= DISPLAY_HEIGHT {
    return Ok(None);
}

Leaving the default Clamp policy in this case would turn a touch below the screen into a false touch on its bottom edge.

§Polling and interrupts

By default, both the target frame cadence and touch cadence are 16_667 microseconds, approximately 60 Hz. poll_interval remains backward compatible and sets both values:

ⓘ
let builder = AdapterBuilder::new(display, touch, runtime)
    .poll_interval(core::time::Duration::from_millis(10));

A shorter interval reduces input latency but increases I²C traffic and CPU active time.

To tune them independently, use frame_interval and touch_poll_interval:

ⓘ
let builder = AdapterBuilder::new(display, touch, runtime)
    .frame_interval(core::time::Duration::from_millis(33)) // about 30 FPS
    .touch_poll_interval(core::time::Duration::from_millis(10)); // 100 Hz input

Each setter overrides only its own cadence. Calling poll_interval later resets both; calling either specific setter later overrides that part. Work that overruns an interval is followed by a zero wait rather than an extra full interval.

An IRQ may wake the MCU or set a “controller needs reading” flag. However:

  • never call Slint APIs directly from an interrupt handler;
  • perform I²C reads in a regular task;
  • after the initial IRQ, keep returning Some(point) while the finger remains down;
  • the release must still produce one Ok(None) sample.

If the controller’s IRQ is a short pulse, merely checking the current GPIO level in read_touch() can miss events. Latch a flag from the IRQ or configure the controller for polling mode.

§Read errors

A TouchInput::Error is converted into slint::PlatformError.

  • With blocking app.run(), the event loop exits with an error.
  • With manual event_loop.step(), the current step returns the error.

For robust products, distinguish temporary I²C failures from permanent failures. A BSP may retry, recover the bus, or skip one sample. Avoid converting every temporary failure to Ok(None): during a hold, this produces a false PointerReleased followed by another PointerPressed.

§Testing a touch implementation

Before connecting a complex UI, verify:

  1. touches in all four corners;
  2. horizontal and vertical movement;
  3. a stationary hold without false releases;
  4. a correct release;
  5. no events outside the LCD area;
  6. operation after wake-up and I²C reinitialization;
  7. coordinates matching the selected mipidsi rotation;
  8. stable IDs while two contacts move and cross;
  9. pinch/rotation handling and lifting either finger first.

A standard Slint button should then press, display its held state, and emit clicked only after a correct press/release sequence.

§The McuRuntime contract

McuRuntime::now must return monotonic time. Slint uses it for timers and animations.

McuRuntime::wait receives the remaining time until the earliest relevant deadline:

  • the duration until the nearest Slint timer;
  • the next animation/frame iteration when one is needed;
  • the next touch poll when touch is configured.

The adapter measures each iteration with McuRuntime::now and subtracts its work time. Thus a 14 ms render at a 16 ms interval waits about 2 ms; a render that takes 20 ms does not add another sleep. No wall clock or std timing is used.

It may return early, for example after a touch IRQ. In a step-based Embassy event loop, the async task performs the wait itself. The runtime still remains part of the installed platform and allows ordinary app.run() to work.

All Slint calls must stay on one thread/task and must not run from an interrupt handler.

§Display and memory

The line renderer uses Rgb565Pixel and calls DrawTarget::fill_contiguous for the changed range of each line.

If an LCD write fails after part of a frame reached the panel, the error is still returned as PlatformError. The adapter also preserves the first display error, requests another redraw, and marks the next rendering attempt as a full screen repaint. After that full repaint succeeds, Slint returns to ReusedBuffer partial rendering; the internal cache is primed without a second LCD transfer, so subsequent dirty updates remain partial.

The line buffer is currently a heap-allocated Vec created once during initialization. It contains exactly one display row. A future non-breaking API can add a caller-owned 'static row for DMA-capable/static memory, but doing so ergonomically requires carrying that lifetime through Slint’s global Platform; version 0.2.2 deliberately avoids an unsafe or invasive redesign.

The Rgb565 and Rgb666 formats exposed by mipidsi 0.10 are supported through conversion from embedded_graphics_core::pixelcolor::Rgb565.

The adapter does not use DMA and does not own the SPI configuration. Tune the SPI frequency, display-interface buffer size, and DMA in the target MCU’s BSP.

§References

Structs§

AdapterBuilder
Builds and installs the Slint MCU platform.
AdapterBuilderWithoutTouch
Builds a Slint MCU platform for a display without touch input.
McuEventLoop
A cooperative, step-based Slint event loop.
NoTouch
A touch provider for displays without a touch controller.
TouchContact
A touch contact with an identifier that remains stable for its lifetime.
TouchPoint
A touch position in the logical pixel coordinate system of the configured display.

Enums§

AdapterError
An error produced while initializing the adapter and constructing the Slint component.
OutOfBoundsTouch
Controls how touch samples outside the Slint viewport are handled.
TouchMode
Selects whether the adapter processes one or multiple simultaneous contacts.

Constants§

MAX_TOUCH_CONTACTS
Maximum number of simultaneous contacts tracked without heap allocation.

Traits§

McuRuntime
Time and waiting operations required by the MCU event loop.
TouchInput
A polling touch-screen abstraction.

Type Aliases§

BuildWithEventLoopResult
Result type returned by AdapterBuilder::build_with_event_loop.