Introduction: Hacking a Sonoff Touch Panel to Work With MQTT and Homeassistant

Picture of Hacking a Sonoff Touch Panel to Work With MQTT and Homeassistant

There are some great hackable devices in the SONOFF range such as the original SONOFF switches, the Slampher and the SONOFF Luxury wall plate which is the subject of this instructable.

These devices are based around the ESP8266 or ESP8285 WifFi modules and are easily hackable.

I'll only cover here how to convert a wall plate to run with MQTT and HomeAsisstant, I wont cover hooking it up to the mains, mains bites bad if you mess things up, and I don't want to be responsible for you injuring, killing or worse still pishing off your wife as you just burnt down the house...

One thing to note, is that if you wish to use these devices in the UK, I'm not sure they comply to CE or UK safety laws.

You should also note that you will need a neutral for the devices to work, most light fittings in the UK will only have live and the switch line.

Step 1: What You're Going to Need

  • SONOFF Luxury Wall plate.
  • FTDI or and Arduino Uno with a DIL Atmega chip.
  • 5 Jumper leads suitable for your FTDI or Arduino to connect to your newly adapted panel.
  • A few centimetres of wire wrap or other such wire.
  • USB Lead to hook your Arduino UNO or FTDI up to your PC.
  • Soldering Iron, Solder.
  • 5 Way right angle header.
  • Screw driver.
  • Needle nosed pliers.
  • Magnifying glass/helping hands.

Arduino IDE installed and ready to go Arduino.

Overview of Arduino install for ESP8266 by TrakerJ.

The following libraries will also be needed to be installed in your Arduino IDE

WifiManager by tzapu PubSubClient by Nick O'Leary

Installing Arduino Libraries by MertArduino

Step 2: Step 2: Dismantling the SONOFF

Picture of Step 2: Dismantling the SONOFF

Simply insert a bladed screw driver into the tab as can be seen in the image above. Give the screw driver a twist and it will soon pop apart. Gentle though, don't want to break the glass panel so early in the game.

Step 3: Step 3: Removing the ESP Module Board

Picture of Step 3: Removing the ESP Module Board

You can now remove the board we are interested in. It has a 2x2 header at the top of the board and a small double sided sticky pad at the bottom.

Carefully lift the board up using your screwdriver if need be, to work the board away for the sticky pad. Be gentle, we don't want to break the board or bend the pins on the 2x2 header

Step 4: Modify the Board

Picture of Modify the Board

Now we need to break out the soldering iron.

While the iron is heating we need to prepare our 5 way header.

With a pair of long nose pliers, carefully push the 5th pin further down into the plastic header thereby lengthening the solder pin.

Once this is as long as can be, gently bend the lead out in line with the header plastic. You can see this better in the image above.

Now insert the 5 way header into the PCB and solder the 4 pins in place on the reverse of the board.

We now need to connect GPIO0 on the ESP8285 to the 5th pin of our header.

Using a magnifying glass and a steady hand, solder the short length of wire to GPIO0 as can be seen in the second image.

Once cooled, carefully dress the wire over the board and take it up to pin 5 of the header and again with your magnifying glass and a steady hand solder the wire on to pin 5.

You can apply a dab of superglue or hot melt glue to the wire to stop it wiggling around and breaking your solder joints.

Step 5: Hook It Up to Your FTDI/UNO

Picture of Hook It Up to Your FTDI/UNO

I use an UNO instead of an FTDI, only reason being there's always one on my desk and its quicker to pop the MCU out and use that than hunt through my component drawers for an FTDI, yes I know lazy...

Any way we now need 5 Dupont wires, I'm using Female to Male

Header Colour Arduino

1 green GND

2 brown TX

3 orange RX

4 red 3.3V

5 yellow GND (This is the bent pin)

Check your connections over, paying attention to Pin 4, as this must only be connected to 3.3V, connecting to 5V will more than likely kill the ESP module.

Once you're happy with the connections you can go ahead and hook up the USB lead.

Step 6: Run Some Tests

Start the Arduino editor and make sure it is connected to the correct serial port, if using the UNO it will be labelled along the lines of Port X (Arduino/Genuino Uno) where X is the actual port number.

Change the board to "Generic ESP8285 Module"

Download the Test_Sketch.ino file above, and save it to a folder called Test_Sketch

Open this in your Arduino IDE and Upload it to your touch plate.

Unplug Pin 5, this only needs to be connected while you are uploading your sketch

Open the Serial monitor.

Once you see the WiFi Led light on your touch plate, each time you touch the touch sensor it should light and you should see a message in the Serial Monitor indicating the touch sensor is activated.

If you are unable to upload the sketch try swapping pins 2 and 3, (TX/RX pins on the UNO or FTDI)

Step 7: The Last Sketch

Download the Live_sketch.ino above, save it to a folder Live_sketch

Load it into your Arduino IDE and edit the following lines..

Line 26:

const PROGMEM char* MQTT_CLIENT_ID = "Study Test Switch";

Change "Study Test Switch" to something suitable for your installation.

Line 27:

const PROGMEM char* MQTT_USER = "MQTT User";

Change "MQTT User" to the user name used to connect to you MQTT server and

Line 28:

const PROGMEM char* MQTT_PASSWORD = "MQTT Password";

Change "MQTT Password" to your MQTT servers password

Lines 29 and 30:

const char* MQTT_LIGHT_STATE_TOPIC = "study/swtest/status"; const char*

const char* MQTT_LIGHT_COMMAND_TOPIC = "study/swtest/switch";

Set the state and command topics inline with your naming conventions

Line 70:

WiFi.hostByName("", MQTT_SERVER_IP);

Change "" to the fully qualified domain name of your MQTT server.

Give your changes the once over to make sure they are correct then upload the sketch.

Step 8: Connect the Wall Plate to You WLan

Picture of Connect the Wall Plate to You WLan

After a couple of minutes open up your phones list of Wireless networks

Search for the network called "TaTaTatooouchMe" and join it.

You will now be asked to authenticate which will produce a page as in the first image

Click ConfigureWiFi and You can now select your WLan, enter the passkey and click save.

After 10-15 seconds you device will be connected to you WLan

Check you device has reverted back to you WLan and the network "TaTaTatooouchMe" has disappeared

If not repeat the steps again

Step 9: Add the Touch Plate to Home Assistant

Picture of Add the Touch Plate to Home Assistant

I separate all of my devices into separate files which I then include in the main configuration.yaml.

Please add this device to wherever you keep yours.

- platform: mqtt

name: "Main Light"

state_topic: "study/swtest/status"

command_topic: "study/swtest/switch"

payload_on: "ON"

payload_off: "OFF"

optimistic: false

You can alter the name to whatever you like, but you must make sure state_topic and command_topic match what you entered in the Live_sketch text on lines 29 and 30.

Run a test to make sure everything is ok with your new entry

/usr/local/bin/hass -c ./ --script check_config

If all appears ok restart hass

service hass-daemon restart

You should now see the new light switch in the home assistant gui.

Check you can toggle the switch from within Home assistant and vice-versa from the switch to home assistant.

Re-assemble your SONOFF and my work here is done.


liverpool1234 (author)2017-10-26


After a failed first attempt I have finally been able to flash my device, so thank you for your help.

would it be possible to connect the sonoff touch to OPENHAB instead of Homeassistant using the above method and if so how would you go about this?

Many Thanks

El Ape (author)liverpool12342017-10-26

Ahh glad you managed to get it sorted in the end :D

I think OpenHAB supports MQTT so I can't why not but as to how its done I don't know I'm afraid as I couldn't get on with it.

I'm sure you'll be able to find some help in their forums though?


liverpool1234 (author)El Ape2017-10-26

Thank you once again for your help look forward to any of your future guides

liverpool1234 (author)2017-10-03


Need your help i am trying to upload the Test Sketch to my Sonoff touch however not matter what i do i always receive the same error message:

espcomm_sync failed

espcomm_open failed

espcomm_upload_mem failed

could you please tell me what i am doing wrong ?


El Ape (author)liverpool12342017-10-10

Hi, I know I replied to this question though I have no idea where it's gone so here goes again...

You need to check you are connected to the right port, easy way, plug in your FTDI, open the ports menu option, check the ports available. Close the menu, disconnect your FTDI, re-open the ports menu and which ever one is missing is the port to select when you want to upload.

Have you selected the correct board? The Sonoff touch use the ESP8285, from the tools menu, click Boards and scroll down to Generic ESP8285 Module.

Check your TX/RX connections, just swap them round and try uploading again, I nearly always get these arse about face :P

Make sure GPIO0 is pulled low when you power up otherwise the module wont be in flash mode and you wont be able to upload.

Hope this one sticks about this time, Cheers

liverpool1234 (author)El Ape2017-10-12

Hello thanks for your response. I have tried all the above and still no joy. Am now thinking I may have damaged the board at some point. Thanks for your help anyway

El Ape (author)liverpool12342017-10-12

Have you tried using it with the ewlink app?

Will at least be able to prove if it is damaged or not.

El Ape (author)liverpool12342017-10-03


Four things to try.

1 Make sure GPIO0 is pulled to ground when you power up. I hook mine up using a breadboard between the FTDI and the touch, it just makes it easier to handle the extra gnd connection for GPIO0

2 Check the Tx/Rx connections, just swap them over and try again.

3 Check you have selected the right board in the IDE, click tools, Board and select "Generic EPS8285 Module"

4 Check you have the right port selected, if you have more than one serial port plug in you're FTDI, wait for it to be detected by your system and then check the ports available in the IDE, unplug the FTDI and check again, you can now be sure you have the right port.

Good Luck

Swansong (author)2017-05-23

Thanks for sharing :)

El Ape (author)Swansong2017-05-23

Thanks for reading :D

DanI54 (author)El Ape2017-10-10

Hi Ape, Is it posible to hack/attach a Temp sensor to the Sonoff Touch? I would like to monitor room temp in house thru all sonoff Touch devices.

Regards Dan

El Ape (author)DanI542017-10-10


can't see any reason why not, you will just need to identify which GPIO's you want to use and solder some wires to the module to bring out to your chosen temperature sensor. However I would of thought with the sensor rammed into the confined space of the back box with all the mains cabling and the Touch there may not be a great deal of space, and your may well see your temperature readings are higher than ambient.

Let me know how it goes though, would be interested how you get on


diy_bloke (author)2017-09-23

There is an error in your LiveSketch.ino

line 14,

#define fDebug true;

should be

#define fDebug true

El Ape (author)diy_bloke2017-09-25

Thanks for that, have updated now. :D

diy_bloke (author)El Ape2017-09-25

I saw you published MQTT as

client.publish(MQTT_LIGHT_STATE_TOPIC, LIGHT_OFF, true);

I usually only do


What is the use of the 3rd parameter?;

Also, I never got the WiFi manager part to work. Just wouldnt connect so I took it out :-) . Made a direct logon, and added OTA

El Ape (author)diy_bloke2017-09-26

It's to do with message retention

As per the documentation...

int publish (topic, payload, retained)

Publishes a string message to the specified topic.


  • topic - the topic to publish to (const char[])
  • payload - the message to publish (const char[])
  • retained - whether the message should be retained (boolean)

    • false - not retained
    • true - retained

There's a good explanation of retained messages here...

Shame about the WiFi manager, it's one of the few libraries that just worked out of the box for me.

I've always been led to believed because of the extra space required for OTA there simply wasn't the room to squeeze it all in on the 1Mb devices. Apart from all that, the amount of devices I have dotted around, when I have used it I find its all to easy to flash the wrong device and end up in a right old two and eight :-/

diy_bloke (author)El Ape2017-09-28

I am stupid, hit me over the head with a hot soldering iron.
The hivemq link looked very familiar, so I looked again at my earlier programs in which I do the Publish(topic,message) through a procedure that ofcourse after I wrote it, I hardly looked at anymore. I totally forgot that I added the retention boolean in that procedure.
Getting old and forgetful. Stupid me

diy_bloke (author)El Ape2017-09-26

Ah great, thanks. I never realised that.
To a large extend I agree with the OTA concern :-)
Ofcourse with the simple functionality of the Sonoff Touch there isnt much need for updates, but with the WiFi manager not working for me, that is a simple way to change the network credentials if necessary. There was still room enough.
The OTA tells me which device is on line, but true you could by accident flash the wrong device.
I have no idea why the WiFi manager wasnt working, truthfully I havent had much luck with it at all.
Anyway, I am quite happy with yr program, could have written something myself or taken tasmota, but with the slight adaptations mentioned it worked great for me

El Ape (author)diy_bloke2017-09-26

Glad it was of use to you :)

diy_bloke (author)El Ape2017-09-26

Anyway, tnx. I thought I knew quite a lot about MQTT and PubSub, but I didnt know about that boolean parameter

ShaneK47 (author)2017-09-15

Hi, noob here and thank you so much for your nice post, here are some questions after reading:

1. Does this whole hacking method can also apply to the 3 gang sonoff touch?

2. When you mentioned the gpio0 to ground, does it means I need to always connect them together during programming/flashing? or just connect them before power on?(because I read somewhere said that it only needs to be connected when power up chip, after that it can be disconnected but still the board is in programming mode)

3. Can this work with homekit and openhab?

sorry about the noob questions


diy_bloke (author)ShaneK472017-09-23

OpenHAB has no trouble with MQTT so it will work with this

El Ape (author)ShaneK472017-09-15

Hi Shane,

you will need to add to the code, if you think of each gang as being a separate switch you will need to include code to handle the two extra switches.

GPIO0 does only need to be taken to ground when you power up however leaving it hooked up while you are programming will not affect things. Of course once you have finished you will need to disconnect.

Can't really help you with the other systems, I've not heard of homekit and I couldn't get along with openhab so never tried it with and of my hacked kit. As long as they support MQTT I cant see it being a problem.

Good luck

diy_bloke (author)2017-08-27

Nicely done.

I was wondering, you keep mentioning the 2x2 header, but i understand correctly that plays no role in this?

El Ape (author)diy_bloke2017-08-27


The 2x2 header connects the touch panel to the main board of the Sonos touch panel.

If you look at the image in Step 3, you can see the 2x2 header

diy_bloke (author)El Ape2017-08-27

thanks, yes, in the mean time I saw it on some other pics. It was just that the way you mentioned it I initially thoughtit was going to play a role somewhere :-)

ShakeelR2 made it! (author)2017-06-04

Hi, thanks for the tutorial

Which point should I connect the 5th bent pin (GPIO) to my FTDI usb (not using Uno)?

I'm using this one btw

El Ape (author)ShakeelR22017-06-04

Hi, you need GPIO0 connected to ground when you want to send your sketches to the ESP module.. I find it easiest to hook up all your wires between the FTDI and the module and then plug in the USB lead. This will bring the unit up in flash mode and allow you to upload sketches.

Good luck ?

ShakeelR2 (author)El Ape2017-06-04

Or should I attach a wire from 5th header pin to the 1st header?

diy_bloke (author)ShakeelR22017-08-27

Pin 1 is connected to ground

Pin 5 has to be temporarily connected to ground

If you make a solder connection from pin 5 to pin 1 you will be able to program the device but afterthat u cannot use it as it will always be in program mode,

so the solution is really very simple: connect gpio0 to ground on power up for programming and when you are done programming remove that connection.
How you do that is mainly your choice but if you use an ftdi module, a small breadboard seems the easiest

ShakeelR2 (author)El Ape2017-06-04

How should I connect GPIO to ground when GND is already connected to it?

El Ape (author)ShakeelR22017-06-04

Plug the FTDI into a bread board, and then you can connect both the GND and GPIO0 of the SONOFF with the GND on the FTDI using the the breadboard rails.

About This Instructable




Bio: All round geek, love tinkering with microcontrollers. pcs. and just making stuff
More by El Ape:ESP8266 Based Temperature Sensor Connected to Home Assistant and MQTTHacking a Sonoff to Work With Home-Assistant and MQTTBuilding an Interface for 433Mhz Controlled Mains Sockets and Home Assistant
Add instructable to: