175 lines
6.9 KiB
Markdown
175 lines
6.9 KiB
Markdown
# YamBMS - loop_task_stack_size
|
|
|
|
[](https://www.gnu.org/licenses/gpl-3.0)
|
|
[](https://github.com/Sleeper85/esphome-yambms/releases/latest)
|
|

|
|

|
|

|
|
|
|
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.
|
|
|
|
## Recommended values
|
|
|
|
| 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.
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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.
|