Merge pull request tasmota#551 from barbudor/pr_rotary_rules_trigger

Rotary encoder triggers in Rules

Author: blakadder

.gitignore

@@ -12,4 +12,8 @@
 ### VisualStudioCode Patch ###
 # Ignore all local history of files
 .history
-site/
+site/
+
+# Python
+venv
+.venv

docs/Commands.md

@@ -461,7 +461,7 @@ SetOption92<a class="cmnd" id="setoption92"></a>|Alternative to `Module 38`: for
 SetOption93<a class="cmnd" id="setoption93"></a>|Control caching of compressed rules<BR>`0` = Disable memory caching of uncompressed rules <BR>`1` = Keep uncompressed rules in memory to avoid CPU load of uncompressing at each tick _(default)_
 SetOption94<a class="cmnd" id="setoption94"></a>|Select MAX31855 or MAX6675 thermocouple support<BR>`0` = Use MAX31855 protocol _(default)_ <BR>`1` = Use simpler MAX6675 protocol instead of MAX31855 
 SetOption97<a class="cmnd" id="setoption97"></a>|Set TuyaMCU serial baudrate<BR>`0` = 9600 bps _(default)_ <BR>`1` = 115200 bps     
-SetOption98<a class="cmnd" id="setoption98"></a>|Provide rotary dimmer rule triggers<BR>`0` = disabled _(default)_ <BR>`1` = enabled     
+SetOption98<a class="cmnd" id="setoption98"></a>|Provide rotary dimmer rule triggers<BR>`0` = disabled _(default)_ <BR>`1` = enabled (see [Rules](Rules#use-a-rotary-encoder))
 SetOption99<a class="cmnd" id="setoption99"></a>|Enable zero-cross capable AC dimmer<BR>`0` = no zero-cross AC dimmer connected _(default)_ <BR>`1` = zero-cross AC dimmer attached. Focus on raising edge and sync frequency     
 SetOption100<a class="cmnd" id="setoption100"></a>|remove Zigbee `ZbReceived` value from `{"ZbReceived":{xxx:yyy}}` JSON message<BR>`0` = disabled _(default)_ <BR>`1` = enabled     
 SetOption101<a class="cmnd" id="setoption101"></a>|Add Zigbee source endpoint as suffix to attributes<BR>`0` = disabled _(default)_ <BR>`1` = enabled<BR>e.g. `Power3` instead of `Power` if sent from endpoint `3`.

docs/Rules.md

@@ -94,7 +94,7 @@ Mqtt#Connected<a id="MqttConnected"></a>|when MQTT is connected
 Mqtt#Disconnected<a id="MqttDisconnected"></a>|when MQTT is disconnected
 Power1#Boot<a id="PowerBoot"></a>|`Relay1` state before Wi-Fi and MQTT are connected and before Time sync but after `PowerOnState` is executed. Power#Boot triggers before System#Boot.<BR>This trigger's value will be the last state of `Relay1` if [`PowerOnState`](Commands.md#poweronstate) is set to its default value (`3`).
 Power1#State<a id="PowerState"></a>|when a power output is changed<br>use `Power1#state=0` and `Power1#state=1` for comparison, not =off or =on<br>Power2 for Relay2, etc.
-Rules#Timer=1<a id="RulesTimer"></a>|when countdown `RuleTimer1` expires
+Rotary1#Pos1<a id="Rotary"></a>|when rotary encoder change. See [Use a rotary encoder](#use-a-rotary-encoder).Rules#Timer=1<a id="RulesTimer"></a>|when countdown `RuleTimer1` expires
 Switch1#Boot<a id="SwitchBoot"></a>|occurs after Tasmota starts before it is initializated.
 Switch1#State<a id="SwitchState"></a>|when a switch changes to state. Will not trigger if SwitchTopic is set.<br>use `Switch1#state=0` and `Switch1#state=1` for comparison, not =off or =on<br>`0` = OFF<BR>`1` = ON<BR>`2` = TOGGLE<BR>`3` = HOLD (`SwitchTopic 0` must be set for this to trigger)<BR>`4` = INC_DEC (increment or decrement dimmer)<BR>`5` = INV (change from increment to decrement dimmer and vice versa)<BR>`6` = CLEAR (button released for the time set with `SetOption32`)
 System#Boot<a id="SystemBoot"></a>|occurs once after Tasmota is fully intialized (after the INFO1, INFO2 and INFO3 console messages). `System#Boot` triggers after Wi-Fi and MQTT (if enabled) are connected. If you need a trigger prior to every service being initialized, use `Power1#Boot`
@@ -488,6 +488,25 @@ This time all lights configured with GroupTopic `grouplight` will change their b
 
 NOTE: You might want to execute command `SaveData 2` to reduce flash writes ;-)
 
+### Use a rotary encoder
+You can capture in rules the value of a rotary encoder connected to 2 GPIOs configured as `Rotary_a|<n>` and `Rotary_b|<n>`. Optionally the button of the rotary encoder can be connected to another GPIO configured as `Button|<n>`. `<n>` must be the same to allow the encoder to manage 2 absolute counters from the same rotary encoder.
+
+To get triggers from the rotary encoder into rules, you must enable [`SetOption98 1`](Commands#setoption98). The rotary encoder `<n>` provides a JSON in the form of `{'Rotary<n>': {'Pos1': value, 'Pos2': value}}`. You can use the following rules triggers:
+
+```haskell
+SetOption98 1
+Rule1
+  ON Rotary1#Pos1 DO something_with %value% ENDON
+  ON Rotary1#Pos2 DO something_with %value% ENDON
+```
+
+#### Result
+`Pos1` is changed when the rotary encoder is turned while button is not pressed. `Pos2` is changed while button is pressed. Both `Pos1` and `Pos2` are published whatever is the button position, so both trig at the same time.
+
+The button will still have it's default action (such as toggling power). If you want to avoid that, you need to capture the button into a dummy rule such as `ON Button1#state DO Delay 0 ENDON`.
+
+The range of the rotary encoder is hardcoded in `#define ROTARY_MAX_STEPS 10`. If you want to change the range, you must change the value in your `user_config_override.h` and [recompile](Compile-your-build).
+
 ------------------------------------------------------------------------------------
 
 ### Use Zigbee to control Tasmota devices