Rules - pauloromeira/Sonoff-Tasmota GitHub Wiki

Starting with version 5.12.0l Sonoff-Tasmota optionally provides Rules heavily inspired by the ESP Easy implementation.

Rules expand the available functionality in Sonoff-Tasmota with user flexibility. It allows for different actions on different button, switch or power responses. Rules are stored in flash and therefore will survive a reboot. Rules act on triggers initiated by events like a System Boot or a Timer being activated.

Using rules many issues can be resolved.

To use rules the define USE_RULES has to be enabled in file user_config_override.h

When enabled three new powerful commands are available.

• Rule controls the storage of user defined rules up to 511 characters. It also allows for enabling or disabling rules. In some situations, like slow changing sensors (temperature), it allows for enabling or disabling one-shot rule activation.
• RuleTimer provides up to eight timers to be used as countdown event.
• Event allows a user to initiate a rule.

See the commands description for the correct syntax and options.

A rule is using the following syntax:

on <trigger> do <command> endon

Rules can be concatenated and have to be on one line:

on <trigger1> do <command> endon on <trigger2> do <command> endon ...

Spaces after on, around do and before endon are mandatory. A rule is not case sensitive.

A trigger consists of one of either:

<SensorName>#<ValueName>
<SensorName>#<ValueName>=<value>
<SensorName>#<ValueName><<value>
<SensorName>#<ValueName>><value>
Tele-<SensorName>#<ValueName>

Available triggers are:

• System#Boot occurs once after mqtt is initialized. Due to command execution it cannot be made available earlier.
• Mqtt#Connected when MQTT is connected.
• Mqtt#Disconnected when MQTT is disconnected.
• Time#Initialized once when NTP is initialized and time is in sync
• Time#Set every hour when NTP makes time in sync
• Clock#Timer=3 when global Timer3 is activated
• Rules#Timer=1 when countdown RuleTimer1 expires
• Event#Anyname when command Event Anyname is executed
• Power1#State when a power output is changed
• Button2#State when a button input is changed
• Switch1#State when a switch input is changed
• Analog#A0div10 when the A0 input changes by more than 1% it provides a value between 0 and 100

In addition all connected sensors can be a trigger in the form as they are represented in the teleperiod or Status 8 JSON message like:

• Dsb18b20#Temperature<20 whenever the temperature of sensor DSB18B20 is below 20 degrees
• AM2301-12#Humidity=55.5 whenever the hunidity 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

To trigger on a sensor at Teleperiod time only you may prefix the sensor with the word tele- to distinguish it from the above shown trigger. See example 5 below.

<value> can be any number or text to test the rule on.

A command is any available command including command Backlog. A command parameter may be replaced with variable %value% to be substituted by the trigger <value>. See example below.

Special commands are the words var1 until var5. They provide a means to store the trigger <value> in a variable %var1% until %var5% to be used in a next rule within the rules. All variables will be empty on start of the first rule. See example 5 below.

Currently no if directive or nested rules are supported.

The following examples will explain some use cases.

As a WS2812 24 led ring draws approximately 24x3x20 mA = 1.44A and the Wemos D1 mini powered from a PC's USB port can only provide up to 0.5A it would be nice to have some kind of mechanism in place to limit the amount of current to the WS2812 ledring to 0.1A. This is still enough to light all 24 leds up to color 202020.

Hardware

• Wemos D1 mini
• INA219 I2C sensor
• WS2812 ledring with 24 leds powered by the Wemos D1 mini 5V thru the INA219 sensor

Software

• Sonoff-Tasmota v5.12.0l or up with define USE_RULES enabled

Rule

• on INA219#Current>0.100 do Backlog Dimmer 10;Color 10,0,0 endon

Result

• When a user raises brightness to a level using more than 0.1A the rule kicks in and lowers the current by executing command Dimmer 10 and changes the color to Red with command Color 10,0,0.

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.

By using a rule a single button can now send any MQTT message allowing much more flexibility.

Hardware

• Sonoff 4CH

Software

• Sonoff-Tasmota v5.12.0l or up with define USE_RULES enabled
• Disable ButtonTopic as it overrides rules for buttons: ButtonTopic 0

Rule

• on button1#state do publish cmnd/ring2/power %value% endon on button2#state do publish cmnd/strip1/power %value% endon

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.

The default Timer1..16 functionality allows for controlling one output to either off, on, toggle or blink. When rules are enabled the blink option will be replaced by rule functionality allowing much more flexibility.

Hardware

• Sonoff 4CH

Software

• Sonoff-Tasmota v5.12.0l or up with define USE_RULES enabled
• 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

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

The rule command once option provides the possibility to trigger only once on a slow change while the change is still within the bounds of the test.

Rule

• on ENERGY#Current>0.100 do publish tool/tablesaw/power 1 endon on ENERGY#Current<0.100 do publish tool/tablesaw/power 0 endon

This creates a rule to publish MQTT commands whenever a Sonoff POW has current passing through it. Used as is, it will publish MQTT commands repeatedly, over and over, while current is >0.100 ... but, executing another command:

Rule 5

Now the MQTT message will be sent once, and only once, while the condition is met. This is perfect for thermostat on/off depending on temperature, bathroom extractor fan on/off depending on humidity, workshop dust collector on/off depending on whether some dust-producing machine is running.

It meets the 'hard thermostat' requests that have been common.

Using variables allows for storing sensor results to be used in composing a single HA message like used with Domoticz. To prevent flooding Domoticz with messages we only want to send a message at TelePeriod time. This is achieved by prefixing the SensorName with the label tele-. This example will use a variable storing the temperature to be used together with humidity in one Domoticz MQTT message.

Hardware

• Sonoff TH or Wemos D1 mini
• AM2301 Temperature and Humidity sensor

Software

• Sonoff-Tasmota v5.12.0m or up with define USE_RULES enabled
• Home Automation tool Domoticz configured with a virtual sensor Temp+Hum using Idx 134

Rule

• on tele-am2301-12#temperature do var1=%value% endon on tele-am2301-12#humidity do publish domoticz/in {"idx":134,"svalue":"%var1%;%value%;1"} endon

Result

• As a result of the tele- prefix the rules will be checked at TelePeriod time for sensor AM2301-12 Temperature and Humidity. The first rule will use the Temperature stored in %value% and save it in %var1% for future use. The second rule will use the Humidity stored in %value% and the Temperature stored in %var1% to compose a single MQTT message suitable for Domoticz.

Clever Dickies now finally have a way to send Temperatures from multiple DS18B20 to Domoticz

Connecting a potentiometer to the Analog A0 input and a rule can be used to control the dimmer state of any device.

Hardware

• Wemos D1 mini
• Potentiometer of 2k2 connected to Gnd, A0 and 3V3
• WS2812 led

Software

• Sonoff-Tasmota v5.12.0n or up with define USE_RULES enabled

Rule

• on analog#a0div10 do dimmer %value% endon

Result

• Turning the potentiometer the voltage on the analog input will change resulting in a value change of 0 (Off) to 100 for the trigger. Using this value to control the dimmer of the WS2812 will control the brightness of the led(s)

Rule

• on analog#a0div10 do publish cmnd/grouplight/dimmer %value% endon

Result

• This time all lights configured with GroupTopic grouplight will change their brightness according to the potentiometer position.

NOTE: You might want to execute command SaveData 2 to reduce flash writes ;-)