Daniel Mack | 73969ff | 2009-03-04 23:27:14 -0800 | [diff] [blame] | 1 | rotary-encoder - a generic driver for GPIO connected devices |
| 2 | Daniel Mack <daniel@caiaq.de>, Feb 2009 |
| 3 | |
| 4 | 0. Function |
| 5 | ----------- |
| 6 | |
| 7 | Rotary encoders are devices which are connected to the CPU or other |
| 8 | peripherals with two wires. The outputs are phase-shifted by 90 degrees |
| 9 | and by triggering on falling and rising edges, the turn direction can |
| 10 | be determined. |
| 11 | |
Ezequiel Garcia | 3a341a4 | 2015-10-13 23:39:50 -0700 | [diff] [blame] | 12 | Some encoders have both outputs low in stable states, others also have |
| 13 | a stable state with both outputs high (half-period mode) and some have |
| 14 | a stable state in all steps (quarter-period mode). |
Johan Hovold | e70bdd4 | 2011-05-11 16:35:30 -0700 | [diff] [blame] | 15 | |
Daniel Mack | 73969ff | 2009-03-04 23:27:14 -0800 | [diff] [blame] | 16 | The phase diagram of these two outputs look like this: |
| 17 | |
| 18 | _____ _____ _____ |
| 19 | | | | | | | |
| 20 | Channel A ____| |_____| |_____| |____ |
| 21 | |
| 22 | : : : : : : : : : : : : |
| 23 | __ _____ _____ _____ |
| 24 | | | | | | | | |
| 25 | Channel B |_____| |_____| |_____| |__ |
| 26 | |
| 27 | : : : : : : : : : : : : |
| 28 | Event a b c d a b c d a b c d |
| 29 | |
| 30 | |<-------->| |
| 31 | one step |
| 32 | |
Johan Hovold | e70bdd4 | 2011-05-11 16:35:30 -0700 | [diff] [blame] | 33 | |<-->| |
| 34 | one step (half-period mode) |
Daniel Mack | 73969ff | 2009-03-04 23:27:14 -0800 | [diff] [blame] | 35 | |
Ezequiel Garcia | 3a341a4 | 2015-10-13 23:39:50 -0700 | [diff] [blame] | 36 | |<>| |
| 37 | one step (quarter-period mode) |
| 38 | |
Daniel Mack | 73969ff | 2009-03-04 23:27:14 -0800 | [diff] [blame] | 39 | For more information, please see |
Masanari Iida | ae13c65 | 2015-06-18 00:12:02 +0900 | [diff] [blame] | 40 | https://en.wikipedia.org/wiki/Rotary_encoder |
Daniel Mack | 73969ff | 2009-03-04 23:27:14 -0800 | [diff] [blame] | 41 | |
| 42 | |
| 43 | 1. Events / state machine |
| 44 | ------------------------- |
| 45 | |
Johan Hovold | e70bdd4 | 2011-05-11 16:35:30 -0700 | [diff] [blame] | 46 | In half-period mode, state a) and c) above are used to determine the |
| 47 | rotational direction based on the last stable state. Events are reported in |
| 48 | states b) and d) given that the new stable state is different from the last |
| 49 | (i.e. the rotation was not reversed half-way). |
| 50 | |
| 51 | Otherwise, the following apply: |
| 52 | |
Daniel Mack | 73969ff | 2009-03-04 23:27:14 -0800 | [diff] [blame] | 53 | a) Rising edge on channel A, channel B in low state |
| 54 | This state is used to recognize a clockwise turn |
| 55 | |
| 56 | b) Rising edge on channel B, channel A in high state |
| 57 | When entering this state, the encoder is put into 'armed' state, |
| 58 | meaning that there it has seen half the way of a one-step transition. |
| 59 | |
| 60 | c) Falling edge on channel A, channel B in high state |
| 61 | This state is used to recognize a counter-clockwise turn |
| 62 | |
| 63 | d) Falling edge on channel B, channel A in low state |
| 64 | Parking position. If the encoder enters this state, a full transition |
Lucas De Marchi | 25985ed | 2011-03-30 22:57:33 -0300 | [diff] [blame] | 65 | should have happened, unless it flipped back on half the way. The |
Daniel Mack | 73969ff | 2009-03-04 23:27:14 -0800 | [diff] [blame] | 66 | 'armed' state tells us about that. |
| 67 | |
| 68 | 2. Platform requirements |
| 69 | ------------------------ |
| 70 | |
| 71 | As there is no hardware dependent call in this driver, the platform it is |
| 72 | used with must support gpiolib. Another requirement is that IRQs must be |
| 73 | able to fire on both edges. |
| 74 | |
| 75 | |
| 76 | 3. Board integration |
| 77 | -------------------- |
| 78 | |
| 79 | To use this driver in your system, register a platform_device with the |
| 80 | name 'rotary-encoder' and associate the IRQs and some specific platform |
| 81 | data with it. |
| 82 | |
| 83 | struct rotary_encoder_platform_data is declared in |
| 84 | include/linux/rotary-encoder.h and needs to be filled with the number of |
| 85 | steps the encoder has and can carry information about externally inverted |
H Hartley Sweeten | bd3ce65 | 2009-04-17 20:12:35 -0700 | [diff] [blame] | 86 | signals (because of an inverting buffer or other reasons). The encoder |
| 87 | can be set up to deliver input information as either an absolute or relative |
| 88 | axes. For relative axes the input event returns +/-1 for each step. For |
| 89 | absolute axes the position of the encoder can either roll over between zero |
| 90 | and the number of steps or will clamp at the maximum and zero depending on |
| 91 | the configuration. |
Daniel Mack | 73969ff | 2009-03-04 23:27:14 -0800 | [diff] [blame] | 92 | |
| 93 | Because GPIO to IRQ mapping is platform specific, this information must |
Daniel Mack | 3ad2f3fb | 2010-02-03 08:01:28 +0800 | [diff] [blame] | 94 | be given in separately to the driver. See the example below. |
Daniel Mack | 73969ff | 2009-03-04 23:27:14 -0800 | [diff] [blame] | 95 | |
| 96 | ---------<snip>--------- |
| 97 | |
| 98 | /* board support file example */ |
| 99 | |
| 100 | #include <linux/input.h> |
| 101 | #include <linux/rotary_encoder.h> |
| 102 | |
| 103 | #define GPIO_ROTARY_A 1 |
| 104 | #define GPIO_ROTARY_B 2 |
| 105 | |
| 106 | static struct rotary_encoder_platform_data my_rotary_encoder_info = { |
| 107 | .steps = 24, |
| 108 | .axis = ABS_X, |
H Hartley Sweeten | bd3ce65 | 2009-04-17 20:12:35 -0700 | [diff] [blame] | 109 | .relative_axis = false, |
| 110 | .rollover = false, |
Daniel Mack | 73969ff | 2009-03-04 23:27:14 -0800 | [diff] [blame] | 111 | .gpio_a = GPIO_ROTARY_A, |
| 112 | .gpio_b = GPIO_ROTARY_B, |
| 113 | .inverted_a = 0, |
| 114 | .inverted_b = 0, |
Johan Hovold | e70bdd4 | 2011-05-11 16:35:30 -0700 | [diff] [blame] | 115 | .half_period = false, |
Sylvain Rochet | 47ec6e5 | 2015-10-13 23:24:36 -0700 | [diff] [blame] | 116 | .wakeup_source = false, |
Daniel Mack | 73969ff | 2009-03-04 23:27:14 -0800 | [diff] [blame] | 117 | }; |
| 118 | |
| 119 | static struct platform_device rotary_encoder_device = { |
| 120 | .name = "rotary-encoder", |
| 121 | .id = 0, |
| 122 | .dev = { |
| 123 | .platform_data = &my_rotary_encoder_info, |
| 124 | } |
| 125 | }; |
| 126 | |