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.
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_RULEShas to be enabled inuser_config_override.hin order to use rules.
Currently no "IF" directive or nested rules are supported.
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
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:
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 |
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
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.