Enabling microSD and Display on QtPy ESP32-S3 SPI Bus Results in Crash to Safe Mode

[jmangum]

CircuitPython version and board name

Adafruit CircuitPython 10.0.1 on 2025-10-09; Adafruit QT Py ESP32-S3 no psram with ESP32S3

Code/REPL

spi = board.SPI()
i2c = board.STEMMA_I2C()

# Setup SD card
tft_sdcs = board.A3
sdcard = sdcardio.SDCard(spi, tft_sdcs)
vfs = storage.VfsFat(sdcard)
storage.mount(vfs, "/sd")

# Set tft pins for QTPy EYESPI BFF on ESP32-S3
tft_cs = board.TX
tft_dc = board.RX
tft_reset = None
tft_backlight = board.A1 # Jumpered EyeSpy BFF Lite pin to Qt Py pin A1
tft_bpwmfreq = 50000 # Default is 50000
displayio.release_displays()
display_bus = FourWire(spi, command=tft_dc, chip_select=tft_cs, reset=tft_reset)
display = GC9A01A(display_bus, width=240, height=240, backlight_pin=tft_backlight, backlight_pwm_frequency=tft_bpwmfreq)
bg_group = displayio.Group()

Behavior

Immediate crash to safe mode.

You are in safe mode because:
Hard fault: memory access or instruction error
Please file an issue with your program at github.com/adafruit/circuitpython/issues.
Press reset to exit safe mode.

Description

Complete hardware setup includes:

• QT Py ESP32-S3 8MB flash no PSRAM
• QT Py EYESPY BFF
• 1.28 inch round 240x240 TFT display with microSD card reader
• APD59960 light/color/proximity/gesture sensor (connected via STEMMA I2C)

The board does not crash under the following two circumstances:

1. If I remove the storage.mount(vfs, "/sd") command (but, of course, I cannot then use the microSD card).
2. If I keep the storage.mount(vfs, "/sd") command but remove everything after it (everything associated with the TFT setup).

Further debugging isolated the crash to when the

display = GC9A01A(display_bus, width=240, height=240, backlight_pin=tft_backlight, backlight_pwm_frequency=tft_bpwmfreq)

is executed (when the storage.mount(vfs, "/sd") command is included).

Additional information

No response

[jmangum]

Further testing shows that crash does not occur immediately for following versions of CircuitPython:

• 9.2.7
• 9.2.9

What happens is that this system will run fine for a while (45 minutes to many hours) then spontaneously go into safe mode. Very hard to isolate as the failures are sporadic when running these two versions of CircuitPython.

[dhalbert]

I'm trying to reproduce this, and haven't succeeded yet. I don't have a GC9A01A display, but FourWire displays are write-only, so that shouldn't matter. I am using a different BFF with an SD card socket.

The test code is missing all the imports, and also has i2c = board.STEMMA_I2C(). If you remove the i2c line does it make any difference? Could you edit the OP to include exactly the code that is causing the safe mode? Thanks.

[jmangum]

Yes, sorry. Here is a stripped-down version that goes into safe mode after a couple of reloads (reset, ctrl-D, ctrl-D did it most times for me). Left all library loads in from the original just in case that matters. BMP images also attached.

green_hour_hand_ellipse_600dpi.bmp
green_minute_hand_ellipse_600dpi.bmp
Sun.bmp

Very hard to pin-down exactly what was tripping the failure.

#
# Bedside Clock
# Hardware:
#    (1) QT Py ESP32-S3 with 8Mb Flash, no PSRAM
#    (2) QT Py EyeSpy BFF
#    (3) 1.28 inch round 240x240 TFT display with microSD card slot
#    (4) APDS9960 light/color/proximity/gesture sensor
#
# JGM: 2025-04-26 (original)
# JGM: 2025-10-19 (stripped version for github issue)

import os
import math
import time
from cedargrove_dst_adjuster import adjust_dst
import ssl
import board
import busio
import displayio
import terminalio
from adafruit_display_text.bitmap_label import Label
import adafruit_imageload
from fourwire import FourWire
from vectorio import Circle
from adafruit_gc9a01a import GC9A01A
from adafruit_display_analogclock import AnalogClock
import sdcardio
import storage
import socketpool
import wifi
from adafruit_datetime import datetime, timedelta
import adafruit_ntp
import rtc
import asyncio
from adafruit_apds9960.apds9960 import APDS9960

print("\n === Analog Bedside Clock ===")

# Setup display at very beginning so that I can see errors on boot-up
spi = board.SPI()
i2c = board.STEMMA_I2C()

# Setup SD card (MUST BE FIRST SPI DEVICE CONNECTED)
tft_sdcs = board.A3
sdcard = sdcardio.SDCard(spi, tft_sdcs)
vfs = storage.VfsFat(sdcard)
storage.mount(vfs, "/sd")

# Set tft pins for QTPy EYESPI BFF on ESP32-S3
tft_cs = board.TX
tft_dc = board.RX
tft_reset = None
tft_backlight = board.A1 # Jumpered EyeSpy BFF Lite pin to Qt Py pin A1
tft_bpwmfreq = 50000 # Default is 50000
displayio.release_displays()
display_bus = FourWire(spi, command=tft_dc, chip_select=tft_cs, reset=tft_reset)
display = GC9A01A(display_bus, width=240, height=240, backlight_pin=tft_backlight, backlight_pwm_frequency=tft_b
pwmfreq)
bg_group = displayio.Group()

# Setup APDS9960 gesture and color (RGBW) sensor
apds = APDS9960(i2c)
# Default all APDS sensing to True to allow sensor to enable
apds.enable_gesture = True
apds.enable_color = True
apds.enable_proximity = True # Note that proximity has to be on for gesture to work
_setgest = 0 # Global variable to track most recent gesture setting
print('APDS setup complete...')

#global _sunriset

plain_clockface = AnalogClock(
    "green_hour_hand_ellipse_600dpi.bmp",
    "green_minute_hand_ellipse_600dpi.bmp",
    (120, 120),
    106,
    number_label_scale=3,
    number_label_color=0x15fd2b,
    hand_transparency_index=0,
)

# Start by loading Sun image...  This will be overwritten by whatever current time of day is...
# Comment-out following to get around image load failure (though this is not consistent behaviour...)
print('Load Sun image...')
'''
bitmap = displayio.OnDiskBitmap("Sun.bmp") # For testing sun image display "/sd/Sun.bmp"
grid = displayio.TileGrid(bitmap, pixel_shader=bitmap.pixel_shader)
bg_group.append(grid)
# End comment-out to get around image load failure
'''

display.root_group = bg_group
display.root_group.append(plain_clockface)
plain_clockface.set_time(time.localtime().tm_hour, time.localtime().tm_min)
print('Clockface loaded...')

[jmangum]

To answer your question as to whether removing the i2c initialization still results in safe mode, I removed that initialization line (and the APDS setup lines) and still encountered the safe mode failure.

[jmangum]

In case it helps in isolating the issue, I have tested the script above with CircuitPython 9.2.7 installed and cannot get it to crash.

[dhalbert]

I have caused a hang, though not safe mode, in a trimmed down version of the program that just mounts the SD card and initializes the display. I will continue to work on this. Thanks for mentioning that it took several runs to cause. It takes about can take 2-3 runs, with ctrl-D in between to cause the problem.

If I disable the USB MSC presentation of the SD drive, the problem goes away. (I had to fix some problems with the disabling logic to make sure that the disabling was happening properly.)

[jmangum]

Very good @dhalbert . In my tests the crash is always to safe mode. In case it matters, I am doing these tests on a Raspberry Pi 3b using Mu (I have noticed varying serial port behavior on my RP3b and Macbook Air).

[dhalbert]

This reliably goes to safe mode without setting up the display at all. Two important things:

• use spi = busio.SPI(board.SCK, board.MOSI, board.MISO) instead of the board.SPI() singleton.
• wait 5 seconds after mounting. This gives enough time for the USB presentation to the host computer to happen.

So I think this has to do with the SPI object management. I discovered this by accident while trying to reproduce the previous test on a Pico W, which doesn't have a board.SPI(), so I had to use busio.SPI(). It does reproduce on that board, so I may be able to debug this on a board that is more easily debugged, like a SAMD51. EDIT: Does not really reproduce on Pico: there is a different error about pin in use. I could not reproduce on SAMD51 or nRF.

import time
import board
import busio
import sdcardio
import storage

# Sleep a bit so we can see print() output.
time.sleep(2)

#spi = board.SPI()
spi = busio.SPI(board.SCK, board.MOSI, board.MISO)

cs = board.A0
sdcard = sdcardio.SDCard(spi, cs)
vfs = storage.VfsFat(sdcard)
storage.mount(vfs, "/sd")
print("SD card mounted")

# Sleep long enough for USB presentation.
time.sleep(5)
print("Done")

[jmangum]

Just FYI. Confirmed that your test code (modified to access CS pin on my EYESPI-BFF/QtPy ESP32-S3 hardware) crashes CircuitPython 10.0.1.

import time
import board
import busio
import sdcardio
import storage

# Sleep a bit so we can see print() output.
time.sleep(2)

#spi = board.SPI()
spi = busio.SPI(board.SCK, board.MOSI, board.MISO)

tft_sdcs = board.A3
sdcard = sdcardio.SDCard(spi, tft_sdcs)
vfs = storage.VfsFat(sdcard)
storage.mount(vfs, "/sd")
print("SD card mounted")

# Sleep long enough for USB presentation.
time.sleep(5)
print("Done")

[jmangum]

Additionally (and maybe not relevant), if I run this test code with CircuitPython 9.2.7 installed I get an SCK pin in use error when I try reloading the program. I have to reset the board to clear this error. I do not get this error if I use spi = board.SPI().