Skip to content

Firmware Builder

The Firmware Builder component provides 3 tools for converting ELF files to flashable or RAM-loadable binaries and for analyzing firmware image structure. These tools wrap esptool elf2image and esptool image-info as async subprocesses.

esp_elf_to_binary

Convert an ELF file to a flashable binary image using esptool elf2image. The resulting .bin file can be written to flash with esp_flash_firmware or esp_flash_multi.

Parameters

Name	Type	Default	Description
`elf_path`	`str`	(required)	Path to the input ELF file.
`output_path`	`str \| None`	`None`	Output binary path. Defaults to `<elf_name>.bin` in the same directory.

Example

result = await client.call_tool("esp_elf_to_binary", {
    "elf_path": "/build/app.elf",
    "output_path": "/build/app.bin"
})

Return Value

{
  "success": true,
  "elf_path": "/build/app.elf",
  "output_path": "/build/app.bin",
  "output_size_bytes": 524288,
  "esptool_output": "esptool.py v4.8\nCreating esp32 image...\nMerge segment 0x3f400020...\n..."
}

esp_elf_to_ram_binary

Convert an ELF file to a RAM-loadable binary using esptool elf2image --ram-only-header. The resulting binary contains only IRAM/DRAM segments and can be loaded directly into device RAM with esp_load_ram.

This is the first half of the rapid development workflow:

Build your project with ESP-IDF
Convert ELF to RAM binary with this tool
Load to device with esp_load_ram

Parameters

Name	Type	Default	Description
`elf_path`	`str`	(required)	Path to the input ELF file.
`output_path`	`str \| None`	`None`	Output binary path. Defaults to `<elf_name>-ram.bin`.
`chip`	`str`	`"auto"`	Target chip type (`auto`, `esp32`, `esp32s3`, `esp32c3`, etc.).

Example

result = await client.call_tool("esp_elf_to_ram_binary", {
    "elf_path": "/build/app.elf",
    "chip": "esp32s3"
})

Return Value

{
  "success": true,
  "elf_path": "/build/app.elf",
  "output_path": "/build/app-ram.bin",
  "chip": "esp32s3",
  "ram_optimized": true,
  "output_size_bytes": 131072,
  "usage_hint": "Load to device with: esp_load_ram(binary_path='/build/app-ram.bin', port='<your-port>')"
}

esp_firmware_analyze

Analyze a firmware binary’s structure using esptool image-info --version 2. Returns parsed metadata including chip target, flash configuration, entry point, and segment layout.

Parameters

Name	Type	Default	Description
`firmware_path`	`str`	(required)	Path to the firmware binary (`.bin`) file.

Example

result = await client.call_tool("esp_firmware_analyze", {
    "firmware_path": "/build/app.bin"
})

Return Value

{
  "success": true,
  "firmware_path": "/build/app.bin",
  "file_size_bytes": 524288,
  "entry_point": "0x40081d5c",
  "chip": "ESP32",
  "flash_mode": "DIO",
  "flash_size": "4MB",
  "flash_freq": "40m",
  "segments": [
    {"index": 0, "length": "0x07a54", "load_address": "0x3f400020"},
    {"index": 1, "length": "0x03bb0", "load_address": "0x3ffb0000"},
    {"index": 2, "length": "0x5c1e4", "load_address": "0x40080000"}
  ],
  "segment_count": 3,
  "validation_hash": "valid",
  "raw_output": "esptool.py v4.8\nImage version: 1\nEntry point: 0x40081d5c\n..."
}

Parsed Fields

Field	Description
`entry_point`	Address where execution begins after load.
`chip`	Target chip the image was built for.
`flash_mode`	SPI flash mode (`QIO`, `QOUT`, `DIO`, `DOUT`).
`flash_size`	Expected flash size encoded in the header.
`flash_freq`	SPI flash frequency (`40m`, `80m`, etc.).
`segments`	List of binary segments with load addresses and lengths.
`validation_hash`	Image hash validation result, if present.