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 | ||
e70bdd41 JH |
12 | Some encoders have both outputs low in stable states, whereas others also have |
13 | a stable state with both outputs high (half-period mode). | |
14 | ||
73969ff0 DM |
15 | The phase diagram of these two outputs look like this: |
16 | ||
17 | _____ _____ _____ | |
18 | | | | | | | | |
19 | Channel A ____| |_____| |_____| |____ | |
20 | ||
21 | : : : : : : : : : : : : | |
22 | __ _____ _____ _____ | |
23 | | | | | | | | | |
24 | Channel B |_____| |_____| |_____| |__ | |
25 | ||
26 | : : : : : : : : : : : : | |
27 | Event a b c d a b c d a b c d | |
28 | ||
29 | |<-------->| | |
30 | one step | |
31 | ||
e70bdd41 JH |
32 | |<-->| |
33 | one step (half-period mode) | |
73969ff0 DM |
34 | |
35 | For more information, please see | |
36 | http://en.wikipedia.org/wiki/Rotary_encoder | |
37 | ||
38 | ||
39 | 1. Events / state machine | |
40 | ------------------------- | |
41 | ||
e70bdd41 JH |
42 | In half-period mode, state a) and c) above are used to determine the |
43 | rotational direction based on the last stable state. Events are reported in | |
44 | states b) and d) given that the new stable state is different from the last | |
45 | (i.e. the rotation was not reversed half-way). | |
46 | ||
47 | Otherwise, the following apply: | |
48 | ||
73969ff0 DM |
49 | a) Rising edge on channel A, channel B in low state |
50 | This state is used to recognize a clockwise turn | |
51 | ||
52 | b) Rising edge on channel B, channel A in high state | |
53 | When entering this state, the encoder is put into 'armed' state, | |
54 | meaning that there it has seen half the way of a one-step transition. | |
55 | ||
56 | c) Falling edge on channel A, channel B in high state | |
57 | This state is used to recognize a counter-clockwise turn | |
58 | ||
59 | d) Falling edge on channel B, channel A in low state | |
60 | Parking position. If the encoder enters this state, a full transition | |
25985edc | 61 | should have happened, unless it flipped back on half the way. The |
73969ff0 DM |
62 | 'armed' state tells us about that. |
63 | ||
64 | 2. Platform requirements | |
65 | ------------------------ | |
66 | ||
67 | As there is no hardware dependent call in this driver, the platform it is | |
68 | used with must support gpiolib. Another requirement is that IRQs must be | |
69 | able to fire on both edges. | |
70 | ||
71 | ||
72 | 3. Board integration | |
73 | -------------------- | |
74 | ||
75 | To use this driver in your system, register a platform_device with the | |
76 | name 'rotary-encoder' and associate the IRQs and some specific platform | |
77 | data with it. | |
78 | ||
79 | struct rotary_encoder_platform_data is declared in | |
80 | include/linux/rotary-encoder.h and needs to be filled with the number of | |
81 | steps the encoder has and can carry information about externally inverted | |
bd3ce655 HS |
82 | signals (because of an inverting buffer or other reasons). The encoder |
83 | can be set up to deliver input information as either an absolute or relative | |
84 | axes. For relative axes the input event returns +/-1 for each step. For | |
85 | absolute axes the position of the encoder can either roll over between zero | |
86 | and the number of steps or will clamp at the maximum and zero depending on | |
87 | the configuration. | |
73969ff0 DM |
88 | |
89 | Because GPIO to IRQ mapping is platform specific, this information must | |
3ad2f3fb | 90 | be given in separately to the driver. See the example below. |
73969ff0 DM |
91 | |
92 | ---------<snip>--------- | |
93 | ||
94 | /* board support file example */ | |
95 | ||
96 | #include <linux/input.h> | |
97 | #include <linux/rotary_encoder.h> | |
98 | ||
99 | #define GPIO_ROTARY_A 1 | |
100 | #define GPIO_ROTARY_B 2 | |
101 | ||
102 | static struct rotary_encoder_platform_data my_rotary_encoder_info = { | |
103 | .steps = 24, | |
104 | .axis = ABS_X, | |
bd3ce655 HS |
105 | .relative_axis = false, |
106 | .rollover = false, | |
73969ff0 DM |
107 | .gpio_a = GPIO_ROTARY_A, |
108 | .gpio_b = GPIO_ROTARY_B, | |
109 | .inverted_a = 0, | |
110 | .inverted_b = 0, | |
e70bdd41 | 111 | .half_period = false, |
73969ff0 DM |
112 | }; |
113 | ||
114 | static struct platform_device rotary_encoder_device = { | |
115 | .name = "rotary-encoder", | |
116 | .id = 0, | |
117 | .dev = { | |
118 | .platform_data = &my_rotary_encoder_info, | |
119 | } | |
120 | }; | |
121 |