Skip to content

Getting Started

Prerequisites~

Needed Hardware~

ESP8266 or ESP8285 Device~

Any variation of the ESP8266 chip can be flashed with Tasmota.

Serial-to-USB Adapter~

The power supplied to the device is one of the most important elements for both flashing the device and for stable operation. You must ensure that the device receives sufficient power (current AND appropriate voltage level) to properly flash the firmware on the device.

  • RECOMMENDED CH340G is the most reliable and the cheapest one to boot (1, 2).
  • FTDI FT232 - these adapters have a lot of fakes in the market so buy only from reliable sources (example). Buy only the variant with a separate 3.3V regulator on PCB!
  • CP2102 or PL2303 - works with certain devices, but using an external 3.3V supply might be necessary. Not recommended for beginners!
  • RaspberryPi - only for advanced users. External 3.3V supply necessary.
  • NodeMCU You can also use a NodeMCU (or similar) as a reliable serial-to-USB adapter if you disable the onboard ESP8266 by bridging the RST and GND pins, and connect TX and RX straight to another ESP82xx instead of crossed.

Note

Don't forget to install drivers for your serial-to-USB adapter.

Danger

Some adapters can be switched between 3.3V and 5V for the data pins, but still provide 5V on the power pin which will irreparably destroy your device. You MUST make sure the data (RX and TX) and VCC pins are set for 3.3V.

NodeMCU and D1 mini (Pro/Lite) boards have a micro USB upload port and don't require an adapter.

Soldering Tools~

To solder you'll of course need a soldering iron, soldering tin and some flux. If you're new to soldering check out some soldering tutorial videos while you're at it.

If you're intimidated by soldering you could get away with holding the headers with jumper wires in the pin holes during flashing but it is not a fool proof process and flashing might fail.

Jumper wires~

You could use any kind of wire but jumper wires (also called DuPont wires) are more practical than soldering and desoldering.

Pin Headers~

Pin headers come in male or female version. Choose according to your jumper wire connectors.

Computer with Linux, Windows or MacOS~

You need a computer with a USB port to upload the firmware to your device and configure it.

Smartphone~

Tasmota installed from a precompiled binary needs to be configured to work with your Wi-Fi network before you can access the Tasmota web UI. This is usually done by connecting to a Tasmota Wi-Fi Access Point with your smartphone (or tablet or computer with Wi-Fi).

Needed Software~

Tasmota Firmware Binary~

Download a Tasmota firmware binary file (.bin). If you're not sure which binary is the right one for you just start with tasmota.bin or consult the builds table to see which features you need.

Official release binaries can be downloaded from firmware server.

Latest development branch binaries are available only from our OTA server. The latest merged development code is compiled hourly.

Flashing Tool~

  • Tasmotizer - NEW flashing and firmware download tool just for Tasmota. (Windows, Linux or Mac)
  • Tasmota PyFlasher - flashing tool intended for Tasmota. (Windows or Mac)
  • ESP-Flasher - GUI flasher for Tasmota based on esptool.py for ESP82XX and ESP32. (Windows or Mac)
  • NodeMCU PyFlasher - easy to use GUI flasher based on esptool.py. (Windows or Mac)
  • Esptool.py - the official flashing tool from Espressif. (Requires Python)
  • Esptool executable - Esptool in executable form, no Python required. (Windows, Linux or Mac)

Serial Terminal~

A program that connects to your Tasmota device directly over the serial connection you used to flash it.

This is an optional way to configure your device using Commands and Backlog.

  • Termite - simple terminal for windows
  • Termie - open source clone of Termite
  • Putty - popular client available on every platform
  • Minicom - one of many Linux terminals

Tip

Enable local echo so that you can see what is typed and transmitted to the device. Enable Append CR+LF since every request needs to end with <CR><LF>.

MQTT Knowledge~

Tasmota is designed to be controlled and communicate via MQTT. To use it to its fullest potential you need an MQTT broker.

Read our article on MQTT to learn why it is essential in Tasmota.

Compiling Tools (Optional)~

If you want to modify the code or default settings and compile your own Tasmota firmware.

Hardware Preparation~

We need to connect to the serial programming interface of the ESP8266 chip. This is done by connecting our serial-to-USB converter TX and RX pins to the ESP8266 RX and TX pins and powering the chip with the 3.3V and GND pins.

In most cases those pins are available on the PCB in the form of pin holes or solder pads but pin headers or jumper wires need to be soldered or otherwise applied. In some cases you will need to solder wires directly on the chip's pins which requires some experience and good soldering equipment.

BEWARE!

DO NOT CONNECT DEVICES TO MAINS POWER WHILE THE COVER IS OPEN AND CIRCUIT BOARD IS EXPOSED!!!

Sonoff Pow Bricked

NEVER TRY TO FLASH WHILE YOUR DEVICE IS CONNECTED TO MAINS POWER!!!

YOU CAN BE ELECTROCUTED IF YOU DON'T KNOW WHAT YOU ARE DOING!

If you are not careful, your own health will be in danger. Shorting your serial interface with mains AC power will fry your device and serial adapter and will also harm or destroy your computer. It is important to always have all mains power cables disconnected from the device while being connected via serial or even while the case of the device is opened.

Serial Connection~

Each device has its pins labelled differently. If the labelling isn't visible on the PCB please refer to the devices flashing guide or search the Internet for correct pin locations. Device specific instructions and restrictions are documented in the Tasmota Device Templates Repository. Pinouts for commonly used Wi-Fi modules are found here

When you have identified pins on your device, connect wires according to the table:

Serial adapter ESP8266 device
3V3 3V3 or VCC
TX RX
RX TX
GND GND

Note that TX from your adapter goes to RX on the ESP8266 device and RX from adapter goes to TX on the device! Image courtesy of https://www.domo-blog.fr/

Programming Mode~

Typical GPIO0 Location

ESP8266 needs to be put into programming mode or flash mode before the firmware can be uploaded. This is done by pulling the GPIO0 pin to GND while the chip is booting.

On most devices the installed control button is connected to GPIO0 and GND, making entering Programming Mode very easy. On others you will need to bridge the pins on the PCB or directly on the chip with a jumper wire. GPIO0 is always in the same location on ESP8266 and ESP8285!

Device specific instructions are documented in Tasmota Device Templates Repository.

To put the ESP8266 into Programming Mode:

  1. Disconnect serial-to-USB adapter and power
  2. Bridge GPIO0 and GND (by pressing the on-board button or connection with a wire)
  3. Connect the serial-to-USB adapter to your computer
  4. After a few seconds disconnect GPIO0 from GND (release button or remove the wire connection). On devices that do not provide the GPIO0 connected button, it may be easier to leave the wired bridge in place throughout the entire flashing process (erase & upload). Doing so will not create any problems. After the firmware is uploaded successfully, remove the bridge. This allows the device to boot normally.

You can test whether your device is in Programming Mode by attempting to read information from the ESP82xx chip. This requires esptool.py. Instructions on installing and using esptool are provided below. For example (COM5 will be your COM port):

  • esptool.py -p COM5 read_mac (It should read the MAC address. It may fail afterwards during Uploading and running a "stub". This is normal.)
  • esptool.py -p COM5 flash_id

If everything went well, you are now in Programming Mode and ready to continue with flashing. If the flashing process is unable to start, disconnect the device and retry the steps.

Common Mistakes~

  • Wire connections and solder joints - Double check all connections and also check for solder overflow.
  • Use a USB data cable - Some USB cables are for charging only and do not connect the data lines needed to load the firmware onto the device.
  • Insufficient power delivered over the serial-to-USB adapter. This leads to flashing failures or corrupted flash altogether. Supply more power with a separate 3.3V power supply or get an adapter with a better power supply. Be sure all DC voltages use the same GND reference.
  • Recheck your serial-to-USB adapter so to ensure that it supplies 3.3V voltage and NOT 5V. 5V will damage the ESP chip!
  • Releasing GPIO0 button/wire before booting is finished - It is safe to leave GPIO0 connected to GND during the entire programming process (erase & upload). Just be sure to remove the GPIO0 to GND bridge before booting the device for regular operation.
  • Make sure that the RX pin is connected to the TX pin between the serial adapter and your ESP device, and vice versa.
  • Erase the flash memory first and cycle power afterwards before uploading the Tasmota firmware binary. Not erasing can leave behind remnants of the previous flash contents which can interfere with the new firmware operation.

Flashing~

If you have followed Hardware preparation, your device should be in Flash Mode and ready for a Tasmota firmware binary file to be flashed. For that you need a flashing tool.

Tip

You may want to back up the device manufacturer's firmware on the one in a million chance you don't like Tasmota.

Tasmotizer!~

Tasmotizer! is specifically designed for use with Tasmota with an easy to use GUI and esptool.py under the hood.

Download the latest release for your platform. In Windows just double click the downloaded file and it'll start, no installation required. For python follow the installation instructions.

Note

If you get an anti-virus infection warning don't fret, it is a known false positive. If you're still apprehensive you can always run the Python version.

It is time to Tasmotize!

Tasmotizer UI

  1. Connect your device to the serial-to-USB adapter or plug in NodeMCU/D1 mini.
  2. Check whether the correct serial port (COM or tty port) is selected. Tasmotizer! will try its best to select the right one for you.
  3. Choose Tasmota firmware binary:
    • BIN file - browse to the Tasmota firmware binary you downloaded or compiled.
    • Release - select from a list of available release binaries
    • Development - select from a list of latest development binaries
  4. optional Backup the original device firmware
  5. Erase flash

Danger

Leave Erase before flashing checked if it is the first time flashing Tasmota on the device or you're experiencing issues with the existing flash and need to do a full erase. If you're upgrading an already flashed Tasmota and wish to keep your settings, uncheck Erase before flashing.

  1. Click Tasmotize and wait until done.

Tasmotizer progress

If the flash was successful it will display:

Tasmotizer success

Unplug your serial programming adapter or device and plug it back in or connect to another power source.

esptool.py~

Esptool is the official Espressif tool for flashing ESP8266 chips. It requires Python, if you do not have an installed copy of Python 2.x or 3.x download and install it from https://www.python.org.

Download the esptool Source code to a folder of your choice. Go to the folder and install Esptool with command

python setup.py install

Upload Tasmota~

Make sure you followed the steps to put your device in flash mode. Place your chosen firmware binary file in the same folder as esptool.py.

Esptool uses the serial interface to communicate with your device. On Windows these interfaces are named COM1, COM2, etc. and on Linux they are named /dev/ttyUSB0, /dev/ttyUSB1, etc. Before using esptool, make sure you know which serial port your programming adapter is connected to.

The following use COM5 as an example. Change COM5 with your serial port designation.

Ensure the device is in flash mode before each step.

Backup Firmware (optional step)~

Backup the current firmware with the following command:

esptool.py --port COM5 read_flash 0x00000 0x100000 fwbackup.bin
When the command completes the device is not in flash mode anymore. Repeat the process of putting your device in programming mode.

Erase Flash Memory~

Erase the complete flash memory holding the firmware with the following command:

esptool.py --port COM5 erase_flash
It only takes a few seconds to erase 1M of flash.

When the command completes the device is not in flash mode anymore. Repeat the process of putting your device in programming mode.

Upload Firmware~

Load the chosen Tasmota firmware file with the following command (e.g., tasmota.bin in this example):

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

Unplug your serial programming adapter or your device and plug it back in or connect to another power source. Your device is now ready for Initial configuration.

For proper device initialization after the firmware upload completes, power down and power up the device.

OTA Conversion~

Tasmota is NOT a developer of these tools. For help and troubleshooting you will need to get support from those projects.

  • Tuya-Convert - easy OTA flash for devices with Tuya chips, no disassembly required
  • Sonoff DIY - OTA flash for select Sonoff devices (some disassembly required)

You've successfully flashed your device with a downloaded binary of Tasmota but now you need to connect the tasmotised device to your Wi-Fi network.

Initial Configuration~

Using Web UI~

Configure Wi-Fi~

Tasmota provides a wireless access point for easy Wi-Fi configuration.

If you flashed using Tuya Convert this is the only option to set up your device.

Tasmota APConnect your device to a power source and grab your smartphone (or tablet or laptop or any other web and Wi-Fi capable device). Search for a Wi-Fi AP named tasmota_XXXXXX-#### (where XXXXXX is a string derived from the device's MAC address and #### is a number) and connect to it. In this example the Wi-Fi AP is named tasmota_3D5E26-7718.

When it connects to the network, you may get a warning that there is no Internet connection and be prompted to connect to a different network. Do not allow the mobile device to select a different network.

Warning

Wi-Fi manager server is active for only 3 minutes. If you miss the window you might have to disconnect your device from power and reconnect.

Sign in to Wi-Fi Network After you have connected to the Tasmota Wi-Fi AP, open http://192.168.4.1 in a web browser on the smartphone (or whatever device you used). Depending on the phone, it will take you to the Tasmota configuration page automatically, or you will get a prompt to sign in to Wi-Fi network or authorize. Tapping on the AP name should also open the configuration page.

Tasmota AP At the top of the page you can select one of the discovered Wi-Fi networks or have Tasmota scan again. Enter your WiFi credentials:

WiFi Network - your Wi-Fi network name (SSID Selecting the desired network name from the list will enter it automatically in this field. SSID's are case sensitive

WiFi Password - password for your Wi-Fi network
Wi-Fi password has to be under 64 characters and without special characters (e.g. asterisks) or white spaces

Click the checkbox if you want to see the password you enter to ensure that it is correct. Click on Save to apply the settings. The device will try to connect to the network entered.

Tasmota AP

If it was successful, you will see this message:

Tasmota AP

Redirecting to the new IP might not work on all phones!

The tasmota_XXXXXX-#### network will no longer be present. Therefore your smartphone will automatically be disconnected and should connect back to its data network.

Failure

Tasmota APIn case the network name or password were entered incorrectly, or it didn't manage to connect for some other reason, Tasmota will return to the "Wi-Fi parameters" screen with an error message.

Configure MQTT~

Look in your router for a newly connected device with the same name as the Wi-Fi access point. In our example it is tasmota_3D5E26-7718.

tasmota_XXXXXX is also the firmware default MQTT topic for that device

If you don't have access to your router you can find your newly flashed device with an IP scanner:

Open the IP address with your web browser and you have full access to Tasmota.

Now is the time to set up MQTT and the last remaining, but equally important, step:

Configure Template or Module~

Configure your device using Templates in Configuration - Configure Template or Modules in Configuration - Configure Module.

Your device running Tasmota is now ready to be controlled.

Check out all the supported devices in Tasmota Device Templates Repository

Configure Other (optional)~

Configure your device name which is displayed in webUI and used for Home Assistant autodiscovery.

Configure web admin password for the webUI. Default username is admin. This type of security is rudimentary since Tasmota doesn't use HTTPS, do not expose your device outside of your local network.

Using Serial Terminal~

If you flashed the device using serial-to-USB adapter (or it is a NodeMCU/D1 mini) you can take advantage of the existing connection and configure your device over the serial connection using Commands.

First you will need a Serial Terminal program.

In this example Termite on Windows is used.

Download Termite and extract the .exe file, no installation necessary. Connect your serial-to-USB adapter or NodeMCU/D1 mini to the computer.

Termite setup

Open Termite and set it to the proper COM port (Termite selects the first available port by default). Set Baud rate to 115200 and Forward to none.

First boot

Connect your device to the serial-to-USB adapter. You should see the initial boot output in Termite. If your screen is empty type status in the bottom command bar and hit enter. If you get a return message from your device similar to the one displayed under purple status you're all set.

To configure Tasmota you need to issue commands, some commands will reboot your device and to avoid that we will use the Backlog command feature.

Configure your Wi-Fi network and a secondary Wi-Fi network

Backlog ssid1 <yourssid>; password1 <your_password>; ssid2 <your_ssid2>; password2 <your_password>
After restart

Device will restart and connect to your network. It will display your devices newly assigned IP. Direct your web browser to that IP address to access the Web UI for further configuration and control.

Configure MQTT broker address, MQTT credentials, unique device topic and OTA url to the latest official release

Backlog mqtthost <yourhost>; mqttuser <user>; mqttpassword <password>; topic <unique_topic>; otaurl http://ota.tasmota.com/tasmota/release/tasmota.bin

Commands and Backlog are powerful and in time you can learn to configure almost everything (NTP servers, longitude and latitude, custom device options, etc) with a few copy and paste moves.

Tip

Keep your personal configuration in a text file and simply copy and paste the backlog commands to a newly flashed device.

After Configuration~

Check out all the Tasmota features and ways to integrate it with other platforms.

Warning

If you experience power fluctuations in your power grid its best to immediately disable Power Cycle Recovery feature with command SetOption65 1 immediately or you might end up with firmware defaults on your device.

Back to top