Sonoff-HomeAssistant (Alternative firmware for Sonoff Switches for use with mqtt/HA)


Hey Guys

A while ago I started playing with Sonoff switches for use with HA. If you don’t know what they are you should have a look at them for your HA project. Very cheap and easy WiFi controlled relay in an easy to install unit based on a ESP8266 chip.

If you don’t need dimming, they are the way to go.

I created a Github repository for anyone who wants to get going fast with them. Have a look here -

Any questions or suggestions I would be happy to answer.

Hope this helps some people get going quickly.

***EDIT: I added additional code to use the Sonoff for Temp / Humidity sensor as well. More details at the Github repository.

Kman :smiley:

The best way for home automation: relays?
Mosquitto with Self Signed Certificate Guide or examples?
Sonoff sockets
ESP Relay / Sonoff default state when cycling power
Immersion heater
SONOFF SV flashed with Espurna is overheating, why?
Is this the place to ask newbie questions?
433toMQTTto433 Bidirectional Arduino Gateway

Hi Kman,

I am currently running my sonoff-relay with homie-esp8266, which is easily to integrate into HA. But it’s always good to have an alternative and I will definitely check this out.

Thanks for your efforts!


Hey jalmeroth

No problems. My version isn’t as fancy as homie. No app, http, setup file etc. Just change the topic in the sketch, upload and use. Personally I found the features unnecessary. I haven’t touched my installed switches since the day I commissioned them. They’ve never dropped their wireless connection and never played up.

When I initially started playing with ESP’s it was fun to get a web page from them for config. Now I don’t care so much and let HA do the controlling and forget that they’re even there :smile:

For a professional installer who needs to make changes on the fly say in a commercial installation, perhaps there would be benefits, but for most home users I recon they will just install and not worry about them again.


great one, just looking for such an api for sonoff
just follow the instructions on your github?



Yeah pretty much. You just need to know how to setup your Arduino environment and solder some pin headers in the Sonoff switch but it’s reasonably easy after that. You’ll need a FTDI adapter and cable. If you search around there are a few guides to help you get that going. They’re a solid switch though and work extremely well.



Hi! I’m waiting 3 sonoff’s from iTead, but meanwhile I’m setting up everything. Can I use the PubSub library from Nick O’Leary? I think it’s installed by default or by MySensors library. I think that Imroy’s is based on this, so it will work?



No it won’t. Even though it’s based from Nick O’Leary library, the calls to the functions are completely different. If you have that setup, I recommend you install a portable version of the Arduino IDE that won’t affect your main install. Basically download the non-installer version of the IDE for your O/S. When you unzip it, stick it into a directory of your choice. It doesn’t really matter. For example D:\arduino_lmroy or whatever you want so you remember. Now before you launch the IDE for the first time create a directory called \portable in D:\arduino_lmroy. In the portable directory create another directory called \sketchbook. Now launch the IDE, go to preferences and point your sketchbook directory to D:\arduino_lmroy\portable\sketchbook.

Now you have a complete stand alone version of the IDE. Install the lmroy version of pubsubclient in D:\arduino_lmroy\portable\sketchbook\libraries. Run the Boards Manager and install the latest version (2.3.0) of the esp8266 boards.

That’s it you’re good to go.



Thanks for the answer!
I’m on OSX, so no portable app, I think, so I’ll just replace library when programing the sonoff.
I’ll update when received the switches and test on my installation.


Hello, KmanOz. thank you for your very useful instruction. Hello danichispa. thank to you too. I just received Sonoff yesterday. I strictly followed your instruction. and I did soldering and uploading your sketch ESPsonoff-v1.0p to Sonoff successfully. I installed Mosquitto MQTT to Raspberry Pi3 by following BRUH Automation youtube video. I put the following code to the configuration.yawl. and I connected all the A.C. wires and turned the unit on. When I click to On/Off switch in the front end. At the beginning, It doesn’t works. when I started the web UI, it shows the ON state from the start. after I tried to switch it off, it bounced back to show ON state every time. But when I shut down the unit several times. It works perfectly once for about an hour until I shut it down. When I shut down and powered up the unit it stops working. Have I missed something in my configuration. and What is the correct way to start the Sonoff. Thank you very much for your great contribution.

I put this code in to the newly installed Home assistant.

  port: 1883
  client_id: home-assistant-1
  keepalive: 60
  username: parnupong
  password: [*********]
  protocol: 3.1
  platform: mqtt
  name: "Living Room"
  state_topic: "home/sonoff/living_room/1/stat"
  command_topic: "home/sonoff/living_room/1"
  qos: 1
  payload_on: "on"
  payload_off: "off"
  retain: true


You seem to have everything OK except for the version of Mosquito you are running. Because I use a specific version of PubSubClient, it requires protocol v3.1.1 not v3.1 that you’re running.


Thanks to you, KmanOz. Now my Sonoff works perfectly. So I don’t have to make messy electrical wiring anymore. Thank you very much for sharing.


Glad to hear it’s all working for you.


Also have a look at ESPEasy which also has support MQTT and looooots of other sensors and stuff. They have created a nice firmware for the ESP8266. It has a nice webinterface and also supports OTA firmware updates i thought. On their forum they also discuss the Sonoff.


Thanks for that. Yes as I’v mentioned before, there are many versions of firmware for the ESP8266 based Sonoff unit. I’m not sure why after you have everything going with mqtt that you would need to access to your Sonoff via http. I have 20 in my home and couldn’t think of anything worse than having to access 20 different ip address’s when you have HA that pulls it all together. I install these things in the wall behind a wall switch and wire them in parallel. Apart from on and off I really don’t need them to do anything else. Also the way they are built, there is very little to no room in them for sensors etc. ESPeasy is great if you are building a custom project from scratch. I designed this firmware specifically for a Sonoff and 1 purpose only, ON or OFF.


Hello KmanOz, thank you very for your last suggestion. After I manage to get Sonoff to work, It is very stable. But when I tried to cut off the power supply then I waited for a while. I turned the electricity on. It powered up but stops communicate with the Web UI in front end. I tried to press the button on Sonoff several times to activate the communication. Sometimes it takes ten minutes. Sometimes more than ten minutes. Sometimes It never go back online. Last night I had to leave it as it was. But in the morning It starts working again and it becomes very stable. As long as I leave its power on, It is very stable. But Once I shut down the unit It is very hard to restart it to work again. May be I don’t know the proper way to start Sonoff. Any comments would be very useful to me. Thank you very much in advanced.


When you turn the switch on, do you notice the LED. Does it flash fast 4 times?


Yes, it flash fast 4 times. and it takes a rest for sometimes (may be about 5 or 10 minutes) and it flash 4 times again. Thanks, KmanOz.


Well you have a problem. It’s either losing it’s connection to your mqtt broker, which could be network related, or it is resetting by itself which I have seen on some Sonoff switches (or should I say esp8266’s). You are going to have to troubleshoot and start understanding mqtt. I would look at logs of your broker to start with. You can also leave the FTDI cable plugged into the Sonoff Switch and power it that way. Open a serial console and have a look at what the switch is doing and why it’s rebooting.


Your suggestion is very useful to me. Thank you very much. I will look into MQTT log file and connect FTDI cable to see the result on serial monitor as you guided. It is very kind of you.


Also check to see this isn’t happening to you.