Switch input - I2C Rotary encoders

I2C Rotary encoders

Plugin details

Type: Switch input

Name: I2C Rotary encoders

Status ESP32: COLLECTION C DISPLAY

Status ESP8266: COLLECTION C DISPLAY

GitHub: P143_I2C_Rotary.ino

Maintainer: tonhuisman

Used libraries: https://github.com/adafruit/Adafruit_Seesaw

Description

To handle user input from a rotary encoder, without an timing critical code, several manufacurers have introduced integrated rotary encoders with a small controller board that interacts with the outside world via I2C. Currently this plugin supports the I2C Rotary encoders available from Adafruit, M5Stack and DFRobot.

The encoders supported have somewhat different capabilities, but they all provide a counter values, and can be pressed to act like a pushbutton. All models also support 1 or more Leds, some with 24 bit color capability (NeoPixel).

Hardware

Configuration

• Name: Required by ESPEasy, must be unique among the list of available devices/tasks.

• Enabled: The device can be disabled or enabled. When not enabled the device should not use any resources.

I2C options

• I2C Address: Depending on the selected Encoder type, different I2C Addresses are available. Adafruit supports 8 addresses, M5Stack only supports 1 address and DFRobot can be configured for 4 different addresses.

The available settings here depend on the build used. At least the Force Slow I2C speed option is available, but selections for the I2C Multiplexer can also be shown. For details see the I2C Bus page

Device Settings

• Encoder type: Select the rotary encoder used, available options:

• Adafruit The Adafruit I2C Rotary encoder (product-ID 4991), with 1 on-board NeoPixel Led that can be independently controlled.

• M5Stack The M5Stack I2C Rotary encoder (product-ID U135), with 2 on-board NeoPixel Leds, that can be controlled independently.

• DFRobot The DFRobot I2C Rotary encoder (product-ID 2575), with 20 on-board mono-color Leds, mounted in a circle, that will light up clockwise when increasing the counter value. The number of rotations/detent to move for lighting up a Led can be set using the Gain. See below for detailed description.

When this setting is changed, the page is saved and reloaded to change the I2C Address selector and show/hide the encoder specific settings.

Encoder specific: Adafruit

• Neopixel 1 initial color: The Led can be set at a specific color when the task is started. This color is specified in RGB values (0..255).

• Initial brightness: To reduce the rather bright light the NeoPixel Led can produce, the brightness can be set. Because of the way this is applied, it may affect the resulting color when setting the brightness very low. The range is 1 (dimmed) to 255 (max. brightness).

Encoder specific: M5Stack

• Neopixel 1 initial color: The first Led can be set at a specific color when the task is started. This color is specified in RGB values (0..255).

• Neopixel 2 initial color: The second Led can be set at a specific color when the task is started. This color is specified in RGB values (0..255).

• Initial brightness: To reduce the rather bright light the NeoPixel Leds can produce, the brightness can be set. This is applied to both leds. Because of the way this is applied, it may affect the resulting color when setting the brightness very low. The range is 1 (dimmed) to 255 (max. brightness).

• Color map Leds: When the Color mapping feature is used, this can be applied to both or just 1 of the Leds. That is selected here. Available options:

• Both leds The same color is set to both leds using the configured mapping.

• Led 1 only Only Led 1 is applied with the mapped color, the other Led can be set using the rules command, see below.

• Led 2 only Only Led 2 is applied with the mapped color, the other Led can be set using the rules command, see below.

Encoder specific: DFRobot

• Led vs. rotation gain: The Leds on the board always light up related to the current Counter state. The relation between the number of detents the encoder is rotated, and the number of leds lighting up, can be configured between 51: 1 led/detent (1 rotation lights up all leds) and 1: ~2.5 rotation lighting up 1 additional led (or reducing the number of leds when turning counter-clockwise).

In Generic settings:

• Offset to position: The DFRobot encoder only has a Counter range of 0..1023. To allow the position to use negative encoder positions, an offset can be applied, f.e. 511 so a range of -511..512 with a 0 center position can be used.

Generic settings

• Initial encoder position: The Counter value the encoder will be set to when starting the task.

• Lowest encoder position:

• Highest encoder position: When the encoder should have an absolute minimum and maximum Counter value, f.e. when being used as a volume control or when controlling a servo, the lowest and highest marks can be set. When turn counter-clockwise and the Counter reaches the lowest value, continuing to turn the knob will nu longer decrease the Counter value. When reverting the rotation, the Counter will immediately be incremented again, until the highest value is reached. This option is disabled when lowest and highest have the same value.

• Offset to position: Only available for DFRobot encoder, see above in Encoder specific: DFRobot section.

• Button action: Select the action the button should have when pressed. Available options:

• Pushbutton: Pushbutton action, will set the State value to 0 when pressed, and 1 when released. Also, and event <taskname>#State=<state> is generated. Initial state is 1.

• Pushbutton (inverted): Like Pushbutton, except state is 1 when pressed, and 0 when released. Initial state is 0.

• Toggle switch: Pressing the button will toggle the state value between 1 (in itial value) and 0.

• Enable Pushbutton longpress: When checked, pressing the button longer before releasing will set the state to 11 for the Pushbutton button action, and 10 for the Pushbutton (inverted) button action. This state corresponds with the regular Switch plugin longpress events. Also this state is used in the generated events.

• Longpress min. interval: The minimal duration the button has to be pressed to be recognized as a longpress. Range 500..5000 milliseconds.

• Counter color mapping: Select the desired color mapping from the current Counter value. Not available for DFRobot encoder. Available options:

• None: Color mapping is disabled.

• Color mapping: Colormap lines #1..#10 are interpreted for setting the color of the Led(s), where each line must have 4 comma separated values to be interpreted:

<counter cutoff>,<red>,<green>,<blue>

<counter cutoff>: If the Counter value is equal or below this value, the set RGB color will be set on the Led(s)

<red>,<green>,<blue>: The red, green and blue values, range 0..255, to be used.

Example Color mapping configuration:

With this Color mapping, the Led(s) will be green when the Counter is 0, orange-ish in ranges -1..-9 and 1..10, and red when -10 or lower, or > 10. This can be adjusted for different colors or ranges. The lowest position is set to -20 and the highest to 20.

• Color gradient: Similar to the Color mapping, the Color gradient uses 4 comma separated values in the Colormap #1..#10 lines, but instead of an exact color, it calculates the relative gradient color between 2 provided colors that the Counter value matches:

With this color gradient setting, the Led(s) will be turning from green to blue when the Counter goes below 0, and from green to red when the Counter value changes from 0 to 20.

NB: Colors will not be exact when a lower value is selected for Initial brightness, or when the brightness is changed from rules.

• Led(s) off on exit: When checked, all controlled leds on the encoders will be turned off, either by setting the color to black, or setting the encoder position to 0 (DFRobot).

Data Acquisition

This group of settings are standard available configuration items.

• Single event with all values: When this setting is enabled, all available values will be sent in a single event <TaskName>#All, with all values in order as arguments to the event.

• Show derived values: When checked, the Devices overview page, and the /json endpoint (used for updating the Devices overview page) will include any Derived values as defined. See the TaskValueSetDerived and TaskValueSetPresentation commands.

• Event & Log derived values: When checked, the Derived values will be generated as Events, to be handled in Rules, and sent to logging devices like the Syslog server and/or SD-card logging.

(The derived values options are only available if String variables feature is included in the build.)

• Send to Controller: Select the Controller(s) to send the Values to, either on a TaskRun command applied to the task, or on an Interval time action.

Send to Controller is only visible when one or more Controllers are configured.

Depending on the controller capabilities, some configuration settings may be shown:

All configured Controllers are shown here, including the enabled or disabled state (multiple Controllers can be enabled, only a single MQTT Controller can be enabled at one time!).

For each controller the user can select wether the data should be sent on each Interval (or explicit TaskRun).

For the Domoticz controllers the value index (IDX) has to be configured.

For some controllers, like Home Assistant/openHAB, there are extra options available.

• Group: This represents the group id to combine all values from multiple tasks into a single grouped-device during MQTT AutoDiscovery. Groups, by design, can span multiple ESPEasy devices, if desired, as long as the Task/Valuename combinations are unique. If a group should only combine Tasks from a single ESPEasy unit, the group id should be unique across multiple ESPEasy units. The group description, default Group <n>, can be adjusted in Home Assistant. If the Group value matches the current Unit nr, the Unit name, %sysname%, is used instead of Group <nr>.

• Retained: For MQTT Controllers, this setting can be enabled to send the values for the current task with the Retain flag set. The Publish Retain flag in the Controller settings will override this by sending all task values with Retain flag enabled.

• Send derived: This checkbox determines if any configured Derived values should also be sent to the controller (and included in the AutoDiscovery if that’s available and enabled).

• Resend MQTT Discovery: When checked, will start a resend of the MQTT Discovery process for this task after a random delay, when Submit is clicked, so any changed settings will be updated in the MQTT broker. This setting is only available if the controller is enabled, the Auto Discovery feature is available and enabled for the controller. This setting is not stored.

Other controllers, like f.e. FHEM HTTP, do not support additional settings besides the checkbox to enable sending the data.

Values

The plugin provides the Counter and State values.

Commands available

Command Syntax	Extra information
i2cencoder,bright,<brightness> <brightness>: Range 1..255.	Set the brightness of the Led(s). NeoPixel leds can be quite bright, to reduce the amount of light, and current used, the brightness can be adjusted. NB: Not applicable for DFRobot.
i2cencoder,led1,<red>,<green>,<blue>	Set the color of the first led to the provided RGB color, with brightness applied. NB: Not applicable for DFRobot encoder.
i2cencoder,led2,<red>,<green>,<blue>	Set the color of the second led to the provided RGB color, with brightness applied. NB: ONLY available for M5Stack encoder.
i2cencoder,gain,<gain> <gain>: Range 1..51.	Set the Led vs. rotation gain, the relation between the number of detents the encoder is rotated, and the number of leds lighting up. It can be configured between 51: 1 led/detent (1 rotation lights up all leds) and 1: ~2.5 rotation lighting up 1 additional led (or reducing the number of leds when turning counter-clockwise). NB: ONLY available for DFRobot encoder.
i2cencoder,set,<position>[,<initialOffset>] <position>: Numeric value. 0 will be used when not provided. <initialOffset>: Range: 0..1023. Not set when not provided.	Set the current encoder position. For DFRobot encoder, the initial offset can be updated (optional). The device configuration setting will also be updated with this value, but not saved.

Events

Event	Extra information
<taskname>#Counter=<counter>,<delta> counter: Current counter value. delta: Change of counter from previous position.	This event is generated on every change of the rotary encoder. Because the encoder can be rotated rather quick, the delta since the previous reading is calculated. If the value is below 0 the encoder is turned counter-clockwise, and when delta is positive, the rotation is clockwise.
<taskname>#State=<state> state: Current state value. Possible values: 0, 1, 10, 11. 0 and 1 for regulat button states, 10 and 11 for longpress states.	This event is generated on buttonpress action. Depending on the action defined, either the button-down and button-up cause this event (Pushbutton), or when the state is changed (Toggle switch).

Change log

Changed in version 2.0: …

added 2022-11-22 Initial release version.