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

8.8 KiB
Raw Blame History

YamBMS - PSRAM options

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

Reference for board_options_PSRAM_options.yaml, the shared sdkconfig_options included by every board_options_PSRAM_*.yaml board file.

Which boards have PSRAM

PSRAM is a property of the board or module, not of the chip family. Two boards built on the same chip may or may not have it.

Chip PSRAM Modes Notes
ESP32 On some modules (WROVER and similar; WROOM has none) Quad only 8 MB chips expose only 4 MB through the cache window at a time
ESP32-S2 On some modules Quad only
ESP32-S3 On some modules (N8R2, N16R8 …) Quad or octal The R suffix in the module reference indicates PSRAM
ESP32-C3 / C6 / H2 None — These options are inert

Check your module before choosing a mode. Declaring octal on a board with quad PSRAM — or on a chip that has no octal support at all — makes PSRAM initialisation fail. It does not produce a clear error message; it shows up later as random cache errors and unstable behaviour. The ESP-IDF boot log reports what was actually detected.

On the original ESP32, 80 MHz PSRAM has additional constraints tied to the flash clock, and early chip revisions require a cache workaround that ESP-IDF enables automatically. If a board misbehaves at 80 MHz, 40 MHz is the safe fallback.

A board file declares the mode and includes this shared options file:

psram:
  mode: octal
  speed: 80MHz

packages:
  psram_options: !include board_options_PSRAM_options.yaml

If a board has no PSRAM, every option below is silently ignored. They are harmless, but they do nothing.

Why these options exist

An ESP32 with PSRAM has two separate pools of RAM:

Pool Size Speed Used for
Internal RAM A few hundred KB, fixed by the chip Fast Everything by default; the only pool usable for DMA
PSRAM 2–16 MB depending on the module Slower Optional overflow, must be explicitly enabled

Internal RAM is the scarce resource. A YamBMS master with 16 BMS creates roughly 1,400 entity objects on top of WiFi, the native API and several peripherals, and internal RAM runs out long before PSRAM does.

Every option below does one thing: move something out of internal RAM and into PSRAM.

Reference build. The figures quoted in this document come from a 16-BMS master: ESP32-S3, octal PSRAM at 80 MHz, ESPHome 2026.7.3, ESP-IDF 5.5.5.

DIRAM   202,299 / 341,760   (59.2 %)   ->   139,461 B free for the heap

They are orders of magnitude, not universal constants. The original ESP32 in particular splits its internal RAM into separate instruction and data regions instead of the unified DIRAM pool the S3 uses, so its size report looks different. Compare against your own baseline rather than against these numbers.

The options

Moving the network stack to PSRAM

CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY: y
CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP: y

These two must be kept together. The first turns EXT_RAM_BSS_ATTR in ESP-IDF's esp_attr.h into a real section directive — without it the macro expands to nothing. The second makes the network stack actually use it. Removing either one cancels the benefit of both.

Measured gain on the reference build: 12,308 bytes of internal RAM. The symbols moved are the socket table, dns_table, dns_requests, the tcpip_* and sntp_* globals, and select_cb_list. Without these options internal .bss would be 133,612 instead of 121,304, pushing DIRAM usage from 59.2 % to 62.8 %.

Why this is safe. Data in PSRAM is unreachable while the flash cache is disabled, which is why PSRAM placement is normally risky. That only affects interrupt handlers flagged to run from IRAM. LWIP has none — these globals are touched exclusively from the tcpip task, in task context, where the cache is always available.

Cost: marginally slower socket and DNS access. Irrelevant at ESPHome traffic levels.

Reading the size report: this segment is reported by esp_idf_size under Flash Data / .bss, not under internal RAM. That is a tooling artefact — flash .rodata and PSRAM share the same address window. The data really is in PSRAM.

Internal RAM reservation

CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL: "65536"

Bytes kept exclusively for allocations that cannot live in PSRAM — DMA buffers and internal-only requests. Once free internal RAM drops to this level, generic allocations fall back to PSRAM instead of starving the reserve.

ESP-IDF's default is 32,768. It is raised here because a YamBMS master runs WiFi, the native API and several UART / SPI / CAN peripherals concurrently, all of which need DMA-capable memory.

On a chip with less internal RAM than an S3, 65,536 is a large share of the total. If free heap gets tight, this is one of the first values to reconsider.

Allocation size threshold

CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL: "4096"

Allocations up to this size go to internal RAM first; larger ones go straight to PSRAM. ESP-IDF's default is 16,384.

Tuning note. Entity objects are typically 100–400 bytes, so at 4096 they all still land in internal RAM. On a node short on internal memory, lowering this to "512" pushes them into PSRAM and gives internal RAM back, at the cost of slower access to every entity. Measure the free heap before and after — this is a trade-off, not a free win.

DMA buffers request MALLOC_CAP_DMA explicitly and stay internal regardless of this value.

Bluetooth (BLE BMS only)

CONFIG_BT_ALLOCATION_FROM_SPIRAM_FIRST: y
CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY: y

These two must also be kept together, for the same reason as the pair above. BT_BLE_DYNAMIC_ENV_MEMORY moves the Bluedroid host environment from static .bss to dynamic allocation; BT_ALLOCATION_FROM_SPIRAM_FIRST sends those allocations to PSRAM first. Alone, the first only shifts the cost from .bss to the internal heap, and the second has nothing to redirect.

Inert on RS485 / CAN-only builds. Both are children of CONFIG_BT_ENABLED in ESP-IDF's Kconfig tree, so they are dropped entirely when the Bluetooth component is not compiled. Verified on a 16-BMS RS485 build: zero CONFIG_BT_ lines in the generated sdkconfig, zero Bluedroid symbols in the ELF, zero bytes consumed.

Caveat. BT_BLE_DYNAMIC_ENV_MEMORY has a history of reliability reports upstream. If BLE users hit crashes, remove this one first when bisecting; BT_ALLOCATION_FROM_SPIRAM_FIRST alone is far less controversial.

Note for BLE nodes. The BLE controller needs internal RAM that PSRAM cannot replace — buffers accessed during radio windows. A BLE node therefore has less free internal RAM than the reference figures above.

Verifying what actually applied

The generated sdkconfig is the only source of truth. ESPHome manages some symbols itself, and those cannot be overridden from sdkconfig_options.

grep -E "SPIRAM|COMPILER_OPTIMIZATION" .esphome/build/<node>/sdkconfig.<node>

To confirm that data really landed in PSRAM, look for the external RAM section in the linker map. This works on any chip:

grep -n '\.ext_ram\.bss' .esphome/build/<node>/build/<node>.map | head

If you prefer to inspect symbols directly, the address tells you where a symbol lives — but the windows are chip-specific:

Chip Internal RAM PSRAM
ESP32 0x3FF… 0x3F8… – 0x3FB…
ESP32-S3 0x3FC… 0x3C… – 0x3D…
NM=$(find ~/.cache/esphome/idf/tools -name '*-elf-nm' | head -1)
$NM -nSC .esphome/build/<node>/build/<node>.elf | awk 'tolower($3)=="b"'

The compile size report is the quickest regression check. On the reference build, internal RAM usage was 202,299 bytes (59.19 %). Any unexpected change after editing these options means something behaved differently than documented here — investigate before shipping.

Note on loop_task_stack_size

This option is not part of this file, and is documented separately.

It is unrelated to PSRAM: it sizes the stack of the FreeRTOS task that runs setup() and the main loop, and the required value depends on entity count, not on available memory. It applies on every ESP32, with or without PSRAM, and raising it consumes internal RAM that a board without PSRAM cannot recover elsewhere.