MemoryErrors feel unpredictable and arbitrary on Circuit Playground / SAMD21

[tom-hoffman]

CircuitPython version and board name

Adafruit CircuitPython 10.0.3 on 2025-10-17; Adafruit CircuitPlayground Express with samd21g18

Code/REPL

# SPDX-FileCopyrightText: 2025 Tom Hoffman
# SPDX-License-Identifier: MIT

# Modular Playground CircuitPython Euclidian Sequencer

DEV_MODE = True

# We use the gc library to check and manage available RAM during development
if DEV_MODE:
    import gc
    gc.collect()
    print("Starting free bytes (after gc) = " + str(gc.mem_free()))

from micropython import const

import math             # need the floor function
import board            # helps set up pins, etc. on the board
import digitalio        # digital (on/off) output to pins, including board LED.
import neopixel         # controls the RGB LEDs on the board

import usb_midi         # basic MIDI over USB support

if DEV_MODE:
    gc.collect()
    print("Free bytes after imports = " + str(gc.mem_free()))

############

# CONSTANTS

_CLOCK_MSG = const(0b11111000)

_LED_COUNT = const(10)
_CLOCK_LIMIT = const(23)  # for quarter note
_MAX_VELOCITY = const(5)
_DEFAULT_VELOCITY = const(4)
_NOTE_COUNT = const(4)
_NOTES = const((36, 38, 59, 47))



# variables

channel_out = 1


############

# board setup steps

# set up the red LED

a_button = digitalio.DigitalInOut(board.BUTTON_A)
a_button.direction = digitalio.Direction.INPUT
a_button.pull = digitalio.Pull.DOWN

b_button = digitalio.DigitalInOut(board.BUTTON_B)
b_button.direction = digitalio.Direction.INPUT
b_button.pull = digitalio.Pull.DOWN

switch = digitalio.DigitalInOut(board.SLIDE_SWITCH)
switch.direction = digitalio.Direction.INPUT
switch.pull = digitalio.Pull.UP

def switchIsLeft():
    return switch.value

pix = neopixel.NeoPixel(board.NEOPIXEL, 10)
pix.brightness = 0.2
pix.fill((255, 0, 255))
pix.show()

innie = usb_midi.ports[0]
outie = usb_midi.ports[1]

if DEV_MODE:
    gc.collect()
    print("Free bytes after board setup = " + str(gc.mem_free()))


############
# Objects

class EuclidianSequencer(object):
    
    def __init__(self):
        self.steps = 9
        self.triggers = 2
        self.sequence = []
        self.active_step = 0
        self.clock_count = 0

    def update(self):
        '''
        Generates a "Euclidian rhythm" where triggers are
        evenly distributed over a given number of steps.
        Takes in a number of triggers and steps, 
        returns a list of Booleans.
        Based on Jeff Holtzkener's Javascript implementation at
        https://medium.com/code-music-noise/euclidean-rhythms-391d879494df
        '''
        slope = self.triggers / self.steps
        result = []
        previous = None
        for i in range(self.steps):
            # adding 0.0001 to correct for imprecise math in CircuitPython.
            current = math.floor((i * slope) + 0.001) 
            result.append(current != previous)
            previous = current
        self.sequence = result
        return self  # so you can do method chaining.

    def addStep(self):
        if self.steps < 10:
            self.steps += 1
        else:
            self.steps = 1
            self.triggers = 0
            self.active_step = 0
        self.update()

    #def incrementActiveStep(self):
    #    pass
     #   #self.active_step = (self.active_step + 1) % self.steps
    
class SequencerApp(object):
    def __init__(self, sequence):
        self.seq = sequence
        self.a = a_button.value
        self.b = b_button.value
        self.switchIsLeft = switch.value
        self.note_index = 0
        self.velocity_index = 4
        self.started = False
        self.starting_step = 0

    def getRed(self, i):
        if i == self.seq.active_step:
            return 64
        else:
            return 0

    def getGreen(self, i):
        if self.seq.sequence[i]:
            return 48
        else:
            return 0

    def getBlue(self, i):
        # add velocity calculation
        return 16

    def updateSequenceDisplay(self):
        for i in range(_LED_COUNT):
            if i < len(self.seq.sequence):
                pix[i] = (self.getRed(i), self.getGreen(i), self.getBlue(i))
            else:
                pix[i] = (0, 0, 0)
            
    def updateConfigDisplay(self):
        pix.fill((8, 8, 8))
    
    def updateNeoPixels(self):
        if switchIsLeft():
            self.updateConfigDisplay()
        else:
            self.updateSequenceDisplay()
        pix.show

    def addTrigger(self):
        pass

    def checkSwitch(self):
        # Return value indicates if NeoPixels need to be updated.
        if self.switchIsLeft != switch.value:
            self.switchIsLeft = switch.value
            return True
        else:
            return False

    def checkA(self):
        # Return value indicates if NeoPixels need to be updated.
        update = False
        if self.a != a_button.value:
            if a_button.value:
                self.seq.addStep()
                update = True
            self.a = a_button.value
        return update

    def getByte(self):
        raw = innie.read(1)
        if raw != b'':
            # convert the byte type to a number
            return ord(raw)     
        else:
            return None
    
    def get_msg(self):
        b = self.getByte()
        if b is None:
            return None
        else:
            return b    

    def incrementClock(self):
        self.clock_count +=1 
        if self.clock_count >= _CLOCK_LIMIT:
            self.clock_count = 0
            #self.seq.incrementActiveStep()
            #self.updateNeoPixels()
            
    def main(self):
        while True:
            # These method calls change state and return True or False.
            # True indicates we need to call updateNeoPixels()
            if (self.checkSwitch() or self.checkA()):
                self.updateNeoPixels()
            msg = self.get_msg()
            if msg is not None:
                # if there is a message flip the red led
                led.value = not(led.value)
                #if msg == _CLOCK_MSG:
                #    pass
                    #self.incrementClock()

app = SequencerApp(EuclidianSequencer().update())
app.updateNeoPixels()

if DEV_MODE:
    gc.collect()
    print("Free bytes after object def and creation = " + str(gc.mem_free()))

app.main()

Behavior

MemoryError: memory allocation failed, allocating 208 bytes

or, commenting out line 211:

Starting free bytes (after gc) = 12420
Free bytes after imports = 11764
Free bytes after board setup = 11428
Free bytes after object def and creation = 10580

Description

Even taking into account that a CPX is very memory constrained with CircuitPython, it has always felt completely arbitrary when one is going to hit a MemoryError. It feels like the amount of memory reported by gc is irrelevant, as I have gotten in the habit of watching gc.mem_free() very closely. I just went from having over 10,000 bytes free according to gc, to failing to start at all with a MemoryError by adding an if statement that increments a variable.

Obviously this is not actually random, but I can't figure out how to predict/mitigate the issue.

This is probably the same issue as: #10359

I accept that it is an edge case, as everyone is moving on to more current microcontrollers or using C if they are trying to milk performance out of older ones, but I had hopes I'd be able to eek at least slightly more complex CircuitPython applications on the CPX with my students.

Is this maybe a stack/heap configuration kinda thing? I don't think it is a recent regression as CircuitPython has always done the to me but I keep hoping I can figure out how to work with it. I am motivated to try to do some more detailed debugging if a dev can point me in the right direction.

Additional information

No response

[tom-hoffman]

Whoops that's not the best version of the code. Better one attached. The incrementClock() function near the bottom is the one where you can trip it to MemoryError.

code.py

[dhalbert]

Since 9.something, we removed a memory allocation scheme that tended to reduce fragmentation. I think that may be what you are running into here.

You might try doing some pre-allocation. For instance, this loop is appending to a list:

        for i in range(self.steps):
            # adding 0.0001 to correct for imprecise math in CircuitPython.
            current = math.floor((i * slope) + 0.001) 
            result.append(current != previous)
            previous = current
        self.sequence = result

How long does this list get? If you have an idea of the maximum length, you could allocate a list or array.array in advance, and keep track of where the last element is, instead of appending to a list that must grow.

[tom-hoffman]

Thanks dhalbert. Yeah on one hand I keep thinking "Oh, I just need to focus on optimization," and little things like that list that could be converted to a 10 number array (there are currently max 10 steps), but the reality is Circuit Python on CPX just goes from "You've got almost 10k free" to MemoryError with one seemingly innocuous line of code.

[tom-hoffman]

OK, re-reading the micropython docs, I think what is confusing me is the relatively invisible bottleneck of compilation time memory use. Once the program is compiled and running, I can have 10k bytes free after compilation, but adding one character too many could cause a compilation time error, even if it has little impact on the memory usage by the running program. I'm going to do some experimenting with breaking out mpy libraries.

[tom-hoffman]

OK, yes, making a library gets around the compilation bottleneck. I think this is a documentation problem. I'll write up a little piece explaining it.

[dhalbert]

Thanks for your sleuthing. We have written up some info about this: https://learn.adafruit.com/welcome-to-circuitpython/library-file-types-and-frozen-libraries#creating-an-mpy-file-3118108 and https://learn.adafruit.com/welcome-to-circuitpython/frequently-asked-questions#memory-issues-3129414

[samblenny]

It looks like you're already using some of the Maximising MicroPython Speed tricks, but a couple other things you could try:

1. Limit the number of names you put in the global scope (i.e. top level code goes in def main(): ..., then have a call to main() be about the only code that runs from outside of a function). The point is that the VM stores function local vars differently than global vars.
2. Use # ... style comments rather than '''...''' style heredoc comments because heredoc comments can get included in the compiled bytecode.

[dhalbert]

because heredoc comments can get included in the compiled bytecode.

This should not happen: they are discarded and are not in the bytecode in MicroPython/CircuitPython. But they still need to be parsed and that might cause memory fragmentation.

[samblenny]

But they still need to be parsed and that might cause memory fragmentation.

Perhaps that's what I experienced then. My impression from old experiments with trying to cram stuff onto a Trinket M0 and a Casio calculator with MicroPython was that avoiding heredoc syntax did seem to help. Not sure exactly why.

[tom-hoffman]

The documentation that finally got me on the right track was this bit:

When a module is imported, MicroPython compiles the code to bytecode which is then executed by the MicroPython virtual machine (VM). The bytecode is stored in RAM. The compiler itself requires RAM, but this becomes available for use when the compilation has completed.

If a number of modules have already been imported the situation can arise where there is insufficient RAM to run the compiler. In this case the import statement will produce a memory exception.

Here's how I'd summarize my understanding of how to make moderately complex CPX apps at this point:

1. Be parsimonious with external imports.
2. Be cognizant of a bunch of memory optimization tips, tricks and techniques.
3. Monitor gc.mem_free()
4. Expect to keep each module below about 200 lines of code, keep code.py small, and use .mpy to avoid the bytecode compilation memory bottleneck as much as possible.
5. If you abruptly go from having a bunch of memory in gc.mem_free() to not starting at all because of a MemoryError, see number 4.