Documentation/input/devices/rotary-encoder.rst

   1 ============================================================
   2 rotary-encoder - a generic driver for GPIO connected devices
   3 ============================================================
   4
   5 :Author: Daniel Mack <daniel@caiaq.de>, Feb 2009
   6
   7 Function
   8 --------
   9
  10 Rotary encoders are devices which are connected to the CPU or other
  11 peripherals with two wires. The outputs are phase-shifted by 90 degrees
  12 and by triggering on falling and rising edges, the turn direction can
  13 be determined.
  14
  15 Some encoders have both outputs low in stable states, others also have
  16 a stable state with both outputs high (half-period mode) and some have
  17 a stable state in all steps (quarter-period mode).
  18
  19 The phase diagram of these two outputs look like this::
  20
  21                   _____       _____       _____
  22                  |     |     |     |     |     |
  23   Channel A  ____|     |_____|     |_____|     |____
  24
  25                  :  :  :  :  :  :  :  :  :  :  :  :
  26             __       _____       _____       _____
  27               |     |     |     |     |     |     |
  28   Channel B   |_____|     |_____|     |_____|     |__
  29
  30                  :  :  :  :  :  :  :  :  :  :  :  :
  31   Event          a  b  c  d  a  b  c  d  a  b  c  d
  32
  33                 |<-------->|
  34                   one step
  35
  36                 |<-->|
  37                   one step (half-period mode)
  38
  39                 |<>|
  40                   one step (quarter-period mode)
  41
  42 For more information, please see
  43         https://en.wikipedia.org/wiki/Rotary_encoder
  44
  45
  46 Events / state machine
  47 ----------------------
  48
  49 In half-period mode, state a) and c) above are used to determine the
  50 rotational direction based on the last stable state. Events are reported in
  51 states b) and d) given that the new stable state is different from the last
  52 (i.e. the rotation was not reversed half-way).
  53
  54 Otherwise, the following apply:
  55
  56 a) Rising edge on channel A, channel B in low state
  57         This state is used to recognize a clockwise turn
  58
  59 b) Rising edge on channel B, channel A in high state
  60         When entering this state, the encoder is put into 'armed' state,
  61         meaning that there it has seen half the way of a one-step transition.
  62
  63 c) Falling edge on channel A, channel B in high state
  64         This state is used to recognize a counter-clockwise turn
  65
  66 d) Falling edge on channel B, channel A in low state
  67         Parking position. If the encoder enters this state, a full transition
  68         should have happened, unless it flipped back on half the way. The
  69         'armed' state tells us about that.
  70
  71 Platform requirements
  72 ---------------------
  73
  74 As there is no hardware dependent call in this driver, the platform it is
  75 used with must support gpiolib. Another requirement is that IRQs must be
  76 able to fire on both edges.
  77
  78
  79 Board integration
  80 -----------------
  81
  82 To use this driver in your system, register a platform_device with the
  83 name 'rotary-encoder' and associate the IRQs and some specific platform
  84 data with it. Because the driver uses generic device properties, this can
  85 be done either via device tree, ACPI, or using static board files, like in
  86 example below:
  87
  88 ::
  89
  90         /* board support file example */
  91
  92         #include <linux/input.h>
  93         #include <linux/gpio/machine.h>
  94         #include <linux/property.h>
  95
  96         #define GPIO_ROTARY_A 1
  97         #define GPIO_ROTARY_B 2
  98
  99         static struct gpiod_lookup_table rotary_encoder_gpios = {
 100                 .dev_id = "rotary-encoder.0",
 101                 .table = {
 102                         GPIO_LOOKUP_IDX("gpio-0",
 103                                         GPIO_ROTARY_A, NULL, 0, GPIO_ACTIVE_LOW),
 104                         GPIO_LOOKUP_IDX("gpio-0",
 105                                         GPIO_ROTARY_B, NULL, 1, GPIO_ACTIVE_HIGH),
 106                         { },
 107                 },
 108         };
 109
 110         static const struct property_entry rotary_encoder_properties[] __initconst = {
 111                 PROPERTY_ENTRY_U32("rotary-encoder,steps-per-period", 24),
 112                 PROPERTY_ENTRY_U32("linux,axis",                      ABS_X),
 113                 PROPERTY_ENTRY_U32("rotary-encoder,relative_axis",    0),
 114                 { },
 115         };
 116
 117         static struct platform_device rotary_encoder_device = {
 118                 .name           = "rotary-encoder",
 119                 .id             = 0,
 120         };
 121
 122         ...
 123
 124         gpiod_add_lookup_table(&rotary_encoder_gpios);
 125         device_add_properties(&rotary_encoder_device, rotary_encoder_properties);
 126         platform_device_register(&rotary_encoder_device);
 127
 128         ...
 129
 130 Please consult device tree binding documentation to see all properties
 131 supported by the driver.