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.

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_RULES in user_config_override.h.

Rule Syntax

Nested rules are not supported.

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 with BREAK 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.

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 = OFF
1 = ON
2 = TOGGLE
3 = 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 =on
Power2 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 = OFF
1 = ON
2 = TOGGLE
3 = 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

Back To Top

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
⚠️ **GitHub.com Fallback** ⚠️