Commit | Line | Data |
---|---|---|
73969ff0 DM |
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 | ||
3a341a4c EG |
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). | |
e70bdd41 | 15 | |
73969ff0 DM |
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 | ||
e70bdd41 JH |
33 | |<-->| |
34 | one step (half-period mode) | |
73969ff0 | 35 | |
3a341a4c EG |
36 | |<>| |
37 | one step (quarter-period mode) | |
38 | ||
73969ff0 | 39 | For more information, please see |
ae13c65b | 40 | https://en.wikipedia.org/wiki/Rotary_encoder |
73969ff0 DM |
41 | |
42 | ||
43 | 1. Events / state machine | |
44 | ------------------------- | |
45 | ||
e70bdd41 JH |
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 | ||
73969ff0 DM |
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 | |
25985edc | 65 | should have happened, unless it flipped back on half the way. The |
73969ff0 DM |
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 | |
bd3ce655 HS |
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. | |
73969ff0 DM |
92 | |
93 | Because GPIO to IRQ mapping is platform specific, this information must | |
3ad2f3fb | 94 | be given in separately to the driver. See the example below. |
73969ff0 DM |
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, | |
bd3ce655 HS |
109 | .relative_axis = false, |
110 | .rollover = false, | |
73969ff0 DM |
111 | .gpio_a = GPIO_ROTARY_A, |
112 | .gpio_b = GPIO_ROTARY_B, | |
113 | .inverted_a = 0, | |
114 | .inverted_b = 0, | |
e70bdd41 | 115 | .half_period = false, |
47ec6e5a | 116 | .wakeup_source = false, |
73969ff0 DM |
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 |