Rules - seurat-atreides/Sonoff-Tasmota GitHub Wiki

Tasmota provides a Rule function heavily inspired by the ESP Easy implementation. Rules expand the functionality of Tasmota with flexible and user configurable rules 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 (f.e. 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 have the Rules feature enabled (the exception being sonoff-minimal.bin and sonoff-classic.bin builds). If you are compiling your own firmware, define USE_RULES has to be enabled in user_config_override.h in order to use rules.

Currently no "IF" directive or nested rules are supported.

Rule Syntax

Every rule needs to follow this syntax:

on <trigger> do <command> endon

on marks the start of a new rule.

<trigger> is what needs to occur for the rule to execute the <command>

do is the separator between the <trigger> and <command>

endon marks the end of that rule. It can be followed by another rule.

Alternatively you can end the rule with break.
break will stop the execution for all the triggers that follow this rule inside the rule set. If a trigger that ends with break occurs, the following triggers of that rule set will not be executed. This allows the rules to somewhat simulate an "IF THEN ELSE" statement.

Rule sets are defined by using the Rule<x> command. After defining one you have to enable the rule set (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 3 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 can be concatenated and have to be in one line:

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.

Example of defining rule set:

Rule1 on <trigger1> do <command> break on <trigger2> do <command> endon

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 are:

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
System#Boot occurs once after MQTT is initialized. Due to the command execution order it cannot occur earlier than that.
Mqtt#Connected when MQTT is connected
Mqtt#Disconnected when MQTT is disconnected
Wifi#Connected when Wi-Fi is connected
Wifi#Disconnected when Wi-Fi is disconnected
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#Set every hour when NTP makes time in sync
Time#Minute every minute
Time#Minute==241 every day once at 04:01 (241 minutes after midnight)
Time#Minute|5 every five minutes
Clock#Timer=3 when global Timer3 is activated
Rules#Timer=1 when countdown RuleTimer1 expires
Event#User when command Event User is executed. You can define your own event values and trigger them with the Event](commands#event) command.
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.
Power1#Boot after Tasmota starts
Button2#State when a button changes state:
0 = OFF
1 = ON
2 = TOGGLE
3 = HOLD
Switch1#State when a switch changes state:
0 = OFF
1 = ON
2 = TOGGLE
3 = HOLD
(SwitchTopic 0 must be set for this to trigger)
Switch1#Boot occurs after Tasmota starts
Dimmer#State when the value for Dimmer is changed
Dimmer#Boot occurs after Tasmota starts
Analog#A0div10 when the A0 input changes by more than 1% it provides a value between 0 and 100
Var#State when the value for Var<x> is changed
Mem#State when the value for Mem<x> is changed

Connected sensors can be a trigger in the form as they are represented in the TelePeriod or Status 8 JSON message.

To trigger only at TelePeriod time, prefix the sensor with the word Tele-.

Trigger When it occurs
Tele-AM2301#Temperature triggers on the TelePeriod time for the sensor AM2301
Dsb18b20#Temperature<20 whenever the temperature of sensor DSB18B20 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

Hardware and software serial interface, RF or IR are also supported based on their JSON status message:

Trigger When it occurs
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

Back To Top

Rule Command

A rule command can be any command listed in the Commands list. That command <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 10 available variables (double precision reals) in Tasmota, Var1 through Var5 and Mem1 through 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%

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 a trigger of that rule.

on AM2301#Temperature do var2 %value% endon
Sets Var2 to the temperature of the sensor AM2301

on Event#temp do var4 %var2% endon
Sets Var4 to Var2's value

on Rules#Timer=1 do Mem2 %time% endon
Sets Mem2 to the current time (minutes elapsed since midnight)

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
After a Wi-Fi reconnect event publish to stat/topic/BLACKOUT a payload containing timestamps of when the Wi-Fi disconnected in From: and when the Wi-Fi connected in To:.

   

For examples of various rules see the Rule Cookbook.

Back To Top

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