This is the splitkb userspace repository. It allows for an external set of QMK keymaps with Halcyon modules to be defined and compiled without having to fork the main QMK or Vial repositories.

If you want to compile standard firmware without any Halcyon modules, you can use the main qmk_userspace repo. If you use the Halcyon to Promicro adapter board without any Halcyon modules you can use the converter without this repository.

Supported controllers:

Supported keyboards:

*Requires the Halcyon converter

Supported converters:

Supported modules:

If you want to add a keyboard which doesn't have support for Halcyon modules yet, please follow the porting guide. Please follow the initial setup and build target steps from this readme first.

This repository contains keymaps for both upstream QMK (default_hlc) and Vial (vial_hlc). For the officially supported keyboards we will always provide these two keymaps.

Before configuring your keymaps or building firmware, you need to set up your build environment.

1. Fork this repository to your own GitHub account.
   • The default halcyon branch includes Vial support.
   • If you prefer upstream QMK without Vial, fork the halcyon-qmk branch instead.
2. Clone the Vial repository to your local machine:
   • For Vial:

     git clone --recursive https://github.com/vial-kb/vial-qmk

   • For upstream QMK:

     git clone --recursive https://github.com/qmk/qmk_firmware

3. Set up QMK using your cloned repository (see QMK Docs for more details):

   qmk setup -H path/to/your/qmk/repository

   When prompted whether to keep the existing repository, select 3.
4. Clone your forked userspace repository to your local machine.

   git clone https://github.com/YOUR_GITHUB_USERNAME/qmk_userspace

5. Enable userspace in QMK config: Navigate into your cloned userspace directory and run:

   cd path/to/your/forked/qmk_userspace
   qmk config user.overlay_dir="$(realpath .)"

   This tells QMK where to find your userspace, regardless of your current working directory.

Note: If you have already forked the qmk/qmk_userspace repository previously, see the Adding to an Existing Fork section below.

1. Start fresh (Optional but recommended): If you want to start completely from scratch without any default compile options, replace the qmk.json in the root folder with the provided qmk_empty.json.

2. Create your keymap: Navigate to keyboards/<keyboard_name>/keymaps and copy/paste the default_hlc or the vial_hlc or vial_hlc_legacy folder, if you still want to use vial. Rename it to your desired keymap name.
   (Updating Keymaps: If you modify an existing keymap (e.g., from the original Kyria, Elora, or Aurora), and want to use a Halcyon encoder module, make sure to add the Halcyon Button mappings and Encoder mapping as shown in the porting guide)
   (If you're unsure what the exact keyboard_name is, you can run qmk list-keyboards | grep <keyboard>)
   For existing Vial users, you should use the vial_hlc_legacy keymap as the location mapping is different in the newer version and this is not compatible with the new version. You would otherwise have to recreate your keymap in Vial. Otherwise you can use the newer vial_hlc keymap.

3. Add your keymap to the build targets by running the following command:

   qmk userspace-add -kb <your_keyboard> -km <your_keymap> -e <halcyon_module>=1 -e TARGET=<filename>

   • This command will automatically update your qmk.json file.
   • filename: Choose a descriptive filename so you can easily differentiate between module firmware (e.g., halcyon_kyria_default_encoder).
   • halcyon_module: Replace this with one of the following environment variables depending on your hardware:

   Module Variable	Description
   HLC_NONE	You have a module installed on the other half, but not this half.
   HLC_ENCODER	You have an encoder module installed.
   HLC_ENCODER_REV2	You have a second revision encoder module installed.
   HLC_TFT_DISPLAY	You have a TFT RGB display installed.
   HLC_CIRQUE_TRACKPAD	You have a Cirque trackpad installed.

• List configured targets: qmk userspace-list
• Show generated compile commands: qmk userspace-compile -n
• Remove a target: qmk userspace-remove -kb <your_keyboard> -km <your_keymap> -e <halcyon_module>=1 -e TARGET=<filename>. You can also remove a target by removing the specific lines in the qmk.json file.

Please see the seperate docs.

If you don't want to build locally, GitHub can compile the firmware for you automatically.

1. Go to the Actions tab of your forked GitHub repository and click "I understand my workflows, go ahead and enable them".
2. Commit and push your local changes to your fork.
3. Check the Actions tab to watch the build process run.
4. Once completed, navigate to the Releases tab on your repository to download your latest compiled firmware .hex or .uf2 files.

Assuming you have completed the initial setup and configured your build targets, you can compile locally.

To build all userspace targets at once:

qmk userspace-compile

To compile a specific target manually:

qmk compile -kb <your_keyboard> -km <your_keymap> -e <your_module>=1 -e TARGET=<filename>

Tip: use qmk userspace-compile -n to get the exact compile command

If you wish to point GitHub Actions to a different QMK repository (such as the main QMK repo instead of Vial), or a different branch, you can modify .github/workflows/build_binaries.yml.

For example, to override the build job to use the QMK branch (which is already done in the halcyon-qmk branch):

    with:
      qmk_repo: qmk/qmk_firmware
      qmk_ref: master

Note: Our Halcyon module code should work fine with the main QMK repository, but it may break if QMK introduces upstream breaking changes. We track QMK updates in the halcyon-qmk branch.

If you already have a custom userspace fork of qmk/qmk_userspace, you can merge the Splitkb additions manually.

1. Add this repository as a remote:

   git remote add splitkb https://github.com/splitkb/qmk_userspace.git

2. Fetch the upstream branches:

   git fetch splitkb

3. Create a local branch based on the appropriate upstream branch:
   • Vial:

     git checkout -b halcyon splitkb/halcyon

   • Upstream QMK:

     git checkout -b halcyon-qmk splitkb/halcyon-qmk

4. Make your changes and push your branch:

   git push -u origin <branch-name>

   Replace <branch-name> with either halcyon or halcyon-qmk.

1. Clone or download the files from the Splitkb fork.
2. Copy and/or merge users/halcyon_modules/rules.mk and the entire users/halcyon_modules/splitkb/ folder into your personal user folder.

⚠️ Warning: We use some quantum functions in our userspace. If your existing userspace relies heavily on custom quantum functions, you may encounter compile conflicts. If you restrict yourself to _user functions, you should be fine.