QSPI bus driver and Waveshare ESP32-S3 Touch AMOLED 2.41" board support by ppsx · Pull Request #10844 · adafruit/circuitpython

ppsx · 2026-02-23T23:09:02Z

Add qspibus display bus and Waveshare ESP32-S3 Touch AMOLED 2.41" board support

Summary

Add qspibus module — a QSPI (quad-SPI) display bus transport for high-speed AMOLED panels. Follows the standard CircuitPython 3-layer pattern: shared-bindings/qspibus, shared-module/qspibus, ports/espressif/common-hal/qspibus.
Add board definition for Waveshare ESP32-S3 Touch AMOLED 2.41" (ESP32-S3, 16MB flash, 8MB PSRAM, RM690B0-based AMOLED display).
Display is initialized in board_init() and available as board.DISPLAY at boot (splash screen + REPL terminal work out of the box). The RM690B0 init sequence is embedded in board.c; a dedicated RM690B0 driver module will follow in a separate PR.
Optimize BusDisplay refresh for QSPI: larger stack buffers (configurable via CIRCUITPY_QSPI_DISPLAY_AREA_BUFFER_SIZE), fill_area/DMA overlap for ~20% throughput improvement.
Add displayio_display_bus_send_region_commands() — a no-transaction variant of the region command helper, enabling single-transaction QSPI refresh (set_region + RAMWR + pixels in one CS assertion).

Hardware

MCU: ESP32-S3 (240 MHz dual-core)
Flash: 16MB QSPI (QIO, 80MHz)
PSRAM: 8MB Octal (OPI, 80MHz)
Display: 600×450 AMOLED, RM690B0 controller, QSPI interface at 40MHz
Touch: FT6336U capacitive (I2C, user-initialized)
USB: 0x303A:0x8278 (Waveshare)

Copilot

Pull request overview

This pull request introduces a new QSPI (Quad-SPI) bus driver for CircuitPython, specifically to support the Waveshare ESP32-S3 Touch AMOLED 2.41" display which uses the RM690B0 controller. The implementation follows CircuitPython's established display bus architecture patterns.

Changes:

Adds a new qspibus module providing QSPI bus protocol support analogous to fourwire for standard SPI
Implements ESP32-S3 specific QSPI bus driver using ESP-IDF's LCD panel IO API with DMA and ISR support
Adds board definition for Waveshare ESP32-S3 Touch AMOLED 2.41" with comprehensive pin mappings
Optimizes display buffer sizes for QSPI panels to reduce command/window overhead

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
`shared-bindings/qspibus/__init__.c`	Python module definition for qspibus
`shared-bindings/qspibus/__init__.h`	Module header with imports
`shared-bindings/qspibus/QSPIBus.c`	Python bindings for QSPIBus class with send(), write_command(), write_data() methods
`shared-bindings/qspibus/QSPIBus.h`	QSPIBus class interface declaration
`ports/espressif/common-hal/qspibus/QSPIBus.c`	ESP32-S3 QSPI implementation using ESP-IDF LCD panel IO with DMA buffers and ISR callbacks
`ports/espressif/common-hal/qspibus/QSPIBus.h`	ESP32-S3 QSPI bus structure definition
`ports/espressif/common-hal/qspibus/__init__.c`	Empty implementation file (placeholder)
`ports/espressif/common-hal/qspibus/__init__.h`	Empty header file (placeholder)
`shared-module/displayio/bus_core.c`	Integrates QSPI bus into displayio bus abstraction
`shared-module/displayio/__init__.h`	Adds QSPI bus to primary display bus union
`shared-module/displayio/__init__.c`	Adds QSPI bus cleanup to display release path
`shared-module/busdisplay/BusDisplay.c`	QSPI-specific buffer optimization for efficient refresh
`py/circuitpy_mpconfig.mk`	Build flag for QSPI bus support
`py/circuitpy_mpconfig.h`	QSPI display buffer size configuration
`py/circuitpy_defns.mk`	Build pattern matching for qspibus module
`ports/espressif/Makefile`	Links esp_lcd component when QSPIBUS enabled
`ports/espressif/boards/waveshare_esp32_s3_amoled_241/mpconfigboard.h`	Board configuration with pin definitions and buffer size
`ports/espressif/boards/waveshare_esp32_s3_amoled_241/mpconfigboard.mk`	Board build configuration enabling QSPIBUS
`ports/espressif/boards/waveshare_esp32_s3_amoled_241/pins.c`	Comprehensive pin mapping with functional names
`ports/espressif/boards/waveshare_esp32_s3_amoled_241/board.c`	Empty board initialization
`ports/espressif/boards/waveshare_esp32_s3_amoled_241/sdkconfig`	ESP-IDF SDK configuration for PSRAM and peripherals
`locale/circuitpython.pot`	Translation strings for QSPI error messages

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

shared-bindings/qspibus/__init__.h

shared-bindings/qspibus/__init__.c

shared-bindings/qspibus/QSPIBus.h

shared-bindings/qspibus/QSPIBus.c

ports/espressif/common-hal/qspibus/__init__.c

ports/espressif/common-hal/qspibus/QSPIBus.h

ports/espressif/common-hal/qspibus/QSPIBus.c

ports/espressif/boards/waveshare_esp32_s3_amoled_241/mpconfigboard.h

ports/espressif/boards/waveshare_esp32_s3_amoled_241/board.c

ports/espressif/common-hal/qspibus/QSPIBus.c

tannewt

This is definitely getting closer! Please prevent additional error messages from being added. You likely can reuse existing ones. Please also iterate with copilot on your own fork before making a PR.

Copilot

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (2)

locale/circuitpython.pot:922

The error message "Data buffer is null" is added to the locale file but is never used in the codebase. Either remove this unused error message from the locale file or add the corresponding validation check in the code where it's needed.

#: ports/espressif/common-hal/qspibus/QSPIBus.c
msgid "Data buffer is null"
msgstr ""

ports/espressif/common-hal/qspibus/QSPIBus.c:359

The ternary operator CIRCUITPY_LCD_POWER_ON_LEVEL ? 1 : 0 is redundant since CIRCUITPY_LCD_POWER_ON_LEVEL is already defined as either 0 or 1 (see lines 32-34). Simplify this to just CIRCUITPY_LCD_POWER_ON_LEVEL to make the code clearer and avoid potential confusion.

        gpio_set_level((gpio_num_t)self->power_pin, CIRCUITPY_LCD_POWER_ON_LEVEL ? 1 : 0);

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

shared-bindings/qspibus/QSPIBus.c

ports/espressif/common-hal/qspibus/QSPIBus.c

shared-bindings/qspibus/QSPIBus.c

Copilot

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

ports/espressif/common-hal/qspibus/QSPIBus.c

locale/circuitpython.pot

ports/espressif/boards/waveshare_esp32_s3_amoled_241/mpconfigboard.h

Copilot

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

ppsx · 2026-02-25T00:08:41Z

Thank you @tannewt for your feedback. I've implemented requested changes and did a couple of sessions with Copilot. Now the code needs some more professional view than me or Copilot :)

tannewt · 2026-02-25T17:23:26Z

Please make sure the automated tests also pass.

Copilot

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

ports/espressif/common-hal/qspibus/QSPIBus.c:467

Inconsistent indentation: this line uses 3 spaces instead of 4 spaces for indentation. All other if statements in this function use 4 spaces.

   if (!self->has_pending_command) {

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

shared-module/displayio/bus_core.h

shared-module/displayio/TileGrid.c

Copilot

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

py/circuitpy_mpconfig.h:407

The comment says this value can be overridden “for larger buffers”, but shared-module/busdisplay/BusDisplay.c enforces a hard maximum of 2048 words via _Static_assert. Either document the effective maximum here as well, or make the maximum configurable/port-specific so the documentation matches actual build constraints.

// QSPI display buffer size in uint32_t words for _refresh_area() VLA.
// Allocated on stack; boards should verify sufficient stack headroom.
// Default 512 words = 2KB. Override per-board for larger buffers.
#ifndef CIRCUITPY_QSPI_DISPLAY_AREA_BUFFER_SIZE
#define CIRCUITPY_QSPI_DISPLAY_AREA_BUFFER_SIZE (512)
#endif

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

py/circuitpy_mpconfig.mk

shared-module/busdisplay/BusDisplay.c

ports/espressif/boards/waveshare_esp32_s3_amoled_241/mpconfigboard.h

Copilot

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

ports/espressif/common-hal/qspibus/QSPIBus.c

py/circuitpy_mpconfig.mk

shared-module/busdisplay/BusDisplay.c

- Align begin_transaction() with bus_free() by delegating to it, so transfer_in_progress and has_pending_command are checked before entering a transaction. This prevents silently discarding a staged write_command() or starting a transaction during active DMA. - Regenerate locale/circuitpython.pot to remove stale "Data buffer is null" entry left over from the previous round of error message reuse.

#1) * Initial plan * Fix stale and missing locale entries for qspibus Co-authored-by: ppsx <7107135+ppsx@users.noreply.github.com> * qspibus: three low-cost cleanups consistent with CircuitPython conventions Co-authored-by: ppsx <7107135+ppsx@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: ppsx <7107135+ppsx@users.noreply.github.com> Co-authored-by: ppsx <ppsx@users.noreply.github.com>

Refactor display bus region-update command emission into a shared helper with optional transaction management. Keep the existing public path unchanged, and add a QSPIBus-only entrypoint that can send region commands without nesting begin/end transaction calls. Also remove the TileGrid 16bpp+Palette fast path so fill_area uses the generic path, and fix indentation in QSPIBus write_data.

tannewt · 2026-03-02T22:43:13Z

You'll need to add qspibus = false to each Zephyr boards autogen to fix the zephyr tests. There is a script in ports/zephyr/cptools that will do it too.

ppsx · 2026-03-03T11:28:06Z

@tannewt - done.
All tests passed.

tannewt

Thanks for continuing to iterate on this. I'm excited by overlapping sending pixels and computing them.

shared-module/busdisplay/BusDisplay.c

shared-module/displayio/bus_core.c

ports/espressif/boards/waveshare_esp32_s3_amoled_241/sdkconfig

ports/espressif/boards/waveshare_esp32_s3_amoled_241/mpconfigboard.h

locale/circuitpython.pot

ports/espressif/common-hal/qspibus/QSPIBus.c

tannewt

Ok, I've got a better idea of how this works and think there are just a couple small tweaks to make to simplify things. Thanks!

shared-module/busdisplay/BusDisplay.c

shared-module/displayio/bus_core.c

shared-module/framebufferio/FramebufferDisplay.c

ppsx · 2026-03-04T19:07:07Z

Thank you, @tannewt, for your professional approach. I learned a lot during this PR :)

tannewt

Very close. One other cleanup to do.

tannewt · 2026-03-05T23:19:16Z

shared-module/displayio/bus_core.c

+
+void displayio_display_bus_set_region_to_update(displayio_display_bus_t *self, displayio_display_core_t *display, displayio_area_t *area) {
+    _displayio_display_bus_send_region_commands(self, display, area, true);
+}


Actually revert the above. You don't need manage_transaction any more. (Please review LLM changes thoroughly before asking me to.)

Thank you and I'm sorry.
I removed the manage_transactions parameter from _displayio_display_bus_send_region_commands - it was always called with true, so the conditionals were unnecessary. All begin_transaction/end_transaction calls are now unconditional.

Copilot AI review requested due to automatic review settings February 23, 2026 23:09

Copilot started reviewing on behalf of ppsx February 23, 2026 23:09 View session

Copilot AI reviewed Feb 23, 2026

View reviewed changes

ppsx force-pushed the rm690b0 branch from 4f99320 to 1934060 Compare February 23, 2026 23:59

tannewt requested changes Feb 24, 2026

View reviewed changes

ppsx force-pushed the rm690b0 branch from d18281b to 99b4e87 Compare February 24, 2026 22:53

ppsx requested a review from Copilot February 24, 2026 23:06

Copilot started reviewing on behalf of ppsx February 24, 2026 23:09 View session

Copilot AI reviewed Feb 24, 2026

View reviewed changes

shared-bindings/qspibus/QSPIBus.c Show resolved Hide resolved

ports/espressif/common-hal/qspibus/QSPIBus.c Outdated Show resolved Hide resolved

shared-bindings/qspibus/QSPIBus.c Outdated Show resolved Hide resolved

ppsx requested a review from Copilot February 24, 2026 23:32

Copilot started reviewing on behalf of ppsx February 24, 2026 23:33 View session

Copilot AI reviewed Feb 24, 2026

View reviewed changes

ports/espressif/common-hal/qspibus/QSPIBus.c Outdated Show resolved Hide resolved

locale/circuitpython.pot Outdated Show resolved Hide resolved

ports/espressif/boards/waveshare_esp32_s3_amoled_241/mpconfigboard.h Outdated Show resolved Hide resolved

ppsx changed the title ~~QSPI bus driver and …RM690B0 display driver for Waveshare ESP32-S3 Touch AMOLED 2.41"~~ QSPI bus driver and Waveshare ESP32-S3 Touch AMOLED 2.41" board support Feb 24, 2026

ppsx requested a review from Copilot February 24, 2026 23:56

Copilot started reviewing on behalf of ppsx February 24, 2026 23:57 View session

Copilot AI reviewed Feb 25, 2026

View reviewed changes

ppsx force-pushed the rm690b0 branch from 8230d2b to d1ed277 Compare February 25, 2026 13:20

ppsx requested a review from Copilot February 25, 2026 19:57

Copilot started reviewing on behalf of ppsx February 25, 2026 19:57 View session

Copilot AI reviewed Feb 25, 2026

View reviewed changes

shared-module/displayio/bus_core.h Outdated Show resolved Hide resolved

shared-module/displayio/TileGrid.c Outdated Show resolved Hide resolved

ppsx force-pushed the rm690b0 branch from 885455c to 61edf63 Compare February 26, 2026 14:50

ppsx requested a review from Copilot February 26, 2026 15:32

Copilot started reviewing on behalf of ppsx February 26, 2026 15:32 View session

Copilot AI reviewed Feb 26, 2026

View reviewed changes

py/circuitpy_mpconfig.mk Show resolved Hide resolved

shared-module/busdisplay/BusDisplay.c Outdated Show resolved Hide resolved

ports/espressif/boards/waveshare_esp32_s3_amoled_241/mpconfigboard.h Outdated Show resolved Hide resolved

ppsx requested a review from Copilot February 26, 2026 16:45

Copilot started reviewing on behalf of ppsx February 26, 2026 16:45 View session

Copilot AI reviewed Feb 26, 2026

View reviewed changes

ports/espressif/common-hal/qspibus/QSPIBus.c Outdated Show resolved Hide resolved

py/circuitpy_mpconfig.mk Show resolved Hide resolved

shared-module/busdisplay/BusDisplay.c Outdated Show resolved Hide resolved

ppsx requested a review from Copilot February 26, 2026 17:02

ppsx and others added 18 commits February 28, 2026 15:41

The last license header and the temple of doom (pot file)

6c2a5ce

~20% improvements in data transfer when drawing

cb468b8

Proper VID/PID

ad93dd9

Proper VID/PID

dee2d9f

Workaround for an issue with esp-idf 5.5.3

3c8e7f8

Fixing Copilot findings

347296c

Fixing Copilot findings (2)

b2149f2

Fixing Copilot findings (3)

1704518

Made board.DISPLAY available

2bd02fa

Removed temp debug settings

d20581b

Fixing Copilot findings (4)

4e4461e

Fixing Copilot findings (5)

bdea521

Fixing Copilot findings (6)

79eb389

Fixing Copilot findings (7)

11299b3

Added common touch pins definitions

551bc83

ppsx force-pushed the rm690b0 branch from 3babdf0 to 551bc83 Compare February 28, 2026 14:42

Added qspibus = false for all Zephyr boards

c0177c8

tannewt requested changes Mar 3, 2026

View reviewed changes

ppsx added 2 commits March 3, 2026 22:52

Fixes after the review

4378f51

Fixes after the review

d2e9a58

tannewt requested changes Mar 4, 2026

View reviewed changes

shared-module/busdisplay/BusDisplay.c Show resolved Hide resolved

shared-module/displayio/bus_core.c Show resolved Hide resolved

shared-module/framebufferio/FramebufferDisplay.c Outdated Show resolved Hide resolved

Review fixes

69dedab

tannewt requested changes Mar 5, 2026

View reviewed changes

Review fixes

2fac7c9

Conversation

ppsx commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tannewt left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

ppsx commented Feb 25, 2026

Uh oh!

tannewt commented Feb 25, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tannewt commented Mar 2, 2026

Uh oh!

ppsx commented Mar 3, 2026

Uh oh!

tannewt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ppsx commented Feb 23, 2026 •

edited

Loading