Plenty of cheap Wi-Fi plugs, relays and switches are built around an Espressif chip and ship with firmware that talks only to the manufacturer's cloud. Tasmota replaces that firmware with an open one that runs entirely on your network: a web page on the device, a console, timers and rules on the device itself, and MQTT for anything bigger. This guide covers what you need, how to flash safely, the first configuration, and how to wire the result into an MQTT broker and Home Assistant.

Check the hardware first

Tasmota runs on Espressif chips only: ESP8266, ESP8285, ESP32, ESP32-S and ESP32-C3. Many newer "smart" devices use other chips (Tuya modules based on Beken or Realtek parts are common), and Tasmota will not run on those. Before you open anything:

  1. Search for your exact model on the community Tasmota Supported Devices Repository (templates.blakadder.com). Each entry lists the chip, how it was flashed and the template you will need later.
  2. Check the hardware revision. The same product name can hide a different chip in a later batch.
  3. Look for an "OTA" note. The Tasmota docs are blunt about over-the-air conversion: Tuya-Convert "does not work in 99% of cases" with current firmware, and the Sonoff DIY method no longer works. Shelly devices running the older MgOS firmware are an exception and can still be converted over the air. For everything else, plan on opening the case and using a serial adapter.

What you need for serial flashing

  • A USB-to-serial adapter that supplies 3.3 V. The docs recommend adapters based on the CH340G or the CP2102N (such as VoltLink). Never feed an ESP 5 V. The chip also needs at least 150 mA, which some cheap adapters cannot provide; if the flash keeps failing, power the board from a separate 3.3 V supply with a shared ground.
  • Jumper wires or pogo pins, and sometimes a soldering iron for the header pads.
  • A flashing tool. The Tasmota Web Installer runs in a Chromium-based browser (Chrome or Edge) and needs nothing else installed. Alternatives are Tasmotizer (ESP82xx only), ESP-Flasher and Espressif's esptool.

The single most important safety rule: the device must never be connected to mains power while it is open or wired to your computer. Flash with the case open and the plug unplugged, every time.

Wiring and flash mode

Connect four lines plus a way to pull GPIO0 down:

Adapter ESP device
3V3 3V3 / VCC
GND GND
TX RX
RX TX

TX goes to RX and RX goes to TX. Getting this backwards is the most common reason for "no serial data received".

To enter flash mode, GPIO0 must be connected to GND while the chip powers up. On many Sonoff-style boards the physical button is already wired to GPIO0: hold it, connect power, then release after a couple of seconds. On other boards you hold a jumper wire from the GPIO0 pad to GND during power-up. You need to enter flash mode again for each operation, such as backup, erase and write.

Back up, erase, flash

Take a backup of the original firmware before you change anything. With esptool on an ESP8266 with 1 MB of flash:

esptool.py --port COM5 read_flash 0x00000 0x100000 fwbackup.bin

Replace COM5 with your port (/dev/ttyUSB0 on Linux). Then re-enter flash mode and erase:

esptool.py --port COM5 erase_flash

Then re-enter flash mode and write Tasmota:

esptool.py --port COM5 write_flash -fm dout 0x0 tasmota.bin

For ESP32 devices use the tasmota32.factory.bin image (or the variant for your chip) instead. If you use the Web Installer, it handles erase and write for you; just pick the right build and tick the erase option.

First boot and Wi-Fi setup

Disconnect the adapter, close the device properly, and only then plug it in. A freshly flashed device starts its own access point named tasmota_XXXXXX-####. Connect to it from your phone or laptop and open 192.168.4.1 if the setup page does not appear by itself. Pick your 2.4 GHz network and enter the password.

Two things from the docs save time here:

  • The access point stays up for 3 minutes after boot. If you miss the window, power-cycle the device.
  • Tasmota does not accept Wi-Fi passwords of 64 characters or longer, and special characters in the password can cause problems.

Once the device joins your network, find its IP address in your router's DHCP list and open it in a browser. Then do three things right away:

  1. Set a web password. In Configuration > Configure Other, set the Web Admin password. The user name is admin. Tasmota's web server has no HTTPS, so keep the device on your LAN or IoT VLAN and never forward its port to the internet.
  2. Give it a static DHCP lease on your router so its address does not change.
  3. Run SetOption65 1 in the console if your power supply is not perfectly stable. It disables the "fast power cycle" detection that can otherwise reset a device to factory defaults after a few quick power interruptions.

Apply a template

A generic Tasmota build does not know which pin drives the relay, the LED or the button on your particular device. That mapping is a template, a short JSON string you copy from the device repository. It looks like this:

{"NAME":"Example Template","GPIO":[416,0,418,0,417,2720,0,0,2624,32,2656,224,0,0],"FLAG":0,"BASE":45}

To apply it in the web UI, open Configuration > Configure Other, paste the string into the Template field, tick Activate and save. From the console you can do the same with:

Template {"NAME":"Example Template","GPIO":[416,0,418,0,417,2720,0,0,2624,32,2656,224,0,0],"FLAG":0,"BASE":45}
Module 0

Module 0 tells Tasmota to use the template you just stored. After the restart, the button should toggle the relay and the web page should show the right controls. Use the template from the repository entry for your model and hardware revision, not the example above.

Connect it to MQTT

The web page is enough for testing, but MQTT is where Tasmota becomes useful. Point it at your broker (Mosquitto, for example) with one Backlog line in the console:

Backlog MqttHost 192.168.10.5; MqttUser tasmota; MqttPassword your-password; Topic plug_desk

Tasmota uses three topic prefixes, built from the default FullTopic %prefix%/%topic%/:

  • cmnd/plug_desk/... for commands you send,
  • stat/plug_desk/... for responses and state changes,
  • tele/plug_desk/... for periodic telemetry.

Test it from any MQTT client:

mosquitto_pub -h 192.168.10.5 -u test -P secret -t cmnd/plug_desk/Power -m TOGGLE
mosquitto_sub -h 192.168.10.5 -u test -P secret -t 'stat/plug_desk/#' -v

You should see stat/plug_desk/RESULT {"POWER":"ON"}. The device also publishes Online or Offline on tele/plug_desk/LWT, which is handy for spotting devices that have dropped off Wi-Fi, and sends sensor and energy data on tele/plug_desk/SENSOR every TelePeriod seconds (300 by default).

A few notes on security: Tasmota speaks MQTT 3.1.1 by default. ESP32 builds support TLS to the broker; on ESP8266 it is not available in the standard builds. On a home network the usual approach is a broker that requires a user name and password and an IoT network segment the devices cannot leave.

Add it to Home Assistant

Home Assistant has an official Tasmota integration that discovers devices over MQTT. With the MQTT integration already set up, add the Tasmota integration, and any device with SetOption19 0 (the default) shows up with its switches, lights and sensors. Two caveats from the Tasmota docs:

  • Leave the FullTopic at its default; discovery depends on it.
  • If you use the Mosquitto app with an ACL file, Tasmota devices need write access to tasmota/discovery/#.

Do not confuse this with SetOption19 1, which switches the device to the older generic MQTT discovery. The Tasmota docs say that method was removed from Tasmota builds, so leave it off.

Common mistakes

  • Retained power messages. If something publishes cmnd/<topic>/Power with the retain flag, the device will apply that message every time it reconnects and override its own PowerOnState. People call this "ghost switching". Clear the retained message on the broker and send commands without retain.
  • Flashing on mains. Worth repeating: open devices are never plugged in.
  • Wrong template revision. A relay that clicks but a button that does nothing usually means the template is for a different board revision.
  • Exposing the web UI. No HTTPS means the password travels in clear text. Keep it on the LAN.
  • Forgetting updates. Tasmota can update itself over the air from the Firmware Upgrade page. Read the release notes first, especially if you rely on a feature that a build might move or drop.