mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-10-31 08:31:29 +01:00
90 lines
3.1 KiB
ReStructuredText
90 lines
3.1 KiB
ReStructuredText
Rotary Encoder Sensor
|
|
=====================
|
|
|
|
.. seo::
|
|
:description: Instructions for setting up rotary encoders.
|
|
:image: rotary_encoder.jpg
|
|
|
|
The ``rotary_encoder`` sensor platform allows you to use any continuous-rotation
|
|
rotary encoders with ESPHome. These devices usually have two pins with which
|
|
they encode the rotation. Every time the knob of the rotary encoder is turned, the
|
|
signals of the two pins go HIGH and LOW in turn. See
|
|
`this Arduino article <https://playground.arduino.cc/Main/RotaryEncoders>`__ to gain
|
|
a better understanding of these sensors.
|
|
|
|
.. figure:: images/rotary_encoder.jpg
|
|
:align: center
|
|
:width: 75.0%
|
|
|
|
Example of a continuous rotary encoder. Pin ``+`` is connected to ``3.3V``,
|
|
``GND`` is connected to ``GND``, and ``CLK`` & ``DT`` are A & B.
|
|
|
|
.. figure:: /components/sensor/images/rotary_encoder-ui.png
|
|
:align: center
|
|
:width: 75.0%
|
|
|
|
To use rotary encoders in ESPHome, first identify the two pins encoding th step value.
|
|
These are often called ``CLK`` and ``DT`` as in above image. Note if the values this sensor
|
|
outputs go in the wrong direction, you can just swap these two pins.
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
sensor:
|
|
- platform: rotary_encoder
|
|
name: "Rotary Encoder"
|
|
pin_a: D1
|
|
pin_b: D2
|
|
|
|
Configuration variables:
|
|
------------------------
|
|
|
|
- **pin_a** (**Required**, :ref:`Pin Schema <config-pin_schema>`):
|
|
The first pin for determining the step value. Must not be a pin from an external I/O expander.
|
|
- **pin_b** (**Required**, :ref:`Pin Schema <config-pin_schema>`):
|
|
The second pin for determining the step value. Must not be a pin from an external I/O expander.
|
|
- **name** (**Required**, string): The name of the rotary encoder sensor.
|
|
- **pin_reset** (*Optional*, :ref:`Pin Schema <config-pin_schema>`):
|
|
An optional pin that resets the step value. This is useful with rotary encoders that have have a
|
|
third pin. Defaults to no reset pin.
|
|
- **resolution** (*Optional*, string): The resolution of the sensor, this controls how many
|
|
pulses are generated by one step:
|
|
|
|
- 1 (default)
|
|
- 2
|
|
- 4
|
|
|
|
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
|
|
- All other options from :ref:`Sensor <config-sensor>`.
|
|
|
|
Debouncing Output
|
|
-----------------
|
|
|
|
This sensor can output a lot of values in a short period of time when turning the knob.
|
|
In order to not put too much stress on your network connection, you can leverage ESPHome's
|
|
sensor filters. The following will only send out values if the last input value is at least
|
|
0.1s seconds old *or* if the new rotary encoder value has changed by 10 from the previous value.
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
sensor:
|
|
- platform: rotary_encoder
|
|
name: "Rotary Encoder"
|
|
pin_a: D1
|
|
pin_b: D2
|
|
filters:
|
|
- or:
|
|
- debounce: 0.1s
|
|
- delta: 10
|
|
|
|
See Also
|
|
--------
|
|
|
|
- :ref:`sensor-filters`
|
|
- :doc:`pulse_counter`
|
|
- :doc:`template`
|
|
- `Mechanical Input Library <https://github.com/jkDesignDE/MechInputs>`__ by `Jochen Krapf <https://github.com/JK-de>`__
|
|
- :apiref:`sensor/rotary_encoder.h`
|
|
- :ghedit:`Edit`
|