Files
roro9stack/docs/adr/0006-framework-rebuilt-for-smaller-tls-buffers.md
twislaandClaude Opus 5.5 fff28af961 Rebuild the framework with smaller TLS buffers (ADR 0006)
custom_sdkconfig makes pioarduino regenerate the ESP-IDF libraries:
asymmetric TLS buffers (16 KB in, 4 KB out) and dynamic buffers that
free handshake-only data once connected. The rebuild also follows the
board: no PSRAM, 8 MB flash. The project now carries the partition
table the hybrid build needs (identical to the framework's: the app
slots must not move under updates over the air). Generated files are
ignored.

Debug Build, GNSS on, IRC on TLS: 78 KB free and a 59 KB low (M2 began
at 31 KB and 12.6 KB; the floor is 40 KB). The full stress set passes
on it: refused installs over Wi-Fi and from SD, put/get, screenshot,
core dump decode, Probation; under all of it at once, the low is 46 KB.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT
2026-10-04 23:32:29 +02:00

2.3 KiB

The framework is rebuilt with our own SDK settings, for smaller TLS buffers

Arduino-ESP32 ships its ESP-IDF libraries prebuilt, with one sdkconfig for every ESP32-S3 board. Its TLS settings give every connection a 16 KB receive buffer and a 16 KB send buffer for its whole life. On a device with no PSRAM and about 340 KB of RAM, an IRC connection over TLS left a 12.6 KB low in M2, against a 40 KB floor.

Those settings are compiled into the libraries, so changing them means rebuilding them. pioarduino supports this as a "hybrid compile": custom_sdkconfig in platformio.ini lists the settings, and the build regenerates the framework's libraries from ESP-IDF (the same 5.5.5 the prebuilt ones come from) before building the app. We set:

  • MBEDTLS_ASYMMETRIC_CONTENT_LEN, with 16 KB to receive (servers send full TLS records) and 4 KB to send (IRC lines are short): 12 KB less per connection.
  • MBEDTLS_DYNAMIC_BUFFER, DYNAMIC_FREE_CONFIG_DATA, DYNAMIC_FREE_CA_CERT: buffers allocated when needed, and handshake-only data (the CA chain) freed once connected.

The rebuild also follows the board definition instead of the generic one: PSRAM support is off (the Cardputer ADV has none) and the flash size is 8 MB.

Consequences

  • With IRC connected over TLS, a Debug Build has 78 KB free and a 59 KB low (it was 31 KB and 12.6 KB), and 46 KB at the lowest under the heaviest combined load measured (IRC, two refused installs, a 1.6 MB put and get).
  • The first build after a fresh checkout, or after changing custom_sdkconfig, takes about 4 minutes instead of 45 s: it downloads ESP-IDF into the PlatformIO volume and compiles it. Later builds reuse it.
  • Everything the firmware depends on was checked in the regenerated sdkconfig: app rollback, core dumps to flash (ELF), the 5 s task watchdog, FreeRTOS run-time stats, the certificate bundle.
  • The project now owns its partition table (default_8MB.csv, identical to the framework's), which the hybrid build requires. Changing it would break updates over the air: the app slots must stay where they are.
  • Generated files (sdkconfig.*, managed_components/, .dummy/) are ignored by git.
  • A TLS server that sends records over 16 KB would still fail, as before; one that needs us to send records over 4 KB would now fail. Neither happens with IRC.