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.
| Artifact | Evidence available | What it cannot establish |
|---|---|---|
| Application only | Application header, segments and available integrity fields | The separate partition layout |
| Recognized merged image | Recognizable boot, table and application artifacts | Universal partition support or hardware validity |
| Unknown or truncated file | Only the bytes that can actually be parsed | A 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.
# 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.
# 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 result | Interpretation | Next check |
|---|---|---|
| Bad structure/checksum | The candidate is not structurally accepted | Re-copy or rebuild; keep the current run |
| Valid structure; S3/C3 | Inspection is not classic execution support | Use the correct target/environment |
| App-only; partitions unknown | No partition proof is present in this artifact | Keep unknown; locate the build manifest |
| Merged; layout unsupported | Recognized data exceeds this runtime’s supported layout | Inspect 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.
# 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.
# 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.
- Header, segment or checksum fails: obtain an intact artifact or rebuild the same target; compare the publisher’s file hash when supplied.
- Structure passes but chip/flash support fails: use the matching classic build or the appropriate external environment; do not relabel header bytes.
- App-only partition result is unknown: retain that uncertainty and locate the matching build artifacts if layout evidence is needed.
- 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.