encoders.md (6351B)
1 # Encoders 2 3 Basic (EC11 compatible) encoders are supported by adding this to your `rules.mk`: 4 5 ```make 6 ENCODER_ENABLE = yes 7 ``` 8 9 and this to your `config.h`: 10 11 ```c 12 #define ENCODER_A_PINS { B12 } 13 #define ENCODER_B_PINS { B13 } 14 ``` 15 16 Each PAD_A/B variable defines an array so multiple encoders can be defined, e.g.: 17 18 ```c 19 #define ENCODER_A_PINS { encoder1a, encoder2a } 20 #define ENCODER_B_PINS { encoder1b, encoder2b } 21 ``` 22 23 If your encoder's clockwise directions are incorrect, you can swap the A & B pad definitions. They can also be flipped with a define: 24 25 ```c 26 #define ENCODER_DIRECTION_FLIP 27 ``` 28 29 Additionally, the resolution, which defines how many pulses the encoder registers between each detent, can be defined with: 30 31 ```c 32 #define ENCODER_RESOLUTION 4 33 ``` 34 35 It can also be defined per-encoder, by instead defining: 36 37 ```c 38 #define ENCODER_RESOLUTIONS { 4, 2 } 39 ``` 40 41 For 4× encoders you also can assign default position if encoder skips pulses when it changes direction. For example, if your encoder send high level on both pins by default, define this: 42 43 ```c 44 #define ENCODER_DEFAULT_POS 0x3 45 ``` 46 47 ## Split Keyboards 48 49 If you are using different pinouts for the encoders on each half of a split keyboard, you can define the pinout (and optionally, resolutions) for the right half like this: 50 51 ```c 52 #define ENCODER_A_PINS_RIGHT { encoder1a, encoder2a } 53 #define ENCODER_B_PINS_RIGHT { encoder1b, encoder2b } 54 #define ENCODER_RESOLUTIONS_RIGHT { 2, 4 } 55 ``` 56 57 If the `_RIGHT` definitions aren't specified in your `config.h`, then the non-`_RIGHT` versions will be applied to both sides of the split. 58 59 Additionally, if one side does not have an encoder, you can specify `{}` for the pins/resolution -- for example, a split keyboard with only a right-side encoder: 60 61 ```c 62 #define ENCODER_A_PINS { } 63 #define ENCODER_B_PINS { } 64 #define ENCODER_RESOLUTIONS { } 65 #define ENCODER_A_PINS_RIGHT { B12 } 66 #define ENCODER_B_PINS_RIGHT { B13 } 67 #define ENCODER_RESOLUTIONS_RIGHT { 4 } 68 ``` 69 70 ::: warning 71 Keep in mind that whenever you change the encoder resolution, you will need to reflash the half that has the encoder affected by the change. 72 ::: 73 74 ## Encoder map {#encoder-map} 75 76 Encoder mapping may be added to your `keymap.c`, which replicates the normal keyswitch layer handling functionality, but with encoders. Add this to your keymap's `rules.mk`: 77 78 ```make 79 ENCODER_MAP_ENABLE = yes 80 ``` 81 82 Your `keymap.c` will then need an encoder mapping defined (for four layers and two encoders): 83 84 ```c 85 #if defined(ENCODER_MAP_ENABLE) 86 const uint16_t PROGMEM encoder_map[][NUM_ENCODERS][NUM_DIRECTIONS] = { 87 [0] = { ENCODER_CCW_CW(MS_WHLU, MS_WHLD), ENCODER_CCW_CW(KC_VOLD, KC_VOLU) }, 88 [1] = { ENCODER_CCW_CW(UG_HUED, UG_HUEU), ENCODER_CCW_CW(UG_SATD, UG_SATU) }, 89 [2] = { ENCODER_CCW_CW(UG_VALD, UG_VALU), ENCODER_CCW_CW(UG_SPDD, UG_SPDU) }, 90 [3] = { ENCODER_CCW_CW(UG_PREV, UG_NEXT), ENCODER_CCW_CW(KC_RIGHT, KC_LEFT) }, 91 }; 92 #endif 93 ``` 94 95 ::: tip 96 This should only be enabled at the keymap level. 97 ::: 98 99 Using encoder mapping pumps events through the normal QMK keycode processing pipeline, resulting in a _keydown/keyup_ combination pushed through `process_record_xxxxx()`. To configure the amount of time between the encoder "keyup" and "keydown", you can add the following to your `config.h`: 100 101 ```c 102 #define ENCODER_MAP_KEY_DELAY 10 103 ``` 104 105 ::: tip 106 By default, the encoder map delay matches the value of `TAP_CODE_DELAY`. 107 ::: 108 109 ## Callbacks 110 111 ::: tip 112 [**Default Behaviour**](https://github.com/qmk/qmk_firmware/blob/master/quantum/encoder.c#L79-): all encoders installed will function as volume up (`KC_VOLU`) on clockwise rotation and volume down (`KC_VOLD`) on counter-clockwise rotation. If you do not wish to override this, no further configuration is necessary. 113 ::: 114 115 If you would like the alter the default behaviour, and are not using `ENCODER_MAP_ENABLE = yes`, the callback functions can be inserted into your `<keyboard>.c`: 116 117 ```c 118 bool encoder_update_kb(uint8_t index, bool clockwise) { 119 if (!encoder_update_user(index, clockwise)) { 120 return false; /* Don't process further events if user function exists and returns false */ 121 } 122 if (index == 0) { /* First encoder */ 123 if (clockwise) { 124 tap_code(KC_PGDN); 125 } else { 126 tap_code(KC_PGUP); 127 } 128 } else if (index == 1) { /* Second encoder */ 129 if (clockwise) { 130 rgb_matrix_increase_hue(); 131 } else { 132 rgb_matrix_decrease_hue(); 133 } 134 } 135 return true; 136 } 137 ``` 138 139 or `keymap.c`: 140 141 ```c 142 bool encoder_update_user(uint8_t index, bool clockwise) { 143 if (index == 0) { /* First encoder */ 144 if (clockwise) { 145 tap_code(KC_PGDN); 146 } else { 147 tap_code(KC_PGUP); 148 } 149 } else if (index == 1) { /* Second encoder */ 150 if (clockwise) { 151 rgb_matrix_increase_hue(); 152 } else { 153 rgb_matrix_decrease_hue(); 154 } 155 } 156 return false; 157 } 158 ``` 159 160 ::: warning 161 If you return `true` in the keymap level `_user` function, it will allow the keyboard/core level encoder code to run on top of your own. Returning `false` will override the keyboard level function, if setup correctly. This is generally the safest option to avoid confusion. 162 ::: 163 164 ## Hardware 165 166 The A an B lines of the encoders should be wired directly to the MCU, and the C/common lines should be wired to ground. 167 168 ## Multiple Encoders 169 170 Multiple encoders may share pins so long as each encoder has a distinct pair of pins when the following conditions are met: 171 - using detent encoders 172 - pads must be high at the detent stability point which is called 'default position' in QMK 173 - no more than two encoders sharing a pin can be turned at the same time 174 175 For example you can support two encoders using only 3 pins like this 176 ``` 177 #define ENCODER_A_PINS { B1, B1 } 178 #define ENCODER_B_PINS { B2, B3 } 179 ``` 180 181 You could even support three encoders using only three pins (one per encoder) however in this configuration, rotating two encoders which share pins simultaneously will often generate incorrect output. For example: 182 ``` 183 #define ENCODER_A_PINS { B1, B1, B2 } 184 #define ENCODER_B_PINS { B2, B3, B3 } 185 ``` 186 Here rotating Encoder 0 `B1 B2` and Encoder 1 `B1 B3` could be interpreted as rotating Encoder 2 `B2 B3` or `B3 B2` depending on the timing. This may still be a useful configuration depending on your use case