Some work on encoder docs

docs/docs/dev-guide-add-encoders.md

@@ -0,0 +1,53 @@
+---
+id: dev-guide-add-encoders
+title: Adding Encoders
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+EC11 encoder support can be added to your board or shield by adding the appropriate lines to your board/shield's .conf, .dtsi, and .overlay files.
+
+<Tabs
+defaultValue="conf"
+values={[
+{label: '.conf', value: 'conf'},
+{label: '.dtsi', value: 'dtsi'},
+{label: '.overlay', value: 'overlay'},
+]}>
+<TabItem value="conf">
+
+In your .conf file you will need to add the following lines so that the EC11 drivers can be enabled:
+
+```
+# Uncomment to enable encoder
+# CONFIG_EC11=y
+# CONFIG_EC11_TRIGGER_GLOBAL_THREAD=y
+```
+
+These should be commented by default if encoders are optional, but can be uncommented if encoders are part of the original design.
+
+</TabItem>
+<TabItem value = "dtsi">
+In your .dtsi file you will need to add the following lines to define the encoder sensor:
+
+
+```
+left_encoder: encoder_left {
+		compatible = "alps,ec11";
+		label = "LEFT_ENCODER";
+		a-gpios = <PIN_A (GPIO_ACTIVE_HIGH | GPIO_PULL_UP)>;
+		b-gpios = <PIN_B (GPIO_ACTIVE_HIGH | GPIO_PULL_UP)>;
+		resolution = <4>;
+	};
+```
+Here you will have to replace PIN_A and PIN_B with the appropriate pins that your PCB utilizes for the encoder(s). 
+
+For keyboards that use the Pro Micro or any of the Pro Micro replacements, Sparkfun's [Pro Micro Hookup Guide](https://learn.sparkfun.com/tutorials/pro-micro--fio-v3-hookup-guide/hardware-overview-pro-micro) has a pinout diagram that can be useful to determine the right pins. Reference either the blue numbers labeled "Arduino" (digital pins) or the green numbers labeled "Analog" (analog pins). For pins that are labeled as both digital and analog, refer to your specific board's .dtsi file to determine how you should refer to that pin.
+
+Replace `left` with `right` to define a right-side encoder, although note that support for peripheral side sensors is still in progress.
+
+</TabItem>
+<TabItem value = "overlay">
+</TabItem>
+</Tabs>

docs/docs/feature/encoders.md

@@ -3,4 +3,38 @@ title: Encoders
 sidebar_label: Encoders
 ---
 
-TODO: Documentation on encoders.
+Existing support for encoders in ZMK is focused around the 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 by defining `sensor-bindings` within a layer but below the `bindings` for the regular keys 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.
+
+Behaviors for 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 would look like:
+
+```
+sensor-bindings = <&inc_dec_cp M_VOLU M_VOLD &inc_dec_kp PGUP PGDN>;
+```
+
+In this example, the left encoder is configured to control volume up and down while the right encoder sends either Page Up or Page Down.

docs/sidebars.js

@@ -23,6 +23,9 @@ module.exports = {
       "dev-posix-board",
       "dev-tests",
     ],
-    "Dev Guides": ["dev-guide-new-shield", "dev-guide-usb-logging"],
+    "Dev Guides": [
+      "dev-guide-new-shield",
+      "dev-guide-add-encoders",
+      "dev-guide-usb-logging"],
   },
 };