Skip to content

Commit 94bc374

Browse files
veypatchveypatch
committed
docs: simplify readme
1 parent 117b461 commit 94bc374

1 file changed

Lines changed: 102 additions & 65 deletions

File tree

‎README.md‎

Lines changed: 102 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,91 +1,128 @@
1-
# Splitkb QMK Userspace
1+
# Splitkb Halcyon Modules QMK Userspace
22

3-
This is the splitkb userspace repository which allows for an external set of QMK keymaps with halcyon modules to be defined and compiled. This is useful for users who want to maintain their own keymaps without having to fork the splitkb QMK or vial repository.
3+
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.
44

5-
If you want to compile firmware without any modules you can also use the [main qmk_userspace repo](https://github.com/qmk/qmk_userspace).
5+
*If you want to compile standard firmware without any Halcyon modules, you can use the [main qmk_userspace repo](https://github.com/qmk/qmk_userspace). If you use the Halcyon to Promicro adapter board without any Halcyon modules you can use the converter without this repository.*
66

7-
If the keyboard has not been merged yet to the main branch of QMK you may need to edit the workflow, for that see [Extra info](#extra-info)
7+
## Supported Keyboards
88

9-
## Howto configure your build targets
9+
Currently supported keyboards:
1010

11-
1. Clone the Vial repo: `git clone --recursive https://github.com/vial-kb/vial-qmk`
12-
1. Run the `qmk setup -H vial-qmk` procedure if you haven't already done so -- see [QMK Docs](https://docs.qmk.fm/#/newbs) for details.
13-
1. When asked if you want to keep the repository, select option 3.
14-
1. Fork this repository
15-
1. If you have already forked the `qmk/qmk_userspace` repository before you can add this repository manually following the [steps below](#adding-splitkb-fork-to-an-existing-fork).
16-
1. Clone your fork to your local machine
17-
1. Enable userspace in QMK config using `qmk config user.overlay_dir="$(realpath qmk_userspace)"`
18-
1. Add a new keymap for your board by copy, pasting and renaming the `default_hlc` keymap within the `keyboards/splitkb/halcyon/$KB$/keymaps` folder.
19-
1. You may want to replace the `qmk.json` with the empty `qmk_empty.json` if you want to start from scratch as it will otherwise compile all default options.
20-
1. Add your keymap(s) to the build by running `qmk userspace-add -kb <your_keyboard> -km <your_keymap> -e <halcyon_module>=1 -e TARGET=<filename>`.
21-
* This will automatically update your `qmk.json` file
22-
* Corresponding `qmk userspace-remove -kb <your_keyboard> -km <your_keymap> -e <halcyon_module>=1 -e TARGET=<filename>`.
23-
* Listing the build targets can be done with with `qmk userspace-list`
24-
* If you want to use a module:
25-
* For the filename make it so you can differentiate between the different firmwares for the modules. `kyria_rev4_default_encoder` for example.
26-
* The following options are available for the halcyon modules:
27-
* HLC_NONE, If you don't have a module installed but you do have a module on the other half.
28-
* HLC_ENCODER, If you have an encoder module installed.
29-
* HLC_TFT_DISPLAY, If you have a tft rgb display installed.
30-
* HLC_CIRQUE_TRACKPAD, If you have a Cirque trackpad installed.
31-
1. Commit your changes
11+
- Halcyon Kyria (rev4)
12+
- Halcyon Elora (rev2)
13+
- Halcyon Corne (rev2)
14+
- Halcyon Ferris (rev1)
15+
- Halcyon Lily58 (rev2)
16+
- Aurora Sweep (rev1)
17+
- Aurora Lily58 (rev1)
18+
- Aurora Corne (rev1)
19+
- Kyria (rev3)
3220

21+
If you want to add a keyboard which doesn't have support for Halcyon modules yet, please follow the [porting guide](PORTING.md). Please follow the [initial setup](#initial-setup--prerequisites) and [build target](#how-to-configure-your-build-targets) steps from this readme first.
3322

34-
## Howto build with GitHub
3523

36-
1. In the GitHub Actions tab, enable workflows
37-
1. Push your changes above to your forked GitHub repository
38-
1. Look at the GitHub Actions for a new actions run
39-
1. Wait for the actions run to complete
40-
1. Inspect the Releases tab on your repository for the latest firmware build
24+
## Initial Setup & Prerequisites
4125

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

43-
## Howto build locally
28+
1. **Fork this repository** to your own GitHub account.
29+
2. **Clone the Vial repository** to your local machine:
30+
```bash
31+
git clone --recursive https://github.com/vial-kb/vial-qmk
32+
```
33+
3. **Run the QMK setup procedure** pointing to the Vial repo (see [QMK Docs](https://docs.qmk.fm/#/newbs) for more details):
34+
```bash
35+
qmk setup -H vial-qmk
36+
```
37+
*(When asked if you want to keep the repository, select option **3**).*
38+
4. **Clone your forked userspace repository** to your local machine.
39+
5. **Enable userspace in QMK config**:
40+
Navigate into your cloned userspace directory and run:
41+
```bash
42+
cd path/to/your/forked/qmk_userspace
43+
qmk config user.overlay_dir="$(realpath .)"
44+
```
45+
*(This ensures your userspace is available to QMK regardless of your current shell location).*
4446

45-
1. Clone the Vial repo: `git clone --recursive https://github.com/vial-kb/vial-qmk`
46-
1. Run the `qmk setup -H vial-qmk` procedure if you haven't already done so -- see [QMK Docs](https://docs.qmk.fm/#/newbs) for details.
47-
1. When asked if you want to keep the repository, select option 3.
48-
1. Fork this repository
49-
1. Clone your fork to your local machine
50-
1. `cd` into this repository's clone directory
51-
1. Set global userspace path: `qmk config user.overlay_dir="$(realpath .)"` -- you MUST be located in the cloned userspace location for this to work correctly
52-
* This will be automatically detected if you've `cd`ed into your userspace repository, but the above makes your userspace available regardless of your shell location.
53-
1. Compile normally: `qmk compile -kb your_keyboard -km your_keymap -e <your_module>=1 -e TARGET=<filename>` or `make your_keyboard:your_keymap -e <your_module>=1 -e TARGET=<filename>`
47+
> **Note:** If you have already forked the `qmk/qmk_userspace` repository previously, see the [Adding to an Existing Fork](#adding-halcyon-support-to-an-existing-userspace-fork) section below.
5448
55-
Alternatively, if you configured your build targets above, you can use `qmk userspace-compile` to build all of your userspace targets at once.
5649

50+
## How to Configure Your Build Targets
5751

58-
## Extra info
52+
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`.
53+
2. **Create your keymap:** Navigate to `keyboards/<keyboard_name>/keymaps` and copy/paste the `default_hlc` folder. Rename it to your desired keymap name.
54+
*(If you're unsure what the exact `keyboard_name` is, you can run `qmk list-keyboards | grep <keyboard>`)*
55+
3. **Add your keymap to the build targets** by running the following command:
56+
```bash
57+
qmk userspace-add -kb <your_keyboard> -km <your_keymap> -e <halcyon_module>=1 -e TARGET=<filename>
58+
```
59+
* *This command will automatically update your `qmk.json` file.*
60+
* **`filename`**: Choose a descriptive filename so you can easily differentiate between module firmware (e.g., `halcyon_kyria_default_encoder`).
61+
* **`halcyon_module`**: Replace this with one of the following environment variables depending on your hardware:
5962

60-
If you wish to point GitHub actions to a different repository, a different branch, or even a different keymap name, you can modify `.github/workflows/build_binaries.yml` to suit your needs.
63+
| Module Variable | Description |
64+
| :--- | :--- |
65+
| `HLC_NONE` | You have a module installed on the *other* half, but not this half. |
66+
| `HLC_ENCODER` | You have an encoder module installed. |
67+
| `HLC_TFT_DISPLAY` | You have a TFT RGB display installed. |
68+
| `HLC_CIRQUE_TRACKPAD` | You have a Cirque trackpad installed. |
6169

62-
To override the `build` job, you can change the following parameters to use a different QMK repository or branch, this can be useful if you want to use a the main QMK repository or a different vial branch. For example:
63-
```
64-
with:
65-
qmk_repo: vial-kb/vial-qmk
66-
qmk_ref: vial
67-
```
68-
Our halcyon module code should work fine with the main QMK repository but it may break if there are any breaking changes from QMK in the future. We will try our best to keep this repository up-to-date. You can track this in the `halcyon-qmk` branch.
70+
#### Useful Userspace Commands
71+
* **List configured targets:** `qmk userspace-list`
72+
* **Show generated compile commands:** `qmk userspace-compile -n`
73+
* **Remove a target:** `qmk userspace-remove -kb <your_keyboard> -km <your_keymap> -e <halcyon_module>=1 -e TARGET=<filename>`
74+
75+
76+
## How to Build with GitHub Actions
77+
78+
If you don't want to build locally, GitHub can compile the firmware for you automatically.
79+
80+
1. Go to the **Actions** tab of your forked GitHub repository and click **"I understand my workflows, go ahead and enable them"**.
81+
2. Commit and push your local changes to your fork.
82+
3. Check the **Actions** tab to watch the build process run.
83+
4. Once completed, navigate to the **Releases** tab on your repository to download your latest compiled firmware `.hex` or `.uf2` files.
6984

7085

71-
## Adding splitkb fork to an existing fork
86+
## How to Build Locally
7287

73-
### New branch
88+
Assuming you have completed the initial setup and configured your build targets, you can compile locally.
7489

75-
If you have already forked the qmk/qmk_userspace repository before you may need to manually add the `halcyon` branch.
90+
**To build all userspace targets at once:**
91+
```bash
92+
qmk userspace-compile
93+
```
94+
95+
**To compile a specific target manually:**
96+
```bash
97+
qmk compile -kb <your_keyboard> -km <your_keymap> -e <your_module>=1 -e TARGET=<filename>
98+
```
99+
100+
## Extra Info & Advanced Configuration
76101

77-
1. Add a new upstream `git remote add upstream https://github.com/splitkb/qmk_userspace.git`
78-
1. Fetch the upstream `git fetch upstream`
79-
1. Create a new branch based on the upstream `git checkout -b halcyon upstream/halcyon`
80-
1. Make any changes you want and push it to github `git push -u origin halcyon`
102+
### Modifying GitHub Actions
103+
If you wish to point GitHub Actions to a different QMK repository (such as the main QMK repo instead of Vial), a different branch, or a specific keymap, you can modify `.github/workflows/build_binaries.yml`.
104+
105+
For example, to override the `build` job to use the QMK branch:
106+
```yaml
107+
with:
108+
qmk_repo: qmk/qmk_firmware
109+
qmk_ref: master
110+
```
111+
*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.*
81112

82-
### Existing branch
113+
### Adding Halcyon support to an Existing Userspace Fork
83114

84-
You may also want to just add the files to your own branch if you have already setup a custom userspace before.
115+
If you already have a custom userspace fork of `qmk/qmk_userspace`, you can merge the Splitkb additions manually.
85116

86-
1. Clone or download the files from our fork or add it as a new branch as above.
87-
1. Copy over the contents of `users/halcyon_modules/rules.mk` and the `users/halcyon_modules/splitkb/` folder to your personal user folder.
117+
#### Option A: Adding the Splitkb Upstream Branch
118+
1. Add this repo as a remote: `git remote add upstream https://github.com/splitkb/qmk_userspace.git`
119+
2. Fetch the upstream: `git fetch upstream`
120+
3. Create a new branch based on our halcyon branch: `git checkout -b halcyon upstream/halcyon`
121+
4. Make your changes and push: `git push -u origin halcyon`
88122

89-
If you want to modify an existing keymap (from the original Kyria, Elora or an Aurora board for example). Make sure to add 10 new keys in your keymap (Look at `keyboards/splitkb/halcyon/kyria/keymaps/default_hlc` for an example).
123+
#### Option B: Copying files to your existing branch
124+
1. Clone or download the files from the Splitkb fork.
125+
2. Copy `users/halcyon_modules/rules.mk` and the entire `users/halcyon_modules/splitkb/` folder into your personal user folder.
126+
3. **Updating Keymaps:** If you modify an existing keymap (e.g., from the original Kyria, Elora, or Aurora), make sure to **add 10 new keys** in your keymap matrix. *(Check `keyboards/splitkb/halcyon/kyria/keymaps/default_hlc` for an example).*
90127

91-
Do note that we use some quantum functions in our userspace so there may be a conflict when compiling. If you use the `_user` functions you should be fine.
128+
> **⚠️ 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.

0 commit comments

Comments
 (0)