Updated Rule Cookbook (markdown)

Rule-Cookbook.md

@@ -21,9 +21,9 @@
   - [Enable a PIR Switch only at night](#enable-a-pir-switch-only-at-night)
     - [PIR Configuration](Wemos-D1-Mini-and-HC-SR501-PIR-Motion-Sensor#alternative-tasmota-configuration-with-rules-recommended-method)
   - [Using clock timer to control a luminance-triggered switch only in mornings](#using-clock-timer-to-control-a-luminance-triggered-switch-only-in-mornings)
-- [Using an external button with single press - double press and hold](#using-an-external-button-with-single-press---double-press-and-hold)
+- [Button with single press, double press, and hold](#button-with-single-press-double-press-and-hold)
-- [ANY action on single/double press for switches AND buttons (rules-based)](#any-action-on-singledouble-press-for-switches-and-buttons-rules-based)
+- [Perform any action on single/double press (for switches AND buttons)](#perform-any-action-on-singledouble-press-for-switches-and-buttons)
-- [Enable or disable doorbell relay with HTTP call](#enable-or-disable-doorbell-relay-with-http-call)
+- [External switch to enable or disable doorbell relay with HTTP call](#External-switch-to-enable-or-disable-doorbell-relay-with-HTTP-call)
 - [Force automatic reconnection to MQTT server via SD DNS](#force-automatic-reconnection-to-mqtt-server-via-sd-dns)
 - [Change distance to percentage](#change-distance-to-percentage)
 - [Distinguish Switch1 and Switch2 without the use of Relay1 and Relay2](#distinguish-switch1-and-switch2-without-the-use-of-relay1-and-relay2)
@@ -31,7 +31,7 @@
 - [Prevent Wemos D1 mini load overcurrent](#prevent-wemos-d1-mini-load-overcurrent)
 - [Using dummy GPIO to send Serial codes to the MCU](#Using-dummy-gpio-to-send-Serial-codes-to-the-MCU)
 - [Arithmetic Commands to be used with VARs](#arithmetic-commands-to-be-used-with-vars)
-  - [Sending the value of a sensor to MQTT only when a delta is reached](#sending-the-value-of-a-sensor-to-mqtt-only-when-a-delta-is-reached)
+  - [Transmit sensor value only when a delta is reached](#Transmit-sensor-value-only-when-a-delta-is-reached)
   - [Adjust the value of a sensor and send it by MQTT](#adjust-the-value-of-a-sensor-and-send-it-by-mqtt)
 - [Switch relays via serial interface](#Switch-relays-via-serial-interface)
 - [Using BREAK to simulate IF..ELSEIF..ELSE..ENDIF](#Using-BREAK-to-simulate-IFELSEIFELSEENDIF)
@@ -807,88 +807,71 @@ Rule2 1
 
 ------------------------------------------------------------------------------
 
-#### Using an external button with single press - double press and hold
+#### Button with single press, double press, and hold
-
-
 You can have all 3 actions but only if defining your GPIO as button. In this case the double press will toggle the relay.
 
 There is also an [option](Control-other-devices) to swap the actions of the **single press** and **double press**.
 
-So,
-
 **_BUTTON WITH 3 DIFFERENT ACTIONS_**
 
 - As an example:
+  **_[assuming Button1]_**
 
-**_[ assuming GPIO0 is configured as Button1 ]_**
+  **single press**: Turn relay 1  
+  **double press**: send a mqtt message  
+  **hold 2 secs**: send another mqtt message
 
-And that you want:
+  ```
-
+  Backlog ButtonTopic 0; SetOption1 1; SetOption11 1; SetOption32 20
-**single press**: Turn relay 1<br>
+  
-**double press**: send a mqtt message<br>
+  Rule on button1#state=3 do publish cmnd/topicHOLD/power 2 endon on button1#state=2 do publish cmnd/topicDOUBLEPRESS/power 2 endon  
-**hold 2 secs**: send another mqtt message
+  
-
+  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:
+  **_[assuming Button1]_**
 
-**_[ assuming GPIO0 is configured as Button1 ]_**
+  **single press**: send a mqtt message  
+  **double press**: Turn relay 1  
+  **hold 2 secs**: send another mqtt message  
 
-And that you want:
+  ```
+  Backlog 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
+  ```
 
-**single press**: send a mqtt message<br>
+  _**Note:**_ `SetOption11 0`  
-**double press**: Turn relay 1<br>
-**hold 2 secs**: send another mqtt message<br>
 
-```
+**_SWITCHES WITH 2 DIFFERENT ACTIONS_**  
-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
-```
 
-please note that `SetOption11 0`.
+**Switches do not have double press feature**  
-
-**_SWITCHES WITH 2 DIFFERENT ACTIONS_**
-
-**Switches do not have double press feature**
 
 - Example:
+  **_[assuming a connected pushbutton configured as Switch1]_**
 
-**_[ assuming GPIO0 is configured as Switch1 and that you have a pushbutton connected ]_**
+  **single press**: Do nothing  
+  **hold 2 secs**: Toggle relay 1
 
-And that you want:
+  ```
-
+  Backlog SwitchTopic1 0; SwitchMode1 5; SetOption32 20  
-**single press**: Do nothing<br>
+  
-**hold 2 secs**: Toggle relay 1
+  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
-```
 
 [Back To Top](#top)
 ------------------------------------------------------------------------------
 
-#### ANY action on single/double press for switches AND buttons (rules-based)
+#### Perform any action on single/double press (for switches AND buttons)
 
-There is a way to program this using rules if you wish to sacrifice a variable.<br>
-
-**Commands:**
 ```
-SwitchMode 5
+SwitchMode 5  
+
 Rule1
 on switch1#state==2 do add1 1 endon
 on switch1#state==2 do power1 2 endon
@@ -898,40 +881,34 @@ on var1#state==2 do publish cmnd/othertasmota/POWER toggle endon
 Rule1 on
 ```
 
-**Explanation:**
+**Explanation:**  
-
 - each toggle of the switch triggers first condition and adds 1 to our variable (var1 in the example),
-- each toggle of the switch toggles the associated relay (```power1 2``` - but can do anything else instead, ```publish``` for example)
+- each toggle of the switch toggles the associated relay (`Power1 2` - but can do anything else instead, `Publish` for example)
-- when var1 changes to non zero, we set it back to 0 but after a ```delay``` (arbitrarily chosen 6 here - 0.6 seconds)
+- when var1 changes to non zero, we set it back to 0 but after a `Delay` (arbitrarily chosen 6 here - 0.6 seconds)
-- when var1 reaches 2 (i.e. the switch has been toggled twice within the last 0.6 seconds), desired action is triggered (here: ```publish``` to othertasmota)
+- when var1 reaches 2 (i.e. the switch has been toggled twice within the last 0.6 seconds), desired action is triggered (here: `Publish` to `othertasmota`)
 
-**Result:**
+**Result:**  
-
+Every time you press the switch, your light toggles state (as it should). If you do press the switch twice in a rapid succession (i.e., double-click), you can trigger a different action (e.g., on a remote device).
-Every time you press the switch your light toggles state (as it should) but if you do it twice in a rapid succession, you can trigger another action elsewhere.
 
 [Back To Top](#top)
 ------------------------------------------------------------------------------
 
-#### Enable or disable doorbell relay with HTTP call
+#### External switch to enable or disable doorbell relay with HTTP call
 
-When you want to send MQTT messages ( we use domoticz in this example ) and choose when you want the relay (GPIO12) on or off, by simply sending HTTP commands to trigger an event.<br>
+When you want to send MQTT messages ( we use domoticz in this example ) and choose when you want the relay on or off, by simply sending HTTP commands to trigger an event.  
-
-In this example we're using rules.
 
 **Initial Config:**
 - PushButton Doorbell
-- GPIO14 12 Switch4 (Sonoff Basic)
+- (Sonoff Basic R1) GPIO14 - Switch4 (12)
+
+Connect the Switch to GND and the GPIO on your device. Be sure put a 4.7k resistor between VCC(3.3v) and the GPIO. This prevents ghost switching (capacitor is optional) See: [YouTube](https://www.youtube.com/watch?v=aq8_os6g13s)  
 
-Connect the PushButton to GND and GPIO14 on your Sonoff Basic.  
-Be sure put a 4.7k resistor between VCC(3.3v) and GPIO14. This prevents ghost switching (capacitor is optional) See: [YouTube](https://www.youtube.com/watch?v=aq8_os6g13s)  
 _Dont forget to change the IDX value_
 
 **Commands:**
 ```
-SwitchTopic 0
+Backlog SwitchTopic 0; SwitchMode4 2; SetOption0 0; PowerOnState 0
-SwitchMode4 2
+
-SetOption0 0
-poweronstate 0
 var1 1
 
 Rule1
@@ -944,29 +921,20 @@ on switch4#state=0 do power1 0 endon
 Rule1 1
 ```
 
-<br>**Usage:**  
+**Usage:**  
 
-Now you can call the event using HTTP to turn off the relay ( GPIO12 ).
+Turn off the relay by calling the event using HTTP:  
-```
+`http://<tasmotaIP>/cm?cmnd=event%20doorbell=0`  
-http://<tasmotaIP>/cm?cmnd=event%20doorbell=0
-```
-and to turn on the relay ( GPIO12 ) use this one below.
-```
-http://<tasmotaIP>/cm?cmnd=event%20doorbell=1
-```
 
-<BR>
+Turn on the relay by calling the event using HTTP:  
-If your Tasmota device is password protected, which is most common then use the following HTTP commands instead.  
+`http://<tasmotaIP>/cm?cmnd=event%20doorbell=1`  
-Make sure you change tasmotaUsername and tasmotaPassword  
 
-Off:
+If your Tasmota device is password protected, which is most common, then use the following HTTP commands instead. Make sure you change `<tasmotaUsername>` and `<tasmotaPassword>`  
-```
+
-http://<tasmotaIP>/cm?&user=<tasmotaUsername>&password=<tasmotaPassword>&cmnd=event%20doorbell=0
+Off:  
-```
+`http://<tasmotaIP>/cm?&user=<tasmotaUsername>&password=<tasmotaPassword>&cmnd=event%20doorbell=0`  
-On:
+On:  
-```
+`http://<tasmotaIP>/cm?&user=<tasmotaUsername>&password=<tasmotaPassword>&cmnd=event%20doorbell=1`
-http://<tasmotaIP>/cm?&user=<tasmotaUsername>&password=<tasmotaPassword>&cmnd=event%20doorbell=1
-```
 
 [Back To Top](#top)
 
@@ -976,9 +944,8 @@ http://<tasmotaIP>/cm?&user=<tasmotaUsername>&password=<tasmotaPassword>&cmnd=ev
 
 In order to search for the MQTT server using SD-DNS service (a.k.a. Bonjour or Zero Network Configuration) the suggested configuration is to leave the MQTT Host field blank.
 
-The standard behavior of Tasmota is 
+The standard behavior of Tasmota is  
-
+- searches for _mqtt._tcp service
-- to search for _mqtt._tcp service
 - resolve that to the proper IP address
 - connect to it 
 - in case the connection is successful, retain the IP address and use that in the subsequent connections
@@ -994,9 +961,7 @@ 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:
 
-```
+`mosquitto_pub -h mqtt_server.local -t "cmnd/mqttTopic/MqttHost" -m ''`
-mosquitto_pub -h mqtt_server.local -t "cmnd/mqttTopic/MqttHost" -m ''
-```
 
 
 [Back To Top](#top)
@@ -1026,26 +991,23 @@ on event#pubdata do publish tele/pannrum-temp/SENSOR %var1% endon
 
 When two (or more) switches are defined as input and you want to distinguish these in the RESULT topic without the use of Relays, then consider the following rules. 
 
+- SwitchMode1 1 will make Switch1#state to be 1 when ON and 0 when OFF  
+  `SwitchMode1 1`
 
-```
+- SwitchMode2 1 will make Switch2#state to be 1 when ON and 0 when OFF  
-- SwitchMode1 1 will make Switch1#state to be 1 when ON and 0 when OFF
+  `SwitchMode2 1`
-SwitchMode1 1
 
-- SwitchMode2 1 will make Switch2#state to be 1 when ON and 0 when OFF
+- Publish json with key POWER1 and value %value%  
-SwitchMode2 1
+  `Rule1 on switch1#state do publish stat/wemos-4/RESULT {"POWER1":"%value%"} endon`
 
-- Publish json with key POWER1 and value %value%
+- Publish json with key POWER2 and value %value%  
-Rule1 on switch1#state do publish stat/wemos-4/RESULT {"POWER1":"%value%"} endon
+  `Rule2 on switch2#state do publish stat/wemos-4/RESULT {"POWER2":"%value%"} endon`
 
-- Publish json with key POWER2 and value %value%
+- Enable Rule1  
-Rule2 on switch2#state do publish stat/wemos-4/RESULT {"POWER2":"%value%"} endon
+  `Rule1 1`
 
-- Enable Rule1
+- Enable Rule2  
-Rule1 1
+  `Rule2 1`
-
-- Enable Rule2
-Rule2 1
-```
 
 Output:
 
@@ -1147,62 +1109,56 @@ Rule3 on system#boot do backlog baudrate 9600; seriallog 2; serialsend5 55aa0003
 ------------------------------------------------------------------------------
 #### Arithmetic commands to be used with VARs
 
-* ADD
+* ADD  
+  `ADD1` to `ADD5`: Add a value to `VARx`  
+  Syntax: `ADDx value`  
+  Usage: `ADD1 15`  
+  Result: `VAR1 = VAR1 + 15`  
 
-`ADD1` to `ADD5`: Add a value to `VARx`
+* SUBTRACT  
-Syntax: `ADDx value`
+  `SUB1 `to `SUB5`: Subtract a value from `VARx`  
-Usage: `ADD1 15`
+  Syntax: `SUBx value`  
-Result: `VAR1 = VAR1 + 15`
+  Usage: `SUB1 15`  
+  Result: `VAR1 = VAR1 - 15`  
 
-* SUBTRACT
+* MULTIPLY  
+  `MULT1 `to `MULT5`: Multiply a value to `VARx`  
+  Syntax: `MULTx value`  
+  Usage: `MULT1 15`  
+  Result: `VAR1 = VAR1 * 15`  
 
-`SUB1 `to `SUB5`: Subtract a value from `VARx`
+* SCALE A VALUE  
-Syntax: `SUBx value`
+  `SCALE1 `to `SCALE5`: Scale a value from a low and high limit to another low and high limit and store it in `VARx` (directly equivalent to MAP arduino command)  
-Usage: `SUB1 15`
-Result: `VAR1 = VAR1 - 15`
 
-* MULTIPLY
+  Syntax: `SCALEx value, fromLow, fromHigh, toLow, toHigh`  
 
-`MULT1 `to `MULT5`: Multiply a value to `VARx`
+  where,  
-Syntax: `MULTx value`
-Usage: `MULT1 15`
-Result: `VAR1 = VAR1 * 15`
 
-* SCALE A VALUE
+  _value_: the number to scale  
+  _fromLow_: the lower bound of the value’s current range  
+  _fromHigh_: the upper bound of the value’s current range  
+  _toLow_: the lower bound of the value’s target range  
+  _toHigh_: the upper bound of the value’s target range  
 
-`SCALE1 `to `SCALE5`: Scale a value from a low and high limit to another low and high limit and store it in `VARx` (directly equivalent to MAP arduino command)
+  _(omitted values are taken as zero)_  
 
-Syntax: `SCALEx value, fromLow, fromHigh, toLow, toHigh`
+  Usage: `SCALE1 15, 0, 100, 0, 1000`  
+  Result: `VAR1 = 150`  
 
-where,
+#### Transmit sensor value only when a delta is reached
-
+Send only when the sensor value changes by a certain amount.
-_value_: the number to scale
-_fromLow_: the lower bound of the value’s current range
-_fromHigh_: the upper bound of the value’s current range
-_toLow_: the lower bound of the value’s target range
-_toHigh_: the upper bound of the value’s target range
-
-_(omitted values are taken as zero)_
-
-Usage: `SCALE1 15, 0, 100, 0, 1000`
-Result: `VAR1 = 150`
-
-#### Sending the value of a sensor to MQTT only when a delta is reached
-
-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
+Rule1
 on SI7021#temperature>%var1% do backlog var1 %value%; publish stat/mqttTopic/temp %value%; var2 %value%; add1 2; sub2 2 endon
 on SI7021#temperature<%var2% do backlog var2 %value%; publish stat/mqttTopic/temp %value%; var1 %value%; add1 2; sub2 2 endon
 ```
 
 #### Adjust the value of a sensor and send it by MQTT
-
+This example adds 2 degrees to the measured temperature and then sends that value to an MQTT topic.
-This example adds 2 degrees to the measured temperature and then sends that value to a MQTT topic.
 
 ```
-Rule
+Rule1
 on tele-SI7021#temperature do backlog var1 %value%; add1 2; event sendtemp endon
 on event#sendtemp do publish stat/mqttTopic/temp %var1% endon
 ```
@@ -1464,9 +1420,7 @@ Rule2 ON Power2#state=1 DO WebSend [192.168.0.144] POWER2 1 ENDON
       ON Power2#state=0 DO WebSend [192.168.0.144] POWER2 0 ENDON
 Rule3 ON Power3#state=1 DO WebSend [192.168.0.144] POWER3 1 ENDON 
       ON Power3#state=0 DO WebSend [192.168.0.144] POWER3 0 ENDON
-Rule1 1
+Backlog Rule1 1; Rule2 1; Rule3 1
-Rule2 1
-Rule3 1
 ```
 
 [Back To Top](#top)