rgbmatrix stops updating display if USB is disconnected from computer

[RetiredWizard]

CircuitPython version and board name

Adafruit CircuitPython 10.0.1 on 2025-10-09; Adafruit MatrixPortal S3 with ESP32S3

Code/REPL

import board
import digitalio
import displayio
import terminalio
import framebufferio
import rgbmatrix
import supervisor
import gifio
import adafruit_ticks

base_width = 64
base_height = 64
bit_depth = 1
chain_across = 1
tile_down = 1
    
serpentine = True

width = base_width * chain_across
height = base_height * tile_down

displayio.release_displays()

addrPins = [
        board.MTX_ADDRA,
        board.MTX_ADDRB,
        board.MTX_ADDRC,
        board.MTX_ADDRD
]
if base_height == 64:
    addrPins.append(board.MTX_ADDRE)

matrix = rgbmatrix.RGBMatrix(
    width=width,height=height, bit_depth=bit_depth,
    rgb_pins=[
        board.MTX_R1,
        board.MTX_G1,
        board.MTX_B1,
        board.MTX_R2,
        board.MTX_G2,
        board.MTX_B2
    ],
    addr_pins=addrPins,
    clock_pin=board.MTX_CLK,
    latch_pin=board.MTX_LAT,
    output_enable_pin=board.MTX_OE,
    tile=tile_down, serpentine=serpentine,
)
# Associate the RGB matrix with a Display so that we can use displayio features

display = framebufferio.FramebufferDisplay(matrix)

# Remove Blinka and CP Status from top line of display
display.root_group[0].hidden = False
display.root_group[1].hidden = True # logo
display.root_group[2].hidden = True # status bar
supervisor.reset_terminal(display.width, height+11)
display.root_group[0].y=-2
display.root_group[0].x=0

led = digitalio.DigitalInOut(board.LED)
led.direction = digitalio.Direction.OUTPUT
led.value = False

fname = 'homer2.gif'
odgcc = gifio.OnDiskGif(fname)
with odgcc as odg:

    colorspace = displayio.Colorspace.RGB565_SWAPPED

    facecc = displayio.TileGrid(odg.bitmap, \
        pixel_shader=displayio.ColorConverter(input_colorspace=colorspace))
    pwidth = odg.bitmap.width
    pheight = odg.bitmap.height

    if pwidth < display.width:
        facecc.x = (display.width-pwidth)//2
    if pheight < display.height:
        facecc.y = (display.height-pheight)//2
    splash = displayio.Group()
    splash.append(facecc)
    display.root_group = splash

    # Display repeatedly.
    while True:
        led.value = not led.value
        start = adafruit_ticks.ticks_ms()
        next_delay = odg.next_frame()
        start = adafruit_ticks.ticks_add(start,int(next_delay*1000))
        while adafruit_ticks.ticks_less(adafruit_ticks.ticks_ms(),start):
            pass

Behavior

If the board is connected to a host computer via the USB cable the GIF animates properly. If the USB cable is unplugged, the animation continues for a 10 to 15 seconds and then stops. The blinking LED continues to blink even though the animation has stopped. If the USB cable is reconnected to the host computer the animation begins again (not where it left off though). A secondary issue is that when the USB cable is plugged back into the host computer and the animation picks up again, the CIRCUITPY drive is remounted as readonly to both the Host computer and the CircuitPython REPL making a hard reset necessary to access the flash storage again.

Description

No response

Additional information

The Matrix Portal S3 has 5V power supplied via the screw terminals on the board. I was not able to recreate the issue using a Matrix Portal M4.

[RetiredWizard]

In case anyone wants to reproduce using the same gif....

homer2.gif.zip

I also tested on a 64x32 matrix panel and got the same results. (code.py should set base_height to 32 in that case)

My bisecting results:
Problem occurs on:
10.0.1, 10.0.0, 10.0.0beta3, 9.2.9, 9.2.7, 9.2.0, 9.2.0beta0, 9.2.0alpha2351
Problem doesn't occur on:
9.1.4

Early in my testing I removed the WiFi credentials from settings.toml which didn't seem to have any impact on the problem.

[RetiredWizard]

This doesn't actually have anything to do with gifio. I was able to recreate the issue by simply reading a binary file and sending output to the matrix panel.

I'm thinking the problem is either related to file I/O or rgbmatrix/framebufferio.

I first created a binary test file:

a = open('test.dat','wb')
for i in range(100000):
    byt = i % 256
    x = a.write(byt.to_bytes(1))
a.close()

And then used the following test program:

import board
import digitalio
import displayio
import terminalio
import framebufferio
import rgbmatrix
import supervisor

base_width = 64
base_height = 32
bit_depth = 1
chain_across = 1
tile_down = 1
    
serpentine = True

width = base_width * chain_across
height = base_height * tile_down

displayio.release_displays()

addrPins = [
        board.MTX_ADDRA,
        board.MTX_ADDRB,
        board.MTX_ADDRC,
        board.MTX_ADDRD
]
if base_height == 64:
    addrPins.append(board.MTX_ADDRE)

matrix = rgbmatrix.RGBMatrix(
    width=width,height=height, bit_depth=bit_depth,
    rgb_pins=[
        board.MTX_R1,
        board.MTX_G1,
        board.MTX_B1,
        board.MTX_R2,
        board.MTX_G2,
        board.MTX_B2
    ],
    addr_pins=addrPins,
    clock_pin=board.MTX_CLK,
    latch_pin=board.MTX_LAT,
    output_enable_pin=board.MTX_OE,
    tile=tile_down, serpentine=serpentine,
)
# Associate the RGB matrix with a Display so that we can use displayio features

display = framebufferio.FramebufferDisplay(matrix)

# Remove Blinka and CP Status from top line of display
display.root_group[0].hidden = False
display.root_group[1].hidden = True # logo
display.root_group[2].hidden = True # status bar
supervisor.reset_terminal(display.width, height+11)
display.root_group[0].y=-2
display.root_group[0].x=0

led = digitalio.DigitalInOut(board.LED)
led.direction = digitalio.Direction.OUTPUT
led.value = False

a = open('test.dat','rb')
passcnt = 0
while True:
    passcnt += 1
    for i in range(100000):
        print(f'{passcnt}:{ord(a.read(1))}')
        if i%256 == 0:
            led.value = not led.value
    a.seek(0)

The behavior was the same, unplugging the USB cable from the host computer resulted in the output stopping after a short while but LED kept blinking. Plugging the USB back in would result in the output continuing but if the elapsed time was long enough passcnt increments appropriately

[RetiredWizard]

Well I'm embarrassed, it looks like I ran into this last December but forgot about it #9854. Looking back at the earlier issue I had submitted it appears that supplying WiFi credentials prevents the problem from occurring which I confirmed with my latest test script.

I did notice that when WiFi credentials were provided in settings.toml, after about the time the display would have stopped updating (10-15 seconds) , there was a momentary pause in the output but it almost immediately recovered and continued running. These momentary pauses continue to occur as the script runs. The 9.1.4 firmware didn't seem to have these momentary pauses.

Back in December, I also saw the issue on an Adafruit Feather ESP32-S3 Reverse TFT so the problem doesn't appear to have anything to do with rgbmatrix either.