Skip to content
ThingFace

ESP32 without PSRAM on Arduino: dynamic TLS buffers

On the classic ESP32 without PSRAM, with the Arduino core 3.3 as it ships, the SDK online leaves little RAM for a second TLS: an app that, besides the cloud, calls an HTTPS API (payments, telemetry) tends to fail in the handshake with (-32512) SSL - Memory allocation failed. The cause is the core's precompiled mbedTLS: it ships with DTLS on, which rules out dynamic buffers, and each TLS connection holds two fixed buffers of ~16.7 KB (input and output) from the first byte to the last, even when idle. This page is the recommended recipe for that case: rebuild the core's mbedTLS with dynamic buffers through pioarduino's custom_sdkconfig. It was tested on an ESP32 without PSRAM with the core 3.3.12.

The ESP-IDF does not need this: the SDK's examples already turn dynamic buffers on (Limits). Boards with PSRAM (WROVER, an S3 with PSRAM) usually do not need it either.

What changes

Measured on 11/11/2026, ESP32 without PSRAM at 240 MHz, core 3.3.12 (pioarduino 55.03.312-1, ESP-IDF 5.5.5), the SDK online with 0 tabs, Wi-Fi and a WebServer on port 80. "Free 8-bit" is heap_caps_get_free_size(MALLOC_CAP_8BIT), the RAM TLS can use (see How to check). The second TLS is a NetworkClientSecure with HTTPClient to a public API with an RSA-2048 chain (TLS 1.2, ECDHE-RSA-AES128-GCM).

Core as it shipsDynamic buffers
The SDK's TLS session, idle40,788 B4,156 B
What the SDK online takes from the 8-bit RAM~82 KB~45 KB
Free 8-bit with the SDK online (minimal sketch)93,464 B132,064 B
Drop of the 8-bit RAM in the second TLS's handshake53.8 KB, with 2 contiguous blocks of 16,717 B23.1 KB; the largest block asked is 5,108 B
App with a display (~114 KB of static RAM): free 8-bit with the SDK online30,496 B (largest block 28,660 B): the second TLS fails69,064 B (largest block 61,428 B): the second TLS works, with 47,212 B at the lowest point
The same app, with one HTTPS session kept open and another opening, and the SDK onlinedoes not fitworks, with 36,348 B at the lowest point

On top of that, the firmware gets ~27 KB smaller in flash (no DTLS), and the static RAM drops ~1.4 KB.

The recipe

1. A PlatformIO folder for this project only

custom_sdkconfig rebuilds the core's libraries and swaps them inside the PlatformIO folder: any other project using the same folder then builds with them (or pioarduino rebuilds them back at each change of project). Use a folder of this project only, through PLATFORMIO_CORE_DIR, whenever you run pio:

# PowerShell (pioarduino refuses Git Bash)
$env:PLATFORMIO_CORE_DIR = "$HOME\pio-my-project"

Install pioarduino's PlatformIO in it at exactly 6.2.0, in a Python environment inside the folder:

python -m venv $HOME\pio-my-project\penv
$HOME\pio-my-project\penv\Scripts\pip download pioarduino==6.2.0 --no-deps -d dl
# the SHA-256 of dl\pioarduino-6.2.0-py3-none-any.whl must be
#   12e251cd3ee51e114ab3f12af74196358263a3983253d172b620d13ff9d9804f
$HOME\pio-my-project\penv\Scripts\pip install dl\pioarduino-6.2.0-py3-none-any.whl
# to pin the dependencies too: pip install --no-deps -r penv.txt <the .whl>, with the penv.txt of
# arduino/platformio/ in the SDK's repository
$HOME\pio-my-project\penv\Scripts\python -m platformio --version   # PlatformIO Core, version 6.2.0

Always run pio through that Python ($HOME\pio-my-project\penv\Scripts\python -m platformio run). Left on its own, pioarduino installs 6.2.0.post1, and the rebuild stops halfway with IncompatiblePlatform: ... depends on PlatformIO Core >=6.2.0 (and removes the platform from the folder).

2. The platformio.ini

[env:esp32]
; the core 3.3.12 (ESP-IDF 5.5.5), a fixed version
platform = https://github.com/pioarduino/platform-espressif32/releases/download/55.03.312-1/platform-espressif32.zip
board = esp32dev
framework = arduino
; the SDK's table (the board's key in the devui partition): extras/partitions.csv of the library
board_build.partitions = <ThingFace library folder>/extras/partitions.csv

; the core's mbedTLS rebuilt: no DTLS (which rules out dynamic buffers), dynamic buffers, the configuration data and the
; roots freed after the handshake, and the output at 4 KB. One option per line, always with =y or =n: a line starting
; with # becomes an .ini comment and disappears without a warning.
custom_sdkconfig =
	CONFIG_MBEDTLS_SSL_PROTO_DTLS=n
	CONFIG_MBEDTLS_DYNAMIC_BUFFER=y
	CONFIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA=y
	CONFIG_MBEDTLS_DYNAMIC_FREE_CA_CERT=y
	CONFIG_MBEDTLS_ASYMMETRIC_CONTENT_LEN=y
	CONFIG_MBEDTLS_SSL_IN_CONTENT_LEN=16384
	CONFIG_MBEDTLS_SSL_OUT_CONTENT_LEN=4096

; REQUIRED: dynamic buffers only work with these 12 --wrap in the link. The ESP-IDF adds them by itself; pioarduino
; does not carry them to the Arduino link, and without them nothing changes and nothing warns.
build_flags =
	-Wl,--wrap=mbedtls_ssl_write_client_hello
	-Wl,--wrap=mbedtls_ssl_handshake_client_step
	-Wl,--wrap=mbedtls_ssl_tls13_handshake_client_step
	-Wl,--wrap=mbedtls_ssl_handshake_server_step
	-Wl,--wrap=mbedtls_ssl_tls13_handshake_server_step
	-Wl,--wrap=mbedtls_ssl_read
	-Wl,--wrap=mbedtls_ssl_write
	-Wl,--wrap=mbedtls_ssl_session_reset
	-Wl,--wrap=mbedtls_ssl_free
	-Wl,--wrap=mbedtls_ssl_setup
	-Wl,--wrap=mbedtls_ssl_send_alert_message
	-Wl,--wrap=mbedtls_ssl_close_notify

The ThingFace library comes in as you already use it (lib_deps or lib_extra_dirs). The project's other build_flags go in the same list, below the --wrap. The 16 KB input stays on purpose: a server that does not accept smaller fragments (most APIs) sends records of up to 16 KB, and with dynamic buffers that buffer only exists while a record arrives.

With the remote firmware update: the recipe keeps the core's curve P-384 and complete bundle of CAs, which the firmware's download needs (the storage's roots are P-384). Do not add CONFIG_MBEDTLS_ECP_DP_SECP384R1_ENABLED=n nor CONFIG_MBEDTLS_CERTIFICATE_BUNDLE=n: without them DevUIOta.begin refuses. The dynamic buffers serve the second TLS session too, the download's.

3. The first build

The first build downloads the ESP-IDF and rebuilds the core's libraries: 6 to 12 minutes on a 16-core PC (measured with 6 parallel jobs: 11 min with the downloads, 5.6 min for a rebuild), and a few GB in the folder of step 1. It says *** Compile Arduino IDF libs for esp32 *** at the start and *** Copied compiled esp32 IDF libraries to Arduino framework *** at the end. The next builds take the usual time while custom_sdkconfig does not change; changing a line of it rebuilds everything again. Every environment of the project should have the same custom_sdkconfig (a common section with extends), or pioarduino rebuilds at each switch.

How to check

1. The --wrap made it into the firmware. Without them the build passes, the board works, and the RAM stays as with the core as it ships. Check the ELF:

<folder of step 1>\packages\toolchain-xtensa-esp-elf\bin\xtensa-esp32-elf-nm .pio\build\esp32\firmware.elf | findstr __wrap_mbedtls_ssl_setup

A line T __wrap_mbedtls_ssl_setup says they are there.

2. Measure the 8-bit RAM, not ESP.getFreeHeap(). On the ESP32, getFreeHeap() and getMaxAllocHeap() also count the free IRAM (~39 KB on the core 3.3.12, ~54 KB with the rebuilt libraries), which only takes 32-bit accesses and which TLS does not use. The largest block getMaxAllocHeap() shows may be the IRAM's: with the 8-bit RAM almost gone, it keeps showing ~36 KB. Measure like this:

#include "esp_heap_caps.h"

Serial.printf("free 8-bit %u, largest block %u, minimum %u\n",
              (unsigned)heap_caps_get_free_size(MALLOC_CAP_8BIT),
              (unsigned)heap_caps_get_largest_free_block(MALLOC_CAP_8BIT),
              (unsigned)heap_caps_get_minimum_free_size(MALLOC_CAP_8BIT));

3. The SDK online costs ~45 KB, not ~82 KB. Measure the line above right before DevUI.begin() and some 10 s after DEVUI_EV_ONLINE: the difference is what the SDK took from the 8-bit RAM. Close to 82 KB, dynamic buffers are not in effect (go back to item 1).

4. The idle TLS session close to 4 KB. To see the mbedTLS alone, count its allocations: this C file (in C, because the core's esp_mem.h does not declare extern "C") adds up what the mbedTLS holds. Call tls_conta_instalar() on the first line of setup() and read tls_vivo with the SDK online: ~4.2 KB with dynamic buffers, ~40.8 KB without them.

/* tls_conta.c */
#include "esp_heap_caps.h"
#include "freertos/FreeRTOS.h"
#include "mbedtls/platform.h"
#include "esp_mem.h"

volatile int tls_vivo;
static portMUX_TYPE trava = portMUX_INITIALIZER_UNLOCKED;

static void *conta_calloc(size_t n, size_t t)
{
    void *p = esp_mbedtls_mem_calloc(n, t);
    if (p) {
        portENTER_CRITICAL_SAFE(&trava);
        tls_vivo += heap_caps_get_allocated_size(p);
        portEXIT_CRITICAL_SAFE(&trava);
    }
    return p;
}

static void conta_free(void *p)
{
    if (p) {
        portENTER_CRITICAL_SAFE(&trava);
        tls_vivo -= heap_caps_get_allocated_size(p);
        portEXIT_CRITICAL_SAFE(&trava);
    }
    esp_mbedtls_mem_free(p);
}

void tls_conta_instalar(void)
{
    mbedtls_platform_set_calloc_free(conta_calloc, conta_free);
}

In the sketch: extern "C" { extern volatile int tls_vivo; void tls_conta_instalar(void); }.

If the core cannot be rebuilt: pause the SDK

Without custom_sdkconfig, the other way out is to stop the SDK while the app uses its own TLS: DevUI.stop(), wait for DevUI.status() == DEVUI_STATUS_STOPPED, make the request and DevUI.begin(cfg) again. STOPPED only shows once the SDK's TLS session is back in the heap (0.2 to 0.35 s after the stop, measured; if the client gets stuck closing, it goes out anyway 20 s later, with a warning in the log); in the same app with a display of the table above, the request works with ~34 KB of 8-bit RAM at the lowest point. The cost: the board is offline in the cloud during the pause, and coming back takes 4.5 to 7.7 s (a new handshake and HELLO). The database's queue in the flash stays; call DevUI.dbQueue(...) again after begin (Database).