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::Builderwith the selected display model, interface, orientation, and reset pin. - Calls
mipidsi::Builder::init. - Installs a global
slint::platform::Platformimplementation. - Renders the UI line by line in RGB565 format.
- Stores only one pixel line, approximately
width × 2bytes, 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:
- updates due Slint timers and animations;
- samples touch when its independent polling deadline is due;
- dispatches any resulting pointer event;
- renders pending changes on the next due frame;
- 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 state | New state | Slint event |
|---|---|---|
None | None | no event |
None | Some(point) | PointerPressed |
Some(old) | Some(new), coordinates changed | PointerMoved |
Some(point) | the same point | no event |
Some(old) | None | PointerReleased, 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;xincreases to the right;yincreases downwards;- maximum values are normally
width - 1andheight - 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:
| Orientation | Logical 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 inputEach 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:
- touches in all four corners;
- horizontal and vertical movement;
- a stationary hold without false releases;
- a correct release;
- no events outside the LCD area;
- operation after wake-up and I²C reinitialization;
- coordinates matching the selected
mipidsirotation; - stable IDs while two contacts move and cross;
- 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§
- Adapter
Builder - Builds and installs the Slint MCU platform.
- Adapter
Builder Without Touch - Builds a Slint MCU platform for a display without touch input.
- McuEvent
Loop - A cooperative, step-based Slint event loop.
- NoTouch
- A touch provider for displays without a touch controller.
- Touch
Contact - A touch contact with an identifier that remains stable for its lifetime.
- Touch
Point - A touch position in the logical pixel coordinate system of the configured display.
Enums§
- Adapter
Error - An error produced while initializing the adapter and constructing the Slint component.
- OutOf
Bounds Touch - Controls how touch samples outside the Slint viewport are handled.
- Touch
Mode - 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.
- Touch
Input - A polling touch-screen abstraction.
Type Aliases§
- Build
With Event Loop Result - Result type returned by
AdapterBuilder::build_with_event_loop.