Rules - stodev-com-br/Tasmota GitHub Wiki
Tasmota provides a Rule feature heavily inspired by the ESPEasy implementation. Rules expand the functionality of Tasmota with flexible and user configurable logic while maintaining a small memory footprint. Automation solutions can be implemented without having to add dedicated code or use external solutions.
- Rule Syntax
- Rule Cookbook (Sample rules)
Rules perform actions based on triggers (e.g., switch state change, temperature threshold, events like system boot, a defined timer elapsing, custom defined events, etc.) They are stored in flash and therefore will survive a reboot.
Most pre-compiled binaries (builds) have the Rules feature enabled. The exception being
tasmota-minimal.bin
. If you are compiling your own firmware, in order to use rules, include#define USE_RULES
inuser_config_override.h
.
Nested rules are not supported.
- Optional
IF / ELSE / ELSEIF
andAND / OR
support 6.6.0.11 - Optional use of expressions support 6.4.1.14
Rule definition statement:
ON <trigger> DO <command> [ENDON | BREAK]
-
ON
- marks the beginning of a rule definition -
<trigger>
- what condition needs to occur for the rule to execute -
DO
- what the rule is to perform if the<trigger>
condition is met -
ENDON
- marks the end of a rule. It can be followed by another rule. -
BREAK
- marks the end of a rule.BREAK
will stop the execution of the remaining rules that follow this rule within the rule set. If a rule that ends withBREAK
is triggered, the following rules in that rule set will not be executed. This allows the rules to somewhat simulate an "IF/ELSE" statement.
Rule sets are defined by using the Rule<x>
command. After defining a rule set, you have to enable it (turn it on) using Rule<x> 1
. Similarly you can disable the rule set using Rule<x> 0
.
See Commands for a complete list of rules related commands.
There are three separate rule sets called Rule1
, Rule2
and Rule3
. Each rule set can contain as many rules as can fit within the 511 character limit. Whenever a rule set is enabled all the rules in it will be active.
Rules inside a rule set Rule<x>
are concatenated and entered as a single statement.
Rule<x> ON <trigger1> DO <command> ENDON ON <trigger2> DO <command> ENDON ...
Spaces after ON
, around DO
, and before ENDON
or BREAK
are mandatory. A rule is not case sensitive.
A rule trigger can consist of:
[TriggerName]#[ValueName]
[TriggerName]#[ValueName][comparison][value]
[SensorName]#[ValueName]
[SensorName]#[ValueName][comparison][value]
Tele-[SensorName]#[ValueName]
Comparison operators:
Operator | Function |
---|---|
= |
equal to (used for string comparison) |
== |
equal to (used for numerical comparison) |
> |
greater than |
< |
lesser than |
!= |
not equal to |
>= |
greater than or equal to |
<= |
lesser than or equal to |
| |
used for modulo operation with remainder = 0 (exact division) |
Trigger | When it occurs |
---|---|
Analog#A0div10 | when the A0 input changes by more than 1% it provides a value between 0 and 100 |
Button2#State | when a button changes state:0 = OFF1 = ON2 = TOGGLE3 = HOLD |
Clock#Timer=3 | when global Timer3 is activated |
Dimmer#Boot | occurs after Tasmota starts |
Dimmer#State | when the value for Dimmer is changed |
Event#eventName | when command Event eventName is executed. You can define your own event values and trigger them with the Event command. |
FanSpeed#Data=3 | when the fan speed is set to 3
|
Mem<x>#State | when the value for Mem<x> is changed |
Http#Initialized | |
Mqtt#Connected | when MQTT is connected |
Mqtt#Disconnected | when MQTT is disconnected |
Power1#Boot |
Relay1 state before Wi-Fi and MQTT are connected and before Time sync but after PowerOnState is executed. Power#Boot triggers before System#Boot.This trigger's value will be the last state of Relay1 if PowerOnState is set to its default value (3 ). |
Power1#State | when a power output is changed use Power1#state=0 and Power1#state=1 for comparison, not =off or =onPower2 for Relay2, etc. |
Rules#Timer=1 | when countdown RuleTimer1 expires |
Switch1#Boot | occurs after Tasmota starts before it is initializated. |
Switch1#State | when a switch changes state:0 = OFF1 = ON2 = TOGGLE3 = HOLD( SwitchTopic 0 must be set for this to trigger) |
System#Boot | occurs once after Tasmota is intialised (after the INFO1, INFO2 and INFO3 console messages). |
System#Save | executed just before a planned restart |
Time#Initialized | once when NTP is initialized and time is in sync |
Time#Initialized>120 | once, 120 seconds after NTP is initialized and time is in sync |
Time#Minute | every minute |
Time#Minute|5 | every five minutes |
Time#Minute=241 | every day once at 04:01 (241 minutes after midnight) |
Time#Set | every hour when NTP makes time in sync |
Var<x>#State | when the value for Var<x> is changed |
Wifi#Connected | when Wi-Fi is connected |
Wifi#Disconnected | when Wi-Fi is disconnected |
Every command with a one level JSON response has the #Data trigger.
Trigger | When it occurs |
---|---|
<command>#Data | A response such as {"Fanspeed":3} has the Fanspeed#Data trigger. A response like {"PulseTime2":{"Set":0,"Remaining":0}} does NOT have the #data trigger as the triggers are PulseTime2#Set and PulseTime2#Remaining. |
Connected sensors can be a trigger in the form as they are represented in the TelePeriod
and Status 8
JSON payloads.
Trigger | When it occurs |
---|---|
DS18B20#Temperature | whenever the temperature of sensor DS18B20 changes |
DS18B20#Temperature<20 | whenever the temperature of sensor DS18B20 is below 20 degrees |
AM2301-12#Humidity==55.5 | whenever the humidity of sensor AM2301-12 equals 55.5% |
INA219#Current>0.100 | whenever the current drawn is more than 0.1A |
Energy#Power>100 | whenever the power used is more than 100W |
To trigger only at TelePeriod time, prefix the sensor with the word Tele-
.
Trigger | When it occurs |
---|---|
Tele-AM2301#Temperature | sensor AM2301 Temperature value when the TelePeriod JSON payload is output |
Hardware and software serial interface, RF, IR and TuyaMCU are also supported based on their JSON status message:
Trigger | When it occurs |
---|---|
TuyaReceived#Data=<hex_string> | whenever <hex_string> is received with TuyaMCU component |
SerialReceived#Data=<string> | whenever <string> is received via hardware serial |
SSerialReceived#Data=<string> | whenever <string> is received via software serial |
IrReceived#Data=801 | whenever an IR signal for a RC5 remote control button 1 is received |
IrReceived#Data=0x00FF9867 | whenever an IR signal with hex code 0x00FF9867 is received |
RfReceived#RfKey=4 | whenever the RF Bridge receives a recognized RfKey 4 signal |
RfReceived#Data=0xE8329E | whenever an RF signal with hex code 0xE8329E is received |
A rule command can be any command listed in the Commands list. The command's <parameter>
can be replaced with %value%
which will use the value of the trigger.
ON Switch1#State DO Power %value% ENDON
To accomplish a rule with one trigger but several commands, you need to use Backlog
:
ON <trigger> DO Backlog <command1>; <command2>; <command3> ENDON
Appending a rule onto an existing rule set
Use the +
character to append a new rule to the rule set. For example:
Existing Rule1: ON Rules#Timer=1 DO Mem2 %time% ENDON
Rule to append: ON button1#state DO POWER TOGGLE ENDON
Command: Rule1 + ON button1#state DO POWER TOGGLE ENDON
Resulting Rule1: ON Rules#Timer=1 DO Mem2 %time% ENDON ON button1#state DO POWER TOGGLE ENDON
There are ten available variables (double precision reals) in Tasmota, Var1..Var5
and Mem1..Mem5
. All Var
will be empty strings when the program starts. The value of all Mem
persists after a reboot. They provide a means to store the trigger %value%
to be used in any rule.
The value of a Var<x>
and Mem<x>
can be:
- any number
- any text
- %var1% to %var5%
- %mem1% to %mem5%
- %time%
- %timestamp%
- %uptime%
- %sunrise%
- %sunset%
- %utctime%
To set the value for Var<x>
and Mem<x>
use the command
Var<x> <value>
Mem<x> <value>
The <value>
can also be the value of the trigger of the rule.
- Set Var2 to the temperature of the AM2301 sensor -
ON AM2301#Temperature DO Var2 %value% ENDON
- Set Var4 to Var2's value -
ON Event#temp DO Var4 %Var2% ENDON
- Set Mem2 to the current time (minutes elapsed since midnight) -
ON Rules#Timer=1 DO Mem2 %time% ENDON
- After a Wi-Fi reconnect event, publish a payload containing timestamps of when Wi-Fi was disconnected in From: and when Wi-Fi re-connected in To: to
stat/topic/BLACKOUT
.Rule1 ON wifi#disconnected DO Var1 %timestamp% ENDON ON wifi#connected DO Var2 %timestamp% ENDON ON mqtt#connected DO Publish stat/topic/BLACKOUT {"From":"%Var1%","To":"%Var2%"} ENDON