Hardware Constraints & Memory Map
Relevant source files
The following files were used as context for generating this wiki page:
The Muse Gadget SDK operates within strict hardware constraints dictated by the specific ESP32 SoC and available memory (Internal RAM and PSRAM). Memory management is critical for features like the home-network tunnel, high-resolution displays, and encrypted Noise sessions. Devices without PSRAM operate with a reduced feature set, specifically losing the home-network tunnel due to memory limitations.
Sources: board-port/esp32/README.md:154-156, board-port/esp32/main/noise_control.cpp:66-71
Memory Architecture and Allocation
The firmware utilizes two primary memory regions: Internal SRAM and External SPIRAM (PSRAM). Internal RAM is scarce and primarily reserved for high-performance operations like Wi-Fi, TLS, and DMA buffers. PSRAM is used for larger, less performance-critical buffers such as display frame buffers and application-level Noise session scratch space.
Memory Capabilities
- MALLOC_CAP_INTERNAL: Reserved for critical stacks (e.g.,
NOISE_CTRL_STACK), Wi-Fi, and TLS record buffers. - MALLOC_CAP_SPIRAM: Preferred for large scratch buffers (
SVC_FRAME_SCRATCH,OUT_SVC_SCRATCH) to avoid fragmenting internal RAM. - MALLOC_CAP_DMA: Mandatory for SPI/LCD transfer buffers on specific boards like the CYD or DevKit.
Sources: board-port/esp32/main/noise_control.cpp:115-125, board-port/esp32/main/noise_control.cpp:783-795, board-port/esp32/main/led_status.c:122
Memory Allocation Flow
The following diagram illustrates how the system prioritizes memory allocation based on hardware availability and the nature of the request.
Noise Control Session Constraints
Noise sessions are heavily constrained by available RAM. The SDK implements a "Small Control Session" mode for boards without PSRAM or the home-network tunnel. In this mode, buffers are downsized to fit within the limited Internal RAM available after Wi-Fi and TLS overhead.
| Buffer Type | Normal (with PSRAM) | Small Session (No PSRAM) | Cardputer ADV |
|---|---|---|---|
| SVC_FRAME_SCRATCH | 12,288 bytes | 17,408 bytes | 17,408 bytes |
| OUT_SVC_SCRATCH | 12,288 bytes | 6,144 bytes | 3,072 bytes |
| OUT_ENV_SCRATCH | 12,288 bytes | 6,144 bytes | 3,072 bytes |
| WS_BUF_SIZE | 65,535 bytes | 7,168 bytes | 4,096 bytes |
Sources: board-port/esp32/main/noise_control.cpp:73-95
Stack Management
The noise_ctrl task requires a 12,288-byte stack. On boards where Muse features are enabled and PSRAM is present, Internal RAM fragmentation can prevent allocation. To mitigate this, the system reserves a stack block at boot and releases it only immediately before task creation.
Sources: board-port/esp32/main/noise_control.cpp:115-125
Flash Partitioning
The SDK uses custom partition tables to manage application slots and manufacturing data. A standard Muse build requires 16 MB of flash, while boards like the M5Stack StickS3 or Cardputer ADV utilize a specialized 8 MB partition table.
| Partition Name | Offset | Size | Purpose |
|---|---|---|---|
| nvs | Standard | 24 KB | Wi-Fi and device tokens |
| otadata | Standard | 8 KB | OTA selection data |
| phy_init | Standard | 4 KB | PHY calibration data |
| factory | 0x10000 | Variable | Initial application image |
| ota_0 / ota_1 | Variable | 2 MB / 4 MB | OTA application slots |
| prod_data | Fixed | Fixed | Manufacturing locations |
Sources: board-port/esp32/AGENTS.md:139-142, board-port/esp32/AGENTS.md:199-204, README.md:112-117
Display and LED Hardware Constraints
Display drivers allocate memory based on the specific controller and bus type. High-resolution panels, such as the SenseCAP Indicator (ST7701S), require large frame buffers typically placed in PSRAM.
Buffer Requirements by Backend
- SPI Panels (ST7789/ILI9341): Utilize
MALLOC_CAP_DMAfors_bar_bufands_anim_bufto support high-speed SPI transfers. - RGB Panels (ST7701S): Utilize
MALLOC_CAP_INTERNALfor bounce buffers to feed the 16-bit RGB bus while the primary frame buffer resides in PSRAM. - Addressable LEDs (WS2812): Require RMT (Remote Control) memory blocks. For 12-LED rings, 192 symbols are allocated to prevent mid-frame refills.
Sources: board-port/esp32/main/led_status.c:120-125, board-port/esp32/main/led_status.c:485-488, board-port/esp32/main/led_status.c:283-290
Home-Network Tunnel Requirements
The home-network tunnel feature imposes the heaviest memory requirements. It necessitates the creation of a virtual network interface (tunnel_netif) and multiplexes 8 KB IP-packet batches over the Noise session. Boards without PSRAM cannot sustain the necessary buffer sizes for both encrypted control and tunnel traffic; therefore, CONFIG_HOMEHUB_TUNNEL must be set to n for these devices.
Sources: board-port/esp32/main/app.c:108-120, board-port/esp32/AGENTS.md:195-197
Hardware-specific memory management ensures the Muse Gadget SDK remains stable across a wide variety of ESP32-based devices, balancing performance with strict resource limits.