espos-memory-budgetlisted
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