FAQ - seurat-atreides/Sonoff-Tasmota GitHub Wiki

Installation

  1. Cannot enter flash mode
  2. Flashing issues
  3. Firmware update with file upload not working
  4. Device is hot! or There was white smoke!
  5. Sonoff 4CH V2 / Sonoff Dual V2 won't flash
  6. Flashing fails on MacOS High Sierra

Wi-Fi

  1. Cannot connect to Wi-Fi
  2. Entered wrong Wi-Fi information
  3. Device often reconnects to Wi-Fi
  4. Wi-Fi stops working
  5. Control device from outside my network

MQTT

  1. Cannot connect to my MQTT broker
  2. Frequent MQTT reconnects
  3. What's Topic, GroupTopic and FallBack Topic

Device

  1. How do I configure this unknown device
  2. Relay clicks/LED flashes at 1 sec interval
  3. Status LED blinking
  4. Random (ghost) switching
  5. Device resets to defaults every minute or so
  6. Cannot find my device in Modules
  7. Device keeps restarting after changing config over MQTT
  8. Can you add this unsupported sensor to Tasmota
  9. Frequent status updates in console and MQTT
  10. Web interface asks for password
  11. Power monitoring shows wrong values
  12. Power monitoring resets Energy Today mid-day
  13. Sensors don't show values
  14. Timers trigger at wrong time
  15. Autodiscovery in Home Assistant doesn't work
  16. Why is my changed config not loaded?
  17. How do I invert the output of the green LED on the Sonoff basic so the LED is on when the relay is off?
  18. What is an Arduino core?
  19. Config problems

Installation

Cannot enter flash mode

If your on device button doesn't allow you to enter flash mode or there is none, you can always connect GPIO0 and GND pins directly on the chip. Search on the internet for your chip pinouts and use the tutorial.

Flashing issues

Double check if you wired the device the serial-to-USB adapter correctly. Almost every device needs RX and TX pins switched to TX and RX. See Hardware Preparation for more.

Another common problem are the jumper cables used. Try another cable if you keep getting connection errors or check the cables for connectivity. Most of them are made cheaply and it happens quite often that those cables do not offer a good connection because of bad crimping or broken copper lines in them.

Be sure to use a USB Data Cable and not a cheap loading cable for mobile phones for connecting the serial-to-USB adapter to your computer. If you are unsure, just try another USB cable. Data USB cables are often thicker than the normal loading cables (and more expensive).

Another problem can be the connection of GPIO0 and GND. Be sure to press the Button correctly, you must "feel" a click. If your device does not have a button, find your chip pinout on the internet and short GPIO0 pin to GND with a wire (or anything metal) as described in Hardware Preparation

If the flash still fails or the progress interrupts, it could be that your computer or serial-to-USB adapter doesn't provide enough powerto the device. Try another computer or use an external power supply (3.3V one).

Use the correct serial-to-USB adapter driver. Check the model of your adapter chip and get the correct driver.

If the flash completes successfully, but you get a hash mismatch (esptool.py error message A fatal error occurred: MD5 of file does not match data in flash! ensure that your 3.3v current is sufficient. Workarounds include using a dedicated bread board power supply or using the 3.3v output of an additional microcontroller. If using an additional power supply to power the device, be sure to use a common ground for the power supply, the device to be flashed and the serial-to-USB adapter.

If esptool.py stops at "Uploading stub...", use --no-stub

Device is hot to the touch

Do you remember the NEVER EVER FLASH WITH 5V!?

Better unpower your device and check if the wiring is correct and the voltage is on your FTDI is set to 3.3V. If you've connected VCC to the wrong pin it might cause your device to overheat and destroy it.

There was white smoke and the device doesn't work anymore!

Yes, you've released the fabled "white smoke", the mysterious substance all electronic devices work on.

In the immortal words of Doctor Bones: It's dead Jim!

Sonoff 4CH V2 / Sonoff Dual V2 won't flash

Testing with two different (fairly new) FTDI boards and two Sonoff 4CH v2.0 and the Sonoff Dual v2.0 boards I found that I was getting errors uploading sketches i.e. "warning: espcomm_sync failed" basically a lack of communication between the two devices.

I found that the problem in both Sonoff's was that instead of the FTDI Sonoff cross-over TX->RX and RX->TX I had to do TX->TX RX->RX this then allowed me to upload the sketch.

Flashing fails on MacOS High Sierra

Related to issue #957.

Solution:

  1. Install the VCP drivers for Mac from the FTDI website : http://www.ftdichip.com/Drivers/VCP.htm
  2. After install, reboot (it does not work if you do not reboot).
  3. After reboot, plug the FTDI USB/serial converter. Accept the security alert from MacOS.
  4. Restart the flash process. It works!

Wi-Fi

Cannot connect to Wi-Fi

If your device does not connect to your Wi-Fi and you've made sure the Wi-Fi credentials are correct, it is caused by using special chars or white spaces in your SSID or Password of your Wi-Fi. Remove them and try again. Other reason can be using an SSID longer than the allowed 32 characters.

With some Wi-Fi routers (i.e. Linksys with DD-WRT), you may have conflicts with the 5GHz radio. Don't choose "Mixed" option. Select "AC/N-Mixed" instead. Moreover, you probably should disconnect 5GHz radio during the configuration process.

DD-WRT also has Wi-Fi Multi-Media (WMM) enabled by default. Disabling WMM can resolve connectivity issues.

I entered the wrong Wi-Fi information

Every device with a button can initiate Wi-Fi AP configuration mode with 4 short presses of the button.

If you flashed a light bulb or any device without a built-in button and entered wrong Wi-Fi password you now have a device that won't connect to your Wi-Fi and you have no button to force Wi-Fi Configuration.

To solve this you can try creating a new Wi-Fi AP with the same SSID and no (none) authentication. Use an old router, a mobile phone or, if you're desperate, change the settings on your main router (but remember to turn authentication back on when you're done. Depending on the router/phone it will ignore the wrong Wi-Fi password since authentication is set to none and let your Tasmota flashed device connect to it.

Now simply connect to the same AP and open the web UI, triple check your ssid and password, enter some simple info for SSID2 which you can create as a hotspot on your phone and save.

If you are unsure what SSID you have entered, you can try to find that with special Wi-Fi sniffing tools. For example Nirsoft WifiChannelMonitor can show your mistakenly configured SSID name.

Wi-Fi reconnects

First thing to try when having Wi-Fi issues:

Erase all flash using esptool.py or esptool.exe and flash via serial (as explained here) using the latest precompiled bins from http://thehackbox.org/tasmota/.

This approach has solved most of the reported issues. Sometimes this is due to a bad flash, a bad OTA or invalid data that remains in the flash where the SDK memory is.

If you still have issues, you should look into your Wi-Fi network:

  • Check the Wi-Fi channel availability and noise with an Android app like Wi-Fi Analyzer. Disable Auto Channel in your Wi-Fi router and select any Wi-Fi channel that is not very congested in your area.
  • Disable Wi-Fi Repeaters and Mesh Networks.
  • Check Wi-Fi signal in your device.

The same Mesh may be stable in one area and lead to unwanted Tasmota reconnects in other areas, presumably when the signals of access points overlap with similar strength. If disabling Mesh Networks is not an option, then keeping the network busy, e.g. by issuing a Ping from another host every 20 seconds has helped to avoid the reconnects.

Wi-Fi Stops Working

There have been many reports of Wi-Fi no longer working after it was working for a while.

Every time this has been reported, it's ended up being a hardware or signal interference problem.

On the hardware side, we've seen reports of bad solder joints on the board that when touched up seem to solve the problem (capacitors being loose can cause this) or low quality/weak power supplies or voltage regulators that cannot cope with the power requirements of Tasmota or have degraded over time.

We've also seen reports then when a specific LED light bulb was hooked up near one, the signal quality dropped to unusable.

All you can really do is check the solder joints, move the device closer to your Access Point. If all else fails, replace the device.

MQTT

Cannot connect to my MQTT broker

Make sure you've configured MQTT correctly. If that didn't solve the issue check your MQTT broker logs. Most likely problem is your broker doesn't allow logins for your Tasmota configure user and password or your ACL settings do not include your device.

In some very specific cases the MQTT broker code clashes with the Arduino Core and doesn't allow a connection. In that case create a different user for your device, try another core binary or a different MQTT broker.

Frequent MQTT reconnects

Most MQTT reconnect messages are linked with Wi-Fi instability first. Resolve any Wi-Fi issue first!

If the console shows repeated messages like:

02:32:54 MQTT: tele/MYSONOFF/LWT = Online (retained)
02:32:54 MQTT: cmnd/MYSONOFF/POWER = 
02:32:55 MQTT: Attempting connection...
02:32:56 mDNS: Query done with 0 mqtt services found
02:32:56 MQTT: Connected

or your mosquitto broker log shows messages like this -

1496455347: New client connected from IP_addr_1 as SONOFF (c1, k15, u'SONOFF_USER').
1496455349: New connection from IP_addr_1 on port 1883.
1496455349: Client SONOFF already connected, closing old connection.
1496455349: Client SONOFF disconnected.
1496455349: New client connected from IP_addr_2 as SONOFF (c1, k15, u'SONOFF_USER').
1496455350: New connection from IP_addr_2 on port 1883.
1496455350: Client SONOFF already connected, closing old connection.
1496455350: Client SONOFF disconnected.

You have more than one device connected with the same %topic% defined. Its important that each device has a unique %topic% instead of the default sonoff.

If that is not the issue, erase all flash using esptool.py or esptool.exe and flash again by wire (as explained here) using the latest precompiled bins with core v2.3 from http://thehackbox.org/tasmota/020300/.

For MQTT disconnections with Arduino core v2.5.0, please try command:

Sleep 0

Device

Relay clicks and LED flashes at 1 sec intervals

This indicates that your device did not get flashed properly. In this case it will toggle all it's pins at 1 sec intervals. A flash erase and a new flash is required.

Status LED blinking

Your device status LED blinks repeatedly when Wi-Fi and/or MQTT is not connected. If you're not using MQTT and did not configure it the status LED will still keep blinking.

You can disable status LED blinking using:

Backlog LedPower 0; SetOption31 1

My device randomly switches on and off. Do I have ghosts in my house?

Most of the issues with random, or "ghost", switching are related to MQTT retain settings. In short, your MQTT broker is retaining a message with the POWER status of the device which gets applied on reboots. Solution here

In some cases, adding a switch to a device causes ghost switching. In this case, you may need to add a low pass filter to dampen any spikes on the input. In the case of the Sonoff T1, a modification to change the filter capacitor on the PCB may be required.

This short 10 minute video by TheHookUp nicely explains what it is and how to prevent it.

Other cause can be of electrical nature. Ff you have connected an external switch using long wires they can pick up stray signals and cause the voltage on the GPIO to vary. Solution here

Cannot find my device in Modules

If you flashed a device which is not listed in the Modules list, use Templates to configure your device. Try looking for it first in the Templates Repository.

Device keeps restarting after changing config over MQTT

If you changed configurations over MQTT, the command can fail due to a bug and the command is repeatedly sent, causing the device to restart.

The restart is normal if you change something at the device configuration.

You need to clear the retain messages of your HA/Broker/MQTT Server.

Read also:

Can you add this unsupported sensor to Tasmota

Short answer: NO!

Long answer: There is not enough time in our coders lives to take requests, if you can code a driver for that sensor and submit a PR it will be considered, otherwise you can only wait for someone else to do it.

Tasmota is sending a lengthy status update (STATUS - STATUS11) every 5 seconds. What's going on?

Turn off TasmoAdmin! It is polling your device with STATUS 0 command with a HTTP request every 5 seconds which causes the status updates and unneccessary stress load on the device. In some cases it might even interfere with normal device operation.

I modified the Web Admin password (Configure Other) and now I cannot access the web interface.

You have set up a password for the web interface. You can login with the username admin and the password you entered.

However, if you don't remember that password there are a few options you can try to gain access to the web interface again.

  1. Reset the password using the WebPassword command.

    • If you have serial connection to the device: Execute WebPassword 0 using a serial terminal interface.

    • If you have configured MQTT: Send 0 to cmnd/<device-topic>/WebPassword. You can send it from any MQTT client. You can also use another Tasmota device using the Publish command - Execute Publish cmnd/<device-topic>/WebPassword 0 from that device's Console.

  2. If the options above are not available: Since Tasmota uses GET request for forms, the password may be in your browser history. Look there for entries with the name you configured for the device. For example, in the following link:

    http://[device-ip]/co?t1={"NAME":"Generic"'"GPIO":[23'22'24'17'134'132'0'0'131'52'21'0'0]'"FLAG":0'"BASE":67}&p1=SecretPassword&b1=on&a1=Sonoff&a2=Sonoff2&a3=Sonoff3&a4=Sonoff4&b2=0&save=

    the p1 parameter contains the password for the web interface (SecretPassword in this case).

    Note: special characters may appear as the characters' corresponding ASCII hexadecimal codes (e.g., "{" = '%7B', etc.)

  3. If you had set up WifiConfig 7 as your Wi-Fi fallback method (by previously executing WiFiConfig in the Console), you can reset the device by booting it into Wi-Fi Manager mode. If the SSID configured in the device is not available (e.g., turn off the router), the device will fallback to that restricted Wi-Fi Manager Mode.

  4. If your device has a physical push-button, reset the firmware to the default settings as detailed here.

  5. If nothing helps, then you have to flash the firmware again using the serial interface. Be sure to erase the flash memory before uploading the binary.

Power monitoring shows wrong values

If the values shown in the Web UI don't seem right and you're using a Supported Module you need to calibrate the power monitoring sensor.

In case you're using a template you created yourself or found in our Templates Repository try the calibration method first. If the values are still wrong or unrealistic the power monitoring sensors' GPIOs are not configured correctly and you will need to find the correct GPIO assignments before proceeding.

Sensors don't show values

Make sure your sensor is properly wired and the GPIOs assigned. Your vanilla sonoff.bin doesn't have complete sensor support. Make sure you've installed sonoff-sensors.bin that support the largest number of sensors. Some sensors require enabling in the code and compiling your own binary. See Builds for a comprehensive list of supported components.

Timers trigger at wrong time

Check if Tasmota is updating its device time over the preconfigured NTP servers and that the time matches your local time. If not, adjust your TimeZone or Daylight Saving Time

Autodiscovery in Home Assistant doesn't work

Binary sonoff-basic.bin (which comes packaged with Tuya Convert) does not support autodiscovery. Please upgrade to sonoff.bin or similar release that supports this feature.

Make sure its enabled in Tasmota it with SetOption19 1 and you configured the Home Assistant MQTT integration with Discovery enabled.

Why is my changed config not loaded?

If you have flashed a precompiled binary, be aware that all the configuration made after the flash (Wi-Fi, MQTT, topics, names, rules, etc) will be lost in a factory firmware reset.

In short: The CFG_HOLDER is the place where the config is stored on your device. The device checks if a config is saved in this CFG_HOLDER (value from the my_user_config.h) and always loads this if exists. => won't load new applied configs in your my_user_config.h

To get the new config on your device, you need to change the CFG_HOLDER. BUT: You should always try to stay on the default CFG_HOLDER, to reach this, you need to flash two times

  • change your config in the my_user_config.h or better user_config_override.h
  • change the CFG_HOLDER number. +1 or -1 is enough (e.g. 0x20161208)
  • flash
  • change the CFG_HOLDER back to default ( 0x20161209 )
  • flash again

After this, your new config is saved in the default CFG_HOLDER on your device.

This is necessary to avoid losing your config if you update to a new firmware by using the pre-build images or if you forget to change the CFG_HOLDER to your custom one if you build the firmware yourself.

How CFG_HOLDER works: The config of your Tasmota is stored in an area of the flash memory (flash config area or FCA). Using a new device (where Tasmota firmware runs the first time) the FCA does not contain a Tasmota configuration so on the very first start of Tasmota it uses your settings from my_user_config.h or user_config_override.h and copy this into the FCA. To prevent that the following Tasmota starts will overwrite your FCA settings again (e.g. because you has changed some things using commands) the FCA will be marked by a header value to indicate not copy the values from my_user_config.h/user_config_override.h again. This header becomes the value from CFG_HOLDER.

On every start the device compares the header of FCA with the CFG_HOLDER from your source code and only if this header value is not identical, Tasmotat will copy the data from my_user_config.h/user_config_override.h to flash settings area - this is normally only the case on a fresh device or if you has changed the CFG_HOLDER value.

Summary: To force Tasmota to overwrite current (valid or invalid) settings in FCA with your settings from my_user_config.h/user_config_override.h you can

  • change CFG_HOLDER value once, compile, reflash device (as described above). To avoid overwriting settings by new versions don't forget either
    • repeat the step above using original CFG_HOLDER value
    • or never forget to change CFG_HOLDER value for even all upcoming version to your value
  • or use the command Reset 1 or Reset 2 after changes in your my_user_config.h/user_config_override.h without the need to double reflash your device and/or double change your CFG_HOLDER value:
    • change values in my_user_config.h/user_config_override.h
    • leave CFG_HOLDER as is
    • start your device and issue command Reset 1 or Reset 2

How do I invert the output of the green LED on the Sonoff basic so the LED is on when the relay is off?

LedState default value is 1 (on) - Show power state on LED. The LED can be disabled completely with LedState 0 (off). However, there is no option to invert the output of the green LED on the Sonoff basic.

What is this Arduino Core

Arduino Core (open source) are the core libraries for ESP8266/ESP8285 chips to make them Arduino Framework Compatible. This Core is programmed on top of the Espressif SDK (closed source).

You can see the Arduino Core Version and the Espressif SDK Version on the Tasmota WebUI under the Information Menu entry. Example: Core-/SDK-Version: 2_3_0/1.5.3(aec24ac9)

  • 2.3.0

    • All Tasmota features work
    • Modem Sleep works to save energy (see Energy Saving)
    • Web UI is slower
    • Low RAM Available - Not many features can be enabled at once (sensors, etc)
    • Has the Krack Vulnerability
    • Software Serial can produce a restart exception (not enough RAM) if several features are enabled. (So, in this case only hardware serial will work - TX and RX pins)
    • Most Wi-Fi Repeaters produces conflicts and disconnections
    • Mesh Networks are not supported
    • Some Routers of brands (Ubiquiti and Fritzbox) produce conflicts and disconnections
    • If the Wi-Fi router has auto channel, channel switching is reliably managed by this core.
  • 2.4.0:

    • This core has several bugs and produces Wi-Fi disconnections. Do not use.
  • 2.4.1:

    • This core has several bugs and produces Wi-Fi disconnections. Do not use.
  • 2.4.2:

    • All Tasmota features work
    • Modem Sleep doesn't work but Tasmota has a CPU dynamic sleep to save energy, so it is not a big issue for this core
    • Web UI is faster
    • Serial Software exceptions of 2.3.0 are solved
    • Krack Vulnerability is solved.
    • More RAM is available
    • Firmware is a little bigger in flash size
    • Most Wi-Fi Repeaters produce conflicts and disconnections
    • Mesh Networks are not supported
    • Some Routers of brands (Ubiquiti and Fritzbox) produce conflicts and disconnections
    • If the Wi-Fi router has auto channel, channel switching is not reliably managed by this core. Use Fixed Channels in the router instead.
  • 2.5.0:

    • This core has some unsolved issues. Do not use.
  • 2.5.2 (bug fix release of 2.5.0 and 2.5.1):

    • All Tasmota features work
    • Extend PWM resolution for low brightness lights (Details)
    • Modem Sleep doesn't work but Tasmota has a CPU dynamic sleep to save energy, so it is not a big issue for this core
    • Alexa works
    • Web UI is fast
    • Serial Software exceptions of 2.3.0 are solved
    • Krack Vulnerability is solved.
    • More RAM is available compared to 2.4.2
    • Firmware is a little bigger in size compared to 2.4.2
    • Most Wi-Fi Repeaters don't produces conflicts or disconnections
    • Mesh Networks are supported
    • Most Routers of brands Ubiquity and Fritzbox don't produces conflicts or disconnections
    • If the Wi-Fi router has auto channel, channel switching is not reliably managed by this core. Use Fixed Channels in the router instead.

Config problems

Can cause boot loops, items to not appear, wrong config values, etc

By default, this firmware tries to preserve the existing config (to support automated updates via OTA upgrades), but various things can happen that cause the existing config to be a problem. Its frequent when upgrading from old releases without following the migration path.

When you change the settings in the code, that doesn't directly change the settings on the running machine when you load it. What happens is that when it boots up, the firmware looks to see if it has a valid config (is it an upgrade to an older Tasmota version), and if the CFG_HOLDER value is in the right place,it assumes that the existing config is valid. If it doesn't find the right value, it assumes that this is not an upgrade and takes the compiled-in config data and writes it out to the config area.

There are multiple ways to force the config to what's set in my_user_config to recover a system.

  1. hold button1 down for 40 seconds
  2. issue a reset command (reset 1 via the web console, /cmnd/sonoff/reset 1 via mqtt)
  3. change the value of CFG_HOLDER in my_user_config and re-flash the device (CFG_HOLDER is a 0xYYYYDDMM setup. Just change it to today. Any future updates should not be hindered by that).

I cannot find an answer here

Check the Troubleshooting section or join Discord, Telegram or Community Forum for direct help from our community.

⚠️ **GitHub.com Fallback** ⚠️