tasmota / docs

Documentation for Tasmota (https://github.com/arendst/Tasmota)

Tasmota Documentation

This is the repo for documentation of the Tasmota open source alternative firmware for ESP8266 available from https://github.com/arendst/Tasmota

The build documentation can be found here: https://tasmota.github.io/docs/

Built on MkDocs using Material for MkDocs theme.

Editing Articles

Edit only articles in /docs folder.

All paths are relative.

Use strict markdown syntax. See Markdown Cheatsheet for a quick reference.

Markdown Enhancements

Admonitions

Reference of all possibilities

Definition Lists

Usage

Marker Highlight

If you want higlight text with marker style yellow enclose it in == ==. More details...

Tabs

Start each tab section with === "Tab title" and indent the tab content by 4 spaces. More information...

Superscript text

Enclose text in ^ ^ to superscript it. Example H^2^0 renders H²O

docs's Issues

Please amend Shelly1 documentation page

Wrong image, GPIO5 reads HIGH when SW is shorted to AC/L. Here below the updated image:

@
re PR: arendst/tasmota#

Please amend the appropriate article in Tasmota documentation

Command BlinkCount limits are wrong in docs

@
re PR: arendst/tasmota#

Please correct the BlinkCount limits in the Tasmota documentation commands section.

It currently states, that the value for BlinkCount is limited to 0..32000, but it's actually valid to use the full uint16 range up to 65535.

Either this should be enforced in code, or the docs should be updated to reflect the correct ranges.

I'm currently writing a Tasmota RPC interface and might come across more of these cases. What is the preferred way of bringing those up (Single Issue, seperate issues, single PR, seperate PRs)?

Please add the new feature to documentation

@
re PR: arendst/tasmota#

Please add another recovery method to page Device Recovery

Another option to perform device recovery (at least for ESP32 devices) is to erase the flash using the esptool:

esptool.exe --chip esp32 --port com4 erase_flash

This might be helpful if the other options don't work at all. (I had a device which couldn't start sucessfully, probably because of invalid data in the file system. By erasing the complete flash I was able to recover from this situation.)

Kind regards

Leading edge dimmer not working for 4 channel RobotDyn

Dear Team,

The description for connection a zero-crossing dimmer doesn't work for connecting a 4 channel RobotDyn dimmer
https://robotdyn.com/ac-light-dimmer-module-4-channel-3-3v-5v-logic-ac-50-60hz-220v-110v.html
I'm using only one channel, but the light only flickers without dimming and I cannot event turn it off.
The described single channel dimmer and the 4 channel one only differ in number of channels and one capacitator.
@stefanbode I need your help. Can you please verify that the recipe isn't missing some ingredients, and it really works for the RobotDyn dimmers.
Best regards,
A.Kotsev

Is SwitchTopic obsolete and need to be removed?

I connected a sensor to a GPIO as switch. I tried "SwitchTopic 1" and got Command Unknown as Result.

Dead link in documentation of ESP32 (docs/docs/ESP32.md)

The link to the required flash files for ESP32 in docs/docs/ESP32.md is dead. It points to https://github.com/arendst/Tasmota/tree/firmware/release-firmware/tasmota32/ESP32_needed_files and I don't know wheter it moved or became obsolete.

Thanks

add docs for I2C HT16K33 based 7 segment LED

@tthk
PRs like arendst/Tasmota#8116, arendst/Tasmota#8900 seem to not have made it to the docs properly.

For a list of things I couldn't find in the docs, see arendst/Tasmota#14451

Please add the new feature to the appropriate article in Tasmota documentation

Please add script example for eZB MD3 to documentation

@
re PR: arendst/tasmota#

I missed a script example for the eZB MD3 (SML) smartmeter.
So I had to work it out by myself, and here it is.
Please add it to
https://tasmota.github.io/docs/Smart-Meter-Interface/

D
B
=>sensor53 r
M 1
+1,3,s,0,9600,Smartmeter
1,77070100010800ff@100000000,Total consumption,KWh,Total_in,3
1,77070100020800ff@100000000,Total generation,KWh,Total_out,3
1,77070100100700ff@1,Power L1+L2+L3,W,P_L1_L2_L3,18
1,77070100240700ff@1,Power L1,W,P_L1,18
1,77070100380700ff@1,Power L2,W,P_L2,18
1,770701004C0700ff@1,Power L3,W,P_L3,18

No Informations in sonoff addon ioBroker

I get no informations in my sonoff addon at my ioBroker Home Server. Any advice?
Thanks

Please add the new feature to documentation

@
re PR: arendst/tasmota#

Please add the new feature to the appropriate article in Tasmota documentation

Please fully explain how to use I2CWRITE and I2CREAD at the console to debug I2C devices.
What is the correct syntax for I2CWrite?
Please explain "I2C: Result 0", "I2C: Result 2" etc..

Example. 1.
If I enter i2cwrite 70, 1 in the console I receive I2C: Result 0:
70 is the I2C address
1 is the data

04:53:13 CMD: i2cwrite 70, 1
04:53:13 CMD: Group 0, Index 1, Command "I2CWRITE", Data "70, 1"
04:53:13 DMP: 70 01
04:53:13 I2C: Result 0
04:53:13 MQT: stat/PoolControl_08EBDC/RESULT = {"I2CWrite":"Done"}

Example 2.
If I enter i2cwrite (70, 1) in the console I receive I2C: Result 2:
70 is the I2C address
1 is the data

04:58:29 CMD: i2cwrite (70, 1)
04:58:29 SRC: WebConsole from 192.168.0.27
04:58:29 CMD: Group 0, Index 1, Command "I2CWRITE", Data "(70, 1)"
04:58:29 DMP: 00 01
04:58:29 I2C: Result 2
04:58:29 MQT: stat/PoolControl_08EBDC/RESULT = {"I2CWrite":"Done"}

Thank You

Please, add to the documentation WL-SW01_10-WiFi-Smart-Switch

@
re PR: arendst/tasmota#

https://tasmota.github.io/docs/devices/WL-SW01_10-WiFi-Smart-Switch/

The programming pin is missed in the description. It is pin "K" in the middle picture of the blue50 platine.

Second: the device is also sold as smart plug Tombux WL-SC01

js_mr1

add commands

arendst/Tasmota#8127

@to-scho

New version of 'BLE Sensors on ESP32 using built-in Bluetooth' would be appreciated

As there was published a branch for Tasmota32
( https://github.com/arendst/Tasmota/tree/firmware/firmware/tasmota32 )

any information about using BLE onboard of ESP32 would be appreciated.

What I am saying is after flasing ESP32 with tasmota32-sensors.bin no activity with BLE can be seen.

MI32* commands return Command:Unknown

What compilation rules were set to make tasmota32-sensor.bin firmware?

Is this support added:
#define USE_MI_ESP32 // Add support for ESP32 as a BLE-bridge (+9k2 mem, +292k flash)

Is it with or without decryption?
#define USE_MI_DECRYPTION
(maybe it would be a good idea to change it without re-compilation but with some OptionXXX )

As was mentioned in
https://tasmota.github.io/docs/Bluetooth/#ble-sensors-using-hm-1x
compatible devices are:

• MJ_HT_V1
• LYWSD02
• LYWSD03MMC
• CGD1
• MiFlora
• NLIGHT
• MJYD2S
• YEE RC
• MHO-C401

and I think there would be a great idea to write what to set step by step to see the result of connection to this devise in ESP32 ant furthermore in popular home automation systems ( possibly some wise rules ).

Thanks,

IF statement preceded by other Tasmota command - different behaviour from docs

In https://tasmota.github.io/docs/Rules/#conditional-rules it says

When the if-statement is preceded by other Tasmota commands you should use Backlog rather than Do , e.g.
Rule1 ON ENERGY#Current>10 Backlog Power1 0; IF (%var1%==1) Power1 1 ENDIF;Power 2 0;Power3 1 ENDON
and not
Rule1 ON ENERGY#Current>10 DO Power1 0; IF (%var1%==1) Power1 1 ENDIF ENDON

But for me only the following worked,
Rule1 ON Switch1#State=2 DO Backlog Power1 OFF; IF (var1==2) ruletimer1 5 ENDIF ENDON

and the below command did not work
Rule1 ON Switch1#State=2 Backlog Power1 OFF; IF (var1==2) ruletimer1 5 ENDIF ENDON

LWT usage at TASMOTA compared to MQTT default

Hi gents, the latest change let me think about the LWT. It is true that normally this is only for unexpected disconnects, but my experience with TASMOTA is, that we use the same topic also for normal disconnects that are intended by the client. E.g. Firmware update, executed by: WifiShutdown();

"Smart Home Integrations" page displays raw markdown for some reason

I was trying to learn more about Tasmota and wanted to see what the integrations were but this page:
https://tasmota.github.io/docs/Integrations/
Displays raw markdown:

MQTT rc-2

Esse problema é a partir da versão 9.3.0
Se baixar a versão 9.1.0 esse problema ainda não existia
Para quem está tendo esse problema basta baixar a versão mais antiga

Please add the new feature to documentation of Smart meter interface examples : DDM18SD Power meter

@
re PR: arendst/tasmota#

Please add the new feature to the appropriate article in Tasmota documentation

;This script, based on tasmota scripting language, is to read data on a unsupported DDM18SD 
;power meter. It has a 8E1 parity and the slave ID address is n 5.
;On a Nodemcu or Wemos D1 board, put wires between GPIO3 and GPIO1 to the RX and 
;TX pinout of a RS485 to TTL board, but leave empty (none) the GPIO Tasmota software settings. 
;A & B connected to the meter pinout. 
;digimp
>B  
->sensor53 r
>M 1  
+1,3,M,0,9600,DDM,1,2,05040000,05040008,05040012,0504001A,05040036,0504002A,05040100,05040400
1,050404ffffffff@i0:1,Tensione,V,DDM_Voltage,2  
1,050404ffffffff@i1:1,Corrente,A,DDM_Current,2  
1,050404ffffffff@i2:1,Consumo Ist.,W,DDM_Power,2
1,050404ffffffff@i3:1,Reactive power,Var,DDM_React_Power,2
1,050404ffffffff@i4:1,Frequenza,Hz,DDM_Frequency,2 
1,050404ffffffff@i5:1,Power factor,,DDM_PF,2
1,050404ffffffff@i6:1,Consumi tot.,Kwh,DDM_Tot_Power,2
1,050404ffffffff@i7:1,Tot. react. power,Kvarh,DDM_Reac_Power,2
#```

Please, add docs for I2C HT16K33 based 7 segment LED

@tthk
re: arendst/Tasmota/pull/8116

add command

@s-hadinger
re PR: arendst/Tasmota#7176

Please edit Commands.md and include new additions.

Adding US-100

@
re PR: arendst/tasmota#

Please add the new feature to the appropriate article in Tasmota documentation

It would be a good idea to add to "HC-SR04 ultrasonic ranging sensor" the US-100. This is a similar sensor where the jumper in the back has to be removed and then everything is the same as in the HC-SR04P (3.3V element).

Please add the new feature to documentation

@
re PR: arendst/tasmota#

Please add a note to the documentation in Flash-Sonoff-using-Raspberry-Pi.md (https://github.com/tasmota/docs/blob/master/docs/Flash-Sonoff-using-Raspberry-Pi.md)

Step 1 installs esptool with PIP. The note should say it may be necessary to install the esptool from source. While trying to erase_flash on a Sonoff S31, I got a message saying function was not supported (sorry, I did not save the error message).

Can't set GPIO17

Hi,
I have a Gosund SP112. I can configure the module easily by the web interface.
As I have more than one of these devices, I want to configure all the others by web or console commands.
This works well for most commands, including most of the GPIOs, but I can't configure GPIO17 to the correct value.
In the web interface of the first Gosund SP112 I have set GPIO17 to "ADC Button".
In the console of the first Gosund SP112 when I enter "GPIO" I get the list of numeric values for each of the GPIO. I see that for GPIO17 the value is set to "4800" for.
But when I enter "GPIO17 4800" on the other Gosund SP112 modules, GPIO17 stays at "None" (0).
Is there any special value format needed for the GPIO17/ADC pin? Or is this just a bug for GPIO17 ?

Firmware tested: 10.1.0

Tasmota not working with ant mqtt cloud broker

I tried to make it work with dozens of mqtt cloud broker but no results. Can u pls post an example(tested) with the most common brokers? Cloudmqtt, hive, thingspeak,...it would be great to have more documentation.thanks

Documentation for Sonoff RF bridge needs to be updated

@
re PR: arendst/tasmota#

Following the instructions here:

https://github.com/tasmota/docs/blob/master/docs/devices/Sonoff-RF-Bridge-433.md

I was not able to flash the RF chip. I got an invalid file signature error trying to upload the hex files given by Tasmota.

When I downloaded the Portisch firmware directly from here:

https://github.com/Portisch/RF-Bridge-EFM8BB1/releases/tag/0x04

It worked just fine.

I would update it myself, but I don't know how, or perhaps have permission.

Regards

Please add the new command to documentation

@ctc
re PR: arendst/Tasmota#8243

Please edit Commands.md and include new additions.

Upgrading and Power Calibration

Hello,

could you add a notice on the behavior of Power Calibration when upgrading?
I search the main repo and the docs but could not find specific information about it

In my case that would be 8.2->8.3 and the devices are now built-in, hence I was looking
for information beforehand

Thanks, Andre

Upgrading Link to 6.7.1 is broken

Clicking on the link for the 6.7.1 firmware in the upgrade flow line yields 404 error.

currently its pointing to:
https://github.com/arendst/Tasmota/releases/download/v6.7.1/sonoff-classic.bin
which gives 404 error

I think the correct link is:
https://github.com/arendst/Tasmota/releases/download/v6.7.1/sonoff-basic.bin

at least thats what worked for me. :)
thanks for your efforts !

Please add the new feature to documentation

@
re PR: arendst/tasmota#

Please add the new feature to the appropriate article in Tasmota documentation

Hi,
I had an issue using the mpr121 at a wemos d1 mini. According to described wiring it connected sda and scl to d2 and d1 of the wemos, but it didn't work.
So I tried to connect them to rx and tx of the wemos and it works. Perhaps you can document this fact as an alternative wiring for wemos in the documentation.

Conflicting instruction on placing EZO module into i2c mode

@
re PR: arendst/tasmota#

Please add the new feature to the appropriate article in Tasmota documentation

The instructions to place the EZO into i2c mode for use with Tasmota instruct the user to short the TX and PGND pins, but the diagram says to short the TX and PRB pins.

https://tasmota.github.io/docs/EZO/

GPIO Conversion - Unclear consecuences/mechanisms of upgrading from 8.5.1 to 9.1

@
re PR: arendst/tasmota#

Please add the new feature to the appropriate article in GPIO-Conversion.md or Upgrading.md (https://github.com/tasmota/docs)

It is clear in the changelog and the GPIO conversion page, that a significant change has been made.
However, it doesnt seem inmediately clear what the impact is for the end user, specially when upgrading.

It might be that I missed it, but there is no metion of this on the release notes, GPIO conversion page or Upgrade page.

Even if there ar no consecuences for the end user, at least a note of this would be good to reassure people that could be unaware of the consecuences/implications when reading the changelog.

Documentation does not appear to explain how to detach switches

I'm using Tasmota 9.2.0

at
https://tasmota.github.io/docs/Buttons-and-Switches/

One paragraph starts with "To detach switches" and stops there. What follows does not appear to explain how to detach the switches at all. Only waaay below, there is a section called "Detach Switches Based On.."

The way it is written, it appears some explanation was there but got accidentally erased.

My primary language is not English, so excuse me for any mistake.

Buttons Default State unclear

@
re PR: arendst/tasmota#

buttons docs does not state whether the

A push-to-make button should use a Button component ...

should have default state LOW or HIGH
but should be HIGH

I would recommend rewriting (but too much effort forking ... )

A push-to-make (default high) button should use a Buttoncomponent while a push-to-break (default low) button should useButtoni (i.e., inverted).

WIFI - CORS : Error in commands page or a bug

the current version for WIFI - CORS states

                           " = disable CORS (Cross Origin Resource Sharing) (default)

but when checking with OWASP ZAP, it seems as if the * = enable value is the default.

I am not capable to dive into the code to see if it is a bug or if it is a doc issue.
If you direct me to a bug page, I can post there if required.

[Pinout]: Wrong diagram for TYWE3L

It seems that the pinouts in the docs are mirrored compared to the official docs from the chip
The official doc (taken from https://fccid.io/2ANDL-TYWE3L/User-Manual/User-Manual-3894982) shows:

I've realized it after almost burning my finger when touching the USB/TTL converter...

mqtt - Securing your IoT from hacking

The suggested access control rules break the Home Assistant MQTT (auto) discovery functionality as the tasmota device tries to write to a number of homeassistant/# topics.
Is there a clever way to fix it for all tasmota devices?

PZEM-004 v3

I loaded the firmware 9.1.0 (sensors) on a D1 MINI to be able to use it with the PZEM-004 V3
I have configured the D1 in the following way:
Tx GPIO01 -> PZEM0xx TX
Rx GPIO03 -> PZEM004 RX

But with this configuration I was not able to get any reading from PZEM004

I changed Rx GPIO03 like this: PZEM016 Rx and by doing so I was able to get readings from the device.

Why does this happen?

Thank you very much

Please add the new feature to documentation

@
re PR: arendst/tasmota#

Please add the new feature to the appropriate article in Tasmota documentation

KAIFA MB310H4BDE

D
B
=>sensor53 r
M 1
+1,3,s,0,9600,Haus
1,77070100010800ff@1000,Zaehlerstand In,KWh,Total_in,2
1,77070100020800ff@1000,Zaehlerstand Out,KWh,Total_out,2
1,77070100100700ff@1,Leistung-akt.,W,Power_curr,0
1,77070100600100ff@#,Server-ID,,Meter_Number,0

Dead Links on tasmota.github.io

I've collected a list of dead URLs found on templates.blakadder.com in this Google Sheet. These URLs are mostly composed of pages with 404 links that should be updated to where the webpage was moved.

Add support for LC Technology v3 - Single Relay

@
re PR: arendst/tasmota#

Please edit Commands.md and include new additions.

Please can you add support for v3 of the LC Tech Relays

I'd like to add a note about the Sonoff Slampher to the docs, but need a pointer

I just received a Sonoff Slampher and tried following the various Internet instructions that suggest grounding the CPU side of R9 to get it into programming mode. R9 is no longer present in the location that the tutorials suggest. I checked which pin it uses on the CPU package and believe that it's on a trace that either goes nowhere or through a via to the other side of the board.

I was about to give up when I discovered that, contrary to the various instructions, simply holding down the button while connecting the vcc/tx/dx/gnd pins put it into programming. It flashed on the first try.

I'd like to leave a note somewhere, but can't find any Sonoff hardware pages.

Is there an appropriate location?

Thanks.

Please add Sonoff Basic R2 V1.3 to documentation

I just purchased a Sonoff Basic, it is R2 V1.3, which is not covered into the page Sonoff-Basic.md.
I flashed it as usual using the serial. If you are interested, you can view and freely copy some photos from here: Sonoff Basic R2 V1.3. In the photos you view the Dupont pin headers, which I soldered on the PCB.

Please add the new feature to documentation - Max value rule

@
re PR: arendst/tasmota#

Please add the new feature to the appropriate article in Tasmota documentation

Can documentation about analog be improved? I could not find anywhere the list of value names. All rule examples use analog#a0, which did nothing for me, perhaps because I'm using ESP32? I worked out that analog#a1 got a value and then eventually, by trial and error I worked out I could use analog#range1.

I would like to suggest the following example for the rules cookbook:

Publish Maximum Value from sensor in a time period:
This rule stores the sensor value in VAR1. When the current value is greater than the previous, VAR1 is updated. If the current value is smaller, VAR1 is unchanged. Then every minute, VAR1 is published and then VAR1 is reset.
This results in output of the maximum/peak value for the minute. Useful, for example in a decibel meter, when the peak value is important, rather than the value that is occurring by chance at normal telemetry time.
This uses Analog range (analog#range1) which is a scaled output value. The raw analog value is analog#a1

Rule
ON System#Boot var1 1 ENDON
ON analog#range1>%var1% DO VAR1 %value% ENDON
ON Time#Minute DO Backlog publish shed/tele/maxdb %var1%; var1 1 ENDON

How to lower the reading frequency for PZEM-004t

Why is tasmota reading data from pzem-004t so frequently? I think it reads every second
For sonoff-pow it's at much lower rate

This way it uses much more power.
There should be a way to lower the sampling rate

Please add the new command to documentation

@device111
re PR: arendst/Tasmota#8152

Please edit Commands.md and include new additions.

Images missing in EXS relay documentation?

@blakadder
re PR: arendst/tasmota#
Please add the new feature to the appropriate article in Tasmota documentation
In the 'Notes' section of docs/devices/EXS-Relay-V3.1-&-V5.1.md there appears to be reference to some images which are absent?
https://github.com/tasmota/docs/blob/3440f6d8ec6d17d44fbaad0d16bdda3df0c84cdd/docs/devices/EXS-Relay-V3.1-&-V5.1.md
Thanks.

Rules IF documentation incorrect

https://tasmota.github.io/docs/Rules/#conditional-rules says nested IF Statements are supported, but regarding they are not arendst/Tasmota#10504.

Syntax

IF statement supports 3 formats:

    IF (<logical-expression>) <statement-list> ENDIF
    IF (<logical-expression>) <statement-list> ELSE <statement-list> ENDIF
    IF (<logical-expression>) <statement-list> [ELSEIF (<logical-expression>) <statement-list> ] ELSE <statement-list> ENDIF
[...]
<statement-list>
- A Tasmota command (e.g.,LedPower on)
- Another IF statement (IF ... ENDIF)
- Multiple Tasmota commands or IF statements separated by ;
[...]

Further the example following the definitions above raising some questions:

For example:
Power1 off; LedPower on; IF (Mem1==0) Var1 Var1+1; Mem1 1 ENDIF; Delay 10; Power1 on
Backlog is implied and is not required (saves rule set buffer space).

But not like this: Power1 off; LedPower on; IF (Mem1==0) Var1 Var1+1; Mem1 1 ENDIF; Delay 10; Power1 on

You should split it in two lines like: ON Power2#state=1 DO Power1 off; LedPower on; ENDON ON 11> Power2#state=1 DO IF (Mem1==0) Var1 Var1+1; Mem1 1 ENDIF; Delay 10; Power1 on ENDON```

The samples looks all the same and there is no real explanation why one is good an the other is bad. 

Please document on variables in the Tasmota docs

There must be some variables available in Tasmota. For instance, in wifi config: %s-%04d. It seems like these variables are not documented.

HP303B

Hi. I downloaded the tasmota.sensors.bin file and flashed it to my Wemos D1 Mini.
Then I configured D2 and D1 to SDA and SCL, so that I can use I2C shields.
All of the Wemos D1 Mini Shield worked, except HP303B, which was not detected.
The shield is OK when I program the board with the Arduino IDE.
What can be wrong?
Thanks in advance!

Please add the new feature to documentation

@arijav
re PR: arendst/Tasmota#8212

Please add the new feature to the appropriate article in Tasmota documentation