Riprogrammar firmware on ESP8266 devices (Sonoff, Shelly, etc.) - MASTERGUIDE

15 minutes of reading
  • Riprofirmware grammation

All environments

Notes and disclaimer
  • qualsiasi modifica all'impianto elettrico dev'essere progettata ed effettuata da personale qualificato;
  • any changes implemented in probefore is a propersonal responsibility as well as a profirst risk and danger (the contents of the present page are purely educational);
  • any changes implemented in proprior to a device it voids the guarantee, quality approvals and certifications.
Driving review: 2.4


Every electronic device contains broadly a small piece of softwareCalled firmware, which determines its functions and behavior. Our car is equipped with different firmware; it has one, the washing machine, our remote control, even a clock radio has a profirst firmware.

Devices based on SOC ESP8266 (a processor equipped with Wi-Fi rather in vogue for its low cost, limited size and great versatility) i'm not far behind: all mount a profirst firmware, usually written and compiled by proconductor. A classic example comes from the line devices ITEAD Sonoff "Smart Home” o Shelly "Home Automation Systems " which, mainly, mount such processor.

Using a similarity, riprogrammare (o flash) the firmware of a device it's like overwriting a whole VHS videotape. Well: the devices that mount the ESP8266 they easily lend themselves to this reproming, which, for the most part, is carried out in order to equip the components with additional (or in any case different) functionalities from the factory ones.

Is the case of alternative firmware like the Sonoff-Tasmota or l 'Espurna, free firmware written for devices based on ESP8266 (like i Sonoff, the Shells and many others): they are implemented to "free" the devices from the factory firmware and implement, apptogether, many additional features.

This guide illustrates how to reprogramming - regardless of the firmware (provided it is designed for this type of SOC) - a device based on ESP8266. It is indeed more than enough one all-inclusive guide, since the methodologies are fundamentally always the same.

It starts

How does it work?

For (re)programmare (or flash) a device based on ESP8266 the operating steps are, broadly:

  • acquire a firmware suitable, pre-filled or to be completed by hand;
  • connect the device to the computer via an adapter USB / TTL and related connection cables;
  • start the proflash certificate (or riproprogramming).

A follow approwe base the various aspects, before moving on to the activity of riprotrue grammar e proere.


The firmware is usually rappresentato from a series of files containing the code (written in very different languages) and le basic settings of the device (for example the name and password of our network Wi-Fi on which the device, at power-up, prowill come to enter automatically).

Such code files and settings, when passed by the hands of a compiler, are "translated" into a single file called "compiled": usually with extension ". Bin“, This file rappresents the content that will be written to the device instead of the pre-existing firmware.

It is therefore clear how necessary it is have the compiled firmware file that interests us, whether it is precompiled by someone else or compiled by hand by ourselves.

Some examples of custom firmware for ESP8266 are:


A file pre-compiled (made available by profirmware grammator, as for example in the case di Sonoff-Tasmota, Or of Ravencore) is solitamente used who needs to update the same firmware by overwriting the version previously installed on the device, or directly as new firmware for a device, as long as the precompiled firmware has an AP mode (Access Point), or a modality for which, after the riprogrammage of the device, it acts automatically from Access Point Wi-Fi, which allows you to connect directly to it solely for the purpose of configure network access Wi-Fi domestic through one propria inteface.
In the absence of this function, at the first reboot the device would not know a which network to connect to and it would ultimately be unusable.

Returning to the case of the older onenameIf, for example, we wanted to update a switch Sonoff Basic previously proconfigured and configured with firmware Tasmota 6.4 with the newest version 6.5, it will be enough download the compiled made available by programmatore and write it on the device. This compiled does not contain any settings (for example, access to Wi-Fi), but this is not a proBlema: on the first reboot the device will know where to go to read in memory the settings already previously configured with the 6.4. Remaining on the example of Tasmota, given that among the many features it provides also the older onenamento OTA (Over-The-Air), to update the firmware it is not even necessary to physically connect to the device, but it is sufficient to "pass" the precompiled firmware via browser or via tool appositi taking advantage of the network Wi-Fi as a means of communication.


Often, however, when insteadprogramma first an ESP8266, the compilation by hand (or better, the configuration of the firmware and then compilation) is one of the most traditional practices even if, as explained above, not necessarily always mandatory.

Manual compilation is usually required when the firmware in question does not have an AP mode explained above: it is therefore necessary configure the firmware upstream, before compiling, with the information needed to connect the target device to the Wi-Fi housekeeper.

What has been said is not only true when we reprogramma "for the first time", but also when you migrate from one type of firmware to another (eg from Tasmota to ESPurna and vice versa, or others).

Modality of reproming


It is the mode used when it comes to riproconfigure the ESP8266 with a compile containing the proyour settings (ie a device to which the firmware is radically changed, see above), although nothing prevents you from using it also in case of updatenameof the firmware in case you want to avoid one proprocedure OTA (Over-The-Air).

It involves using a simple and inexpensive device, called USB / TTL (or FTDI) which acts as a "bridge" between our computer and the device to reprogramming.

scheme of a generic USB / TTL.

This device has one side a standard USB connection; on the other, four contacts which rappresent:

  • a positive pole 3,3v (VDD) - (no 5v: if a voltage selector is present on the USB / TLL, make sure it is set to 3,3v);
  • a negative ground pole (GND);
  • TX (or TXD);
  • RX (or RXD).

These contacts must be connected on the board of the device to reprogramming, taking care to connect the positive and negative pole with the correspondents on the board, while TX and RX must be connected with their duals, or TX with RX e RX with TX (mistake this step is one of the most classic mistakes when prosee the reportproprogramming).

The two poles + and - serve to feed the board, while TX and RX serve respectively to send / receive data in phase of proprogramming.

To connect these four poles to the board of the device to be reprogrammars are usually used Dupont connection cables and possibly gods pin contacts (Optional). The latter can be welded on the board, but usually it's enough appobject to contacts to make the connection work (for example, see also "fresh laundry method“).

Below is a relative example to the connection contacts of the Sonoff POW:

Sonoff POW - USB connection: TTL - 2
connection example

Simply connecting the computer to the device via USB / TTL, the latter it simply turns on and becomes operational. To make it so proIn order to receive new firmware, it will first need to be set in flash mode, as we will see later.


To reproweighing an ESP8266 using a USB / TTL is obviously You must also use software ad hoc. There are many, but this guide will focus on using Atom (available for Windows, Mac, Linux) and / or of esptool.

The first, Atom, is useful both for configure, compile and send to the device (via USB / TTL) a custom firmware; The second one, esptool, is useful to make a backup of the existing firmware on the ESP8266 (maybe the original one), a total firmware cancellation (to "clean" it in case of proproblems) or to send to the device a firmware pre-compiled (that it is for adjournmentnamento or for first installation, in case of firmware offering AP mode).

We will see to follow how to configure and use these software.

Through OTA

As anticipated sopra, in some cases the firmware allows you to install a new version (an update)namethen, using one proprocedure OTA (Over-The-Air), or through a prothat, by browser or other methods, it allows to install an updated precompiled on the device. This approthat's especially welcome when the devices are in operation and are unreachable with ease (just think of an intelligent wall-mounted switch).

In the case of Tasmota, for example, with each new version release (which on inDomus we never miss to notify) it is sufficient to connect to the repository made available by the developer, download the next onenamento and, via browser (or tools such as TasmoAdmin), prosee morenameaway Wi-Fi.

Nb in the case of firmware Tasmota it is necessary to download the othernamento ("sonoff.bin") And the greaternamento minimal ("sonoff-minimal.bin"). This because It is not possible directly install the older onenamento (the file is too big for the memory of the ESP8266 device, on pain of overwriting the data related to the settings) and it is necessary before update with the version minimal, then with the complete and definitive one.
Through SonOTA

It exists - for the reproming of the devices only Sonoff - also another technique which does NOT include the use of physical connectors such asUSB / TTL. This technique uses Open Source software (Sonota) and the Wi-Fi housekeeper; since we have appurate a brick risk using this technique, we do not recommend it, remaining convinced of the promanual cedar through USB / TTL which, although initially more difficult, is the one that gives the most certain and reliable results.


From the 2019 some new components of the line ITEAD "Sonoff Smart Home” (eg. i Sonoff Basic R3, Sonoff RF R3 e Sonoff Mini), natively support the riprofirmware weight no need for physical connection. This procedura, illustrated in this guide , it is safer than the one illustrated in the previous point (SONOTA), but it remains on average dangerous in terms of a brick risk.

La proprocedure

Finally, let's see how prosee a riproconfigure the firmware of an ESP8266 device.

We analyze two specific cases:

  • Case 1: device on which the firmware we're going to write is different from the existing one (eg. firmware Tasmota which replaces the factory one) no offer AP mode;
  • Case 2: device on which we will go to update a custom firmware already present or install a new precompiled firmware which offers AP mode;

Case 1: new firmware (without AP)

If the firmware we're going to install no offers AP mode, then we are forced to compile our firmware by equipping it of the necessary information to have our ESP8266 device automatically accessed in the Wi-Fi domestic post-riproprogramming.

La procedura provides for the combined use of Atom and an adapter USB / TTL.
The sequence is as follows:

Lump sum:

  1. install and configure Atom.
  2. connect the adapter USB / TTL via USB to the computer to discover the COM port assigned to it.

Whenever yes riproprogram with new firmware an ESP8266 device:

  • download the latest firmware version;
  • open the firmware with Atom;
  • configure and compile the firmware;
  • connect the adapter USB / TTL to the device board;
  • connect the adapter USB / TTL to the computer USB taking care to set the device in flash mode";
  • upload the firmware;
  • verify the goodness of the riproprogramming.

One-off activity

1) Install Atom

ATOM LogoAtom it is, first of all, a text editor very powerful and versatile. Its peculiarity lies in the fact of being modulate, or provides the ability to install a series of additional packages, including those needed to compile firmware / software, write code in different languages ​​and much more.

That's why inDomus adopts Atom as a favorite editor: not only is it useful to compile firmware, as we will see, but it is also excellent as an editor for configuration files related to HUB home automation and much more.

Atom you download for free (for Windows, macOS and Linux) from the site
Once downloaded, install like any freeware available from the Internet.

For the purposes of this guide it is necessary, once installed and executed, install an additional package called "platformhyoid".

To go to:

  • su Windows, Menu : File > Settings > install
  • su macOS, Menu : To Tom > Preferences > install
  • on Linux, Menu : Edit > Preferences > install

and in the search hole search, for theappanointed, "platformhyoid". Once you find the package, click on "Install".

ATOM install packages
scroll to zoom

After successful installation close and reopen Atom, which at this point prowill install a series of integrative packages completely automatically.

At the end, PlatformIO will ask to restart for a last time Atom.

2) Discover the COM port

An adapter USB / TTL (FTDI) is the simple device that allows us to put in communication our computer and the heart of the ESP8266 SOC based device.

Without need, for the moment, to connect this device to the one to reprogramming, proinstead look to connect the latter (via USB cable) to our computer. If drivers are required, prosee the installation.

Then select the Atom menu item PlatformIO > Serial Monitor.
A fi will opennestas follows:

After a moment, in the entry "Port (The Harbour District)”Will indicate which COM port the computer has assigned to the USB / TTL module.
Take note of it.
Now disconnect the module from the USB port.

NOTE for users Apple: Atom should identify a different port than the classic COMx. To understand how to configure the door in this series, refer to to this thread. Beyond what is expressed in the link, always remember to install the correct driver for Mac by the profirst USB / TLL adapter.

After installing the correct driver, in the system report of the Mac, under USB, you will need to (by connecting the USB / TTL adapter) a voice similar to the one below:

FT232R on Mac

Riprotrue grammar e proman

Now Atom is installed and configured and the COM port is known, it is possible download, configure and compile the firmware.

Since where to download, how to configure and how to compile the firmware depends from the firmware itself, at this point a small deviation is made on the following guide, which explains step by step the various aspects related to the various firmware.

Following and completing the following guide, we get to the point of having configured and then compiled on profirst firmware:

Compile a custom firmware for ESP8266 (Tasmota, ESPurna etc.) with Atom

"Flash" MODE

At this point we are proto connect our device adapter USB / TTL and then the latter to the USB port Of computer.


First, therefore, connect the four contacts of theUSB / TTL on the board (in the modes explained before) after that, before to also connect the USB port to the computer, provvedere to perform the necessary action (depending on the device) in order to set it in "flash" mode.

La flash mode is the mode in which the ESP8266 prepares itself to accept a new firmware, or to allow the reading of the pre-existing firmware, or delete it.

To do this it is necessary - usually - connect together two specific points on the board: the point called GPIO0 and the contact used also in connection with theUSB / TTL called GRN (ground, earth). These two points must be put in contact with each other while connecting the USB / TTL to the USB port, after which they must be disconnected.

To recap:

  • I connect the USB / TTL to the board;
  • put in connection GPIO0 and GND;
  • I connect the USB port of the USB with the USB port of the computer;
  • I remove the connection between GPIO0 and GND.

At this point the device will be in "flash" mode.

La procedura can be complicated, but often comes to our aid the nature of the device itself. Some, in fact, instead of forcing us to look for the GPIO0 and find ways to connect it with a wire to the GND, offer us specific solutions. For example, in the case of Sonoff Basic it's enough keep the button on the board pressed during USB connection to get it into "flash" mode.

How to flash the proYour device must be the subject of personal research. However, we have provided a list of related techniques ai Sonoff:

How to set the flash mode in the devices Sonoff


At this point everything is pronto for riproadjust the device:

  • we have carried out configuration and compilation firmware;
  • we have set flash mode on the device "

so we just have to overwrite the firmware on the device via upload.

Nb in case you want to do a backup of the existing firmware, make a small detour to the next chapter.

To start the procedura, click at Atom on:

Menu : PlatformIO > Upload

doing so, the software prowill see you connect to the device via the USB / TTL adapter e prosee it this way at its reproprogramming.

Se at the end was originally the proprocedure apphe will give “SUCCESS"(Similar to the firmware compilation screen), everything will have gone the right way. In the case instead the proprocedure fails ("FAILED"), Repeat the above steps, taking care to check carefully COM and connections configuration.


Once it is successful, reprogrammation is necessary to verify that everything works properly. Disconnect the USB cable and then reconnect it immediately, this time WITHOUT set the device in "flash" mode: this will cause it is powered up and starts functioning normally without going into the mode proprogramming.

At this point the device will have turned on and will have entered into ours Wi-Fi, as already informed with respect to the access coordinates. To connect to it, however, it is necessary to discover which IP our router has assigned to it, which we cannot know a priori.

To do this, simply click on "PlatformIO> Serial Monitor”And, in the following screen:

select under "Baudrate" setting up "115200"While the field"Port (The Harbour District)'should automatically configure based on the COM port assigned by the computer to the USB / TTL adapter.

By clicking on "Start" dovrebbe appenter a screen as follows:

scroll to zoom

which should indicate the IP obtained from the device when it entered the network Wi-Fi, in this case "". Now, opening up any browser on the proyour computer, enter the address the IP just obtained and press enter.

The type of interface varies depending on the firmware; in case of Tasmota dovrebbe appenter a screen similar to the following:

Case 2: updatenamento or new firmware (with AP)

If the firmware we're going to install is an adjournernameprecompiled or a pre-compiled new firmware which provides AP mode, then the procedura is certainly simpler.

In the first case (updatenamento), the roads they are two:

  • Update Searchnameconnected with physical connection;
  • Update Searchnamevia OTA (Over-The-Air), if offered by the firmware;

in the second case, the road is alone that of an adjournernamethrough physical connection, but without the need to use Atom (as in the "Case 1") To compile and then upload the firmware.

Let's analyze the update mode firstnameOTA, then the two cases for which the physical connection is foreseen, for the most partnamento or for new firmware with AP mode.


The OTA (Over-The-Air) is instead a procedura which allows use the connection Wi-Fi to update the firmware. this procedura varies from firmware to firmware; it is usually done via browser and web interface offered by the firmware itself.

What is needed is, basically, of the compiled file of the firmware to be updated: once "fed" to the web interface, will be the firmware itself a prosee morenameself-esteem. This compiled file can be downloaded as a precompiled one or filled in manually with the techniques explained above.


To update a device previously proprogrammed Tasmota it's enough manually fill in the updated version firmware and recover the file "firmware.bin"(See the" note "section at the end of the indicated passage) Indeed you must first compile the firmware "minimal" (or "env_default = sonoff-minimal" In the file plaformio.ini), shelve the file "firmware.bin"Resulting from the compilation, recompile the firmware"complete” (“env_default = sonoff”- or distribution language - In the file plaformio.ini) and set the second file aside "firmware.bin".

Alternatively, you can download these files directly from the network, made available precompiled by the developer of this firmware.

Subsequently, it is necessary to connect via web browser to the device equipped with firmware Tasmota e to select "To sign Upgrade" to the item "Upgrade by file upload", Select the file"firmware.bin"Above concerning the version"minimal", Then click the"Start upgrade"And simply wait for the transaction to finish. At the end, reconnect to the web interface and redo the procedura, this time passing it the file "firmware.bin"Firmware"complete".

A dedicated guide is available here all'aggiornameof the massive Sonoff-Tasmota with one centralized operation, through TasmoAdmin.

Physical connection

Where it is to install an updatenamenot achievable OTA or a new firmware with AP mode, then the mode that provides for physical connection remains the only possibility.

Unlike "Case 1“, In this scenario we don't need to manually compile the firmware, because:

  • sending an updatenameHowever, we would only overwrite the firmware, while the portion of memory containing the information needed to access the Wi-Fi it would not be touched, therefore at the post-update rebootnameSince the device would be able to return to the network without it proproblems;
  • sending a new firmware with AP, post-ri modeprogrammation the device would not know about which Wi-Fi access (unlike the "1 Case"), but offering yourself as an Access Point would allow the user to access it, provide him with the access coordinates to the Wi-Fi domestic, thus solving the proBlema downstream.

In this scenario, every time you reproprogram with new firmware an ESP8266 device la procedura is the following:

  • download the latest firmware in precompiled format;
  • connect the adapter USB / TTL to the device board;
  • discover the COM port assigned to it;
  • connect the adapter USB / TTL to the computer USB taking care to set the device in flash mode";
  • upload the firmware;
  • verify the goodness of the riproprogramming.

To upload the firmware we will use esptool, great little free software which allows you to

  • carry out the reprogrammation of an ESP8266 device;
  • backup the firmware of an ESP8266 device;
  • perform a total deletion of the firmware of an ESP8266 device.

Similarly to how Atom does, esptool is a software that, through the use of USB / TTL, allows you to reproconfigure the sign of an ESP8266 device. Moreover, it enables the ability to perform a backup of the firmware in use on the device, as well as allowing the total cancellation of the same.

One of the most classic fields of use of esptool is the one dedicated to uploading firmware as Ravencore; the latter is a firmware for ESP capable of providing direct compatibility with Appthe HomeKits to components based on ESP8266 SOC.

For all the operations allowed by this simple but powerful tool it is necessary that the device is set in flash mode; you also need to know the COM port on which the USB / TTL adapter is configured at your computer.

The upload is done through a simple command, in broad terms as follows: --port COMx write_flash -fs 1MB -fm dout 0x0 nomefile.bin

Where COMx is the name of the COM port on which the USB / TTL adapter is certified e filename.BIN is the name of the precompiled firmware file to upload (which is an update)namento or a new firmware).

How to backup, restore (and upload) and delete firmware on ESP8266 devices, the guide is as follows:

Backup, restore and deletion of a firmware Sonoff (and similar)

ITEAD Sonoff BasicATTENZIONE: remember that there is on our FORUM community an ad hoc section dedicated to Sonoff (and more generally to devices ESP8266), for any doubt, question, information on the specific merit of these components.

Please comment below