qmk_firmware/docs/feature_encoders.md

152 lines
4.5 KiB
Markdown
Raw Normal View History

2018-10-26 22:19:23 +02:00
# Encoders
Basic encoders are supported by adding this to your `rules.mk`:
```make
ENCODER_ENABLE = yes
```
2018-10-26 22:19:23 +02:00
and this to your `config.h`:
```c
#define ENCODERS_PAD_A { B12 }
#define ENCODERS_PAD_B { B13 }
```
2018-10-26 22:19:23 +02:00
Each PAD_A/B variable defines an array so multiple encoders can be defined, e.g.:
```c
#define ENCODERS_PAD_A { encoder1a, encoder2a }
#define ENCODERS_PAD_B { encoder1b, encoder2b }
```
If your encoder's clockwise directions are incorrect, you can swap the A & B pad definitions. They can also be flipped with a define:
2018-10-26 22:19:23 +02:00
```c
#define ENCODER_DIRECTION_FLIP
```
2018-10-26 22:19:23 +02:00
Additionally, the resolution, which defines how many pulses the encoder registers between each detent, can be defined with:
2018-10-26 22:19:23 +02:00
```c
#define ENCODER_RESOLUTION 4
```
2018-10-26 22:19:23 +02:00
2020 November 28 Breaking Changes Update (#11053) * Branch point for 2020 November 28 Breaking Change * Remove matrix_col_t to allow MATRIX_ROWS > 32 (#10183) * Add support for soft serial to ATmega32U2 (#10204) * Change MIDI velocity implementation to allow direct control of velocity value (#9940) * Add ability to build a subset of all keyboards based on platform. * Actually use eeprom_driver_init(). * Make bootloader_jump weak for ChibiOS. (#10417) * Joystick 16-bit support (#10439) * Per-encoder resolutions (#10259) * Share button state from mousekey to pointing_device (#10179) * Add hotfix for chibios keyboards not wake (#10088) * Add advanced/efficient RGB Matrix Indicators (#8564) * Naming change. * Support for STM32 GPIOF,G,H,I,J,K (#10206) * Add milc as a dependency and remove the installed milc (#10563) * ChibiOS upgrade: early init conversions (#10214) * ChibiOS upgrade: configuration file migrator (#9952) * Haptic and solenoid cleanup (#9700) * XD75 cleanup (#10524) * OLED display update interval support (#10388) * Add definition based on currently-selected serial driver. (#10716) * New feature: Retro Tapping per key (#10622) * Allow for modification of output RGB values when using rgblight/rgb_matrix. (#10638) * Add housekeeping task callbacks so that keyboards/keymaps are capable of executing code for each main loop iteration. (#10530) * Rescale both ChibiOS and AVR backlighting. * Reduce Helix keyboard build variation (#8669) * Minor change to behavior allowing display updates to continue between task ticks (#10750) * Some GPIO manipulations in matrix.c change to atomic. (#10491) * qmk cformat (#10767) * [Keyboard] Update the Speedo firmware for v3.0 (#10657) * Maartenwut/Maarten namechange to evyd13/Evy (#10274) * [quantum] combine repeated lines of code (#10837) * Add step sequencer feature (#9703) * aeboards/ext65 refactor (#10820) * Refactor xelus/dawn60 for Rev2 later (#10584) * add DEBUG_MATRIX_SCAN_RATE_ENABLE to common_features.mk (#10824) * [Core] Added `add_oneshot_mods` & `del_oneshot_mods` (#10549) * update chibios os usb for the otg driver (#8893) * Remove HD44780 References, Part 4 (#10735) * [Keyboard] Add Valor FRL TKL (+refactor) (#10512) * Fix cursor position bug in oled_write_raw functions (#10800) * Fixup version.h writing when using SKIP_VERSION=yes (#10972) * Allow for certain code in the codebase assuming length of string. (#10974) * Add AT90USB support for serial.c (#10706) * Auto shift: support repeats and early registration (#9826) * Rename ledmatrix.h to match .c file (#7949) * Split RGB_MATRIX_ENABLE into _ENABLE and _DRIVER (#10231) * Split LED_MATRIX_ENABLE into _ENABLE and _DRIVER (#10840) * Merge point for 2020 Nov 28 Breaking Change
2020-11-28 21:02:18 +01:00
It can also be defined per-encoder, by instead defining:
```c
#define ENCODER_RESOLUTIONS { 4, 2 }
```
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:
```c
#define ENCODER_DEFAULT_POS 0x3
```
## Split Keyboards
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:
```c
#define ENCODERS_PAD_A_RIGHT { encoder1a, encoder2a }
#define ENCODERS_PAD_B_RIGHT { encoder1b, encoder2b }
2020 November 28 Breaking Changes Update (#11053) * Branch point for 2020 November 28 Breaking Change * Remove matrix_col_t to allow MATRIX_ROWS > 32 (#10183) * Add support for soft serial to ATmega32U2 (#10204) * Change MIDI velocity implementation to allow direct control of velocity value (#9940) * Add ability to build a subset of all keyboards based on platform. * Actually use eeprom_driver_init(). * Make bootloader_jump weak for ChibiOS. (#10417) * Joystick 16-bit support (#10439) * Per-encoder resolutions (#10259) * Share button state from mousekey to pointing_device (#10179) * Add hotfix for chibios keyboards not wake (#10088) * Add advanced/efficient RGB Matrix Indicators (#8564) * Naming change. * Support for STM32 GPIOF,G,H,I,J,K (#10206) * Add milc as a dependency and remove the installed milc (#10563) * ChibiOS upgrade: early init conversions (#10214) * ChibiOS upgrade: configuration file migrator (#9952) * Haptic and solenoid cleanup (#9700) * XD75 cleanup (#10524) * OLED display update interval support (#10388) * Add definition based on currently-selected serial driver. (#10716) * New feature: Retro Tapping per key (#10622) * Allow for modification of output RGB values when using rgblight/rgb_matrix. (#10638) * Add housekeeping task callbacks so that keyboards/keymaps are capable of executing code for each main loop iteration. (#10530) * Rescale both ChibiOS and AVR backlighting. * Reduce Helix keyboard build variation (#8669) * Minor change to behavior allowing display updates to continue between task ticks (#10750) * Some GPIO manipulations in matrix.c change to atomic. (#10491) * qmk cformat (#10767) * [Keyboard] Update the Speedo firmware for v3.0 (#10657) * Maartenwut/Maarten namechange to evyd13/Evy (#10274) * [quantum] combine repeated lines of code (#10837) * Add step sequencer feature (#9703) * aeboards/ext65 refactor (#10820) * Refactor xelus/dawn60 for Rev2 later (#10584) * add DEBUG_MATRIX_SCAN_RATE_ENABLE to common_features.mk (#10824) * [Core] Added `add_oneshot_mods` & `del_oneshot_mods` (#10549) * update chibios os usb for the otg driver (#8893) * Remove HD44780 References, Part 4 (#10735) * [Keyboard] Add Valor FRL TKL (+refactor) (#10512) * Fix cursor position bug in oled_write_raw functions (#10800) * Fixup version.h writing when using SKIP_VERSION=yes (#10972) * Allow for certain code in the codebase assuming length of string. (#10974) * Add AT90USB support for serial.c (#10706) * Auto shift: support repeats and early registration (#9826) * Rename ledmatrix.h to match .c file (#7949) * Split RGB_MATRIX_ENABLE into _ENABLE and _DRIVER (#10231) * Split LED_MATRIX_ENABLE into _ENABLE and _DRIVER (#10840) * Merge point for 2020 Nov 28 Breaking Change
2020-11-28 21:02:18 +01:00
#define ENCODER_RESOLUTIONS_RIGHT { 2, 4 }
```
2018-10-26 22:19:23 +02:00
## Callbacks
The callback functions can be inserted into your `<keyboard>.c`:
```c
bool encoder_update_kb(uint8_t index, bool clockwise) {
return encoder_update_user(index, clockwise);
}
```
2018-10-26 22:19:23 +02:00
or `keymap.c`:
```c
bool encoder_update_user(uint8_t index, bool clockwise) {
if (index == 0) { /* First encoder */
2019-01-18 16:33:43 +01:00
if (clockwise) {
tap_code_delay(KC_VOLU, 10);
2019-01-18 16:33:43 +01:00
} else {
tap_code_delay(KC_VOLD, 10);
2018-10-26 22:47:00 +02:00
}
} else if (index == 1) { /* Second encoder */
2019-01-18 16:33:43 +01:00
if (clockwise) {
rgb_matrix_increase_hue();
2019-01-18 16:33:43 +01:00
} else {
rgb_matrix_decrease_hue();
2019-01-18 16:33:43 +01:00
}
2018-10-26 22:19:23 +02:00
}
return false;
}
```
2018-10-26 22:19:23 +02:00
!> If you return `true`, this will allow the keyboard level code to run, as well. Returning `false` will override the keyboard level code. Depending on how the keyboard level function is set up.
Layer conditions can also be used with the callback function like the following:
```c
bool encoder_update_user(uint8_t index, bool clockwise) {
if (get_highest_layer(layer_state|default_layer_state) > 0) {
if (index == 0) {
if (clockwise) {
tap_code(KC_WH_D);
} else {
tap_code(KC_WH_U);
}
} else if (index == 1) {
if (clockwise) {
tap_code_delay(KC_VOLU, 10);
} else {
tap_code_delay(KC_VOLD, 10);
}
}
} else { /* Layer 0 */
if (index == 0) {
if (clockwise) {
tap_code(KC_PGDN);
} else {
tap_code(KC_PGUP);
}
} else if (index == 1) {
if (clockwise) {
rgb_matrix_increase_speed();
} else {
rgb_matrix_decrease_speed();
}
}
}
return false;
}
```
?> Media and mouse countrol keycodes such as `KC_VOLU` and `KC_WH_D` requires `EXTRAKEY_ENABLE = yes` and `MOUSEKEY_ENABLE = yes` respectively in user's `rules.mk` if they are not enabled as default on keyboard level configuration.
2018-10-26 22:19:23 +02:00
## Hardware
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.
## Multiple Encoders
Multiple encoders may share pins so long as each encoder has a distinct pair of pins when the following conditions are met:
- using detent encoders
- pads must be high at the detent stability point which is called 'default position' in QMK
- no more than two encoders sharing a pin can be turned at the same time
For example you can support two encoders using only 3 pins like this
```
#define ENCODERS_PAD_A { B1, B1 }
#define ENCODERS_PAD_B { B2, B3 }
```
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:
```
#define ENCODERS_PAD_A { B1, B1, B2 }
#define ENCODERS_PAD_B { B2, B3, B3 }
```
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