Adding Easier Configuration for Dual-Side Encoders On Split Keyboards (#1133)

* added arg and property for `add_buttons: int` for adding singleton/single-pin buttons to the `coord_mapping`, rather than the user needing to create the coord_mapping manually.

* added documentation for the `add_buttons` argument

* updated description for Multiple Scanners with Custom `coord_mapping`

Author: Vacant0mens

docs/en/encoder.md

@@ -3,7 +3,7 @@ Add twist control to your keyboard! Volume, zoom, anything you want.
 
 I2C encoder type has been tested with the Adafruit I2C QT Rotary Encoder with NeoPixel.
 
-**Note:** If you have a **split** keyboard and encoders on **both sides** should work, it's currently necessary to use the encoder-scanner explained at the bottom of [scanners docs](scanners.md).
+**Note:** If you have a **split** keyboard and encoders on **both sides** should work, it's currently necessary to use the encoder-scanner. See the Advanced Configuration section of the [scanners docs](scanners.md).
 
 ## Enabling the extension
 The constructor(`EncoderHandler` class) takes a list of encoders, each one defined as either:

docs/en/scanners.md

@@ -150,24 +150,42 @@ class MyKeyboard(KMKKeyboard):
 
 ### RotaryioEncoder
 
-Matrix events from a quadrature ("rotary") encoder?
+Matrix events from a quadrature ("rotary") encoder.
+
+For any rotary encoders that you may include in your keyboard configuration, you can add this scanner to handle the input of the encoder actions (usually: left turn, right turn, and click) and to be able to configure them via the `keyboard.keymap` as if they were regular keys.
+
+Often, rotary encoders are attached as accessories, i.e. alongside a key/button matrix. The below example shows how this can be configured.
 
 ```python
 from kmk.scanners.encoder import RotaryioEncoder
+from kmk.scanners import DiodeOrientation
 
 class MyKeyboard(KMKKeyboard):
     def __init__(self):
         super().__init__()
+        row_pins = (board.GP2, board.GP3, board.GP4, board.GP5, board.GP6)
+        col_pins = (board.GP29, board.GP28, board.GP27,  board.GP26,  board.GP22, board.GP20)
 
         # create and register the scanner
-        self.matrix = RotaryioEncoder(
+        rotary = RotaryioEncoder(
             pin_a=board.GP0,
             pin_b=board.GP1,
             # optional
             divisor=4,
         )
+        matrix = MatrixScanner(
+            row_pins=self.row_pins,
+            column_pins=self.col_pins,
+            columns_to_anodes=DiodeOrientation.ROW2COL
+        )
+        self.matrix = [
+            matrix,
+            rotary
+        ]
 ```
 
+If your design requires symetrical encoders (e.g. one on each half of a split keyboard), see Multiple Scanners section below for more details.
+
 
 ## `Scanner` base class
 
@@ -201,14 +219,66 @@ class MyKeyboard(KMKKeyboard):
             # etc...
         ]
 ```
-#### Multiple Scanners `coord_mapping` and keymap changes
-To add more scanners you need to add onto your `coord_mapping`.
+
+
+#### Adding Single-Pin Buttons or Rotary Encoders to Keymap Using Scanners and Split
+
+In many cases, split keybaords are symetrical in form and function. Some split keyboards also have additional hardware like one or more rotary encoders, or non-matrix-connected media or macro buttons. In this case, you will want to configure multiple scanners.
+
+The `Split` class that you're probably already using creates the `coord_mapping` indexes automatically. However, the `add_buttons` argument will cause it to append any additional "buttons" (or encoder actions) to the `coord_mapping` for _each half_ of the keyboard.
+
+By default, `Split` will also configure `MatrixScanner` and assign it to `KMKKeyboard.matrix` as a single/default scanner, but with the additional actions/keys from `RotaryioEncoder`, it will need to be configured in your custom class so that `RotaryioEncoder` can be configured and appended to `KNKKeyboard.matrix`. This enables the rotary actions to map from the `coord_mapping` to the `keybaord.keymap` correctly, making it easy to assign keycodes to the actions or buttons.
 
 Example:
+```python
+from kmk.scanners import DiodeOrientation
+from kmk.scanners.keypad import MatrixScanner
+from kmk.scanners.encoder import RotaryioEncoder
+from kmk.modules.split import Split
+
+
+class MyKeyboard(KMKKeyboard):
+    def __init__(self) -> None:
+        super().__init__()
+        self.diode_orientation = DiodeOrientation.ROW2COL
+        split_args = {
+            'split_side': None, # EE Hands
+            'data_pin': board.GP1,
+            'data_pin2': board.GP0,
+            'split_flip': True,
+            'use_pio': True,
+            'uart_flip': True,
+            'add_buttons': 2 # add left- and right-turn actions for one encoder on each side; see `split_keyboards.md`
+        }
+        self.row_pins = (board.GP2, board.GP3, board.GP4, board.GP5, board.GP6)
+        self.col_pins = (board.GP29, board.GP28, board.GP27,  board.GP26,  board.GP22, board.GP20)
+        self.split = Split(**split_args)
+        self.modules.append(self.split)
+
+        matrix = MatrixScanner(row_pins=self.row_pins, column_pins=self.col_pins, columns_to_anodes=DiodeOrientation.ROW2COL)
+        rotary = RotaryioEncoder(pin_a=board.D7, pin_b=board.D8)
+        self.matrix = [
+            matrix,
+            rotary
+        ]
+
+
+if __name__ == '__main__':
+    keyboard = MyKeyboard()
+    keyboard.go()
+```
+
+
+#### Multiple Scanners `coord_mapping` and keymap changes
+For a more manually-controlled configuration, you can add any other scanners that you need and create your `coord_mapping` in your own code (leaving off the `add_buttons` argument when initializing `Split`)
+Creating and assigning a custom `coord_mapping` should be done before intitializing `Split` or any scanners.
+
+The below examples illustrate how the additional encoder actions are assigned to the `coord_mapping`. Your configuration should follow this pattern.
+
 
 `coord_mapping` with just one `MatrixScanner` on a 58 key split keyboard:
 ```python
-coord_mapping = [
+keyboard.coord_mapping = [
      0,  1,  2,  3,  4,  5,         35, 34, 33, 32, 31, 30,
      6,  7,  8,  9, 10, 11,         41, 40, 39, 38, 37, 36,
     12, 13, 14, 15, 16, 17,         47, 46, 45, 44, 43, 42,
@@ -217,9 +287,9 @@ coord_mapping = [
     ]
 ```
 
-`coord_mapping` using `MatrixScanner` and `RotaryioEncoder` on the same 58 key split keyboard with an encoder on each half:
+`coord_mapping` using `MatrixScanner` and `RotaryioEncoder` on the same 58 key split keyboard, adding an encoder to each half:
 ```python
-coord_mapping = [
+keyboard.coord_mapping = [
      0,  1,  2,  3,  4,  5,         37, 36, 35, 34, 33, 32,
      6,  7,  8,  9, 10, 11,         43, 42, 41, 40, 39, 38,
     12, 13, 14, 15, 16, 17,         49, 48, 47, 46, 45, 44,
@@ -229,9 +299,14 @@ coord_mapping = [
     ]
 ```
 
-On the top left side of a standard split keyboard `coord_mapping`, right below that you see a split keyboard where `RotaryioEncoder` and `MatrixScanner` (the default scanner) are used.
-In the single scanner example, we used to count from 0 to 29 while the top right side starts at 30.
-With the addition of the encoder scanner, the left side has 2 additional keys making it count up to 31 and the right side would then start at 32 and count to 63.
-This means that keys 30, 31, 62, and 63 are for encoders.
-Notice that all of the encoders are at the end of the array, because we put the encoder scanner after the matrix scanner in `keyboard.matrix`.
-Therefore, we need to add 4 more key codes in the corresponding places of our `keyboard.keymap`, they will be used for the encoders.
+Note that in both examples, the left-side indexes count from 0 to 29 for the first five rows. But the right side of the first (single scanner) example starts at 30 (in the top right corner) and ends at 59 in the center.
+
+With the addition of the `RotaryioEncoder` scanner, the left side has 2 additional keys (30 and 31) causing the right side to start at 32 and count to 61 in the center, with two more keys at the bottom (62 and 63).
+**This means that keys 30, 31, 62, and 63 are for the encoders.**
+
+Notice that, despite the visual layout, all of the encoder keys are at the **_end_** of the array. This is because `RotaryioEncoder` was **_after_** `MatrixScanner` **_in the list_** when the `keyboard.matrix` was assigned. (see example in the previous section above)
+
+Therefore, 4 more key codes can be added in the corresponding places in the `keyboard.keymap`, and they will be assigned to the encoders' actions.
+
+
+Also note, it may be necessary to configure `Split().split_offset` when configuring your own `coord_mapping` to make sure that the encoders are assigned properly. The value will usually be the first/lowest index value of the right side. In the case of the second example above, the offset value would be 32, but this also depends on your `coord_mapping` layout.

docs/en/split_keyboards.md

@@ -50,6 +50,7 @@ split = Split(
     data_pin2=None,  # Second uart pin to allow 2 way communication
     uart_flip=True,  # Reverses the RX and TX pins if both are provided
     use_pio=False,  # Use RP2040 PIO implementation of UART. Required if you want to use other pins than RX/TX
+    add_buttons = 0 # add single-pin buttons, rotary encoder actions, etc. per-side.
 )
 
 ```
@@ -111,6 +112,10 @@ In order to enable it, you must:
 - pass `use_pio=True` into the `Split()` constructor.
 
 
+### `add_buttons`
+if you have additional single-pin buttons, rotary encoders, or other non-matrix actions that will be assigned to keys, you can add this argument with the number of buttons per-side. This will enable you to include them at the end of your keymap without needing to manually configure `keyboard.coord_mapping`.
+
+
 ### `data_pin`/`data_pin2`
 For UART `SplitType`: on the `split_target` side, `data_pin` is the one use for RX, `data_pin2` the one for TX.
 

kmk/modules/split.py

@@ -41,6 +41,7 @@ def __init__(
         data_pin2=None,
         uart_flip=True,
         use_pio=False,
+        add_buttons=0,  # add single-pin buttons, rotary encoder actions, etc. per-side.
     ):
         self._is_target = True
         self._uart_buffer = []
@@ -54,9 +55,10 @@ def __init__(
         self.uart_flip = uart_flip
         self._use_pio = use_pio
         self._uart = None
+        self.add_buttons = add_buttons
         self._uart_interval = uart_interval
         self.uart_header = bytearray([0xB2])  # Any non-zero byte should work
-
+        debug('Split module initializing...')
         if self.split_type == SplitType.BLE:
             try:
                 from adafruit_ble import BLERadio
@@ -99,6 +101,7 @@ def during_bootup(self, keyboard):
             if not self.data_pin:
                 self.data_pin = keyboard.data_pin
 
+        debug('Checking split side...')
         # if split side was given, find target from split_side.
         if self.split_side == SplitSide.LEFT:
             self._is_target = bool(self.split_target_left)
@@ -119,11 +122,18 @@ def during_bootup(self, keyboard):
             elif name.endswith('R'):
                 self.split_side = SplitSide.RIGHT
 
+        debug(f'Split side assigned to as: {self.split_side}')
+
         if not self._is_target:
             keyboard._hid_send_enabled = False
 
         if self.split_offset is None:
-            self.split_offset = keyboard.matrix[-1].coord_mapping[-1] + 1
+            if self.add_buttons > 0:
+                self.split_offset = (
+                    keyboard.matrix[-1].coord_mapping[-1] + 1 + self.add_buttons
+                )
+            else:
+                self.split_offset = keyboard.matrix[-1].coord_mapping[-1] + 1
 
         if self.split_type == SplitType.UART and self.data_pin is not None:
             if self._is_target or not self.uart_flip:
@@ -140,11 +150,11 @@ def during_bootup(self, keyboard):
                     self._uart = busio.UART(
                         tx=self.data_pin, rx=self.data_pin2, timeout=self._uart_interval
                     )
-
+        debug(f'Split type assigned as: {self.split_type}')
         # Attempt to sanely guess a coord_mapping if one is not provided.
         if not keyboard.coord_mapping and keyboard.row_pins and keyboard.col_pins:
             cm = []
-
+            debug('Calculating coord_mapping...')
             rows_to_calc = len(keyboard.row_pins)
             cols_to_calc = len(keyboard.col_pins)
 
@@ -157,8 +167,23 @@ def during_bootup(self, keyboard):
                 for cidx in range(cols_to_calc):
                     cm.append(cols_to_calc * ridx + cidx)
                 for cidx in cols_rhs:
-                    cm.append(cols_to_calc * (rows_to_calc + ridx) + cidx)
-
+                    # add indexes accounting for any added buttons
+                    if self.add_buttons != 0:
+                        cm.append(
+                            cols_to_calc * (rows_to_calc + ridx)
+                            + cidx
+                            + (self.add_buttons),
+                        )
+                    else:
+                        cm.append(cols_to_calc * (rows_to_calc + ridx) + cidx)
+            # append addded buttons to the final list
+            for a in range(self.add_buttons):
+                cm.append(cols_to_calc * rows_to_calc + cols_rhs[-1] + (a))
+            for a in range(self.add_buttons, self.add_buttons * 2):
+                cm.append(cols_to_calc * (rows_to_calc + cols_rhs[0]) + (a))
+
+            debug('Done calculating coord_mapping:')
+            debug(f'{cm}')
             keyboard.coord_mapping = tuple(cm)
 
         if not keyboard.coord_mapping and debug.enabled: