Merge remote-tracking branch 'upstream/main' into underglow/state-persistence

docs/docs/feature/encoders.md

@@ -3,4 +3,42 @@ title: Encoders
 sidebar_label: Encoders
 ---
 
-TODO: Documentation on encoders.
+Existing support for encoders in ZMK is focused around the five pin EC11 rotary encoder with push button design used in the majority of current keyboard and macropad designs.
+
+## Enabling EC11 Encoders
+
+To enable encoders for boards that have existing encoder support, uncomment the `EC11_CONFIG=y` and `CONFIG_EC11_TRIGGER_GLOBAL_THREAD=y` lines in your board's .conf file in your `zmk-config/config` folder. Save and push your changes, then download and flash the new firmware.
+
+## Customizing EC11 Encoder Behavior
+
+Encoder behavior in ZMK is configured in two different locations as the push button and rotation behaviors are handled in two separate ways.
+
+### Push Button
+
+Keyboards and macropads with encoder support will typically take the two EC11 pins responsible for the push button and include them as part of the matrix for the keys. To configure what is sent by the push button, find the encoder's position in the keyboard matrix and assign it a behavior the same as you would any other key.
+
+### Rotation
+
+Rotation is handled separately as a type of sensor. The behavior for this is set in `sensor-bindings`, which is defined in each keymap layer in the following format:
+
+```
+sensor-bindings = <BINDING CW_KEY CCW_KEY>;
+```
+
+- `BINDING` is one of two rotation bindings that are currently defined, `&inc_dec_cp` for consumer key presses or `&inc_dec_kp` for normal key presses (see [Key Press](/docs/behavior/key-press) for the difference between the two).
+- `CW_KEY` is the keycode activated by a clockwise turn.
+- `CCW_KEY` is the keycode activated by a counter-clockwise turn.
+
+Additional encoders can be configured by adding more `BINDING CW_KEY CCW_KEY` sets immediately after the first.
+
+As an example, a complete `sensor-bindings` for a Kyria with two encoders could look like:
+
+```
+sensor-bindings = <&inc_dec_cp M_VOLU M_VOLD &inc_dec_kp PGUP PGDN>;
+```
+
+Here, the left encoder is configured to control volume up and down while the right encoder sends either Page Up or Page Down.
+
+## Adding Encoder Support
+
+See the [New Keyboard Shield](/docs/dev-guide-new-shield) documentation for how to add or modify additional encoders to your shield.

docs/docs/feature/keymaps.md

@@ -4,7 +4,7 @@ title: Keymaps & Behaviors
 sidebar_label: Keymaps
 ---
 
-ZMK uses an declarative approach to keymaps, instead of using C code for all keymap configuration.
+ZMK uses a declarative approach to keymaps instead of using C code for all keymap configuration.
 Right now, ZMK uses the devicetree syntax to declare those keymaps; future work is envisioned for
 supporting dynamic loading of declarative keymaps, e.g. over USB Mass Storage or via a custom BLE
 service.
@@ -55,7 +55,7 @@ in the stack _also_ get the event.
 ## Behavior Bindings
 
 Binding a behavior at a certain key position may include up to two extra parameters that are used to
-alter the behavior when that specific key position is activated/deactived. For example, when binding
+alter the behavior when that specific key position is activated/deactivated. For example, when binding
 the "key press" (`kp`) behavior at a certain key position, you must specific _which_ keycode should
 be used for that key position.
 
@@ -80,7 +80,7 @@ A keymap file is composed of several sections, that together make up a valid dev
 
 ### Includes
 
-THe devicetree files are actually preprocessed before being finally leveraged by Zephyr. This allows using standard C defines to create meaningful placeholders
+The devicetree files are actually preprocessed before being finally leveraged by Zephyr. This allows using standard C defines to create meaningful placeholders
 for what would otherwise be cryptic integer keycodes, etc. This also allows bringing in _other_ devicetree nodes from separate files.
 
 The top two lines of most keymaps should include: