twislaandClaude Sonnet 5.5
3b4100dc6a
/dev/ has Debug Builds and the Debug Console (builds and the token, the console and its protocol, files and screenshots, driving the UI, crashes and Safe Mode, the command reference), Build, test and release (including how an update works), the architecture decisions and the milestone plans. Generated from the repository by site/tools/gen_dev_docs.py: the ADRs, the milestones, the README's sections, and the command reference, read from the firmware's own `help` text. The pages are committed (Zola cannot read outside its folder); the Site workflow checks they are current, and now also runs when src/main.cpp changes. M0, M1 and CONTEXT.md are not published. README: the gnss commands that the table lacked. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT
2.7 KiB
+++ title = "The framework is rebuilt with our own SDK settings, for smaller TLS buffers" description = "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…" weight = 6
[extra]
docs = true
source = "docs/adr/0006-framework-rebuilt-for-smaller-tls-buffers.md"
tag = "ADR 0006"
+++
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.