QSPI bus driver and Waveshare ESP32-S3 Touch AMOLED 2.41" board support

locale/circuitpython.pot

@@ -99,6 +99,7 @@ msgid "%q contains duplicate pins"
 msgstr ""
 
 #: ports/atmel-samd/common-hal/sdioio/SDCard.c
+#: ports/espressif/common-hal/qspibus/QSPIBus.c
 msgid "%q failure: %d"
 msgstr ""
 
@@ -646,6 +647,10 @@ msgstr ""
 msgid "Baudrate not supported by peripheral"
 msgstr ""
 
+#: ports/espressif/common-hal/qspibus/QSPIBus.c
+msgid "Begin transaction first"
+msgstr ""
+
 #: shared-module/busdisplay/BusDisplay.c
 #: shared-module/framebufferio/FramebufferDisplay.c
 msgid "Below minimum frame rate"
@@ -712,6 +717,10 @@ msgstr ""
 msgid "Buffer too small"
 msgstr ""
 
+#: ports/espressif/common-hal/qspibus/QSPIBus.c
+msgid "Bus in display transaction"
+msgstr ""
+
 #: ports/atmel-samd/common-hal/paralleldisplaybus/ParallelBus.c
 #: ports/espressif/common-hal/paralleldisplaybus/ParallelBus.c
 #: ports/nordic/common-hal/paralleldisplaybus/ParallelBus.c
@@ -865,6 +874,7 @@ msgid "Coordinate arrays types have different sizes"
 msgstr ""
 
 #: shared-module/usb/core/Device.c
+#: ports/espressif/common-hal/qspibus/QSPIBus.c
 msgid "Could not allocate DMA capable buffer"
 msgstr ""
 
@@ -967,6 +977,7 @@ msgstr ""
 
 #: ports/espressif/common-hal/busio/SPI.c
 #: ports/espressif/common-hal/canio/CAN.c
+#: ports/espressif/common-hal/qspibus/QSPIBus.c
 msgid "ESP-IDF memory allocation failed"
 msgstr ""
 
@@ -1517,6 +1528,7 @@ msgstr ""
 #: ports/stm/common-hal/busio/UART.c shared-bindings/fourwire/FourWire.c
 #: shared-bindings/i2cdisplaybus/I2CDisplayBus.c
 #: shared-bindings/paralleldisplaybus/ParallelBus.c
+#: shared-bindings/qspibus/QSPIBus.c
 #: shared-module/bitbangio/SPI.c
 msgid "No %q pin"
 msgstr ""
@@ -1599,6 +1611,10 @@ msgstr ""
 msgid "No out in program"
 msgstr ""
 
+#: ports/espressif/common-hal/qspibus/QSPIBus.c
+msgid "No pending command"
+msgstr ""
+
 #: ports/atmel-samd/common-hal/busio/I2C.c
 #: ports/espressif/common-hal/busio/I2C.c
 #: ports/mimxrt10xx/common-hal/busio/I2C.c ports/nordic/common-hal/busio/I2C.c
@@ -1746,6 +1762,7 @@ msgid "Operation or feature not supported"
 msgstr ""
 
 #: ports/espressif/common-hal/espidf/__init__.c
+#: ports/espressif/common-hal/qspibus/QSPIBus.c
 msgid "Operation timed out"
 msgstr ""
 

ports/espressif/Makefile

@@ -780,6 +780,9 @@ endif
 ifneq ($(CIRCUITPY_PARALLELDISPLAYBUS),0)
 	ESP_IDF_COMPONENTS_LINK += esp_lcd
 endif
+ifneq ($(CIRCUITPY_QSPIBUS),0)
+	ESP_IDF_COMPONENTS_LINK += esp_lcd
+endif
 ifneq ($(CIRCUITPY_USB_DEVICE),0)
 	ESP_IDF_COMPONENTS_LINK += usb
 endif

ports/espressif/boards/waveshare_esp32_s3_amoled_241/board.c

@@ -0,0 +1,8 @@
+// This file is part of the CircuitPython project: https://circuitpython.org
+// SPDX-FileCopyrightText: Copyright (c) 2026 Przemyslaw Patrick Socha
+// SPDX-License-Identifier: MIT
+
+#include "supervisor/board.h"
+
+void board_init(void) {
+}

ports/espressif/boards/waveshare_esp32_s3_amoled_241/mpconfigboard.h

@@ -0,0 +1,41 @@
+// This file is part of the CircuitPython project: https://circuitpython.org
+// SPDX-FileCopyrightText: Copyright (c) 2026 Przemyslaw Patrick Socha
+// SPDX-License-Identifier: MIT
+
+#pragma once
+
+#define MICROPY_HW_BOARD_NAME "Waveshare ESP32-S3-Touch-AMOLED-2.41"
+#define MICROPY_HW_MCU_NAME   "ESP32S3"
+
+// USB identifiers
+#define USB_VID 0x303A
+#define USB_PID 0x8278
+#define USB_MANUFACTURER "Waveshare"
+#define USB_PRODUCT "ESP32-S3-Touch-AMOLED-2.41"
+
+// I2C bus - Disabled on boot to avoid conflicts. User must manually initialize I2C.
+#define CIRCUITPY_BOARD_I2C         (0)
+#define CIRCUITPY_BOARD_I2C_PIN     {{.scl = &pin_GPIO48, .sda = &pin_GPIO47}}
+
+// QSPI display refresh buffer: 2048 uint32_t words = 8KB on stack.
+// ESP32-S3 main task stack is 24KB; verified safe with this board.
+#define CIRCUITPY_QSPI_DISPLAY_AREA_BUFFER_SIZE (2048)
+
+// AMOLED Display (displayio + qspibus path)
+#define CIRCUITPY_BOARD_DISPLAY      (0)
+#define CIRCUITPY_LCD_CS             (&pin_GPIO9)
+#define CIRCUITPY_LCD_CLK            (&pin_GPIO10)
+#define CIRCUITPY_LCD_D0             (&pin_GPIO11)
+#define CIRCUITPY_LCD_D1             (&pin_GPIO12)
+#define CIRCUITPY_LCD_D2             (&pin_GPIO13)
+#define CIRCUITPY_LCD_D3             (&pin_GPIO14)
+#define CIRCUITPY_LCD_RESET          (&pin_GPIO21)
+#define CIRCUITPY_LCD_POWER          (&pin_GPIO16)
+#define CIRCUITPY_LCD_POWER_ON_LEVEL (1)  // GPIO level: 1=high, 0=low
+
+// No default SPI bus — SD card uses SDIO, display uses QSPI.
+#define CIRCUITPY_BOARD_SPI         (0)
+
+// Default UART bus
+#define DEFAULT_UART_BUS_RX (&pin_GPIO44)
+#define DEFAULT_UART_BUS_TX (&pin_GPIO43)

ports/espressif/boards/waveshare_esp32_s3_amoled_241/mpconfigboard.mk

@@ -0,0 +1,38 @@
+# This file is part of the CircuitPython project: https://circuitpython.org
+# SPDX-FileCopyrightText: Copyright (c) 2026 Przemyslaw Patrick Socha
+# SPDX-License-Identifier: MIT
+
+CIRCUITPY_CREATOR_ID  = 0x57415645  # 'WAVE' (Waveshare)
+CIRCUITPY_CREATION_ID = 0x41323431  # 'A241' (AMOLED 2.41)
+
+USB_VID = 0x303A
+USB_PID = 0x8278
+USB_MANUFACTURER = "Waveshare"
+USB_PRODUCT = "ESP32-S3-Touch-AMOLED-2.41"
+
+IDF_TARGET = esp32s3
+
+# Flash configuration - 16MB QSPI Flash
+CIRCUITPY_ESP_FLASH_SIZE = 16MB
+CIRCUITPY_ESP_FLASH_MODE = qio
+CIRCUITPY_ESP_FLASH_FREQ = 80m
+
+# PSRAM configuration - 8MB Octal PSRAM
+CIRCUITPY_ESP_PSRAM_SIZE = 8MB
+CIRCUITPY_ESP_PSRAM_MODE = opi
+CIRCUITPY_ESP_PSRAM_FREQ = 80m
+
+OPTIMIZATION_FLAGS = -Os
+
+# QSPI bus for RM690B0 AMOLED display
+CIRCUITPY_QSPIBUS = 1
+CIRCUITPY_PARALLELDISPLAYBUS = 0
+
+# No camera on this board
+CIRCUITPY_ESPCAMERA = 0
+
+# Capacitive touch not available; board uses I2C touch controller
+CIRCUITPY_TOUCHIO = 0
+
+# SD card via SDMMC interface
+CIRCUITPY_SDIOIO = 1

ports/espressif/boards/waveshare_esp32_s3_amoled_241/pins.c

@@ -0,0 +1,100 @@
+// This file is part of the CircuitPython project: https://circuitpython.org
+// SPDX-FileCopyrightText: Copyright (c) 2026 Przemyslaw Patrick Socha
+// SPDX-License-Identifier: MIT
+
+#include "py/obj.h"
+#include "py/mphal.h"
+#include "shared-bindings/board/__init__.h"
+#include "shared-bindings/microcontroller/Pin.h"
+
+static const mp_rom_map_elem_t board_module_globals_table[] = {
+    CIRCUITPYTHON_BOARD_DICT_STANDARD_ITEMS
+
+    // =================================================================
+    // ONBOARD PERIPHERALS - Functional Names
+    // =================================================================
+
+    // Boot/Control/Battery/Display Power
+    // NOTE: GPIO16 is shared between battery control circuitry and LCD power
+    // (see CIRCUITPY_QSPIBUS_PANEL_POWER_PIN in mpconfigboard.h).
+    { MP_ROM_QSTR(MP_QSTR_BOOT),        MP_ROM_PTR(&pin_GPIO0) },
+    { MP_ROM_QSTR(MP_QSTR_KEY_BAT),     MP_ROM_PTR(&pin_GPIO15) },
+    { MP_ROM_QSTR(MP_QSTR_BAT_CONTROL), MP_ROM_PTR(&pin_GPIO16) },
+    { MP_ROM_QSTR(MP_QSTR_LCD_POWER),   MP_ROM_PTR(&pin_GPIO16) },
+    { MP_ROM_QSTR(MP_QSTR_BAT_ADC),     MP_ROM_PTR(&pin_GPIO17) },
+
+    // I2C Bus (shared by Touch, RTC, IMU, IO Expander)
+    // NOTE: board.I2C auto-initialization is disabled (CIRCUITPY_BOARD_I2C=0)
+    // to avoid boot conflicts. Users must manually create I2C bus:
+    //   i2c = busio.I2C(board.SCL, board.SDA)
+    { MP_ROM_QSTR(MP_QSTR_SDA),     MP_ROM_PTR(&pin_GPIO47) },
+    { MP_ROM_QSTR(MP_QSTR_SCL),     MP_ROM_PTR(&pin_GPIO48) },
+
+    // Touch Panel (FT6336U on I2C)
+    { MP_ROM_QSTR(MP_QSTR_TP_SDA),    MP_ROM_PTR(&pin_GPIO47) },
+    { MP_ROM_QSTR(MP_QSTR_TP_SCL),    MP_ROM_PTR(&pin_GPIO48) },
+    { MP_ROM_QSTR(MP_QSTR_TP_RESET),  MP_ROM_PTR(&pin_GPIO3) },
+
+    // RTC (PCF85063 on I2C)
+    { MP_ROM_QSTR(MP_QSTR_RTC_SDA), MP_ROM_PTR(&pin_GPIO47) },
+    { MP_ROM_QSTR(MP_QSTR_RTC_SCL), MP_ROM_PTR(&pin_GPIO48) },
+
+    // IMU (QMI8658 on I2C)
+    { MP_ROM_QSTR(MP_QSTR_IMU_SDA), MP_ROM_PTR(&pin_GPIO47) },
+    { MP_ROM_QSTR(MP_QSTR_IMU_SCL), MP_ROM_PTR(&pin_GPIO48) },
+
+    // I/O Expander (TCA9554 on I2C)
+    { MP_ROM_QSTR(MP_QSTR_EXIO_SDA), MP_ROM_PTR(&pin_GPIO47) },
+    { MP_ROM_QSTR(MP_QSTR_EXIO_SCL), MP_ROM_PTR(&pin_GPIO48) },
+
+    // USB
+    { MP_ROM_QSTR(MP_QSTR_USB_D_N), MP_ROM_PTR(&pin_GPIO19) },
+    { MP_ROM_QSTR(MP_QSTR_USB_D_P), MP_ROM_PTR(&pin_GPIO20) },
+
+    // UART
+    { MP_ROM_QSTR(MP_QSTR_TX),  MP_ROM_PTR(&pin_GPIO43) },
+    { MP_ROM_QSTR(MP_QSTR_RX),  MP_ROM_PTR(&pin_GPIO44) },
+
+    // QSPI Display (RM690B0) - canonical generic LCD aliases.
+    { MP_ROM_QSTR(MP_QSTR_LCD_CS),    MP_ROM_PTR(&pin_GPIO9) },
+    { MP_ROM_QSTR(MP_QSTR_LCD_CLK),   MP_ROM_PTR(&pin_GPIO10) },
+    { MP_ROM_QSTR(MP_QSTR_LCD_D0),    MP_ROM_PTR(&pin_GPIO11) },
+    { MP_ROM_QSTR(MP_QSTR_LCD_D1),    MP_ROM_PTR(&pin_GPIO12) },
+    { MP_ROM_QSTR(MP_QSTR_LCD_D2),    MP_ROM_PTR(&pin_GPIO13) },
+    { MP_ROM_QSTR(MP_QSTR_LCD_D3),    MP_ROM_PTR(&pin_GPIO14) },
+    { MP_ROM_QSTR(MP_QSTR_LCD_RESET), MP_ROM_PTR(&pin_GPIO21) },
+
+    // Display Aliases
+    { MP_ROM_QSTR(MP_QSTR_DISPLAY_CS),  MP_ROM_PTR(&pin_GPIO9) },
+    { MP_ROM_QSTR(MP_QSTR_DISPLAY_SCK), MP_ROM_PTR(&pin_GPIO10) },
+    { MP_ROM_QSTR(MP_QSTR_DISPLAY_D0),  MP_ROM_PTR(&pin_GPIO11) },
+    { MP_ROM_QSTR(MP_QSTR_DISPLAY_D1),  MP_ROM_PTR(&pin_GPIO12) },
+    { MP_ROM_QSTR(MP_QSTR_DISPLAY_D2),  MP_ROM_PTR(&pin_GPIO13) },
+    { MP_ROM_QSTR(MP_QSTR_DISPLAY_D3),  MP_ROM_PTR(&pin_GPIO14) },
+    { MP_ROM_QSTR(MP_QSTR_DISPLAY_RST), MP_ROM_PTR(&pin_GPIO21) },
+
+    // SD Card (SDIO / SDMMC)
+    { MP_ROM_QSTR(MP_QSTR_SDIO_CLK), MP_ROM_PTR(&pin_GPIO4) },
+    { MP_ROM_QSTR(MP_QSTR_SDIO_CMD), MP_ROM_PTR(&pin_GPIO5) },
+    { MP_ROM_QSTR(MP_QSTR_SDIO_D0),  MP_ROM_PTR(&pin_GPIO6) },
+    { MP_ROM_QSTR(MP_QSTR_SDIO_D3),  MP_ROM_PTR(&pin_GPIO2) },
+
+    // =================================================================
+    // GENERAL PURPOSE I/O (IOxx - Espressif Convention)
+    // =================================================================
+    // Only pins NOT dedicated to onboard peripherals are exposed here.
+    // Use functional names above for dedicated pins (e.g., SDA, SD_CS).
+
+    { MP_ROM_QSTR(MP_QSTR_IO0),   MP_ROM_PTR(&pin_GPIO0) },   // BOOT button (available when not holding BOOT)
+    { MP_ROM_QSTR(MP_QSTR_IO1),   MP_ROM_PTR(&pin_GPIO1) },   // Available
+    { MP_ROM_QSTR(MP_QSTR_IO3),   MP_ROM_PTR(&pin_GPIO3) },   // TP_RESET (available if touch not used)
+    { MP_ROM_QSTR(MP_QSTR_IO7),   MP_ROM_PTR(&pin_GPIO7) },   // Available
+    { MP_ROM_QSTR(MP_QSTR_IO8),   MP_ROM_PTR(&pin_GPIO8) },   // Available
+    { MP_ROM_QSTR(MP_QSTR_IO18),  MP_ROM_PTR(&pin_GPIO18) },  // Available
+    { MP_ROM_QSTR(MP_QSTR_IO40),  MP_ROM_PTR(&pin_GPIO40) },  // Available
+    { MP_ROM_QSTR(MP_QSTR_IO41),  MP_ROM_PTR(&pin_GPIO41) },  // Available
+    { MP_ROM_QSTR(MP_QSTR_IO42),  MP_ROM_PTR(&pin_GPIO42) },  // Available
+    { MP_ROM_QSTR(MP_QSTR_IO45),  MP_ROM_PTR(&pin_GPIO45) },  // Available
+    { MP_ROM_QSTR(MP_QSTR_IO46),  MP_ROM_PTR(&pin_GPIO46) },  // Available
+};
+MP_DEFINE_CONST_DICT(board_module_globals, board_module_globals_table);

ports/espressif/boards/waveshare_esp32_s3_amoled_241/sdkconfig

@@ -0,0 +1,33 @@
+#
+# Configuration file for the Waveshare ESP32-S3 Touch AMOLED 2.41
+#
+
+# PSRAM Configuration
+CONFIG_SPIRAM=y
+CONFIG_SPIRAM_BOOT_INIT=y
+CONFIG_SPIRAM_USE_MALLOC=y
+CONFIG_SPIRAM_MODE_OCT=y
+CONFIG_SPIRAM_FETCH_INSTRUCTIONS=y
+CONFIG_SPIRAM_RODATA=y
+CONFIG_SPIRAM_SPEED_80M=y
+CONFIG_SPIRAM_MEMTEST=y
+CONFIG_SPIRAM_CLK_IO=39
+CONFIG_SPIRAM_CS_IO=38
+
+# Performance and Cache
+CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_240=y
+CONFIG_ESP32S3_DATA_CACHE_LINE_64B=y
+
+# Default flash settings for this board
+CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y
+CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="esp-idf-config/partitions-16MB.csv"
+CONFIG_PARTITION_TABLE_FILENAME="esp-idf-config/partitions-16MB.csv"
+
+# Networking
+CONFIG_LWIP_LOCAL_HOSTNAME="waveshare-esp32-s3-amoled"
+
+# Disable USB-Serial/JTAG console - CircuitPython uses TinyUSB (USB OTG) for REPL
+CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=n
+
+# Enable .app_desc structure
+CONFIG_APP_RETRIEVE_LEN_ELF_SHA=16