esphome-docs/components/sensor/rotary_encoder.rst

73 lines
2.8 KiB
ReStructuredText
Raw Normal View History

2018-05-17 21:40:19 +02:00
Rotary Encoder Sensor
=====================
2018-11-14 22:12:27 +01:00
.. seo::
:description: Instructions for setting up rotary encoders.
:image: rotary_encoder.jpg
2018-05-17 21:40:19 +02:00
The ``rotary_encoder`` sensor platform allows you to use any continuous-rotation
2019-02-16 23:25:23 +01:00
rotary encoders with ESPHome. These devices usually have two pins with which
2018-05-17 21:40:19 +02:00
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.
2018-06-01 18:10:00 +02:00
.. figure:: images/rotary_encoder.jpg
2018-05-17 21:40:19 +02:00
: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
2018-05-17 21:40:19 +02:00
:align: center
:width: 75.0%
2019-02-16 23:25:23 +01:00
To use rotary encoders in ESPHome, first identify the two pins encoding th step value.
2018-05-17 21:40:19 +02:00
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
2018-05-17 21:40:19 +02:00
# Example configuration entry
sensor:
- platform: rotary_encoder
name: "Rotary Encoder"
pin_a: D1
pin_b: D2
Configuration variables:
2018-08-24 22:44:01 +02:00
------------------------
2018-05-17 21:40:19 +02:00
2018-06-01 18:10:00 +02:00
- **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.
2019-02-26 21:14:23 +01:00
- **resolution** (*Optional*, string): The resolution of the sensor, this controls how many
pulses are generated by one step:
- 1 (default)
- 2
- 4
2018-06-01 18:10:00 +02:00
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
2019-03-14 16:41:37 +01:00
- **min_value** (*Optional*, int): The minimum value this rotary encoder will go to, turning
the knob further will not decrease the number. Defaults to no minimum.
- **max_value** (*Optional*, int): The maximum value this rotary encoder will go to, turning
the knob further will not increase the number. Defaults to no maximum.
2019-02-17 12:28:17 +01:00
- All other options from :ref:`Sensor <config-sensor>`.
2018-05-17 21:40:19 +02:00
2018-06-01 18:10:00 +02:00
See Also
2018-08-24 22:44:01 +02:00
--------
2018-06-01 18:10:00 +02:00
- :ref:`sensor-filters`
- :doc:`pulse_counter`
- :doc:`template`
2018-08-24 22:44:01 +02:00
- `Mechanical Input Library <https://github.com/jkDesignDE/MechInputs>`__ by `Jochen Krapf <https://github.com/JK-de>`__
2019-05-12 22:44:59 +02:00
- :apiref:`rotary_encoder/rotary_encoder.h`
- :ghedit:`Edit`