This is the Splitkb Halcyon ZMK config repository. It allows for an external set of ZMK keymaps with or without Halcyon modules to be defined and compiled. If you want to add support to your existing keyboard, please look at the porting guide.
Supported boards:
| Board name | Board variable |
|---|---|
| Halcyon Wireless controller | halcyon_wireless//zmk |
| Halcyon Dongle | halcyon_dongle//zmk |
| Halcyon Wired controller* | halcyon_wired//zmk |
*While the wired controller is supported, full testing has not been done. Some configurations may not work as expected.
Supported keyboard shields:
| Keyboard name | Shield variable |
|---|---|
| Halcyon Kyria (rev4) | halcyon_kyria |
| Halcyon Elora (rev2) | halcyon_elora |
| Halcyon Corne (rev2) | halcyon_corne |
| Halcyon Ferris (rev1) | halcyon_ferris |
| Halcyon Lily58 (rev2) | halcyon_lily58 |
| Aurora Sweep (rev1)* | splitkb_aurora_sweep |
| Aurora Lily58 (rev1)* | splitkb_aurora_lily58 |
| Aurora Corne (rev1)* | splitkb_aurora_corne |
| Aurora Helix (rev1)* | splitkb_aurora_helix |
| Aurora Sofle v2 (rev1)* | splitkb_aurora_sofle |
| Kyria (rev3)* | kyria_rev3 |
*The files for the Aurora and Kyria rev3 shields can be found in the Aurora branch. If you want to customize your keyboard behavior and keep the Halcyon module functionality, make sure to use that branch. You can delete any files for the keyboards you are not using.
Supported converters:
| Converter name | Shield variable |
|---|---|
| Halcyon to Promicro adapter | halcyon_to_promicro |
Supported battery boards:
| Battery board name | Shield variable |
|---|---|
| LiPo Battery board | mod_battery_lipo |
| Coincell Battery board | mod_battery_coincell |
Supported module shields:
| Module name | Shield variable |
|---|---|
| Halcyon TFT LCD Display Module | mod_display_tft |
| Halcyon Rotary Encoder Module Revision 2 | mod_encoder_left and mod_encoder_right |
| Halcyon Cirque Touchpad Module | mod_cirque_central_hw, mod_cirque_central, mod_cirque_hw_left and mod_cirque_hw_right |
| Halcyon Epaper Display Module | mod_display_epaper |
| Halcyon MIP Display Module (TBA) | mod_display_mip |
Create a fork of this repository using the Use this template button and select Create a new repository.
Follow the steps from the ZMK documentation. When you arrive at Config Repo Setup step, follow the steps where you already have a ZMK config repo on github where you point to the newly cloned fork.
The aurora branch will have already setup the config. You can clear the
build.yamlfile and follow the instructions and examples below to set up your specific build.
By default the ZMK CLI will create build targets for the left and right half. The build.yaml file will need to be updated to support the various modules as shown above.
The following section explains how to correctly compose the shield values.
Dongles use a fixed composition:
shield: <keyboard>_dongle mod_cirque_central<keyboard>_dongleis your keyboard’s dongle shieldmod_cirque_centralis required when one of the halfs includes a cirque trackpad
No other modules are added to dongles.
A keyboard build generally looks like this:
shield: <converter_shield> <keyboard>_<side> <battery> <module>
cmake-args: -DCONFIG_ZMK_SPLIT_ROLE_CENTRAL=n<converter_shield>= optional, only needed when using the Halcyon to Promicro adapter<keyboard>= one of the supported keyboards<side>=leftorright<battery>= your selected battery module<module>= your selected Halcyon module, which will be explained in the next section- The
cmake-argsis only needed for the left side or on dongle builds
At the bottom there are some examples.
Match the module to the correct side:
-
Left encoder:
shield: <keyboard>_left <battery> mod_encoder_left
-
Right encoder:
shield: <keyboard>_right <battery> mod_encoder_right
Match the module to the correct side:
-
Left-side pointing:
shield: <keyboard>_left <battery> mod_cirque_hw_left
-
Right-side pointing:
shield: <keyboard>_right <battery> mod_cirque_hw_right
-
Left central pointing device:
shield: <keyboard>_left <battery> mod_cirque_central_hw
-
Right-side pointing:
shield: <keyboard>_right <battery> mod_cirque_hw_right
When NOT using a dongle but you are using a Cirque trackpad on the right half, the left side will need
mod_cirque_centralappended to the build.
For all other module types:
-
Left:
shield: <keyboard>_left <battery> <module>
-
Right:
shield: <keyboard>_right <battery> <module>
If building a Studio build, append:
cmake-args: -DCONFIG_ZMK_STUDIO=y
snippet: studio-rpc-usb-uartTo the central half. This will be either the dongle or the left side when NOT using a dongle.
Halcyon Kyria with a dongle with ZMK Studio enabled, a epaper display and coincell battery on the left half, and a rotary encoder and coincell battery on the right half.
---
include:
- board: halcyon_dongle//zmk
shield: halcyon_kyria_dongle
cmake-args: -DCONFIG_ZMK_STUDIO=y
snippet: studio-rpc-usb-uart
- board: halcyon_wireless//zmk
shield: halcyon_kyria_left mod_battery_coincell mod_display_epaper
cmake-args: -DCONFIG_ZMK_SPLIT_ROLE_CENTRAL=n
- board: halcyon_wireless//zmk
shield: halcyon_kyria_right mod_battery_coincell mod_encoder_right
Aurora corne without dongle, no module and LiPo battery on the left half, and a a cirque touchpad and LiPo battery on the right half.
---
include:
- board: halcyon_wireless//zmk
shield: halcyon_to_promicro splitkb_aurora_corne_left mod_battery_lipo mod_cirque_central
- board: halcyon_wireless//zmk
shield: halcyon_to_promicro splitkb_aurora_corne_right mod_battery_lipo mod_cirque_hw_right
Building the Halcyon boards and shields is of course also possible locally. For this you will just need to follow the ZMK guide.
The only thing of note is that you will need to add the following repository as a module.
ZMK allows for a lot of different configuration options. On our Halcyon keyboards we enable a couple of these options to improve the user experience. It is good to know which options are enabled if you ever plan to customize the firmware.
| Config | Description | Board/shield |
|---|---|---|
| CONFIG_ZMK_SLEEP | Enable sleep to increase battery life | halcyon_wireless |
| CONFIG_BT_CTLR_TX_PWR_PLUS_8 | Increase TX on dongle | halcyon_dongle |
| CONFIG_ZMK_IDLE_TIMEOUT=900000 | Increase idle timeout to decrease the number of updates the epaper display does | mod_display_epaper |
| CONFIG_ZMK_BATTERY_REPORT_INTERVAL=600 | Battery life is weeks to months so updating less makes sense | mod_battery_* |
| CONFIG_ZMK_RGB_UNDERGLOW_AUTO_OFF_USB | Makes sure that the EXT_POWER turns off when you unplug the keyboard with coin cell battery to increase battery life | mod_battery_coincell |
| CONFIG_ZMK_RGB_UNDERGLOW=y | Enable RGB | keyboard shield |
| CONFIG_ZMK_RGB_UNDERGLOW_ON_START=n | Disable RGB on start | keyboard shield |
| CONFIG_ZMK_RGB_UNDERGLOW_BRT_MAX=20 | Set a limit to the brightness, so your battery won't drain quickly | keyboard shield |
Within the ZMK Halcyon module repository we define all keyboard shields, controller boards, halcyon module shields and drivers.
With Zephyr, what ZMK is based on, it's quite easy to override any functions in the keymap file.
As an example, overriding the number of times the LED will blink and at which percentage, can be done like the following in a .keymap file.
&battery_empty_led {
battery_threshold_percentage = <40>;
num_blinks = <10>;
};Please look at the ZMK documentation if you want to change the behavior of the display. You can also look at the README from the Halcyon Epaper shield to see how you can add a custom image.
Keycodes can be changed in the sensor-bindings of your keymap where the order is as following; left halcyon encoder, right halcyon encoder, left soldered encoder and right soldered encoder.
Behavior can be changed by adding input processors. You can look at the ZMK documentation for the available options.