Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Post-build Analysis

Three tools run after a successful build to tell you how big the firmware is, what libraries went into it, and whether anything looks wrong.

ToolWhat it does
size.runFlash and RAM usage — by section, component, or file.
sbom.createGenerate an SPDX software bill of materials.
diag.runRun idf.py diag to collect diagnostic info.

All three require a task_id from a completed build.

size.run

Runs size analysis on a completed build. Parses the output of idf.py size and returns a structured report.

Input:

{
  "task_id": "0abf...e2",
  "detail": "summary"
}
FieldRequiredNotes
task_idYesA completed build’s task ID.
detailNo"summary" (default), "components", or "files".

Returns:

{
  "task_id": "0abf...e2",
  "detail": "summary",
  "size_report": {
    "flash_used": 200000,
    "flash_remaining": 3800000,
    "ram_used": 42000,
    "ram_remaining": 285680
  }
}

At "components" detail, the report breaks down usage by ESP-IDF component. At "files", it goes down to individual object files.

CLI: espctl size

Reads the size report that idf.py size (or a remote build) wrote to build/<target>/size_output.txt and prints a flash/RAM breakdown. Does not itself rerun idf.py size — run a build first.

espctl size [--target <chip>]

Inputs

FlagDefaultNotes
--targetdefault_target from .espctl.tomlChip — esp32, esp32s3, etc. Reads build/<target>/size_output.txt.

Output

Human mode:

Memory Usage:
  Flash: 200000 / 4194304 bytes (4.8%)
  RAM:    50000 / 327680 bytes (15.3%)

Sections:
  DRAM     50000 / 327680 bytes (15.3%)

JSON (--json): a SizeReport object with flash_used, flash_total, ram_used, ram_total, and a sections array.

Failure modes

ConditionExitMessage
size_output.txt missing1No size data found. Run 'idf.py size' first, or build with size analysis.
target invalid2invalid target: <name>
parse failure1could not parse size output

Examples

# Use the default target from .espctl.toml
espctl size

# Explicit target
espctl size --target esp32s3

# JSON for piping into a comparator script
espctl --json size --target esp32s3 | jq '.flash_used'
  • size.run — the MCP equivalent, accepts a task_id and a richer "components" / "files" detail level.
  • parse_size_report — turns raw idf.py size log output into the same structured shape.

sbom.create

Generates an SPDX software bill of materials for a completed build. Lists every library and component that went into the firmware.

Input:

{
  "task_id": "0abf...e2",
  "scan_vulnerabilities": true
}
FieldRequiredNotes
task_idYesA completed build’s task ID.
scan_vulnerabilitiesNoRun a vulnerability scan after generating the SBOM. Default false.

Returns: The task ID and a recipe_id ("idf_sbom") that tells the build agent to execute the SBOM generation.

Use this when you need to:

  • Audit what’s in your firmware before shipping.
  • Check for known vulnerabilities in third-party components.
  • Meet compliance requirements that mandate an SBOM.

Privacy note: When scan_vulnerabilities is true, the build machine queries external vulnerability databases (CVE/OSV) over the network. Your dependency list is sent to these services. If this is a concern, leave scan_vulnerabilities off and scan the SBOM file yourself with a local tool.

diag.run

Runs idf.py diag on a completed build to collect diagnostic information. Useful when a build succeeded but the firmware behaves unexpectedly.

Input:

{ "task_id": "0abf...e2" }
FieldRequiredNotes
task_idYesA completed build’s task ID.

Returns: The task ID and a recipe_id ("idf_diag") that tells the build agent to run diagnostics.

See also