← ClaudeAtlas

espos-memory-budgetlisted

Diagnose out-of-memory failures on ESP32 firmware (espOS or any ESP-IDF project): why PSRAM appears to do nothing, why a classic ESP32 reports internal RAM that malloc cannot get, which pool TLS and the radio really draw from, how to size task stacks from measurement instead of guesswork, and what keeps an image inside its app slot.
signalk-espOS/skills · ★ 0 · Data & Documents · score 72
Install: claude install-skill signalk-espOS/skills
# Diagnosing an ESP32 memory budget Verified against ESP-IDF **v6.0.3**, October 2026. The Kconfig defaults and the allocation sites below are the things most likely to change, so re-check them against your own IDF before trusting a number. ## The first rule: measure regions, not totals `heap_caps_get_free_size()` returning "plenty free" while an allocation fails is the normal shape of these bugs. Two different mistakes hide behind a total: ```c #include "esp_heap_caps.h" heap_caps_get_free_size(MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT); /* general */ heap_caps_get_largest_free_block(MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT); /* fragmentation */ heap_caps_get_free_size(MALLOC_CAP_DMA); /* a SUBSET */ heap_caps_print_heap_info(MALLOC_CAP_DMA); /* per region */ ``` * **A large total with a small largest block** is fragmentation. A caller wanting one contiguous buffer fails while the total looks healthy. `esp_bt_controller_init()` wants ~24 KB in one piece; it fails at 33 KB free / 16 KB largest and allocates nothing, so free size is identical either side of the call. * **`MALLOC_CAP_DMA` is a subset of internal memory**, not a synonym. Quote the wrong one and you overstate the headroom available to whatever you are debugging. * **`MALLOC_CAP_INTERNAL` alone counts IRAM on a classic ESP32.** The IRAM left over after code is heap there, but only 32-bit accesses may use it, so no buffer, stack or Wi