Memory Budgeting
Make memory a measured budget, not a nominal board label. The implementation is
embedded C/C++; scripts may parse build or runtime logs when that is the useful
deterministic tool.
Intake
Record exact board/module, flash/RAM/EEPROM/PSRAM, bootloader and partition
layout, framework, compiler flags, libraries, static buffers, task stacks,
filesystem/OTA needs, peak protocol sizes, and available measurement output.
Process
- Separate static data, code/flash, heap, task stacks, interrupt state,
filesystem, bootloader, and OTA/update slots.
- Establish a numeric budget and minimum margin for every category. Use board
references rather than copying a family-level number into a project claim.
- Capture compiler size output and map changes to a feature or dependency.
- Measure runtime free heap, largest block, stack high-water marks, and reset/
allocation failures under representative load where the framework exposes
them.
- On AVR, keep literals in flash with
F() where appropriate, prefer bounded buffers and fixed-size storage, and avoid unbounded dynamic String use. On ESP32/RP2040,
still bound buffers and distinguish heap, stack, flash, and filesystem.
- Re-run the stress case after each memory-affecting change and record the
tradeoff.
Anti-rationalization
| Shortcut |
Response |
| "The datasheet says 520 KB, so memory is fine." |
Separate usable heap, stacks, reserved regions, and radio/RTOS use. |
| "It compiled." |
Inspect size output and exercise runtime allocation paths. |
| "Make the buffer bigger." |
Bound the protocol and prove the required maximum. |
| "Use String everywhere." |
Check fragmentation and lifetime; use bounded alternatives where needed. |
| "OTA only needs the application image." |
Budget both update slots, bootloader, metadata, and rollback image. |
Verification
- Build-size output and runtime memory evidence name the exact target/version.
- Each budget has a margin and a failure response.
- Stress tests cover peak message, sensor, logging, radio, and task load as
applicable.
- Optimization does not remove bounds, safety checks, or recovery behavior.
Shared output contract
Use the shared Arduino skill contract:
state assumptions, required tools and versions, implementation steps,
tests/evidence by proof stage, known limitations, and recovery/security notes.
1---2name: memory-budgeting3description: Use when Arduino or embedded projects hit SRAM, flash, heap, stack, partition, JSON-buffer, or performance limits, or when reviewing String use, F() placement, OTA slots, FreeRTOS stacks, or memory margin.4---5
6# Memory Budgeting
7
8Make memory a measured budget, not a nominal board label. The implementation is
9embedded C/C++; scripts may parse build or runtime logs when that is the useful
10deterministic tool.
11
12## Intake
13
14Record exact board/module, flash/RAM/EEPROM/PSRAM, bootloader and partition
15layout, framework, compiler flags, libraries, static buffers, task stacks,
16filesystem/OTA needs, peak protocol sizes, and available measurement output.
17
18## Process
19
201. Separate static data, code/flash, heap, task stacks, interrupt state,
21 filesystem, bootloader, and OTA/update slots.
222. Establish a numeric budget and minimum margin for every category. Use board
23 references rather than copying a family-level number into a project claim.
243. Capture compiler size output and map changes to a feature or dependency.
254. Measure runtime free heap, largest block, stack high-water marks, and reset/
26 allocation failures under representative load where the framework exposes
27 them.
285. On AVR, keep literals in flash with `F()` where appropriate, prefer bounded buffers and fixed-size storage, and avoid unbounded dynamic `String` use. On ESP32/RP2040,
29 still bound buffers and distinguish heap, stack, flash, and filesystem.
306. Re-run the stress case after each memory-affecting change and record the
31 tradeoff.
32
33## Anti-rationalization
34
35| Shortcut | Response |
36|---|---|
37| "The datasheet says 520 KB, so memory is fine." | Separate usable heap, stacks, reserved regions, and radio/RTOS use. |
38| "It compiled." | Inspect size output and exercise runtime allocation paths. |
39| "Make the buffer bigger." | Bound the protocol and prove the required maximum. |
40| "Use String everywhere." | Check fragmentation and lifetime; use bounded alternatives where needed. |
41| "OTA only needs the application image." | Budget both update slots, bootloader, metadata, and rollback image. |
42
43## Verification
44
45- Build-size output and runtime memory evidence name the exact target/version.
46- Each budget has a margin and a failure response.
47- Stress tests cover peak message, sensor, logging, radio, and task load as
48 applicable.
49- Optimization does not remove bounds, safety checks, or recovery behavior.
50
51## Shared output contract
52
53Use [the shared Arduino skill contract](../../docs/arduino-skill-contract.md):
54state assumptions, required tools and versions, implementation steps,
55tests/evidence by proof stage, known limitations, and recovery/security notes.
wedsamuel1230