`OnDiskBitmap` Issue on UM FeatherS3 While Connected to PC With SD Card Inserted

[sco1]

CircuitPython version and board name

Adafruit CircuitPython 10.2.1 on 2026-05-13; FeatherS3 with ESP32S3
Board ID:unexpectedmaker_feathers3

Code/REPL

import displayio
import time
from adafruit_featherwing import tft_featherwing_35

DEFAULT_BASE_MAP = "./assets/default_map.bmp"


class FeatherS3:
    def __init__(self):
        self._fw = tft_featherwing_35.TFTFeatherWing35V2()
        self.display = self._fw.display
        self.display.rotation = 180

    @property
    def width(self):
        return self.display.width

    @property
    def height(self):
        return self.display.height


class SkyPortalUI:
    def __init__(self, device):
        self.device = device
        self.display = self.device.display

        # Set up main display element
        self.main_display_group = displayio.Group()
        self.display.root_group = self.main_display_group

    def set_base_map(self):
        map_img = displayio.OnDiskBitmap(DEFAULT_BASE_MAP)

        map_group = displayio.Group()
        map_sprite = displayio.TileGrid(map_img, pixel_shader=map_img.pixel_shader)

        map_group.append(map_sprite)
        self.main_display_group.append(map_group)


feather = FeatherS3()
print("Initialized feather")

main_ui = SkyPortalUI(feather)
print("Initialized UI")

main_ui.set_base_map()
print("Base map set?")

print("Looping forever")
while True:
    time.sleep(1)
    feather.display.refresh()

Behavior

Description

Continuation of our chat from Discord!

Hardware:

• FeatherS3 - ESP32-S3 Development Board by Unexpected Maker
• Adafruit TFT FeatherWing - 3.5" 480x320 Touchscreen for Feathers - V2 with TSC2007
• 32GB SD card, FAT32

With the reproducer above, also uses this default map (saved as ./assets/default_map.bmp), and vendored CP10.2.1 libraries. The vendored libraries are sourced from adafruit-circuitpython-bundle-10.x-mpy-20260815 and circuitpython-community-bundle-10.x-mpy-20260806.

With CP10.2.1 the following behavior is observed using a powered USB hub connected to my Windows PC:

• Computer on, SD card inserted - Map not rendered as expected
• Computer on, SD card removed - Map renders as expected
• Computer off, SD card inserted - Map renders as expected
• Computer off, SD card removed - Map renders as expected

Also reported by folks trying out in Discord, not sure if they were connected to a computer or just power:

• UM FS3[D] and Featherwing V2, no SD card, both 10.2.1 and 10.3.0.alpha.4 - Map renders as expected
• Feather S3 8mb flash no psram, no SD card - Map renders as expected

The sample code renders the map image on CP9.2.9 as expected. The sample code also works as expected using my PyPortal on CP10.2.1. Both scenarios are with SD card inserted & computer on.

Additional debug tasks:

• Set CIRCUITPY_SDCARD_USB=false in settings.toml
• Try Macbook Pro

Additional information

No response

[grgrant]

I am using 10.2.1, the UM FS3[D] and the Featherwing V2, I'm now using a SanDisk 16G MSDOS FAT32 SD card. Map renders as expected. I didn't use the vendor(ed) libraries from @sco1 but instead got the latest 10.2.1 libraries via circup. My setup is a Macbook Pro M4 OSX with directly connected device and no external USB hub. I also tried with a powered cable not connected to my computer and it renders the map.

[dhalbert]

Marking this as "Support" for the moment, until it's resolved whether it's a library problem or not.

[grgrant]

I don't know if this is an artifact of my setup Mac OSX with tio for USB Serial connection. I'm now a newly formatted filesystem on 10.2.1 with only code.py, default_map.bmp, and circup installed libraries.

I have the issue that code.py hangs without displaying the bitmap. When connected to power only it displays fine. Also when I Control-C and Control-D to reload it displays fine. It is only on boot or reset that it seems to hang in the loop.

I added a time.sleep(5) at the beginning to allow the USB serial to settle and I get all the program outputs just no display of the map until I do a soft-reload.

[sco1]

It does not appear that setting CIRCUITPY_SDCARD_USB=false in settings.toml changes any seen behavior, though even with true I'm still only seeing the placeholder text file. Also tried with the 16GB card from my PyPortal with the same result.

Trying with my MBP I'm seeing pretty much the same behavior as on PC, though the map appears to render more than on PC:

[grgrant]

@sco1 As of this morning I was consistently getting a full noise screen with no map on first boot using 10.2.1. And getting a full map if I did a soft reload after.

I tried the CIRCUITPY_SDCARD_USB=false and wondered why the drive still showed up. Then it occurred to me that it might have been post 10.2.1 that that knob was added. I installed 10.3.0.alpha.4 and now the settings.toml sdcard usb setting works correctly. Full noise on first boot with CIRCUITPY_SDCARD_USB=true and map loading fine with CIRCUITPY_SDCARD_USB=false.

Now with 10.3.0.alpha.4 when I do a soft reload after the first boot noise with SDCARD_USB=true, I'm seeing a single map colored line at the bottom of the screen and the previous REPL above it ending with

soft reboot
code.py output:

[sco1]

Thanks for trying that out. I just tried out 10.3.0-alpha.4 with similar findings:

• With CIRCUITPY_SDCARD_USB=true, from a fresh boot I get the noise/partial load, however a soft reboot does not resolve
• With CIRCUITPY_SDCARD_USB=false, from a fresh boot I get a full map load.

In both cases I'm connected through the USB hub to a Windows PC. Also tried with my full library with the same result.

I will note that with both true and false the only thing I see still in ./sd/ is the placeholder text file, which seems strange.