Getting Started

Prerequisites~

Needed Hardware~

ESP Device~

Every Espressif ESP8266, ESP8285, ESP32, ESP32-S or ESP32-C3 chipset based device can be flashed with Tasmota. The term ESP refers to any of them.

Serial Programmer~

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 (CH340G, Sparkfun, Soldered Connect, CH340N with AMS1117).
• RECOMMENDED VoltLink - USB to serial adapter board based on the popular CP2102N chip with built-in ESP auto-reset circuitry and a 500mA voltage regulator
• CP2102 or PL2303 - works with certain devices, but using an external 3.3V supply might be necessary. Not recommended for beginners!
• NodeMCU You can also use a NodeMCU (or similar) as a reliable serial programmer if you disable the onboard ESP by bridging GND to the RST or EN pin, and connect TX and RX straight to another ESP82xx instead of crossed.

Many serial programmers do not have a voltage regulator on board like the pictured ones. The ESP requires at least 150mA, many 3.3V serial programmers cannot supply this much current as many serial programming tasks do not require a large amount of power.

When using an external 3.3V supply, ensure the ground (GND) of both are connected together, this ensures a common ground. A PC power supply can be a source for 3.3V DC power.

Devices with an USB upload port typically have a serial programmer built in, such as NodeMCU, D1 mini or M5Stack products.

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 there are 3D printed jigs available for different modules and devices. At worst, you could get away with holding the headers tightly with jumper wires in pin holes during flashing but it is not a foolproof 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~

• Tasmota Web Installer - flash Tasmota using a Chrome based browser for ESP82XX and ESP32
• Tasmotizer - flashing and firmware download tool for ESP82XX only. (Windows, Linux or Mac)
• ESP-Flasher - GUI flasher for Tasmota based on esptool.py for ESP82XX and ESP32. (Windows, Linux or Mac)
• Esptool.py - the official flashing tool from Espressif for ESP82XX and ESP32.

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.

Hardware Preparation~

We need to connect to the serial programming interface of the ESP chip. This is done by connecting our serial-to-USB converter TX and RX pins to the ESP 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.

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

YOU CAN BE ELECTROCUTED IF YOU DO NOT 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 Supported Devices 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:

Note that TX from your adapter goes to RX on the ESP device and RX from adapter goes to TX on the device!

Programming Mode~

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

On many devices the installed control button is connected to GPIO0 and GND, making entering Programming Mode easy. On others you will need to bridge the pins on the PCB or directly on the chip with a jumper wire. GPIO0 locations for popular modules can be found in Pinouts!

Device specific instructions are documented in Tasmota Supported Devices Repository.

To put the ESP into Programming Mode:

1. Disconnect serial programmer and power
2. Bridge GPIO0 and GND (by pressing the on-board button or connection with a wire)
3. Connect the serial programmer 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.

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 programmer. 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 line.
• Recheck your serial programmer 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. Note: some devices can have the TX and RX pins labelled in reverse. In that case connect TX to TX and RX to RX pins of your adapter.
• Erase the flash first and power cycle 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 Programming Mode and ready for a Tasmota firmware binary to be installed.

Choose an installation method:

pip install esptool

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

esptool.py --port COM5 erase_flash

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

esptool.py write_flash 0x0 tasmota32.factory.bin

Initial Configuration~

Using Tasmota Web InstallerUsing Web UIUsing Serial Terminal

Once the installation is successful, click on NEXT. The installer will scan for Wi-Fi networks and select the strongest one. Use the dropdown to select between networks.

Enter the Wi-Fi password.

Wait until configuration completes and click CONTINUE

From here click on VISIT DEVICE to enter the WebUI for further configuration.

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

Connect 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.

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.

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.

If it was successful, you will see this message:

Some phones will redirect you to the new IP immediately, on others you need to click the link to open it in a browser.

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

<img alt="Tasmota AP" src="../_media/wificonfig6.jpg" style="margin:5px;width:200px;float:right"></img>In 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.

If you don't know the IP of the newly flashed device look in your router settings or find it with an IP scanner:

• Fing - for Android or iOS
• Angry IP Scanner - open source for Linux, Windows and Mac. Requires Java.
• Super Scan - Windows only (free)

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:

Set up your device's feature using a Template in Configuration - Configure Template or Module in Configuration - Configure Module.

Configure Other (optional)

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

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.

If you flashed the device using serial programmer (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 that connects to Tasmota console over the serial connection you used to flash it.

• 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>.

In this example Termite on Windows is used.

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

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.

Connect your device to the serial programmer. 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>

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~

Your device running Tasmota is now ready to be controlled.

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