Updated Rules (markdown)

Michael Ingraham 2019-02-11 10:36:05 -05:00
parent a121c8e12a
commit ec3dd58d94
1 changed files with 89 additions and 89 deletions

178
Rules.md

@ -51,13 +51,13 @@ Rules can be concatenated and have to be on one line:
Spaces after **on**, around **do** and before **endon** are mandatory. A rule is **not** case sensitive.
Before 6.1.0 20180706, there was one buffer for all rule commands. To store a complete set of commands in the flash memory buffer the ``rule`` keyword can be used:
Before 6.1.0 20180706, there was one buffer for all rule commands. To store a complete set of commands in the flash memory buffer the ``Rule`` keyword can be used:
``rule on [trigger1] do <command> endon on [trigger2] do [command] endon ...``
``Rule on [trigger1] do <command> endon on [trigger2] do [command] endon ...``
Starting with 6.1.0 20180706, there are three buffers for rule commands. Each of those buffers can be switched on and off individually. Instead of ``rule`` use ``rule[123]``:
Starting with 6.1.0 20180706, there are three buffers for rule commands. Each of those buffers can be switched on and off individually. Instead of ``Rule`` use ``Rule[123]``:
``rule1 on [trigger1] do [command] endon on [trigger2] do [command] endon ...``
``Rule1 on [trigger1] do [command] endon on [trigger2] do [command] endon ...``
## 6.3.0.15 - Added ``BREAK`` as an alternative ``ENDON``
``BREAK`` will stop the execution for the triggers that follow.
@ -81,7 +81,7 @@ ENDIF
With the actual rules, if we use a set like the following:
```
rule1
Rule1
on event#temp>85 do VAR1 more85 endon
on event#temp>83 do VAR1 more83 endon
on event#temp>81 do VAR1 more81 endon
@ -111,7 +111,7 @@ This is the output in the console:
So, all the triggers where TEMP>100, are firing. With the ``BREAK`` statement the rule set can be changed to:
```
rule
Rule
on event#temp>85 do VAR1 more85 break
on event#temp>83 do VAR1 more83 break
on event#temp>81 do VAR1 more81 endon
@ -332,7 +332,7 @@ Result
#### 2. Execute any MQTT message when a button is pressed
When a button is pressed the user has the possibility to send a MQTT message based on FullTopic and ButtonTopic. This MQTT message is going to be received by the MQTT Broker and if there is any other device(s) subscripted to that Topic, it will receive also that message. So this approach can be used for sending messages/commands to MQTT Broker to Home Automation System, and/or sending messages/commands to MQTT Broker to other device(s).
A problem with this solution is that on a Sonoff 4CH all four buttons will be sending the same MQTT topic using only a different Power index number like ``cmnd/buttontopic/power3 toggle``.
A problem with this solution is that on a Sonoff 4CH all four buttons will be sending the same MQTT topic using only a different Power index number like ``cmnd/ButtonTopic/power3 toggle``.
By using a rule a single button can now send any MQTT message allowing much more flexibility.
@ -344,10 +344,10 @@ Software
- Disable ButtonTopic as it overrides rules for buttons: ``ButtonTopic 0``
Rule
- ``rule on button1#state do publish cmnd/ring2/power %value% endon on button2#state do publish cmnd/strip1/power %value% endon``
- ``Rule on button1#state do publish cmnd/ring2/power %value% endon on button2#state do publish cmnd/strip1/power %value% endon``
(You will likely need to enable this rule if it's the first time you've used them)
"rule1 on".
"Rule1 on".
Result
- When button 1 is pressed the rule kicks in and sends a MQTT message substituting variable ``%value%`` with the button state like ``cmnd/ring2/power 2``. When button 2 is pressed a MQTT message like ``cmnd/strip1/power 2`` will be sent.
@ -368,12 +368,12 @@ Software
- Configure timer5 for rule execution when activated: ``timer5 {"Arm":1,"Mode":0,"Time":"16:00","Days":"1111111","Repeat":1,"Action":3}``
Rule
- ``on clock#timer=5 do backlog power2 on;power1 off;power3 2 endon``
- ``on clock#Timer=5 do backlog power2 on;power1 off;power3 2 endon``
Result
- When the timer expires the rule kicks in and set Power1 to OFF, Power2 to ON and Toggles Power3
If you want to have blink functionality define a rule like ``on clock#timer=5 do power 3 endon``
If you want to have blink functionality define a rule like ``on clock#Timer=5 do power 3 endon``
[BackToExamples](https://github.com/arendst/Sonoff-Tasmota/wiki/Rules#examples)
@ -454,7 +454,7 @@ NOTE: You might want to execute command ``SaveData 2`` to reduce flash writes ;-
------------------------------------------------------------------------------
#### 7. Setting variables
Demonstrate the use of variables. Make sure to execute commands ``rule 4``(Disable one-shot detection) first when trying the following example.
Demonstrate the use of variables. Make sure to execute commands ``Rule 4``(Disable one-shot detection) first when trying the following example.
* Set a variable
@ -502,14 +502,14 @@ mqtt: ``cmnd/[topic]/event anyname=number``
Everything together:
``rule on event#togglevar1 do event toggling1=%var1% endon on event#toggling1<1 do event setvar1=1 endon on event#toggling1>0 do event setvar1=0 endon on event#setvar1 do var1 %value% endon on event#getvar1 do var1 endon on event#message do publish stat/sonoff/log %value% endon``
``Rule on event#togglevar1 do event toggling1=%var1% endon on event#toggling1<1 do event setvar1=1 endon on event#toggling1>0 do event setvar1=0 endon on event#setvar1 do var1 %value% endon on event#getvar1 do var1 endon on event#message do publish stat/sonoff/log %value% endon``
**NOTE**
Note that the following won't work:
``rule on event#setvar1 do backlog var1 %value%; power1 %var1% endon``
``Rule on event#setvar1 do backlog var1 %value%; power1 %var1% endon``
Well at least not as you probably would expect. The var1 value used by the power1 command will be the value present before the backlog command is executed. This is so, because the rule will replace %var1% BEFORE the backlog commands are put in the backlog-log.
@ -565,7 +565,7 @@ Result: `VAR1 = 150`
When it is needed that a sensor value is only sent when it changes a delta, can be solved applying the following rule example:
```
rule
Rule
on SI7021#temperature>%var1% do backlog var1 %value%; publish stat/sonoff/temp %value%; var2 %value%; add1 2; sub2 2 endon
on SI7021#temperature<%var2% do backlog var2 %value%; publish stat/sonoff/temp %value%; var1 %value%; add1 2; sub2 2 endon
```
@ -575,7 +575,7 @@ on SI7021#temperature<%var2% do backlog var2 %value%; publish stat/sonoff/temp %
This example adds 2 degrees to the measured temperature and then sends that value to a MQTT topic.
```
rule
Rule
on tele-SI7021#temperature do backlog var1 %value%; add1 2; event sendtemp endon
on event#sendtemp do publish stat/sonoff/temp %var1% endon
```
@ -599,16 +599,16 @@ Inital Config:
* Available physical button as **switch1**
* **Relay1** will be used the controller
* **Rules** must be used to control Relay so the pushbutton must only control **switch1** and not directly control the relay - For this we use switchmode1 3 as described below and create the necessary rules because the pushbutton control of the relay is only disabled when the rules are in place.
* **Rules** must be used to control Relay so the pushbutton must only control **switch1** and not directly control the relay - For this we use SwitchMode1 3 as described below and create the necessary rules because the pushbutton control of the relay is only disabled when the rules are in place.
Inital config on console:
* `switchmode1 3` <- Use the switch1 as pushbutton (It will allow us to disable the link between the button and the relay by inserting a rule to dictate what the pushbutton will do - **NOTE: Until rules are created the pushbutton will still control the relay!**)
* `rule 1 ` <- turn on rules
* `rule 4` <- turn off one-shot rule
* `SwitchMode1 3` <- Use the switch1 as pushbutton (It will allow us to disable the link between the button and the relay by inserting a rule to dictate what the pushbutton will do - **NOTE: Until rules are created the pushbutton will still control the relay!**)
* `Rule 1 ` <- turn on rules
* `Rule 4` <- turn off one-shot rule
* `teleperiod 60` <- check temp every minute
* `setoption26 1` <- use power1 on mqtt messages
* `setoption0 0` <- dont save relay status on eeprom
* `SetOption26 1` <- use power1 on mqtt messages
* `SetOption0 0` <- dont save relay status on eeprom
* `poweronstate 0` <- start all relays off
* `mem1 0` <- thermostat status: 0-off 1-enabled - View or set by MQTT cmnd/sonoff/mem1
* `mem2 25` <- setpoint Temp upper limit - View or set by MQTT cmnd/sonoff/mem2
@ -618,7 +618,7 @@ Inital config on console:
Rules:
On boot start a watch dog timer to check temp sensor connection.
`rule on system#boot do ruletimer1 70 endon`
`Rule on system#boot do RuleTimer1 70 endon`
An available button is configured as switch to set thermostat ON or OFF
`on switch1#state do backlog event toggling1=%mem1% endon`
@ -626,10 +626,10 @@ An available button is configured as switch to set thermostat ON or OFF
`on event#toggling1=1 do mem 0 endon`
Check temp sensor connection. If fails, set to off and turn off thermostat. Also continue checking
`on rules#timer=1 do backlog var1 0; ruletimer1 70; power1 0 endon`
`on Rules#Timer=1 do backlog var1 0; RuleTimer1 70; power1 0 endon`
Resets checking timer if temperature is connected
`on tele-SI7021#temperature do backlog var1 1; ruletimer1 30; event ctrl_ready=1; event temp_demand=%value%; endon`
`on tele-SI7021#temperature do backlog var1 1; RuleTimer1 30; event ctrl_ready=1; event temp_demand=%value%; endon`
Thermostat control - upper limit and lower limit and enabled
`on on event#ctrl_ready>%mem1% do var1 0 endon on event#temp_demand>%mem2% do power1 0 endon on event#temp_demand<%mem3% do power1 %var1% endon`
@ -658,20 +658,20 @@ To get the status:
Everything together:
INITIAL CONFIG: (To note ruletimer1 must be greater that teleperiod for expected results)
INITIAL CONFIG: (To note RuleTimer1 must be greater that teleperiod for expected results)
`backlog switchmode1 3; rule 1; rule 4; teleperiod 60; setoption26 1; setoption0 0; poweronstate 0; mem1 0; mem2 25; mem3 23; var1 0`
`backlog SwitchMode1 3; Rule 1; Rule 4; teleperiod 60; SetOption26 1; SetOption0 0; poweronstate 0; mem1 0; mem2 25; mem3 23; var1 0`
RULES:
```
rule1 on system#boot do ruletimer1 70 endon on Switch1#State do event toggling1=%mem1% endon on event#toggling1=0 do mem 1 endon on event#toggling1=1 do mem 0 endon on rules#timer=1 do backlog var1 0; ruletimer1 70; power1 0; endon on tele-SI7021#temperature do backlog var1 1; ruletimer1 70; event ctrl_ready=1; event temp_demand=%value%; endon on event#ctrl_ready>%mem1% do var1 0 endon on event#temp_demand>%mem2% do power1 0 endon on event#temp_demand<%mem3% do power1 %var1% endon
Rule1 on system#boot do RuleTimer1 70 endon on Switch1#State do event toggling1=%mem1% endon on event#toggling1=0 do mem 1 endon on event#toggling1=1 do mem 0 endon on Rules#Timer=1 do backlog var1 0; RuleTimer1 70; power1 0; endon on tele-SI7021#temperature do backlog var1 1; RuleTimer1 70; event ctrl_ready=1; event temp_demand=%value%; endon on event#ctrl_ready>%mem1% do var1 0 endon on event#temp_demand>%mem2% do power1 0 endon on event#temp_demand<%mem3% do power1 %var1% endon
```
EXAMPLE RULES WITHOUT TEMP SENSOR TO TEST THE THERMOSTAT RULES
```
rule on system#boot do ruletimer1 70 endon on Switch1#State do event toggling1=%mem1% endon on event#toggling1=0 do mem 1 endon on event#toggling1=1 do mem 0 endon on rules#timer=1 do backlog var1 0; ruletimer1 70; power1 0; endon on event#temp do backlog var1 1; ruletimer1 70; event ctrl_ready=1; event temp_demand=%value%; endon on event#ctrl_ready>%mem1% do var1 0 endon on event#temp_demand>%mem2% do power1 0 endon on event#temp_demand<%mem3% do power1 %var1% endon
Rule on system#boot do RuleTimer1 70 endon on Switch1#State do event toggling1=%mem1% endon on event#toggling1=0 do mem 1 endon on event#toggling1=1 do mem 0 endon on Rules#Timer=1 do backlog var1 0; RuleTimer1 70; power1 0; endon on event#temp do backlog var1 1; RuleTimer1 70; event ctrl_ready=1; event temp_demand=%value%; endon on event#ctrl_ready>%mem1% do var1 0 endon on event#temp_demand>%mem2% do power1 0 endon on event#temp_demand<%mem3% do power1 %var1% endon
```
TESTS:
@ -686,7 +686,7 @@ TESTS:
TIMERS:
* With the above the timers can be used to control mem1 and add a schedule to when the thermostat will be enabled
`rule2 on Clock#Timer=1 do mem 1 endon on Clock#Timer=2 do mem 0`
`Rule2 on Clock#Timer=1 do mem 1 endon on Clock#Timer=2 do mem 0`
[BackToExamples](https://github.com/arendst/Sonoff-Tasmota/wiki/Rules#examples)
@ -696,7 +696,7 @@ TIMERS:
#### 10. Simple Staircase Timer
**Rule:**
`rule1 on button1#state do backlog power1 %value%; ruletimer1 600 endon on rules#timer=1 do power1 off endon`
`Rule1 on button1#state do backlog power1 %value%; RuleTimer1 600 endon on Rules#Timer=1 do power1 off endon`
**Result:**
@ -704,13 +704,13 @@ TIMERS:
* On Button press the Light in the Staircase will switch on/off
` ruletimer1 600 endon`
` RuleTimer1 600 endon`
* Additionaly ruletimer1 will begin to countdown 10 minutes
* Additionaly RuleTimer1 will begin to countdown 10 minutes
` on rules#timer=1 do power1 off endon`
` on Rules#Timer=1 do power1 off endon`
* After the ruletimer1 expires the ligth will be switched off (if you forgot to switch it off)
* After the RuleTimer1 expires the ligth will be switched off (if you forgot to switch it off)
[BackToExamples](https://github.com/arendst/Sonoff-Tasmota/wiki/Rules#examples)
@ -737,39 +737,39 @@ and i type the following rules in the konsole:
**Rules:**
`switchmode1 1`
`SwitchMode1 1`
`rule1 on analog#a0<400 do backlog rule3 0; rule2 1 endon on analog#a0>500 do backlog rule2 0; rule3 1 endon`
`Rule1 on analog#a0<400 do backlog Rule3 0; Rule2 1 endon on analog#a0>500 do backlog Rule2 0; Rule3 1 endon`
`rule2 on switch1#state do backlog power1 1; ruletimer1 30 endon on rules#timer=1 do power1 off endon`
`Rule2 on switch1#state do backlog power1 1; RuleTimer1 30 endon on Rules#Timer=1 do power1 off endon`
`rule3 on switch1#state do power1 off endon`
`Rule3 on switch1#state do power1 off endon`
`rule1 1` (activate rule1)
`Rule1 1` (activate Rule1)
`rule1 6` (one shot detection)
`Rule1 6` (one shot detection)
optional
`rule2 4`
`Rule2 4`
`rule3 4`
`Rule3 4`
**Result:**
`on analog#a0>400`
disable rule3 and activate rule2
disable Rule3 and activate Rule2
`on analog#a0>500`
disable rule2 and activate rule3
disable Rule2 and activate Rule3
* rule2 activates the LEDs for ruletimer1 30 seconds on each trigger from PIR the ruletimer start again.
* Rule2 activates the LEDs for RuleTimer1 30 seconds on each trigger from PIR the RuleTimer start again.
`on rules#timer=1 do power1 off`
The LEDs turn off after the ruletimer expires
`on Rules#Timer=1 do power1 off`
The LEDs turn off after the RuleTimer expires
* rule3 is active on daylight and pipe the PIR signal in a power1 off signal. The LEDs stay off.
* Rule3 is active on daylight and pipe the PIR signal in a power1 off signal. The LEDs stay off.
[BackToExamples](https://github.com/arendst/Sonoff-Tasmota/wiki/Rules#examples)
@ -791,8 +791,8 @@ on APDS9960#Ambient<%var1% do power1 on endon
_All together to work as a rule:_
```
rule 1
rule on switch1#state=1 do var1 100 endon on switch1#state=0 do backlog var1 0; power1 off endon on APDS9960#Ambient<%var1% do power1 on endon
Rule 1
Rule on switch1#state=1 do var1 100 endon on switch1#state=0 do backlog var1 0; power1 off endon on APDS9960#Ambient<%var1% do power1 on endon
```
@ -805,9 +805,9 @@ rule on switch1#state=1 do var1 100 endon on switch1#state=0 do backlog var1 0;
Assuming that your switch is on `GPIO00` and configured as `Switch1`:
```
switchmode1 1
rule 1
rule on Switch1#state=1 do Timers 0 endon on Switch1#state=0 do Timers 1 endon
SwitchMode1 1
Rule 1
Rule on Switch1#state=1 do Timers 0 endon on Switch1#state=0 do Timers 1 endon
```
Switchmode1 1 will make Switch1#state to be 1 when ON and 0 when OFF
@ -828,34 +828,34 @@ Behaviour: Disable Button1 Short Press and Toggle Relay1 only when holding the b
Type in the console:
```
buttontopic 0
setoption1 1
setoption32 20
rule on button1#state=3 do power1 2 endon on button1#state=2 do delay endon
rule 1
ButtonTopic 0
SetOption1 1
SetOption32 20
Rule on button1#state=3 do power1 2 endon on button1#state=2 do delay endon
Rule 1
```
**Commands Explanation**
`buttontopic 0` : (default) To not use topics for buttons <br>
`setoption1 1` : Allow only single, double and hold press button actions <br>
`setoption32 20` : Set key hold time from 0.1 to 10 seconds (20 = 2 seconds) <br>
`rule on button1#state=3 do power1 2 endon` : When holding the button1 for 2 seconds it wil toggle relay 1 (state = 3 means HOLD) <br>
`ButtonTopic 0` : (default) To not use topics for buttons <br>
`SetOption1 1` : Allow only single, double and hold press button actions <br>
`SetOption32 20` : Set key hold time from 0.1 to 10 seconds (20 = 2 seconds) <br>
`Rule on button1#state=3 do power1 2 endon` : When holding the button1 for 2 seconds it wil toggle relay 1 (state = 3 means HOLD) <br>
`on button1#state=2 do delay endon` : Do nothing when short pressing the button1 (state = 2 means TOGGLE) <br>
`rule 1` : To enable rules
`Rule 1` : To enable rules
NOTE: There is not a state number for "double press" for Buttons. It is designed that double press will toggle the relay. More information at: https://github.com/arendst/Sonoff-Tasmota/wiki/Control-other-devices
In the case you do not want the double press feature you can configure your button as switch and also set the switchmode that fits you (like switchmode 5 to make it behave as a pushbutton) [SWITCH does not have double press ]
In the case you do not want the double press feature you can configure your button as switch and also set the SwitchMode that fits you (like SwitchMode 5 to make it behave as a pushbutton) [SWITCH does not have double press ]
**Another example but using switch instead of button:**
```
switchtopic1 0
switchmode1 5
setoption32 20
rule on switch1#state=3 do power1 2 endon on switch1#state=2 do delay endon
rule 1
SwitchTopic1 0
SwitchMode1 5
SetOption32 20
Rule on switch1#state=3 do power1 2 endon on switch1#state=2 do delay endon
Rule 1
```
@ -896,14 +896,14 @@ PreInfo:
Commands:
```
switchmode1 1
SwitchMode1 1
rule1
Rule1
on Switch1#state=1 do backlog event checksunrise=%time%; event checksunset=%time% endon
on event#checksunrise<%sunrise% do power1 1 endon
on event#checksunset>%sunset% do power1 1 endon
rule1 1
Rule1 1
```
[BackToExamples](https://github.com/arendst/Sonoff-Tasmota/wiki/Rules#examples)
@ -932,12 +932,12 @@ And that you want:
**hold 2 secs**: send another mqtt message
```
buttontopic 0
setoption1 1
setoption11 1
setoption32 20
rule on button1#state=3 do publish cmnd/topicHOLD/power 2 endon on button1#state=2 do publish cmnd/topicDOUBLEPRESS/power 2 endon
rule 1
ButtonTopic 0
SetOption1 1
SetOption11 1
SetOption32 20
Rule on button1#state=3 do publish cmnd/topicHOLD/power 2 endon on button1#state=2 do publish cmnd/topicDOUBLEPRESS/power 2 endon
Rule 1
```
- Another example:
@ -955,8 +955,8 @@ ButtonTopic 0
SetOption1 1
SetOption11 0
SetOption32 20
rule on button1#state=3 do publish cmnd/topicHOLD/power 2 endon on button1#state=2 do publish cmnd/topicSINGLEPRESS/power 2 endon
rule 1
Rule on button1#state=3 do publish cmnd/topicHOLD/power 2 endon on button1#state=2 do publish cmnd/topicSINGLEPRESS/power 2 endon
Rule 1
```
please note that `SetOption11 0`.
@ -1002,20 +1002,20 @@ _Dont forget to change the IDX value_
**Commands:**
```
switchtopic 0
switchmode4 2
setoption0 0
SwitchTopic 0
SwitchMode4 2
SetOption0 0
poweronstate 0
var1 1
rule1
Rule1
on event#doorbell do var1 %value% endon
on switch4#state=1 do publish domoticz/in {"idx":11,"nvalue":1} endon
on switch4#state=1 do power1 %var1% endon
on switch4#state=0 do publish domoticz/in {"idx":11,"nvalue":0} endon
on switch4#state=0 do power1 0 endon
rule1 1
Rule1 1
```
<br>**Usage:**<br>
@ -1059,8 +1059,8 @@ In such case, when the active MQTT fails for any reason, the expected behavior i
That can be easily configured defining the following rule on the device console:
```
rule1 1
rule1 on Mqtt#Disconnected do MqttHost 0 endon
Rule1 1
Rule1 on Mqtt#Disconnected do MqttHost 0 endon
```
If the MqttHost field already contains an IP, you have to delete it using the web interface or the following MQTT command:
@ -1081,7 +1081,7 @@ In the example 100% is everything below 69cm and 0% is everything above 128cm.
This is used for showing fill percentage of a wood pellets storage.
```
rule
Rule
on tele-SR04#distance do backlog var1 %value%; event checklimit=%value%; event senddistance endon
on event#checklimit>128 do var1 128 endon
on event#checklimit<69 do var1 68 endon