A comprehensive memory management library for ESP32 microcontrollers, providing efficient data structures that leverage PSRAM and HIMEM for expanded storage capabilities.
The ESP32 can only address 4MB of PSRAM directly, so the remaining 4MB (HIMEM) are usually unsued!
esp32-psram is a C++ library that helps you manage large amounts of data on ESP32 devices by utilizing the full external PSRAM (SPI RAM) supporting the high memory (HIMEM) regions. This allows your applications to work with much larger datasets than would be possible using just internal RAM.
-
Memory-Efficient Data Structures:
VectorPSRAM
: Vector implementation that automatically stores data in PSRAMVectorHIMEM
: Vector implementation for extremely large datasets using ESP32's high memory region
-
File System Abstractions:
FilePSRAM
: File-like interface backed by PSRAMFileHIMEM
: File-like interface backed by high memory- SD card-like API using familiar file operations to write to PSRAM or HIMEM.
-
Streaming Data Handling:
RingBufferStreamRAM
: Circular buffer implementation in RAM (Stream-based)RingBufferStreamPSRAM
: Circular buffer implementation in PSRAM (Stream-based)RingBufferStreamHIMEM
: Circular buffer implementation in high memory (Stream-based)- Fully compatible with Arduino's Stream class
-
Typed Ring Buffers:
TypedRingBufferRAM<T>
: Type-safe circular buffer for any data type using RAMTypedRingBufferPSRAM<T>
: PSRAM version for storing complex data structuresTypedRingBufferHIMEM<T>
: High memory version for storing complex data structures- Optimized for struct/class storage with proper memory management
-
Use any STL Class in PSRAM:
- Adapt any STL class that accepts with an Allocator by using the AllocatorPSRAM
- Download the latest release from GitHub
- Extract the ZIP file
- Move the folder to your Arduino libraries directory (typically
~/Arduino/libraries/
on Linux/macOS orDocuments\Arduino\libraries\
on Windows) - Restart Arduino IDE
Memory Type | Access Speed | Capacity | Use Case |
---|---|---|---|
RAM (DRAM) | Very Fast | ~200-300KB | Small, performance-critical data |
PSRAM | Fast | Up to 4MB | Medium-sized datasets, frequent access |
HIMEM | Medium | Up to 8MB | Large datasets, less frequent access |
ESP32 Board | PSRAM Size | HIMEM Support | Notes |
---|---|---|---|
ESP32 | Up to 4MB | Yes | Most common ESP32 modules |
ESP32-S2 | Up to 2MB | Limited | Check board specifications |
ESP32-S3 | Up to 8MB | Yes | Best memory capabilities |
ESP32-C3 | None | No | Not compatible with this library |
The ESP32-PSRAM library is designed with these principles in mind:
- Familiar interfaces: API design mimics standard C++ containers and Arduino libraries
- Memory efficiency: Automatic use of appropriate memory regions
- Type safety: Template-based to work with any data type
- Flexibility: Configurable for different memory types and use cases
- Zero overhead: Direct memory access with minimal abstraction layers
MIT License
Contributions are welcome! Please feel free to submit a Pull Request.
This library was inspired by the need for better memory management solutions on ESP32, especially for audio, image processing, and data logging applications.