Replacing the ITEAD Sonoff firmware

About a week ago I received a ITEAD Sonoff, which is a nifty little device, for the surprisingly low price of only $4.85 (currently typing, normal price $6).


There are two versions, one with and one without RF, I went for the one without, because I will only be using it over WiFi.

Why the Sonoff?

The Sonoff isn’t the first of its kind on the market, so why this, and not one of the other?

The choice of this all comes down to how much control you want to have over your items, and how much you want others to just take care of it for you. As default the Sonoff comes pre-loaded with firmware, and can be controlled from a smartphone from the app for it. This is pretty much the same deal with other devices on the market, but with the Sonoff you are able to take it a step further.

Inside the Sonoff, there is an ESP8266 hidden, and this takes care of everything, and any one spending just a few minutes on this blog, have most likely found this IC mentioned at least once already. Not only does it have a chip easy to program, ITEAD was also nice enough to break the pins out, needed for flashing it. And this is exactly what I am about to do!

Lets flash!

Before ordering the Sonoff, I had been doing a bit of reading on how to flash it, and found it very confusing, but I ordered it, and hoped it would all make sense when I could actually look at it, sadly, it was just as confusing after getting it. So instead I closed all the pages, and decided to give it a shot myself, and it turned out to be simpler than I thought.

2016-05-22 14.13.54


Before doing anything, disconnect the Sonoff from mains.

First thing you need to do, is to solder a header to the 1×5 row of holes.

These go to the TX and RX pins on the ESP8266, and are also used to provide 3v3 and GND to run the circuit.

Then it should look something like on the picture above.

The connection closest to the button at the top, is 3v3, underneth TX, then RX and last GND. The last connection is not one we are going to use for this.

To attach the programmer, first make sure it is set to 3V3, then connect it as following:

Programmer Sonoff (counting from top to bottom)
3V3 1
TX 2 (RX)
RX 3 (TX)

Then hold the button down on the Sonoff, and attach the programmer to your computer. Holding the button down while applying power to the ESP8266 will bring it into flash mode, which will allow you to put new firmware onto it.

My choice was to put NodeMCU onto it, which went without a hitch.

Pin functions

After having put another firmware onto the ESP8266, we would probably want to be able to control the relay again, and for that we need the pin number.

Function GPIO NodeMCU
Button 0 3
Relay 12 6
Green LED 13 7
Spare (pin 5) 14 5

The LED on the board is actually a red/green bi-color led, but the red side is only connected to the RF module, which in my version isn’t mounted.

My code

After putting NodeMCU on mine, I modified some of my old code to match the pins on the Sonoff. This code will make it connect to a MQTT borker, turn the relay on and off, flash the led on activity, and allow the button on the Sonoff to act as a toggle switch for the relay too.

-- Timers
-- 0 = WiFi status + mqtt connect
-- 1 = MQTT offline
-- 2 = Free
-- 3 = Free
-- 4 = Free
-- 5 = MQTT activity
-- 6 = Button debounce

mqttBroker = ""
mqttUser = "none"
mqttPass = "none"


wifi.sta.config ("SSID", "PASSKEY")

-- Pin which the relay is connected to
relayPin = 6
gpio.mode(relayPin, gpio.OUTPUT)
gpio.write(relayPin, gpio.LOW)

-- Connected to switch with internal pullup enabled
buttonPin = 3
buttonDebounce = 250
gpio.mode(buttonPin, gpio.INPUT, gpio.PULLUP)

-- MQTT led
gpio.mode(mqttLed, gpio.OUTPUT)
gpio.write(mqttLed, gpio.HIGH)

-- Make a short flash with the led on MQTT activity
function mqttAct()
	if ( == 1) then gpio.write(mqttLed, gpio.HIGH) end
	gpio.write(mqttLed, gpio.LOW)
	tmr.alarm(5, 50, 0, function() gpio.write(mqttLed, gpio.HIGH) end)

m = mqtt.Client("Sonoff-" .. deviceID, 180, mqttUser, mqttPass)
m:lwt("/lwt", "Sonoff " .. deviceID, 0, 0)
m:on("offline", function(con)
	ip = wifi.sta.getip()
	print ("MQTT reconnecting to " .. mqttBroker .. " from " .. ip)
    tmr.alarm(1, 10000, 0, function()

-- Pin to toggle the status
buttondebounced = 0
gpio.trig(buttonPin, "down",function (level)
	if (buttondebounced == 0) then
		buttondebounced = 1
		tmr.alarm(6, buttonDebounce, 0, function() buttondebounced = 0; end)
		--Change the state
		if ( == 1) then
			gpio.write(relayPin, gpio.LOW)
			print("Was on, turning off")
			gpio.write(relayPin, gpio.HIGH)
			print("Was off, turning on")

-- Update status to MQTT
function mqtt_update()
	if ( == 0) then
		m:publish("/home/".. roomID .."/" .. deviceID .. "/state","OFF",0,0)
		m:publish("/home/".. roomID .."/" .. deviceID .. "/state","ON",0,0)
-- On publish message receive event
m:on("message", function(conn, topic, data)
    print("Recieved:" .. topic .. ":" .. data)
		if (data=="ON") then
		print("Enabling Output")
		gpio.write(relayPin, gpio.HIGH)
	elseif (data=="OFF") then
		print("Disabling Output")
		gpio.write(relayPin, gpio.LOW)
		print("Invalid command (" .. data .. ")")

-- Subscribe to MQTT
function mqtt_sub()
	m:subscribe("/home/".. roomID .."/" .. deviceID,0, function(conn)
		print("MQTT subscribed to /home/".. roomID .."/" .. deviceID)

tmr.alarm(0, 1000, 1, function()
	if wifi.sta.status() == 5 and wifi.sta.getip() ~= nil then	
		m:connect(mqttBroker, 1883, 0, function(conn)
			gpio.write(mqttLed, gpio.HIGH)
			print("MQTT connected to:" .. mqttBroker)
			mqtt_sub() -- run the subscription function


  • hi Mikey

    how to flash new firmware? (which software / bin file). i try esp8266flashloader (win32) and nodecmu lasted version unluck.
    please advise.

    thank you
    prasong p

  • Which tool did you use to flash the ESP? I’ve been trying with one of the windows tools but failled miserably. There are also some parameters that should be chosen and I didn’t really know what they should be. Nice work! Your website looks very neat too 🙂

  • Hello! You try other firmware? Maybe EspEasy from ?

  • why need to reflash the firmware ?

    • Because I wanted to integrate them into my own home automation system, so instead of having to use multiple systems and rely on them being online, I only need one now.

  • How did you flash the actual code? I’ve managed to use the utility to flash NodeMCU successfully but I can’t figure out how to upload the actual code? I’m so confused!

    Arduino IDE throws an error message because it doesn’t like the — in the 1st line of code.
    “error: expected unqualified-id before ‘–‘ token”

    • You don’t use the Arduino IDE to upload LUA code to NodeMCU, you use LuaUploader

      • Thanks @Mikey.
        I’ve uploaded the code but now when I click list files and then load from ESP I get the following:
        SENT: l = file.list()
        SENT: for k,v in pairs(l) do
        SENT: print(“name:”..k..”, size:”..v)
        SENT: end

        SENT: — Print File Content —
        SENT: filename = ‘Sonoff-MQTT.lua’
        SENT: txt = ”
        SENT: repeat
        SENT: line = file.readline()
        SENT: if (line~=nil) then txt = txt .. line end
        SENT: until line == nil
        SENT: file.close()
        SENT: print(txt)

        Does that mean that nothing has happened?

        • It says there is a file named “Sonoff-MQTT.lua” stored on it. If you want it to start it when it boots, you need to call it “init.lua”, but best practice is to make a simple file which counts down 3-5 seconds, then runs the actual script. This is done because it can be very tricky to get it out of a boot loop if it crashes as soon as it tries to run the script.

          • Thanks very much for that. I didn’t know about the “init.lua”. It might be worth updating the article to include this info for noobies such as myself.

            I’ve now created two files on my Sonoff. Sonoff-MQTT.lua and init.lua. The latter has just the following “tmr.alarm(0,5000,1,function() dofile(‘Sonoff-MQTT.lua’) end)”. Is this the correct syntax? If yes, how do I test the results? Do I connect the Sonoff to the mains or is there a safer way to power it without using mains power (just in case lol)?

          • It actually does tell you when NodeMCU is starting up, if you watch the output from it. Because it then says it can’t find init.lua

            My init.lua got a bit more in it

            countdown = 3
            countdown = countdown-1
            if countdown<1 then
            countdown = nil
            local s,err
            if"") then
            s,err = pcall(function() dofile("") end)
            s,err = pcall(function() dofile("run.lua") end)
            if not s then print(err) end

            This makes sure the code is non blocking, and also gives a bit response to work with when booting it up.

            I am not sure what you mean if you connect it to mains or not. During flashing the new code to it, you have had it powered up through USB I assume? And powering it through that you can test to see if the relay is activated when you expect it to. Even if it did not do as you expect, it still should not be more dangerous to connect it to mains, you haven't changed anything on the hardware, just the code running on it. Just never have it connected to your computer and mains at the same time!

  • So I’ve basically copied and modified your init.lua as follows:

    countdown = 3
    countdown = countdown-1
    if countdown<1 then
    countdown = nil
    local s,err
    if"") then
    s,err = pcall(function() dofile("") end)
    s,err = pcall(function() dofile("Sonoff-MQTT.lua") end)
    if not s then print(err) end

    It's connected to my computer via the USB-to-TTL device and I seem to be able to upload code to it but I'm not convinced that it's actually "saving" anything. Basically, I created the init.lua and Sonoff-MQTT.lua files and uploaded them. I got confirmation in the "output" window showing "SENT: xxxx" but when I cleared the output and cleared the code in the editor then pressed "Load from ESP" I got this:
    SENT: — Print File Content —
    SENT: filename = 'init.lua'
    SENT: txt = ''
    SENT: repeat
    SENT: line = file.readline()
    SENT: if (line~=nil) then txt = txt .. line end
    SENT: until line == nil
    SENT: file.close()
    SENT: print(txt)

    and nothing happened. Shouldn't it have populated the editor with the content of init.lua saved in the Sonoff?

    Also, I'm having to press-and-hold before while connecting the Sonoff to the USB port otherwise nothing works. I take it this is still required to upload the lua files after flashing NodeMCU right?

    • After having flashed it with NodeMCU you should no longer be needing to hold anything. Holding the button only sets the ESP8266 to go into the mode where you can flash it with new firmware. After NodeMCU has been loaded onto it, it should just be allowed to start normally, then it will take care of storing the LUA script.

  • I don’t know what to do now. Is my Sonoff fried? I can still flash it with the NodeMCU flashing tool you linked to so I think that’s a good sign right?

    It gets to the end and says:

    Note:Program flash success.
    Note:Serial port disconnected.

    There’s also a green tick next to NODEMCU TEAM at the bottom left hand side of the window.

    • Strange things can happen when flashing NodeMCU, try flashing an older version, then the newest again afterwards. Flashing the same version on top of itself have caused strange problems for me before.

      And so far I haven’t managed to kill a ESP8266 chip, so I doubt you have too.

      • So…I tried another firmware “nodemcu_integer_0.9.5_20150318.bin” and this time connecting and attempting to list files returns gibberish

        ??ZtGE Ht?lE
        H?$xdl?0??UGHI$|$lH0??TGE ?|$lEPd?ZtGE H|?lE


        What firmware did you use?

  • hola quiero que mi sonoff funciones como pulso seco, sin corriente para poder abrir un porton de garage tipo pulsador quisiera que funcione, es posible???

  • Hello Mikey! Have you tried to recude power consumption of the sonoff switch in the software?

    • Hello, I am not sure what you mean. The power consumption of the sonoff itself, or the device attached to it?

      The sonoff itself draw between 1 and 2 watts with the relay energized. This version of the sonoff can’t measure what the device attached to it draw, for that you need the sonoff pow. I don’t have one of those yet, but I got one coming in the mail. 🙂

  • Hi, I am interested in using the ESP8266 to control mains appliances, but I don’t understand why a smart phone can’t talk directly (via the wifi network, to the ESP8266. Why do I need a MQTT Broker, which I guess would run on a PC or Raspberry Pi.

    • Hello, the ESP8266 can also easily be controlled directly from a smartphone, or anything else being able to connect to a web server.

      To use an ESP8266 directly, you could instead set up a web server on the ESP8266, and have your phone call that. The reason I use MQTT is because it got less overhead than opening a web page, and it also makes it easier for me to work in OpenHAB.

  • Maybe it’s worth mentioning that flashing to NodeMCU requires setting baudrate 115200.

  • So for flashing the ROM the power supplied by the serial adapter is sufficient? For the other ESP-based boards (ESP-01, ESP-07, ESP-12) you need an additional 3.3V supply because the chip uses more mA than the adapter can supply, so are you saying this is not the case with the Sonoff?

  • Would it be possible to use another ESP8266 (such as a WeMos D1) to flash the Sonoff ESP8266? 🙂

  • hi, I want to use amazon alexa or apple ios to control Sonoff; is there a custom code available that allows integration into amazon or apple devices. I don’t want to use the app that comes with SonOff; I want to write something in python to control the devices and integrate into alexa as found in the link below:

    any thoughts?

  • I’ve long been searching and trying, but it still does not work, maybe someone can help me
    I have a Sonoff Switch which I want to put on and off with UDP command.

    I read a lot about the firmware update, but if that’s not necessary, I would not do that. because I have not enough knowledge in this area

    I use a loxone miniserver to send UDP commands.
    I need to know which UDP port is used.

    I’m also need the ASCII udp commands that i can use to turn the sonoff switch ON and OFF.

    I can test the commands with a udp sender on my windows computer.
    For example i have another webrelais that already work.
    To turn OFF this webrelais i use port 1200 and ASCII command: u=2password\n
    To turn ON this webrelais i use port 1200 and ASCII command: a=2password\n

    is there anyone who can tell me which port and commands for ON and OFF i can use for the sonoff switch?
    Or is it not possible to turn the switch ON and OFF on this way without updated the firmware of the sonoff switch?

  • Thanks for the article, it worked first time. However when I publish MQTT OFF commands to the Sonoff the relay sometimes remains on even though I hear a click. I might have to send the command 3 or 4 times to get it to switch off. Also the click from the relay is louder when switching on. I’m not sure what’s happening yet, I’ll have to do some digging around with the scope. Anyone else had this?

    • Maybe yours got a defective relay, the sound on mine is also a little different when getting pulled and released, but that is pretty normal. But it should release properly every time too.

      • Just had chance to do some more testing. It’s not a sticky relay, I scoped the coil & it’s definitely not getting the OFF command. It works fine if I disconnect from the mains & power it from the serial port. It also works fine connected to the mains when I use the pushbutton on the Sonoff. It’s only when I send the MQTT OFF whilst connected to the mains that it will fail to turn off (About 1 in 10). I’ll order another couple & try those in case it’s a weird hardware fault but I’m a bit stumped why this is happening.

  • Hi. A Spanish speaker Carlos asked you the following: If there is a way to use the Sonoff as a pulse sender to open the garage door. So it close and immediately open the relay with the same command.
    I feel interesting on that too…Thanks.

    • With the original firmware on, no. It only works as a switch with that.

      With some modification and a new firmware it could be used to just send pulses, but then it would make more sense to get another board with an ESP8266 on it and a relay.

      The Sonoff gets mains in at one end, and outputs it at the other end through a relay, the two output terminals are never connecting to each other.

  • Hi Mickey, maybe you can help me out.
    I just have flashed my first Sonoff and it does not startup ad all.

    I used the your code and add my wifi credentials to it via notepad and save the file as .bin.
    Than i used NODEMCU to flash the sonoff. Every thing looks fine but now the Sonoff does nothing :(.

    Can have any idea what went wrong ?

    Rg Frank

  • Hi Mikey, thanks for the reply.
    I just have manged to get it working.
    Thank you . Rg Frank

  • How are you sending ON or OFF command from mqtt broker to control the sonoff relay switch? I have broker and sonoff connected. Thanks

    • m:publish(“/home/”.. roomID ..”/” .. deviceID .. “/state”,”OFF”,0,0)
      m:publish(“/home/”.. roomID ..”/” .. deviceID .. “/state”,”ON”,0,0)

      These two lines are what makes it trigger the on or off function, so /home/1/bugzapper/state with the message ON should turn it on.

    • This is not triggering any action:
      mosquitto_pub -u sonoff -P sonoff -h -t /home/1/bugzapper/state -m “ON”

      I dont’ know what is wrong 🙁

      I have message from Lua Uploader like:
      MQTT connected to:
      MQTT subscribed to /home/1/bugzapper

      And from moquitto too:

      New client connected from as Sonoff-bugzapper (c1, k180, u’sonoff’)

      Thanks for your help.

  • How did you connect the Sonoff to your PC; what hardware did you wire the pins to?

  • Mike, Thank you very much for this, looking forward to trying on mine. You really put the effort into all your replies to help others too, great effort, really appreciated.

  • Hello,
    I have a Sonoff and I wanna use it for a staircases light.
    I need help to set a timestamp whenever it receives a command, to stop automatically after 10-15 min. after each start.

    Thank you in advance!

  • Hello Mikey, I would need to send HTTP commands to control a Sonoff device through the network, can you help me? Thanks in advance.

  • Hi Mikey,
    I am a real newbie with this technology.
    I got the Sonoff switch just to see if I could control an outlet via the internet (and because it is so cheap!)
    I installed the eWeLink App on my android phone and got everything connected, paired and working fine.
    However, in the App after I select my (one and only) switch it reads (in red), “Firmware version can be upgraded, please go to device page to update firmware”
    Then (in white)
    Manufacturer: Maker
    I don’t know how to update the firmware, as suggested.
    Do they really want me to open the unit and solder in a USB connection to update the firmware?
    If the unit has wireless communication to the router, can’t the firmware be updated through that connection?
    Sorry if this question is too basic for this forum.
    You are running a great service here, where so little user information is available on the web and in the documents that come with the switch.

    • Go into the device page, and press the circle with the three dots in the upper right corner, then go into Settings. In there you then press on the firmware version bar, and it should ask you if you want to update. And that should be it.

      You only need to open it up if you want to completely change the code in it, but that would then also require you to do all the other stuff with setting a server up and such to control it.

    • Oh, DUH!
      (…and I have an advanced degree in Physics)

      I watched the firmware update progress to 90%, then it got stuck.
      Finally I got a “firmware update failed” message.
      But the red notice to update is gone and it seems to be working fine, so I think I’ll just let it be.
      Thanks for the very prompt and “right on target” response.

      • It should show current & latest firmware side by side. If different, try again!
        I did 5 times struck at 90% and 6th time passed. Latest firmware is very stable.

  • dear All,
    i have managed to flash sonoff basic several times, but in some cases after the flash and reboot i can connect to the device via serial just for a minute. After that i cant reconnect. On the usb/ttl i have 2 leds, monitoring th rx/tx traffic, one of them lights up – in normal case just blinks when there is a traffic.
    So i can flash it, connect to it, but it crashes, and no way to reconnect / re-flash. Is there someone, with similar experience? Even some advice?

  • Hi, i just found out your article. I must say, i love what you did with your MQTT implementation and the binding with the led/button man !

    Congrats !

  • hi. i need to connect sonoff switch with a google home. can you tell me how i do that. tks

  • Can you use the GPIO14 pin to connect a sensor? Is that pin free to be used?

  • If dessolder original eeprom,and replace with new eeprom with new firmware, is possible restore original firmware if replace original seldom?

    • Yes should be, but try looking into cloning it instead, so you can download everything from it, and flash it with it again if you want to go back to original later.

    • Is available firmware for “sonoff pow” for use internal server with domoticz ? Original server ithead not have graph in daily use,only total for day, Ihave need accurate control minute per minute. And if have internet problem the server ithead not memorize power in the server, internal server is very good, do you have help? Thanks

  • Michael Söllner

    Hello Mikey.

    I followed your Tutorial one Step after another, but my Device wont boot. It still is flashable.

    I Tried to solve the Problem so far:

    – flash a file to clear the flash (ESPEasy_R0_1024)
    – i flashed other Custom Roms
    – i flashed ESPEasy 147

    Nothing gets the Thing to work, but as i said, its still flashable. Please help me 🙂

  • do i need to add 240 v power to the module to make it work

  • Hello !!!! Thanks for all this information and please sorry but I don’t speak english very well.
    I’m looking for a firmware capable to do the following:
    When the Sonoff receive an order from the physically push button or by the control app, change the estate of output relay for only 1 second and then the relay return to it’s original state. When the physically push button or turn On / Off from the app is pressed again, the output relay change again they stat for only one second.
    Basically I’m trying to convert the output relay from latching to momentary pulse. I know that the relay output will generate a momentarý output power (220V in my case) but I’m planning to put another relay on the output to have an insulated and non powered contact.
    Thanks a lot for all the information included on this post.
    Thanks alot for all the information included on this post and I hope that someone can help me with this request.

  • hello

    thank you for the article, help a lot !
    some questions though …

    what is the next step ?
    say i connected it to the lamp or …

    how to connect it to the harmony ? alexa ? .. any hints ?

    thank you !

  • Is there a model or firmware config that will make the switch dimmable? or is it just HIGH / LOW?

  • Off topic/ does anyone know why my stock sonoff switch blocks other devices pc, laptop, phone etc. wired and wifi from connecting to internet. Randomly

  • Hi Mikey,
    Thank you for this information! I managed to flash my Slampher (v 0.2) with the Sonoff-Tasmota firmware.
    ( from Theo Arends)
    I have about 8 Sonoff devices all flashed with this firmware and i am using it with mqtt and openHAB. All are working perfectly.
    But with the Slampher i do not know how i can get the device in WiFi Access Point Mode in order to configure the firmware with the correct wifi and mqtt settings.

    With the other Sonoffs i have (S20 and Basic) you have to quickly press the button 4 times, then the firmware enters in Wifi access mode. But with the Slampher this does not seem to work.

    I wonder whether you have any idea how i can get the button presses working. Hopefully you have experience with the Slampher as well.

    Regards, Bert

  • i really appreciate the discussions in this thread. But as a newbie in this, I’m still a little confused. I want to use the sonoff basic with alexa or with google home, However, I do not want to use the EWeLink app to configure this unit. I’d rather configure it some other way and yet be able to connect it to Alexa or google home. if this is possible, I’d like to see if someone can help with detailed steps.
    Thank you

  • I can flash NodeMCU using NodeMCU Firmware Programmer but It doesn’t appear to run. No communication to serial port when I attempt to load init.lua. I tried two different (formerly) working SONOFF modules (version TH_V1.1 2017-5-5) . I’m using an FTDI MM232 module which is capable of 100ma supply current. After flashing NodeMCU, when I attempt to connect using ESPlorer v0.2.0-rc5 it says Port Open 9600 and Comunication with MCU.. then nothing. Tried all baud rates and nothing I have tried variations on flash size and flash type (I assume it should be 1M, QIO. 40Mhz) but nothing I try seems to work. I get the same result when attempting to flash using Arduino. I’m a pretty experienced embedded programmer but a newbie to the NodeMCU and Arduino so I’m sure there is some trivial step that I am missing given the success of so many others. Others have had similar problems, but I don’t see any concrete things that were done to solve there problem that apply here.

    Can you offer any suggestions to help me move forward on this?

    • Ho dear do you need use phyton for dump or download.

      Pls install phyton27 and try speed com 11520

      Regards cento

  • Can i control it from internet not from local network? Im using Sonoff basic.

  • Hello friend i have dump for 2.0.2 sonof pow
    File bin.
    Installed espurna and other.
    I have reinstalled original fw with phyton and ftdi232.

    Do you have backup bin for 2.0.4 by phyton.

    I need update original firmware. 1024byte

    Update new rev 2.0.6 not working.
    Changed Wi-Fi
    Changed router
    Changed dns

    3 day not update tryyy

    Have help ?

    Thanks for news.

  • Yes by other connection you control sonoff. Sonoff need Wi-Fi connection and internet in office for working.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.