Table of Contents
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)
Introduction
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_RULESinuser_config_override.h.
Rule Syntax
Nested rules are not supported.
- Optional
IF / ELSE / ELSEIFandAND / ORsupport 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 executeDO- what the rule is to perform if the<trigger>condition is metENDON- marks the end of a rule. It can be followed by another rule.BREAK- marks the end of a rule.BREAKwill stop the execution of the remaining rules that follow this rule within the rule set. If a rule that ends withBREAKis 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.
Rule Trigger
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) |
Some of available triggers:
| 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 |
Rule Command
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
Rule Variables
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
Wiki has moved to link on the left.