Recommended way to get PSRAM / SPIRAM supported for a chip

[rmelick]

I've just started prototyping a new project with Micropython, and would like to utilize an ESP32-C5 (in particular, the Seeed Studio XIAO ESP32-C5). This board uses the ESP32-C5HR8 chip from Espressif, which includes 8MB of PSRAM (see section 1.2 of the datasheet).
, and I would like to utilize that extra memory.

Previously, I played around with an ESP32-S3R8 (also from Seeed Studio), and to utilize the built-in PSRAM I needed to install the "Support for Octal-SPIRAM" firmware from the Generic ESP32-S3 micropython page.

Today, the Generic ESP32-C5 micropython page does not have links for downloading a different "Support for Octal-SPIRAM" firmware.

So, I have two questions:

1. What is the preferred way to add support for PSRAM for these ESP chips? Is it to add a different firmware to the Generic ESP32-C5 download page (like what was done for the ESP32-S3)? Or should a new board be added (e.x. SEEED_XIAO_ESP32C5) that always supports the additional PSRAM? I believe there are other boards out there that use the PSRAM chip variant (like this one from Waveshare)
2. For my own curiosity and learning, what is actually happening underneath to support PSRAM? Is there a downside to supporting it (e.x. could it always be supported in the default firmware)? Is this support different for different ports (like rp2 or stm32) or is the process the same?

I did install the latest micropython onto my ESP32-C5, just to make sure it wasn't detecting the PSRAM. Here is the comparison by the C5 and the S3, where the S3 had the "Support for Octal-SPIRAM" firmware installed and working PSRAM.

MicroPython v1.28.0 on 2026-04-06; ESP32C5 module with ESP32C5
Type "help()" for more information.
>>> import gc
>>> gc.collect()
>>> gc.mem_free()
227152


MicroPython v1.27.0 on 2025-12-09; Generic ESP32S3 module with Octal-SPIRAM with ESP32S3
Type "help()" for more information.
>>> import gc
>>> gc.collect()
>>> gc.mem_free()
8316688

[Josverl]

I think the sparkfun thingplus esp32-C5 board has Spiram enabled.

You can look at its config to start configuring you own board variant.

https://github.com/search?q=repo%3Amicropython%2Fmicropython+path%3Aports%2Fesp32%2Fboards+mpconfigvariant_SPIRAM+OR+sdkconfig.spiram+OR+sdkconfig.spiram_oct+OR+sdkconfig.spiram_sx&type=code

[projectgus]

The ESP32-C5 packages mentioned here have Quad SPI PSRAM not Octal SPI PSRAM, so it should be straightforward to enable support (as per @Josverl's comment we have one board which already has this.)

What is the preferred way to add support for PSRAM for these ESP chips? Is it to add a different firmware to the Generic ESP32-C5 download page (like what was done for the ESP32-S3)? Or should a new board be added (e.x. SEEED_XIAO_ESP32C5) that always supports the additional PSRAM? I believe there are other boards out there that use the PSRAM chip variant (like this one from Waveshare)

The base ESP32_GENERIC_S3 actually supports quad PSRAM already in the default variant, and probably we can make the same change to ESP32_GENERIC_C5 so it will use PSRAM automatically if it's there.

It'd also be good to add a SEEED_XIAO_ESP32C5 board, but this is for a different reason - so that the pin assignments in MicroPython can be correct.

For my own curiosity and learning, what is actually happening underneath to support PSRAM? Is there a downside to supporting it (e.x. could it always be supported in the default firmware)?

It's a bit fiddly, but enabling it in esp32 boards generally only requires enabling support in the SDK config, which makes the binary a little bit larger and sometimes prints an error on boot if the PSRAM isn't found when the chip probes for it. This is why it's enabled in the default ESP32_GENERIC_S2 and ESP32_GENERIC_S3 boards, for example. And I think we can probably do the same for ESP32_GENERIC_C5.

There are some special cases:

• Original ESP32s need a bunch of costly software workarounds enabled when using PSRAM, so the default variant doesn't support PSRAM and we have a second spiram variant which enables PSRAM support but is otherwise a bit larger and slower due to the workarounds.
• Octal PSRAM uses eight data lines instead of four, and an ESP32 firmware has to support either one or the other. This is why we have the Octal SPIRAM variant for ESP32-S3.

Is this support different for different ports (like rp2 or stm32) or is the process the same?

It's different, to get acceptable performance the PSRAM support has to be closely integrated with the hardware of the chip.

• Espressif integrate support for PSRAM in their ESP-IDF SDK (meaning their code does all of the detection, initialisation, memory management, etc.) So all we really do for the esp32 port is enable different SDK config options.
• RP2350 PSRAM support depends on some custom support code we currently have in MicroPython, but it might move to the Raspberry Pi SDK side soon. See rp2: Upstream PSRAM support in Pico SDK #19209
• In stm32 port we have configuration for some boards with full SDRAM chips, but I don't think we have any SPI PSRAM support in this port.

[projectgus]

Have opened a PR to add PSRAM support to ESP32_GENERIC_C5 board: #19303

@rmelick Once this merges you'll be able to download a nightly build which has PSRAM support enabled.

[rmelick]

Thanks for the quick response everyone! @projectgus , I went ahead and tested the "default" v1.28.0 release on my ESP32-S3, to see if it would detect the PSRAM (and to give an idea of whether your changes for the C5 would work automatically too).

Unfortunately, it looks like something isn't quite working, gc.mem_free is only reporting 222 kilobytes, instead of the 8 megabytes it reported with the octal SPIRAM build.

MicroPython v1.28.0 on 2026-04-06; Generic ESP32S3 module with ESP32S3
Type "help()" for more information.
>>> import gc
>>> gc.collect()
>>> gc.mem_free()
222416

If I put the board back into the bootloader, I can see that esptool thinks it should have PSRAM

esptool flash-id

esptool v5.2.0
Connected to ESP32-S3 on COM4:
Chip type:          ESP32-S3 (QFN56) (revision v0.2)
Features:           Wi-Fi, BT 5 (LE), Dual Core + LP Core, 240MHz, Embedded PSRAM 8MB (AP_3v3)
Crystal frequency:  40MHz
USB mode:           USB-Serial/JTAG
MAC:                80:b5:4e:f1:b5:a0

Stub flasher running.

Flash Memory Information:
=========================
Manufacturer: c8
Device: 4017
Detected flash size: 8MB
Flash type set in eFuse: quad (4 data lines)
Flash voltage set by eFuse: 3.3V

Hard resetting via RTS pin...

I have tried to get the boot logs from running machine.reset (like in this comment), but I don't see any logs printed. I attempted putting the following into a boot.py

# This file is executed on every boot (including wake-boot from deepsleep)
import esp
esp.osdebug(0)
#import webrepl
#webrepl.start()

But still, after a reboot, all I saw was the MicroPython prompt (MicroPython v1.28.0 on 2026-04-06; Generic ESP32S3 module with ESP32S3)

[rmelick]

I think I've found the "issue", which is just that the chip on my ESP32-S3 board does actually use Octal SPIRAM, not Quad.

The Seeed Studio site shows that the board uses an ESP32-S3R8 and the datasheet from Espressif shows that the SR8 uses Octal SPIRAM.

Given that the C5HR8 is listed in the datasheet as using Quad SPIRAM, it seems likely that your PR will make things work right away :).

[rmelick]

I just wanted to follow up here, and say that the nightly builds are working! Thanks for the help everyone.

MicroPython v1.29.0-preview.414.g533a154c8a on 2026-06-23; ESP32C5 module with ESP32-C5
Type "help()" for more information.
>>> import gc
>>> gc.collect()
>>> gc.mem_free()
8316032