Decoding an ESP8266 Firmware Image

I recently coded a Python script for Decoding an ESP8266 Firmware Image. It’s the first part of my quest to create a Linux tool for creating a single flash image.

More specifically, the script will decode a single binary image or a ‘combined’ image. A combined image (single flash image) can be created with the flash download tool from Expressif. (Exressif is the company which makes the ESP8266.)  However, that download tool only runs on Windows. Here is what the Expressif Flash Tool looks like:


ESP8266 Flash Tool on Windows

Notice, the ‘CombineBin’ button. It is used to create a single binary image from the multiple files (‘segments’). In that image you can see seven files (the current SDK 2.1.0 files as of this post date) listed and the addresses to load them . I used the ‘CombineBin’ button and created a single binary image called sdk-2.1.0.bin. (The default file name it creates is called target.bin.)

I run Linux. and the recommend ESP8266 tool for it is The esptool script, however, does not have a option to create a single combined image. It may have that feature as an enhancement at some future time. Hence, my quest, to develop a Linux tool to create a single flash image.

I like to keep my ESP8266 firmware current. To flash the latest SDK, I use this script:

While that works fine, I think it would be more efficient to create a single combined image to flash. Especially since I have a number of ESP8266 modules to flash. The single image (sdk-2.1.0.bin created from the windows tool) can be flashed as follows:

To create a tool to combine all the ‘single’ images into one, one needs to know the format of the single images and the format of the ‘combined’ image.

Espressif has a brief document (HERE), describing the firmware image format. However, that document does not fully cover what is need to decode a combined image. Also, it does not cover all of the single image ‘formats’. has an image_info command, however, it only works on single modules. It does not work on combined modules.

In my ‘reverse engineering’ attempt at Decoding an ESP8266 Firmware Image, I created this Python script called Here is the code: can be used to decode any of the single modules that comprise the combined sdk-2.1.0.bin image or it can be used to decode the ‘combined’ image.

When it is used to decode the combined sdk-2.1.0.bin image via:

Here is what the output looks like:

From that output, one can see where (address) and how each of the single images are placed in the ‘combined’ image.  Now that the combined image format is known, a script can be coded to create it from the individual files.

Leave a Reply

Your email address will not be published.