fix(docs): Updated encoder config docs.

* Update new shield guide for new sensor/encoder settings. * Add DTS section to encoder config docs. Co-authored-by: Cem Aksoylar <[email protected]>
petejohanson · Nov 3, 2023 · 4990e2a · 4990e2a
1 parent 9e8ee86
commit 4990e2a
Show file tree

Hide file tree

Showing 2 changed files with 57 additions and 10 deletions.
diff --git a/docs/docs/config/encoders.md b/docs/docs/config/encoders.md
@@ -29,13 +29,55 @@ If `CONFIG_EC11` is enabled, exactly one of the following options must be set to
 
 ### Devicetree
 
+#### Keymap Sensor Config
+
+For shields/boards that export a `sensors` node configuration label, both global and per-sensor settings can be set by overriding the properties there.
+
+To override the general settings, update them on the exported `sensors` node, e.g.:
+
+```
+&sensors {
+    triggers-per-rotation = <18>;
+};
+```
+
+Per sensor overrides can be added with ordered nested nodes with the correct overrides, e.g.:
+
+```
+&sensors {
+    left_config {
+        triggers-per-rotation = <18>;
+    };
+
+    right_config {
+        triggers-per-rotation = <24>;
+    };
+};
+```
+
+:::note
+
+The names of the child nodes are not important, and are applied in order to the sensors listed in the `sensors` property of the sensors node.
+
+:::
+
+Applies to the node and child nodes of: `compatible = "zmk,keymap-sensors"`
+
+Definition file: [zmk/app/drivers/zephyr/dts/bindings/zmk,keymap-sensors.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/drivers/zephyr/dts/bindings/zmk%2Ckeymap-sensors.yaml)
+
+| Property                | Type | Description                                                     | Default |
+| ----------------------- | ---- | --------------------------------------------------------------- | ------- |
+| `triggers-per-rotation` | int  | Number of times to trigger the bound behavior per full rotation |         |
+
+#### EC11 Nodes
+
 Applies to: `compatible = "alps,ec11"`
 
 Definition file: [zmk/app/module/dts/bindings/sensor/alps,ec11.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/module/dts/bindings/sensor/alps%2Cec11.yaml)
 
-| Property     | Type       | Description                           | Default |
-| ------------ | ---------- | ------------------------------------- | ------- |
-| `label`      | string     | Unique label for the node             |         |
-| `a-gpios`    | GPIO array | GPIO connected to the encoder's A pin |         |
-| `b-gpios`    | GPIO array | GPIO connected to the encoder's B pin |         |
-| `resolution` | int        | Number of encoder pulses per tick     | 1       |
+| Property  | Type       | Description                                    | Default |
+| --------- | ---------- | ---------------------------------------------- | ------- |
+| `label`   | string     | Unique label for the node                      |         |
+| `a-gpios` | GPIO array | GPIO connected to the encoder's A pin          |         |
+| `b-gpios` | GPIO array | GPIO connected to the encoder's B pin          |         |
+| `steps`   | int        | Number of encoder pulses per complete rotation |         |
diff --git a/docs/docs/development/new-shield.md b/docs/docs/development/new-shield.md
@@ -430,31 +430,36 @@ If building locally for split boards, you may need to add these lines to the spe
 In your device tree file you will need to add the following lines to define the encoder sensor:
 
 ```dts
-left_encoder: encoder_left {
+    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>;
+        steps = <80>;
         status = "disabled";
     };
 ```
 
-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.
+Here you need to replace `PIN_A` and `PIN_B` with the appropriate pins that your PCB utilizes for the encoder(s). See [shield overlays section above](#shield-overlays) on the appropriate node label and pin number to use for GPIOs.
+
+The `steps` property should corresponded to the documented pulses per rotation for the encoders used on the keyboard, typically found on the datasheet of the component. If users use different encoders when they build, the value can be overridden in their keymap.
 
 Add additional encoders as necessary by duplicating the above lines, replacing `left` with whatever you would like to call your encoder, and updating the pins. Note that support for peripheral (right) side sensors over BLE is still in progress.
 
 Once you have defined the encoder sensors, you will have to add them to the list of sensors:
 
 ```dts
-    sensors {
+    sensors: sensors {
         compatible = "zmk,keymap-sensors";
         sensors = <&left_encoder &right_encoder>;
+        triggers-per-rotation = <20>;
     };
 ```
 
 In this example, a left_encoder and right_encoder are both added. Additional encoders can be added with spaces separating each, and the order they are added here determines the order in which you define their behavior in your keymap.
 
+In addition, a default value for the number of times the sensors trigger the bound behavior per full rotation is set via the `triggers-per-rotation` property. See [Encoders Config](../config/encoders.md#devicetree) for more details.
+
 </TabItem>
 <TabItem value = "overlay">
 Add the following lines to your overlay file(s) to enable the encoder: