Skip to content

stm: add paralleldisplaybus using the FSMC - #11908

Merged
tannewt merged 1 commit into
adafruit:mainfrom
vegardw:stm-fsmc-display
Nov 18, 2026
Merged

tannewt merged 1 commit into
adafruit:mainfrom
vegardw:stm-fsmc-display

Conversation

@vegardw

@vegardw vegardw commented Nov 18, 2026

Copy link
Copy Markdown

Adds paralleldisplaybus.ParallelBus to the STM port, using the FSMC, with FSMC pin tables for the STM32F412Rx package from #11896. No upstream board enables it yet: the ELECFREAKS Retro Arcade will, in its board PR.

Problem

The Retro Arcade's ILI9341 display (320×240) is wired to the STM32F412's FSMC as an 8-bit 8080-style bus: D0–D7 on the FSMC data pins, the write strobe on FSMC_NWE. The STM port has no paralleldisplaybus backend, so it can't drive it.

Fix

A write-only, 8-bit ParallelBus on FSMC bank 1 in SRAM mode. Each byte is one store to 0x60000000, and the FSMC clocks it out with a write pulse. Command, chip select and reset are GPIOs; no FSMC address lines are used.

  • data_pins must be the FSMC D0–D7 pins in order, write an FSMC_NWE pin and read (if given) FSMC_NOE, checked against new pin tables before anything is claimed. The data0= form is refused: the FSMC data lines aren't consecutive GPIOs.
  • frequency sets the write timing (DATAST), so the bus never runs faster than asked. A write takes DATAST + 3 HCLK cycles and DATAST is at most 255, so a frequency below the slowest write (258 cycles, 387597 Hz at 100 MHz) is refused instead of running faster.
  • deinit() does nothing for a bus whose constructor refused, as on the other ports, so a refused second bus can't turn off the FSMC under a working display when its slot is released.
  • The pin tables are added for the STM32F412Rx (LQFP64). CIRCUITPY_PARALLELDISPLAYBUS stays off unless a board turns it on.

Testing

On an ELECFREAKS Retro Arcade (STM32F412RE) with its board definition (not yet upstream), on main e8042e8c9d (which includes #11896), using the script below:

Check Result
Data pins out of order; a write pin that isn't FSMC_NWE; data0=; frequency=100_000 each refused with ValueError
ParallelBus with the board's pins, and a BusDisplay builds
Raw bus speed, a 30720-byte send() 83 ns per byte (about 12 MB/s)
Full-screen refresh, 320×240 at 16 bits 241 ms
Colour bars red, green, blue and white from left to right, checked by eye
A refused second ParallelBus (free, non-FSMC pins) on a test build with two display slots, released when code.py ends the board display keeps working; without the deinit() guard the board hard-faults into safe mode at that point

The last row isn't part of the script: it used test builds that set CIRCUITPY_DISPLAY_LIMIT to 2 (the Retro Arcade has one slot, so it can't happen there), with and without the guard, and a code.py that only tries the second bus. The same checks without the frequency refusal passed earlier on macOS and Linux, with the same timing; the REPL, displayio and Stage also display correctly on this board. Boards that don't enable it build to byte-identical firmware (Meowbit in ru, Feather STM32F405 Express, F412ZG Discovery, Swan R5, Nucleo H743ZI2), on the same main. The branch was then rebased onto main 15f9a04b06, which only adds vectorio, LVGL and Zephyr changes; there the Retro Arcade builds, and the Meowbit (ru) and F412ZG Discovery images are still unchanged by this PR. No upstream STM board enables CIRCUITPY_PARALLELDISPLAYBUS yet, so CI compiles this backend only once a board does.

How to run the test

You need an STM32F412Rx board with an 8-bit parallel ILI9341 on the FSMC pins (the Retro Arcade), or adapt the pins and init sequence. Copy the script as code.py and watch the serial console and the screen:

cp parallelbus_test.py /media/$USER/CIRCUITPY/code.py
python3 -m serial.tools.miniterm /dev/ttyACM0 115200

Expect six PASS lines, the timing, and red, green, blue and white bars. The script releases the board's display, so hard-reset afterwards to get board.DISPLAY back.

parallelbus_test.py
# Copy to CIRCUITPY as code.py on the ELECFREAKS Retro Arcade.
#
# Releases the board's display, checks that bad pin sets and a frequency the bus
# can't go down to are rejected, then builds the FSMC bus and an ILI9341 display
# from Python, measures the bus speed and shows four colour bars: red, green,
# blue and white from left to right. Prints PASS or FAIL for each check on the
# serial console.
import time

import busdisplay
import displayio
import microcontroller
import paralleldisplaybus

pin = microcontroller.pin
# FSMC D0-D7, in order
DATA = [pin.PB14, pin.PC06, pin.PC11, pin.PC12, pin.PA02, pin.PA03, pin.PA04, pin.PA05]
CONTROL = {
    "command": pin.PC03,
    "chip_select": pin.PB12,
    "read": pin.PC05,
    "reset": pin.PB07,
    "frequency": 15_000_000,
}

# MakeCode's ILI9341 set-up: command, argument count (+0x80 if a delay in ms follows), arguments.
INIT = (
    b"\xef\x03\x03\x80\x02"
    b"\xcf\x03\x00\xc1\x30"
    b"\xed\x04\x64\x03\x12\x81"
    b"\xe8\x03\x85\x00\x78"
    b"\xcb\x05\x39\x2c\x00\x34\x02"
    b"\xf7\x01\x20"
    b"\xea\x02\x00\x00"
    b"\xc0\x01\x23"  # power control
    b"\xc1\x01\x10"
    b"\xc5\x02\x3e\x28"  # VCOM control
    b"\xc7\x01\x86"
    b"\x36\x01\x28"  # memory access control: MV, BGR (landscape)
    b"\x37\x01\x00"
    b"\x3a\x01\x55"  # 16 bits per pixel
    b"\xb1\x02\x00\x10"  # frame rate
    b"\xb6\x03\x08\x82\x27"
    b"\xf2\x01\x00"
    b"\x26\x01\x01"
    b"\xe0\x0f\x0f\x31\x2b\x0c\x0e\x08\x4e\xf1\x37\x07\x10\x03\x0e\x09\x00"
    b"\xe1\x0f\x00\x0e\x14\x03\x11\x07\x31\xc1\x48\x08\x0f\x0c\x31\x36\x0f"
    b"\x11\x80\x78"  # sleep out, 120 ms
    b"\x29\x80\x78"  # display on, 120 ms
)


def check(name, ok):
    print("PASS" if ok else "FAIL", name)


def rejected(name, **pins):
    try:
        paralleldisplaybus.ParallelBus(**pins)
        check(name, False)
    except (ValueError, NotImplementedError) as error:
        check(f"{name}: {error}", True)
    # A failed constructor keeps its display bus slot until this, as for any bus type.
    displayio.release_displays()


displayio.release_displays()

rejected("data pins out of order", data_pins=DATA[1:] + DATA[:1], write=pin.PC02, **CONTROL)
rejected("write pin that isn't FSMC NWE", data_pins=DATA, write=pin.PC01, **CONTROL)
rejected("data0= instead of data_pins=", data0=pin.PB14, write=pin.PC02, **CONTROL)
# The slowest FSMC write is 258 HCLK cycles (about 388 kHz at 100 MHz).
slow = dict(CONTROL)
slow["frequency"] = 100_000
rejected("frequency below the slowest FSMC write", data_pins=DATA, write=pin.PC02, **slow)

bus = paralleldisplaybus.ParallelBus(data_pins=DATA, write=pin.PC02, **CONTROL)
check("FSMC bus with the board's pins", True)

display = busdisplay.BusDisplay(
    bus, INIT, width=320, height=240, backlight_pin=pin.PB09, auto_refresh=False
)

# Raw speed: 30720 bytes of black to the top of the screen.
data = bytes(30720)
start = time.monotonic_ns()
bus.send(0x2C, data)
ns_per_byte = (time.monotonic_ns() - start) / len(data)
check(f"bus speed {ns_per_byte:.0f} ns per byte", ns_per_byte < 200)

palette = displayio.Palette(4)
for i, colour in enumerate((0xFF0000, 0x00FF00, 0x0000FF, 0xFFFFFF)):
    palette[i] = colour
bars = displayio.Bitmap(4, 3, 4)
for x in range(4):
    for y in range(3):
        bars[x, y] = x
group = displayio.Group(scale=80)
group.append(displayio.TileGrid(bars, pixel_shader=palette))
display.root_group = group
start = time.monotonic()
display.refresh()
print(f"full-screen refresh: {(time.monotonic() - start) * 1000:.0f} ms")
print("Check the screen: red, green, blue and white bars from left to right.")
while True:
    time.sleep(1)

Trade-offs and Alternatives

  • Writes only, 8 bits, and only the F412Rx pin tables; other STM variants with an FSMC can add tables later. One bus: there is one FSMC bank 1, and a second ParallelBus is refused because its data pins are taken.
  • Bit-banging the bus with GPIOs would work on any pins, but the FSMC is much faster and is what this display is wired for. codal-stm32, which MakeCode Arcade uses, drives it the same way (FSMCIO.cpp), and the FSMC register set-up here follows that driver, except that the write timing comes from frequency.
  • A frequency the FSMC can't go down to is refused rather than silently run faster.

Generative AI

I used generative AI (Claude Code and Codex) to write and test this change. I have reviewed it, and I am responsible for the code and this description.

🤖 Generated with Claude Code

ParallelBus for the STM port, driving an 8-bit 8080-style display
through FSMC bank 1 in SRAM mode: each byte is one store to 0x60000000,
and the FSMC generates the write strobe. Data pins are validated against
the FSMC D0-D7 pin tables (added for the STM32F412Rx), the write strobe
must be FSMC_NWE and the read strobe FSMC_NOE. DC, CS and reset are
GPIOs. A frequency below the slowest FSMC write (258 HCLK cycles) is
refused. The FSMC register set-up follows codal-stm32's driver for this
display (src/FSMCIO.cpp), used by MakeCode Arcade, except the write
timing. The bus is off unless a board sets CIRCUITPY_PARALLELDISPLAYBUS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@tannewt tannewt left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you!

@tannewt
tannewt merged commit 3dd2ff2 into adafruit:main Nov 18, 2026
39 checks passed
@vegardw
vegardw deleted the stm-fsmc-display branch November 19, 2026 06:29
vegardw added a commit to vegardw/circuitpython that referenced this pull request Nov 19, 2026
Brings in the FSMC parallel display bus (adafruit#11908) and the pin-table
fixes (adafruit#11902), now merged upstream. The display-bus code was already
the same here, so the merge had no conflicts. The tree is now main
plus the board commit, the board README and Stage at the commit that
adds this board.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
vegardw added a commit to vegardw/circuitpython that referenced this pull request Nov 19, 2026
The MCU, bootloader and display-bus support are now in main (adafruit#11896,
adafruit#11903, adafruit#11908), as is the audiopwmio silent-source fix (adafruit#11889). Say
so, update the base and free flash, and state briefly what was tested
on the device and what wasn't.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants