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

Copilot

Pull request overview

Copilot reviewed 23 out of 23 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-26T21:01:16Z

Please make sure the automated tests also pass.

Hi @tannewt. I did all I could however some tests are failing because of zephyr which I obviously haven't touched.
I did some more sessions with Copilot.
Additionally I've introduced a proper board.DISPLAY implementation which should be more useful than external rm690b0 module.
Is there anything else I can do?

…LED 2.41

- Reuse existing CircuitPython error messages to reduce translation burden: "QSPI command/color timeout" -> "Operation timed out", "QSPI send[color] failed: %d" / "SPI bus init failed: %d" / "Panel IO init failed: %d" -> "%q failure: %d", "Failed to allocate DMA buffers" / "QSPI DMA buffers unavailable" -> "Could not allocate DMA capable buffer", "Data buffer is null" -> "Buffer too small". Net removal of 8 unique translatable strings with 0 new ones. - Regenerate locale/circuitpython.pot to remove stale entries. - Add _Static_assert in BusDisplay.c to guard the QSPI stack-allocated refresh buffer size (max 2048 uint32_t words = 8KB). - Add comment clarifying that inflight_transfers bookkeeping is task-context only (ISR only signals semaphore), so no atomics needed. - Fix SPDX file header format across all new qspibus files to match the CircuitPython project convention.

- Add reset() method binding (common_hal implementation already existed) with "No %q pin" error matching FourWire/ParallelBus pattern. - Remove deinit(), __enter__(), __exit__() from Python API; display bus lifecycle is managed through displayio.release_displays(). - Remove two unreachable data == NULL guards: Python binding validates buffers via mp_get_buffer_raise(), and displayio always passes valid pointers.

- 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.

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 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 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

Copilot started reviewing on behalf of ppsx February 26, 2026 20:05 View session

Copilot AI reviewed Feb 26, 2026

View reviewed changes

ppsx requested a review from tannewt February 27, 2026 10:47

ppsx force-pushed the rm690b0 branch from 9099f83 to 1934060 Compare February 27, 2026 12:42

bablokb mentioned this pull request Feb 28, 2026

Add W55RP20-EVB-Pico, W6300-EVB-Pico2 Board #10610

Open

ppsx force-pushed the rm690b0 branch from a0799a8 to 9099f83 Compare February 28, 2026 14:31

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

QSPI bus driver and RM690B0 display driver for Waveshare ESP32-S3 AMO…

89c8186

…LED 2.41

Update: Fixes in locale/circuitpython.pot

21bf0f7

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

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!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

ppsx commented Feb 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ppsx commented Feb 23, 2026 •

edited

Loading