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

|
||

|
||

|
||
|
||
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:
|
||
|
||
```yaml
|
||
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
|
||
|
||
```yaml
|
||
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
|
||
|
||
```yaml
|
||
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
|
||
|
||
```yaml
|
||
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)
|
||
|
||
```yaml
|
||
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`.
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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…` |
|
||
|
||
```bash
|
||
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.
|