Files
esphome-yambms/documents/README/LOOP_TASK_STACK.md
T

6.9 KiB

YamBMS - loop_task_stack_size

Badge License: GPLv3 Badge Version GitHub stars GitHub forks GitHub watchers

Reference for the loop_task_stack_size option. Read this before changing it.

This document covers raising the value. Lowering it below the ESPHome default is not documented here and is not recommended: the gain is a few kilobytes, and the failure mode is a rare crash on a code path you did not test.

Stack and heap in one minute

An ESP32 stores data in two very different ways, and both come out of the same pool of internal RAM.

Stack Heap
What it is Scratch space for the function currently running A reserve the program borrows from on demand
Reserved when At compile time, one fixed block per task At runtime, piece by piece
Holds Local variables, return addresses Objects whose count is not known in advance
In YamBMS The local variables of setup() Every sensor object, every API connection, every network buffer
Runs out how Silently overwrites neighbouring memory malloc() returns null

The stack is a fixed-size block. ESPHome runs setup() and the main loop inside a FreeRTOS task called loopTask, whose stack defaults to 8192 bytes. That block is reserved at compile time and never grows.

The heap is everything left over. When YamBMS creates 1,400 sensor objects at boot, they come from the heap. On a board with PSRAM, most of them end up in PSRAM rather than internal RAM.

Raising loop_task_stack_size enlarges the stack block, which takes internal RAM away from the heap — byte for byte, nothing else changes.

Why the default is sometimes not enough

ESPHome generates setup() as a single flat function. Every entity registration adds local variables to the same stack frame, so the frame grows in direct proportion to the number of entities.

Measured on YamBMS with YamBMS RS485 BMS (bms_combine_modbus_client.yaml) packages:

setup() frame = 784 + 400 x nb_BMS bytes

  12 BMS -> 5,584 B   ~2,350 B left for everything else   -> boots
  16 BMS -> 7,184 B     ~760 B left for everything else   -> boot loop

That frame stays alive while App.setup() initialises every component, so the remaining bytes must also cover component init, NVS reads, log formatting and CPU register spills. When they do not fit, the overflow writes past the end of the stack and corrupts whatever sits next to it in memory.

Symptoms

  • Boot loops that start only after adding BMS or entities, with no hard threshold — it scales with config size.
  • Guru Meditation Error whose type changes between reboots: sometimes LoadProhibited, sometimes an Interrupt WDT, sometimes a cache error.
  • No stack overflow message. The FreeRTOS canary is often skipped entirely by a large stack frame, so nothing warns you.
  • Adjusting PSRAM options changes nothing, because the stack is not in PSRAM.

If a boot loop produces no ESPHome log output at all and a constant abort(), that is a different problem — the board ran out of internal RAM before startup. Lower the value rather than raising it, and reduce the config.

BMS per node loop_task_stack_size
up to 6 8192 (ESPHome default — leave unset)
7 to 24 16384
25 to 64 32768 (maximum accepted value)

Values include roughly 4 KB of reserve above the measured setup() frame.

These values are for YamBMS RS485 BMS (bms_combine_modbus_client.yaml). BLE BMS instantiate esp32_ble_tracker and one ble_client per BMS, which gives a different fixed cost and a different slope. The model above has not been calibrated for them.

The 16384 and 32768 rows assume a board with PSRAM. Not because the stack needs PSRAM — it never lives there — but because a config large enough to need them will run out of heap long before it runs out of stack. On a board without PSRAM, keep 8192 unless you have a measured reason not to.

How to apply it

The value belongs in your main configuration, not in a board or PSRAM package: it depends on how many BMS you configured, not on your hardware.

substitutions:
  loop_task_stack_size: "8192"   # see LOOP_TASK_STACK.md before changing

esp32:
  framework:
    advanced:
      loop_task_stack_size: ${loop_task_stack_size}

Check the cost before flashing

Raising this value consumes internal RAM permanently. The size report at the end of every compile tells you the cost, with no hardware required:

RAM:   [======    ]  59.2% (used 202299 bytes from 341760 bytes)

Recompile after changing the value and compare. Going from 8192 to 16384 should increase the used figure by exactly 8,192 bytes; 8192 to 32768 by 24,576. Anything else means something unexpected happened.

Leave yourself comfortable margin on the free figure. If free internal RAM drops low, you trade a boot-time crash for runtime symptoms instead: API disconnections, WiFi failing to reconnect, entities failing to initialise.

To confirm the value actually reached the firmware:

NM=$(find ~/.cache/esphome/idf/tools -name '*-elf-nm' | head -1)
$NM -SC .esphome/build/<node>/build/<node>.elf | grep loop_task_stack

The second column is the size in hex: 00002000 = 8192, 00004000 = 16384, 00008000 = 32768.

Confirm on hardware

The size report proves the cost. Only a running device proves the value is sufficient. Add this temporarily and read the log after boot:

esphome:
  on_boot:
    priority: -100.0
    then:
      - lambda: 'ESP_LOGW("mem", "loopTask HWM=%u B", uxTaskGetStackHighWaterMark(nullptr));'

HWM is the smallest amount of stack that was still free — the remaining margin, in bytes. Below about 2,000, go up one step in the table.

Note that loopTask also runs the main loop forever, not just setup(). Rare paths such as an OTA update, an API reconnection or verbose logging can push deeper than boot does, so keep margin rather than tuning to the exact boot figure.

Calibrating for a different node type

If your node is not a standard YamBMS RS485 BMS (bms_combine_modbus_client.yaml) setup, measure your own frame size instead of using the table. Add this and compile twice with a different number of BMS:

esphome:
  build_flags:
    - "-Wframe-larger-than=4096"

The compiler prints the frame size directly:

warning: the frame size of 7184 bytes is larger than 4096 bytes

Two data points give you the fixed cost and the cost per BMS. Add about 4 KB of reserve and round up to the next step.