You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Before continuing, complete the setup described in the main README.
3
+
Ensure the setup in the main README is completed before proceeding.
4
4
5
-
This guide can be used for both a keyboard design with a **Halcyon and VIK connector** or the **Halcyon to Promicro adapter**.
5
+
This guide applies to:
6
6
7
-
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.
7
+
* Keyboards with a **Halcyon + VIK connector**
8
+
* Keyboards using the **Halcyon → Pro Micro adapter**
8
9
9
-
#Adding support for Halcyon Modules (Except Halcyon Encoders)
10
+
## 1. Enable Halcyon Modules in Your Keymap
10
11
11
-
> **⚠️** 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.
12
+
Copy or create your keymap in this repository.
12
13
13
-
Create or copy your keymap to this repository.
14
+
In your keymap directory, update or create `rules.mk`:
14
15
15
-
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.
16
-
17
-
You can now compile using the steps from the main readme.
18
-
19
-
# Adding support for Halcyon Encoders
20
-
21
-
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.
22
-
23
-
## 1. Prepare your Userspace Overlay
24
-
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
-
26
-
Create one of the following folders:
27
-
28
-
*`keyboards/<your_keyboard>_hlc/`
29
-
*`keyboards/<your_keyboard>/<rev>_hlc/`
30
-
31
-
Which one you use depends on how the keyboard is structured:
32
-
33
-
***If the keyboard uses revision folders** (e.g., `rev1`, `rev2`), create `keyboards/<your_keyboard>/<rev>_hlc/` and copy the contents of that specific revision folder.
34
-
***If the keyboard does not use revisions**, create `keyboards/<your_keyboard>_hlc/` and copy the entire base keyboard folder.
16
+
```make
17
+
USER_NAME := halcyon_modules
18
+
```
35
19
36
-
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.
20
+
If using the Halcyon → Pro Micro adapter, also add:
37
21
38
-
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.
22
+
```make
23
+
CONVERT_TO = halcyon
24
+
```
39
25
40
-
## 2. Register encoder support.
41
-
Even if you are compiling for a trackpad or TFT display, QMK needs the encoder initialized. We do this by defining a dummy encoder.
26
+
## 2. Configure Encoder Support
42
27
43
-
In your `keyboard.json`, add a `"rotary"` array under `"encoder"` using `"NO_PIN"`:
28
+
Edit:
44
29
45
-
```json
46
-
"encoder": {
47
-
"rotary":[
48
-
{"pin_a": "NO_PIN", "pin_b": "NO_PIN"}
49
-
]
50
-
}
51
30
```
52
-
53
-
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:
Next, open `users/halcyon_modules/splitkb/config.h` in the userspace directory.
73
-
Add a keyboard-specific override using the following structure. The pin numbers (`22` and `18` in this example) must match the encoder pins defined in the keyboard’s `keyboard.json`.
34
+
Add a keyboard-specific override. Pin values must match those defined in `keyboard.json`.
74
35
75
-
The `#ifdef` name must match the keyboard identifier, with `/` replaced by `_`.
36
+
Replace `/` with `_` in the keyboard identifier:
76
37
77
38
```c
78
39
#ifdef KEYBOARD_splitkb_halcyon_elora_rev2_hlc
79
-
#undef ENCODER_A_PINS
80
40
#define ENCODER_A_PINS { GP22, HLC_ENCODER_A }
81
-
#undef ENCODER_B_PINS
82
41
#define ENCODER_B_PINS { GP18, HLC_ENCODER_B }
83
42
#endif
84
-
````
43
+
```
85
44
86
-
If the `keyboard.json` also defines a `"split"` encoder, you must override the right-half pins as well:
45
+
If the keyboarddefines a split encoder, also override right-half pins:
87
46
88
47
```c
89
48
#ifdef KEYBOARD_splitkb_aurora_corne_rev1_hlc
@@ -99,127 +58,54 @@ If the `keyboard.json` also defines a `"split"` encoder, you must override the r
99
58
#endif
100
59
```
101
60
61
+
## 3. Expand the Matrix
102
62
103
-
## 3. Expand the Matrix Pins
104
-
*WIP: Currently we're still exploring options to support row2col and direct pins.*
105
-
106
-
We need to add a "dummy row" to the microcontroller to physically map the 5 module keys.
107
-
108
-
Find the `"matrix_pins"` block. Add `"NO_PIN"` to the end of the `"rows"` array.
109
-
**If it is a split keyboard**, you must also do this for the right half!
110
-
111
-
```json
112
-
"matrix_pins": {
113
-
"cols":["GP9", "GP4", "GP7", "GP6", "GP5"],
114
-
"rows":["GP20", "GP25", "GP11", "GP8", "NO_PIN"]
115
-
},
116
-
"split": {
117
-
"matrix_pins": {
118
-
"right": {
119
-
"cols": ["GP5", "GP6", "GP7", "GP4", "GP9"],
120
-
"rows":["GP20", "GP25", "GP11", "GP8", "NO_PIN"]
121
-
}
122
-
}
123
-
}
124
-
```
125
-
126
-
## 4. Shift Right-Half Matrix Indices (Split Keyboards Only)
127
-
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.
128
-
129
-
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`.
63
+
In your keymap's `config.h`, override the column count when Halcyon is enabled. Create the file if needed.
130
64
131
-
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]`)*.
132
-
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!
65
+
Determine the current column count from `keyboard.json`, then add 5:
133
66
134
-
*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.*
135
-
136
-
## 5. Rename and Expand the Layout
137
-
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.
138
-
139
-
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).
140
-
141
-
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.
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.
154
-
```json
155
-
{"matrix": [4, 0], "x": 0, "y": 6},
156
-
{"matrix": [4, 1], "x": 1, "y": 6},
157
-
{"matrix": [4, 2], "x": 2, "y": 6},
158
-
{"matrix": [4, 3], "x": 3, "y": 6},
159
-
{"matrix": [4, 4], "x": 4, "y": 6},
160
-
161
-
{"matrix": [9, 0], "x": 14, "y": 6},
162
-
{"matrix": [9, 1], "x": 13, "y": 6},
163
-
{"matrix": [9, 2], "x": 12, "y": 6},
164
-
{"matrix": [9, 3], "x": 11, "y": 6},
165
-
{"matrix": [9, 4], "x": 10, "y": 6}
67
+
```c
68
+
#ifdef HALCYON_ENABLE
69
+
#undef MATRIX_COLS
70
+
#define MATRIX_COLS 11 // original + 5
71
+
#endif
166
72
```
167
73
168
-
## 6. Update your `keymap.c` or `keymap.json`
169
-
Because your layout macro now has a new name and expects 5 (or 10) more keys, compiling an old keymap will fail.
170
-
171
-
1. Change the layout macro in your `keymap.c` or `keymap.json` to match the name you set in Step 4 (e.g., `LAYOUT_hlc(...)`).
172
-
2. Add the 10 new keycodes to the end of your keymap array. Look at `keyboards/splitkb/halcyon/kyria/keymaps/default_hlc/keymap.c` for a working example. Currently only the first key is mapped as `KC_MUTE` for the encoder button and the rest are mapped to `KC_NO`.
173
-
174
-
## 7. Modifying the `qmk.json`
74
+
## 4. Define Halcyon Button Mappings
175
75
176
-
Because you created a keyboard overlay using the `_hlc` suffix, you must also update `qmk.json`so the build system targets the modified keyboard instead of the original one.
76
+
Update `keymap.c`, or create a new file if you're using the `keymap.json`(e.g. `halcyon_keys.c`).
177
77
178
-
Locate the keyboard entry inside `qmk.json` and adjust the `keyboard` field to point to the overlay you created.
This ensures the CI system builds the firmware using the overlayed keyboard definition rather than the original keyboard from the main repository.
214
-
215
-
## 8. Compile
216
-
After porting the keyboard you can compile it using the same userspace build process described in the main README.
107
+
(Extend layers as needed; unused entries can remain `_______`.)
217
108
218
-
### Build Locally
219
-
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.
109
+
## 5. Compile
220
110
221
-
1. Open your terminal and create a symlink from your userspace to your local QMK (or Vial) repository:
0 commit comments