Microduck Robot●microduck-robot.com

ESP32 BIN Files: App-Only, Merged Images and Preflight

Identify the build artifact before loading it. An app-only file cannot prove its partition layout, and a structurally valid image may still be unsupported by the classic ESP32 emulator. A failed candidate preflight leaves the current firmware running.

Commands: esptool 4.8.1 and 5.1.0. Site baseline: Arduino-ESP32 3.3.8 / ESP-IDF 5.5.4. Sources checked 2026-11-15.

Choose the artifact, not just the extension

A compiler may produce an application, bootloader and partition-table binary as separate files. They are not interchangeable merely because each ends in .bin. Keep the build target, configuration and file list together.

A recognized merged image contains multiple build artifacts in their declared positions. Renaming a file or concatenating binaries does not establish that layout. Use the table to decide what evidence the selected file can supply.

Scroll sideways to compare all columns.

ArtifactEvidence availableWhat it cannot establish
Application onlyApplication header, segments and available integrity fieldsThe separate partition layout
Recognized merged imageRecognizable boot, table and application artifactsUniversal partition support or hardware validity
Unknown or truncated fileOnly the bytes that can actually be parsedA valid image based on its .bin name

Inspect a local file with the matching esptool

The following example inspects an individual firmware.bin in an environment fixed to esptool 4.8.1. The command reads the local file and does not open a serial connection. Check the installed package version before copying its flags.

Local inspection · esptool 4.8.1
# esptool 4.8.1 environment
python -m pip show esptool
python -m esptool image_info --version 2 "firmware.bin"

In an esptool 5.1.0 environment, use image-info instead of image_info and omit the old --version option. Keep the original components and manifest when investigating a merged image; image-info is not a complete partition validator.

Local inspection · esptool 5.1.0
# esptool 5.1.0 environment
python -m pip show esptool
python -m esptool image-info "firmware.bin"

Read structure and simulator support separately

Image structure includes header and segment consistency, the segment XOR checksum and an appended SHA-256 when present. A missing digest does not automatically mean corruption; a valid digest is not proof of authorship or correct hardware behavior.

Execution is a separate decision. This runtime requires a supported classic ESP32 profile with known DIO/4 MiB flash metadata and an executable layout. Recognizing an S3/C3 header does not mean those chips can be simulated. Read both report sections.

Scroll sideways to compare all columns.

Observed resultInterpretationNext check
Bad structure/checksumThe candidate is not structurally acceptedRe-copy or rebuild; keep the current run
Valid structure; S3/C3Inspection is not classic execution supportUse the correct target/environment
App-only; partitions unknownNo partition proof is present in this artifactKeep unknown; locate the build manifest
Merged; layout unsupportedRecognized data exceeds this runtime’s supported layoutInspect the specific layout finding

Keep unknown partition information unknown

An app-only file does not contain the separate partition-table artifact. The emulator can supply its own default classic boot/partition profile when applicable; that assumption is not recovered from the user file and does not verify a custom layout.

Only a recognized merged image permits the implemented partition checks. Bounds, overlap, format or table-integrity failures need investigation. A supported subset passing does not certify every possible ESP-IDF layout or the assembled device.

Merge only from the matching build manifest

This merge example is only for the matching classic ESP32 ESP-IDF build directory that actually contains flash_args. The response file supplies that build’s file/offset pairs. It writes a local output file, not a device. Do not replace it with offsets copied from another board.

Offline merge from the build manifest · esptool 4.8.1
# esptool 4.8.1; matching classic ESP32 ESP-IDF build directory
python -m esptool --chip esp32 merge_bin -o "merged-flash.bin" "@flash_args"

Use the separate syntax below for esptool 5.1.0. Arduino exports may use a different build recipe: keep their actual manifest/log rather than inventing flash_args. No command here flashes, erases or automatically changes an image header to make it appear compatible.

Offline merge from the build manifest · esptool 5.1.0
# esptool 5.1.0; matching classic ESP32 ESP-IDF build directory
python -m esptool --chip esp32 merge-bin -o "merged-flash.bin" "@flash_args"

Follow the first failed check

Keep the filename, build target, tool versions and both report sections with your findings. The site checks a candidate before replacing the run; an unsuccessful preflight is not an instruction to stop the firmware already running.

  1. Header, segment or checksum fails: obtain an intact artifact or rebuild the same target; compare the publisher’s file hash when supplied.
  2. Structure passes but chip/flash support fails: use the matching classic build or the appropriate external environment; do not relabel header bytes.
  3. App-only partition result is unknown: retain that uncertainty and locate the matching build artifacts if layout evidence is needed.
  4. Recognized layout or runtime checks still fail: inspect the named finding first. Load only after the required checks pass; the browser does not flash hardware.

BIN file questions

Does a valid app-only BIN prove the partition layout?

No. The partition table is a separate build artifact. A default profile supplied by the simulator is an execution assumption, not evidence of the file’s original custom layout.

Why can a file pass structure and still be refused?

Structure and emulator support are different checks. Chip, flash metadata or layout may be outside the current classic ESP32 profile even when image bytes are coherent.

Why does image_info or --version stop working in esptool 5.1.0?

Use image-info in 5.1.0. Its new output is the default and the old --version option was removed. The 4.8.1 example uses image_info --version 2; do not mix the two command forms.

Will a failed preflight replace the firmware already running?

No. A failed candidate check leaves the current run intact. The page loads only after the required checks and does not flash or write to a real board.

Project sources

Contact us