improve support

Author: veypatch

.github/workflows/build_binaries.yaml

@@ -12,7 +12,7 @@ jobs:
     with:
       qmk_repo: vial-kb/vial-qmk
       qmk_ref: vial
-      preparation_command: 'ln -s "$GITHUB_WORKSPACE/converters/promicro_to_halcyon/" qmk_firmware/platforms/chibios/converters/ && cd "$GITHUB_WORKSPACE/keyboards" && find . -type d -name "*_vik" | while read -r dir; do mkdir -p "$GITHUB_WORKSPACE/qmk_firmware/keyboards/$(dirname "$dir")"; ln -s "$GITHUB_WORKSPACE/keyboards/$dir" "$GITHUB_WORKSPACE/qmk_firmware/keyboards/$dir"; done'
+      preparation_command: 'ln -s "$GITHUB_WORKSPACE/converters/promicro_to_halcyon/" qmk_firmware/platforms/chibios/converters/ && cd "$GITHUB_WORKSPACE/keyboards" && find . -type d -name "*_hlc" | while read -r dir; do mkdir -p "$GITHUB_WORKSPACE/qmk_firmware/keyboards/$(dirname "$dir")"; ln -s "$GITHUB_WORKSPACE/keyboards/$dir" "$GITHUB_WORKSPACE/qmk_firmware/keyboards/$dir"; done'
 #   publish:
 #     name: 'QMK Userspace Publish'
 #     uses: qmk/.github/.github/workflows/qmk_userspace_publish.yml@main

CONVERT.md PORTING.mdCONVERT.md renamed to PORTING.md

@@ -1,14 +1,24 @@
 # Porting a Keyboard to support Halcyon Modules
 
+Before continuing, complete the setup described in the main README.
+
 This guide can be used for both a keyboard design with a **Halcyon and VIK connector** or the **Halcyon to Promicro adapter**.
 
 If you want to use the Splitkb Halcyon modules (Encoder, TFT Display, Cirque Trackpad) on a keyboard that doesn't natively support them yet, you will need to prepare its QMK configuration.
 
-Because Halcyon modules hook into the keyboard by acting as **5 extra keys per microcontroller**, the keyboard's `keyboard.json` and `info.json` matrix and layouts must be expanded to accommodate them.
+# Adding support for Halcyon Modules (Except Halcyon Encoders)
+
+> **⚠️** If you want to support Halcyon Encoders, please read the steps [below](#adding-support-for-halcyon-encoders). If you only plan on using any other modules, you won't need to follow those steps.
+
+Create or copy your keymap to this repository. 
+
+Within the keymap folder, add `USER_NAME := halcyon_modules` to the `rules.mk`. If you're using the Halcyon to Promicro adapter, also add `CONVERT_TO=halcyon` to the `rules.mk`. Create the file if it doesn't exist yet.
 
-By doing this inside your cloned `splitkb/qmk_userspace`, you keep your modifications clean and separate from the main QMK/Vial repositories!
+You can now compile using the steps from the main readme.
 
----
+# Adding support for Halcyon Encoders
+
+Because the Halcyon Encoder module hook into the keyboard by acting as **1 extra keys per microcontroller**, the keyboard's `keyboard.json` and `info.json` matrix and layouts must be expanded to accommodate them. We accomodate for **5 extra keys** to provide easier support when new modules may release in the future.
 
 ## 1. Prepare your Userspace Overlay
 If the keyboard does not exist in the userspace yet, you must create an overlay for it. This overlay lives in your userspace and uses the `_hlc` suffix to indicate a modified keyboard.
@@ -25,10 +35,10 @@ Which one you use depends on how the keyboard is structured:
 
 Copy all files normally required to compile the keyboard (such as `keyboard.json`, `rules.mk`, `config.h`, etc.). Place your modified `keyboard.json` and any other altered files in this overlay. The GitHub CI will automatically merge this overlay with the base keyboard when using the revision folder from the main repository during the build process. Otherwise it will compile the new keyboard completely.
 
-Also make sure to copy over the keymap folder.
+Also make sure to copy over the keymap folder. Within the keymap folder, add `USER_NAME := halcyon_modules` to the `rules.mk`. If you're using the Halcyon to Promicro adapter, also add `CONVERT_TO=halcyon` to the `rules.mk`. Create the file if it doesn't exist yet.
 
-## 2. Register the Encoder Engine
-Even if you are compiling for a trackpad or TFT display, QMK needs the encoder engine initialized. We do this by defining a dummy encoder.
+## 2. Register encoder support.
+Even if you are compiling for a trackpad or TFT display, QMK needs the encoder initialized. We do this by defining a dummy encoder.
 
 In your `keyboard.json`, add a `"rotary"` array under `"encoder"` using `"NO_PIN"`:
 
@@ -40,7 +50,7 @@ In your `keyboard.json`, add a `"rotary"` array under `"encoder"` using `"NO_PIN
     }
 ```
 
-If the keyboard already has an encoder, append the dummy one to the existing array:
+If the keyboard already has an encoder, append the dummy one to the existing array. You may also need to do this in the `"split"` array if that exists:
 
 ```json
     "encoder": {
@@ -49,6 +59,14 @@ If the keyboard already has an encoder, append the dummy one to the existing arr
             {"pin_a": "NO_PIN", "pin_b": "NO_PIN"}
         ]
     }
+    "split": {
+        "encoder": {
+            "rotary": {
+                {"pin_a": "GP22", "pin_b": "GP18", "resolution": 2},
+                {"pin_a": "NO_PIN", "pin_b": "NO_PIN"}
+            }
+        }
+    }
 ```
 
 ## 3. Expand the Matrix Pins
@@ -73,48 +91,49 @@ Find the `"matrix_pins"` block. Add `"NO_PIN"` to the end of the `"rows"` array.
         }
     }
 ```
-*Tip: If your matrix uses a `"direct"` 2D array instead of rows/cols, add a completely new array row filled with 5 `"NO_PIN"` values (e.g., `["NO_PIN", "NO_PIN", "NO_PIN", "NO_PIN", "NO_PIN"]`).*
 
-## 4. Rename and Expand the Layout
-To avoid conflicts and explicitly use this new configuration, rename the layout key inside the `"layouts"` block (e.g., change `"LAYOUT"` or `"LAYOUT_split_3x6_3"` to `"LAYOUT_hlc"`).
+## 4. Shift Right-Half Matrix Indices (Split Keyboards Only)
+Because QMK maps split keyboard matrices sequentially, adding a dummy row to the left half pushes all the original right half's rows down by 1. 
+
+For example, if your left half originally used rows `0` to `3`, your right half started at `4`. Since the left half now uses `0` to `4` (due to the added Halcyon row), the right half must now start at `5`.
+
+1. **In your `"layouts"` block:** Look at all the *pre-existing* right-hand keys and increase their row index (the first number in the `"matrix": [row, col]` array) by `1`. *(e.g., `[4, 2]` becomes `[5, 2]`)*.
+2. **In your `"rgb_matrix"` block:** If the keyboard has per-key RGB, you must do the exact same `+1` row shift for the `"layout"` array located inside `"rgb_matrix"` so the lighting correctly aligns with the shifted matrix!
+
+*Tip: Use your text editor’s find-and-replace to update both the `"layouts"` and `"rgb_matrix"` blocks at once. Start with the highest right-hand row index and increment each by 1. For example, replace `[7` → `[8`, `[6` → `[7]`, and continue downward until you reach the original left-hand row count. For the Kyria (4 rows per half), stop at 4. This keeps the right-hand matrix and RGB layout correctly aligned after adding the Halcyon row.*
+
+## 5. Rename and Expand the Layout
+To avoid conflicts and explicitly use this new configuration, rename the layout key inside the `"layouts"` block (e.g., change `"LAYOUT"` or `"LAYOUT_split_3x6_3"` to `"LAYOUT_hlc"`). You may need to copy this `"layouts"` block from the `info.json` which is in the root of the keyboard folder.
 
 Next, map the new Halcyon inputs to the visual layout array. You need to add **5 keys per module** (so 5 extra keys for a unibody keyboard, or 10 extra keys for a split keyboard).
 
 Map `"matrix": [row, col]` to the new row index you just created. *(Note: arrays are 0-indexed, so if you originally had 4 rows, your new row is index `4`).* Give them a `y` coordinate that pushes them visually to the bottom of the layout.
 
 **For Unibody Keyboards (Add 5 keys):**
 ```json
-    {"matrix": [4, 0], "x": 1, "y": 6},
-    {"matrix": [4, 1], "x": 2, "y": 6},
-    {"matrix": [4, 2], "x": 3, "y": 6},
-    {"matrix": [4, 3], "x": 4, "y": 6},
-    {"matrix": [4, 4], "x": 5, "y": 6}
+                {"matrix": [4, 0], "x": 0, "y": 6},
+                {"matrix": [4, 1], "x": 1, "y": 6},
+                {"matrix": [4, 2], "x": 2, "y": 6},
+                {"matrix": [4, 3], "x": 3, "y": 6},
+                {"matrix": [4, 4], "x": 4, "y": 6},
 ```
 
 **For Split Keyboards (Add 10 keys: 5 Left, 5 Right):**
 Assuming the Left hand's new row is `4`, and the Right hand's new row is `9`. Notice how the right hand's `x` values usually count backwards to match physical mirroring.
 ```json
-    {"matrix": [4, 0], "x": 0, "y": 6},
-    {"matrix": [4, 1], "x": 1, "y": 6},
-    {"matrix": [4, 2], "x": 2, "y": 6},
-    {"matrix": [4, 3], "x": 3, "y": 6},
-    {"matrix": [4, 4], "x": 4, "y": 6},
-
-    {"matrix": [9, 0], "x": 14, "y": 6},
-    {"matrix": [9, 1], "x": 13, "y": 6},
-    {"matrix": [9, 2], "x": 12, "y": 6},
-    {"matrix": [9, 3], "x": 11, "y": 6},
-    {"matrix": [9, 4], "x": 10, "y": 6}
+                {"matrix": [4, 0], "x": 0, "y": 6},
+                {"matrix": [4, 1], "x": 1, "y": 6},
+                {"matrix": [4, 2], "x": 2, "y": 6},
+                {"matrix": [4, 3], "x": 3, "y": 6},
+                {"matrix": [4, 4], "x": 4, "y": 6},
+
+                {"matrix": [9, 0], "x": 14, "y": 6},
+                {"matrix": [9, 1], "x": 13, "y": 6},
+                {"matrix": [9, 2], "x": 12, "y": 6},
+                {"matrix": [9, 3], "x": 11, "y": 6},
+                {"matrix": [9, 4], "x": 10, "y": 6}
 ```
 
-## 5. Shift Right-Half Matrix Indices (Split Keyboards Only)
-Because QMK maps split keyboard matrices sequentially, adding a dummy row to the left half pushes all the original right half's rows down by 1. 
-
-For example, if your left half originally used rows `0` to `3`, your right half started at `4`. Since the left half now uses `0` to `4` (due to the added Halcyon row), the right half must now start at `5`.
-
-1. **In your `"layouts"` block:** Look at all the *pre-existing* right-hand keys and increase their row index (the first number in the `"matrix": [row, col]` array) by `1`. *(e.g., `[4, 2]` becomes `[5, 2]`)*.
-2. **In your `"rgb_matrix"` block:** If the keyboard has per-key RGB, you must do the exact same `+1` row shift for the `"layout"` array located inside `"rgb_matrix"` so the lighting correctly aligns with the shifted matrix!
-
 ## 6. Update your `keymap.c` or `keymap.json`
 Because your layout macro now has a new name and expects 5 (or 10) more keys, compiling an old keymap will fail. 
 
@@ -162,32 +181,14 @@ Update the entry to:
 
 This ensures the CI system builds the firmware using the overlayed keyboard definition rather than the original keyboard from the main repository.
 
-## 7. Compile
-Because of the hacky way this overlay ties into the QMK build system, GitHub CI handles the file merging automatically, but local compilation requires an extra symlinking step.
+## 8. Compile
+After porting the keyboard you can compile it using the same userspace build process described in the main README.
 
-### Option A: Build via GitHub CI (Recommended)
-Simply commit and push your changes to your fork of the repository. The GitHub Actions workflow will automatically handle the hacky merges, compile the firmware, and upload the binaries in the **Releases** tab of your repository!
-
-### Option B: Build Locally
+### Build Locally
 Because QMK doesn't natively support overlaying base `keyboard.json` files from an external userspace directory, you must symlink your customized keyboard folder into your local QMK/Vial tree so the compiler can find it.
 
 1. Open your terminal and create a symlink from your userspace to your local QMK (or Vial) repository:
    ```bash
    ln -s /path/to/qmk_userspace/keyboards/<your_keyboard> /path/to/vial-qmk/keyboards/<your_keyboard>
    ```
-2. Once symlinked, you can compile your new Halcyon-supported variant normally using the userspace build commands:
-   ```bash
-   qmk compile -kb <your_keyboard> -km <your_keymap> -e HLC_ENCODER=1 -e TARGET=<filename>
-   ```
-
-   Or compile all boards present in the `qmk.json`
-   ```bash
-   qmk userspace-compile
-   ```
-
-**Available Module Flags:**
-* `HLC_NONE` (Module installed on the other half, but this half is blank)
-* `HLC_ENCODER` (Rotary Encoder installed)
-* `HLC_ENCODER_REV2` (Second revision rotary Encoder installed)
-* `HLC_TFT_DISPLAY` (TFT RGB Display installed)
-* `HLC_CIRQUE_TRACKPAD` (Cirque Trackpad installed)
+2. Once symlinked, you can compile it using the same userspace build process described in the main README.