STM32H7 LTDC + board family: would a contribution series be welcome, and what's the preferred architecture?

[nuraci]

Hi @kdschlosser, hi everyone,

I've spent the last several months building LVGL+MicroPython support for a family of affordable STM32H743 boards (DEV190806042, FK743M5-XIH6, STM32H7_CORE). They share the same recipe: external SDRAM, QSPI flash, and an RGB TFT panel driven by the H7's hardware LTDC peripheral. Working end-to-end on real hardware, I currently have:

• Three MicroPython board definitions (mpconfigboard, QSPI block device, linker with heap in SDRAM, USB FS dual CDC + MSC).
• A C MicroPython module that drives LTDC with double buffering, VSYNC-synced flush, DMA2D-accelerated partial updates, framebuffer write-through via the MPU, and AXI QoS tuned to avoid LTDC underrun.
• A GT911 I2C touch driver and a small Python layer for auto board/panel selection.
• A working LVGL demo.

I originally pushed this upstream as lvgl/lv_micropython#104, #105 and lvgl/lv_binding_micropython#407, but that side of the project is effectively unmaintained: the STM32 CI workflow is disabled, the runner-update PR has been open since Aug 2025, my PRs are sitting untouched. I'd rather invest the migration effort once and land it where the project is actually moving — i.e. here.

Before I start cutting code I'd like to align on architecture. To keep this thread focused I'll lead with the one question that drives everything else.

LTDC doesn't really fit the lcd_bus "push pixels" model — it's a hardware scan-out from SDRAM, conceptually closer to the ESP32 RGBBus. Would you prefer:

(a) an LTDCBus as a subclass of lcd_bus, symmetric with RGBBus;
(b) a standalone driver under api_drivers/common_api_drivers/display/ behind a CONFIG_STM32 / port guard;
(c) something built on top of the existing generic rgb_display driver?

I have follow-on questions — board routing (direct PR to micropython/micropython vs micropy_updates/), alignment with the existing GT911 driver, and how STM32 SoC-specific drivers should be wired into make.py — but they all depend on (a)/(b)/(c), so let's start there.

One practical note: you've mentioned on the LVGL forum that lack of STM32 hardware is a blocker. I have these three boards on my bench and I'm willing to do the debugging and ongoing maintenance for them. If a self-hosted GitHub Actions runner wired to one of the boards would help close the CI loop, I can set that up.

Refs:

• Stalled PRs: Add STM32H743 board support: DEV190806042, FK743M5-XIH6, STM32H7_CORE lvgl/lv_micropython#104, No picture appears on the ili9341 display #105 — Add LTDC display and GT911 touch drivers for STM32H7 boards lvgl/lv_binding_micropython#407
• Boards docs/photos/videos: https://github.com/Copper-And-Code/stm32h7-boards-docs

Thanks!
— Nuraci (@nuraci)

[nuraci]

demo_auto.mp4

[kdschlosser]

what exactly do you need to know? I will give you whatever information you need an if the API needs to change in order for the STM bus drivers to work with the current design between the bus drivers and the display drivers then I am OK with doing that.

nothing gets changed in libs/micropython. If the code in micropython needs to be changed then changes needs to be hot patched and written in python scripts to handle that. That's of the change is not for a specific port. If the change is port specific then a copy of the existing file need to be placed in the micropy_updates folder retaining the directory structure from the port folder to the file. then that file needs to have the modifications made to it as needed.

The bus drivers need to be written in a manner that allows them to be a runtime choice. as an example. If using an I8080 display either 8 pins or 16 pins should be able to be selected when the bus driver starts, The use of DMA memory should also be a runtime choice if a choice is available to make.

[nuraci]

Thanks @kdschlosser. Reading your reply, my takeaways are:

1. Boards routing: anything port-specific lives in micropy_updates/ports/stm32/boards/... mirroring the upstream tree. lib/micropython/ stays untouched. I'll also submit the three boards to micropython/micropython upstream in parallel, so the patches in micropy_updates/ can be dropped at a later submodule bump.
2. LTDC architecture: from your "STM bus drivers" wording I'm reading option (a) — LTDC as a subclass of lcd_bus, i.e. LTDCBus. Tell me if I'm misreading.
3. Runtime configurability: no compile-time pinning. All hardware choices (pin width, DMA, framebuffer count, pixel format, panel timings) become constructor arguments. Understood.

With that, here's where I'll likely need to extend the existing bus API. Push back where any of these conflicts with your intent:

• Framebuffer allocation. Today bus.allocate_framebuffer on ESP32 maps to heap_caps_malloc(SPIRAM | DMA). On STM32H7 the framebuffer must live in external SDRAM at a fixed mapped address (not on the heap), cacheline-aligned, with the MPU region set to write-through. I'd add a per-port backend behind the same signature — invisible to display drivers.
• Continuous scan-out vs push. LTDC isn't a "push pixels" peripheral; it continuously scans the framebuffer at the panel refresh rate. The current tx_color / flush_ready contract would mean "DMA2D blit from staging to active framebuffer complete and next VSYNC reached" rather than "bytes shifted out". I'd drive the callback from the LTDC line-interrupt. Callback semantics from the display driver's point of view stay the same.
• LTDCBus constructor parameters (all runtime): panel timings (HSYNC/VSYNC/back+front porch/pixel clock), pixel format (RGB565 / RGB888 / ARGB8888 / L8), framebuffer count (1 or 2), DMA2D enable, optional second LTDC layer for cursor/OSD.
• DMA2D as a sibling module. DMA2D is used by the bus for partial flushes but is also useful to user code for blits and color conversion. I'd expose it as a small standalone module rather than hiding it inside LTDCBus.

Proposed PR sequence, smallest-first to keep reviews tractable:

1. PR1 — scaffolding: LTDCBus skeleton + one board (STM32H7_CORE) + minimal demo. Single framebuffer, RGB565, no DMA2D yet. Goal: validate the architecture before scaling.
2. PR2: DMA2D + double buffering + VSYNC sync.
3. PR3: the other two boards (FK743M5-XIH6, DEV190806042) + per-panel timing tables.
4. PR4 (only if needed): adjustments to the existing GT911 driver and make.py wiring for STM32 SoC-specific drivers.

Two small things deferred until PR1 lands, so we don't fragment this thread:

• Existing GT911 driver in api_drivers/common_api_drivers/indev/ — happy to use it as-is on the three boards; any known issues I should pre-empt?
• Self-hosted runner offer still stands once the architecture is stable and there's something worth keeping green.

Will start on PR1 unless you flag any of the above as off-track.

— Nuraci

[kdschlosser]

You really cannot stage the bus drivers. They need to be an all or none for each driver. Meaning if you are writing the driver for the I8080 bus it needs to support 8 lanes, 18 lanes and DMA buffers out of the box.

Look at the drivers for the ESP32. that is basically how they need to be done. I am not familiar with the STM SDK or to what extent they provide helper functions and structures for getting a display up and running.

There are 2 libraries that I looked at the code for to see what the STM32 code looks like and it appears like it is a lot of macros based on the MCU that is being used.

https://github.com/RobertoBenjami/stm32_hal_graphics_display_drivers
https://github.com/RobertoBenjami/stm32_graphics_display_drivers

While those drivers could not be used directly because the display bus is a compile time choice and not runtime the information in it can be used as a reference to write the drivers for this project. They would need to be written in the same manner that is seen with the ESP32 drivers.

[kdschlosser]

I am also unfamiliar with the terms LTDC and FSMC etc... the display bus types conform to MIPI naming which is RGB, SPI, I8080, DSI and I2C.

[nuraci]

Thanks @kdschlosser, this clarifies a lot — three things land:

1. LTDC = STM32 backend of RGBBus. Got it. Hardware scan-out from a framebuffer to a parallel TFT panel is exactly the RGB / MIPI DPI model. The st_ltdc.LTDC from my original PR becomes the STM32 implementation of the existing RGBBus, not a new class.
2. No staging. Understood. The bus driver lands complete: all relevant pixel formats, single/double buffer runtime selectable, full panel timing parameters, the lot. Boards remain separate PRs since they're not bus driver work.
3. Benjami repos as study material, not basis. Agreed — useful for LTDC register sequences and panel init patterns, not for the API shape.

Before I start cutting code I'd appreciate three quick pointers to avoid going sideways:

• Which file in this repo do you consider the canonical reference for RGBBus? I want to read it end-to-end against the API I'll need to match.
• Multi-layer support. LTDC has 2 hardware layers with alpha blending. Your preference: hide it as an internal optimization (single visible layer to Python), or extend the RGBBus API to optionally expose layers across backends?
• Framebuffer allocation for fixed-mapped memory. On STM32H7 the SDRAM lives at a known physical address (0xC0000000), not allocatable from a heap. Is there an existing precedent in the codebase for this pattern, or should I propose an allocate_framebuffer extension that accepts a pre-mapped region?

Will start reading code and come back with a concrete proposal once those are settled.

— Nuraci