Combining the three .bin files created by PlatformIO for an ESP32-S3 to a single .bin file

Summary

When I build my ESP32-S3 code using PlatformIO I end up with three separate .bin files. Using esptool.py we can combine these three files into a single .bin file. This can be flashed to the ESP32 using esptool.py. This gives me a chance of remotely programming my ESP32 device over a website which I think will only work with a single file.

The Problem

When I build my ESP32-S3 code through PlatformIO on VSCode I get three separate .bin files. These are called:

bootloader.bin partitions.bin firmware.bin

These are flashed to my ESP32-S3 device using the command line:

esptool.py --baud 115200 --port /dev/ttyACM0 --chip esp32-s3 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x0000 bootloader.bin 0x8000 partitions.bin 0x10000 firmware.bin

Full instructions on how to flash these files using the command line can be found here

I’m trying to develop a website to allow the easy update of my ESP32-S3 based devices by somebody who doesn’t want to use the command line. Which is most people. All sensible people. To enable this I need to create a single .bin file. I think…

The solution

We can combine the three .bin files using the merge_bin option of esptool.py. To see the help for the merge_bin option type:

esptool.py merge_bin -h

The magic command that “works for me” to merge the three .bin files that PlatformIO creates into a single .bin file called merged-flash.bin is:

esptool.py --chip esp32-s3 merge_bin --output merged-flash.bin --flash_mode dio 0x0000 bootloader.bin 0x8000 partitions.bin 0x10000 firmware.bin

I get the reassuring output:

esptool.py v4.8.1
SHA digest in image updated
Wrote 0xea360 bytes to file merged-flash.bin, ready to flash to offset 0x0

To flash this to my ESP32-S3 device, this command works:

esptool.py --baud 115200 --port /dev/ttyACM0 --chip esp32-s3 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x0000 merged-flash.bin

Success! The single file loads and my device works as expected.