Tutorial Rules

Introduction

Along with ESP Easy R108, a new feature was enabled, named Rules. Rules can be used to create very simple flows to control devices on your ESP.

Enable Rules

To enable rules, go to Tools/Advanced and check the Rules checkbox.

After clicking Submit, you will find a new page added. Here you can start experimenting with Rules:

The example above shows an experiment with a LED, connected via a resistor of 1k to GPIO12. To be able to read the state of the LED (on or off) a switch input is created with the same GPIO port:

After rebooting the ESP, the LED will start blinking 10 seconds on en 10 seconds off.

Enjoy.

Syntax

The syntax of a rule can be:
 on <event>[=,<,>][value] do <action>

or

 on <event>[=,<,>][value] do
  <action>
  <action>
 endon

Also simple if ... else ... endif statements are possible, but nesting and Boolean logic are not supported.

However there is a workaround for the limitation of not being able to nest. An event can be called from an event.

  On event
   If condition1 is met
    Event checkAND 
   Endif
  Endon

  On checkAND do
   If condition2 is met
    Desired action
   Endif
  Endon

Task values can be obtained in the same way as with the LCD and OLED template with [Device Name#Value Name] Timers can be used to time things.

Some examples:

PIR and LDR

 On PIR#Switch do
   if [LDR#Light]<500
     gpio,16,[PIR#Switch]
   endif
 endon

In other words: If the PIR switch is set (to either 1 or 0) and if the light value < 500, then set GPIO port 16 of the ESP.

 On PIR#Switch=1 do
   if [LDR#Light]<500
     gpio,16,[PIR#Switch]
   endif
 endon

Now the event is only triggered when the pir switches on.

SR04 and LDR

 on SR04#range<100 do
   if [ldr#lux]<500
     gpio,2,0
     gpio,16,1
   else
     gpio,2,1
     gpio,16,0
   endif
 endon

Timer

There are 8 timers (1-8) you can use:

 On System#Boot do    //When the ESP boots, do
   servo,1,12,0
   timerSet,1,10      //Set Timer 1 for the next event in 10 seconds
 endon
 On Rules#Timer=1 do  //When Timer1 expires, do
   servo,1,12,30
   timerSet,2,1       //Set Timer 2 for the next event in 1 second
 endon
 On Rules#Timer=2 do  //When Timer2 expires, do
   servo,1,12,0
   timerSet,1,30      //Set Timer1 for the next event in 30 seconds
 endon

Starting/stopping repeating timers with events

To disable an existing timer, set it to 0. This is useful to make repeating timers for things like alarms or warnings:

 //start the warning signal when we receive a start_warning event:
 On start_warning do 
   timerSet,1,2
 endon
 
 //stop the warning signal when we receive a stop_warning event:
 On stop_warning do
   timerSet,1,0
 endon
 
 //create an actual warning signal, every time timer 1 expires:
 On Rules#Timer=1 do 
   //repeat after 2 seconds 
   timerSet,1,2
 
   //pulse some led on pin 4 shortly
   Pulse,4,1,100
 
   //produce a short 1000hz beep via a piezo element on pin 14
   tone,14,1000,100
 
 endon

To start or stop the warning signal use http:

 http://192.168.0.123/control?cmd=event,start_warning
 
 http://192.168.0.123/control?cmd=event,stop_warning

HTTP call

When you enter this with the correct IP address in the URL of your browser:

 http://<ESP-ip>/control?cmd=event,givemesomewater

And have this rule in the addressed ESP:

 on givemesomewater do
   gpio,2,1  // open valve
   timerSet 1,600 // 10 minute timer
 endon

 on Rules#Timer=1 do
   gpio,2,0 // close valve
 endon

Provided that you also have the valve etc, the plants will be happy.

SendTo and Publish

With SendTo you can add a Rule to your ESPEasy, capable of sending an event to another unit. This can be useful in cases where you want to take immediate action. There are two flavors: - SendTo to send remote unit control commands using the internal peer to peer UDP messaging - Publish to send remote commands to other ESP using MQTT broker

SendTo: SendTo <unit>,<command>

Imagine you have two ESPEasy modules, ESP#1 and ESP#2 In the Rules section of ESP#1 you have this:

 on demoEvent do
   sendTo 2,event,givemesomewater (to use the previous example.
 endon

And ESP#2 has the rules according to the previous example (givemesomewater)

If you then enter this with the correct IP address in the URL of your browser:

 http://<ESP#1-ip >/control?cmd=event,demoEvent

Then ESP#1 shall send the event 'givemesomewater' to ESP#2.

It is also possible to directly order gpio changes, like:

 on demoEvent do
   sendTo 2,GPIO,2,1
 endon

Publish

 Publish <topic>,<value>

To be created.

Time

With Rules you can also start or stop actions on a given day and time, or even on every day.

 On Clock#Time=All,18:25 do // every day at 18:25 hours do ...
  gpio,14,0
 endon

Or for a specific day:

 On Clock#Time=Sun,18:25 do  // for Sunday, but All, Sun, Mon, Tue, Wed, Thu, Fri, Sat will do.
  gpio,14,0
 endon

It is also possible to use the system value %systime% in rules conditions to make things happen during certain hours of the day:

  On Pir#Switch=1 do
   If %systime% < 07:00
    Gpio,16,1
   Endif
   If %systime% > 19:00
    Gpio,16,1
   Endif
  Endon

This will set gpio 16 to 1 when the pir is triggered, if the time is before 7 in the morning or after 19:00 in the evening. ( useful if you don't have a light sensor)

SendToHTTP

To send a message to another device, like a command to switch on a light to Domoticz

 On System#Boot do    //When the ESP boots, do
   timerSet,1,10      //Set Timer 1 for the next event in 10 seconds
 endon
 
 On Rules#Timer=1 do  //When Timer1 expires, do
   SendToHTTP 192.168.0.243,8080,/json.htm?type=command&param=switchlight&idx=174&switchcmd=On
 endon

Many users have reported problems with commands being truncated, particularly when trying to send commands to domoticz. It seems to be a parsing error. There is the following workaround

   SendToHTTP 192.168.0.243,8080,/json.htm?type=param=switchlight&command&idx=174&switchcmd=On

Dew Point for temp/humidity sensors (BME280 for example)

If you have a sensor that is monitoring the air temperature and the relative humidity you may calculate the dew point with rules. This example use MQTT to publish the values but you may change this to whatever you want. We also make use of a "dummy device" to dump values, this example use two BME280 with different i2c addresses. [How to change i2c address of BME280]

Set up BME280 devices as follows:


Set up dummy device as follows:



For dew point on the outside:

 on TempHumidityPressure_OUTSIDE#%RH do
  TaskValueSet,7,1,[TempHumidityPressure_OUTSIDE#°C]-(100-[TempHumidityPressure_OUTSIDE#%RH])/5  // "7" is the number of the task that the dummy device is on, "1" is its first value where we dump our result
  if [TempHumidityPressure_OUTSIDE#%RH]>49
   Publish %sysname%/DewPoint_OUTSIDE/°C,[Dew_point#°C1]
  else
   Publish %sysname%/DewPoint_OUTSIDE/°C,[Dew_point#°C1]*  //This asterix shows that the calculation is not correct due to the humidity being below 50%!
  endif
 endon

For dew point on the inside:

 on TempHumidityPressure_INSIDE#%RH do
  TaskValueSet,7,2,[TempHumidityPressure_INSIDE#°C]-(100-[TempHumidityPressure_INSIDE#%RH])/5  // "7" is the number of the task that the dummy device is on, "2" is its second value where we dump our result
  if [TempHumidityPressure_INSIDE#%RH]>49
   Publish %sysname%/DewPoint_INSIDE/°C,[Dew_point#°C2]
  else
   Publish %sysname%/DewPoint_INSIDE/°C,[Dew_point#°C2]*  //This asterix shows that the calculation is not correct due to the humidity being below 50%!
  endif
 endon

[More info about the simplified dew point calculation is found here.]

Report IP every 30 seconds using MQTT

On System#Boot do    //When the ESP boots, do
 Publish %sysname%/IP,%ip%
  timerSet,1,30      //Set Timer 1 for the next event in 30 seconds
endon
On Rules#Timer=1 do  //When Timer1 expires, do
 Publish %sysname%/IP,%ip%
  timerSet,1,30       //Resets the Timer 1 for another 30 seconds
endon

Download the TXT file (coming soon)