Skip to content

Commit 70f8f7b

Browse files
bstiqbstiq
committed
compile firmware for dilemma procyon
1 parent 48aff6c commit 70f8f7b

File tree

2 files changed

+182
-6
lines changed

2 files changed

+182
-6
lines changed

‎fw/compile-firmware.md‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ You will have to modify the keymap `C` code, and from there compile your firmwar
2525

2626
If that seems too complicated, you can also use one of the [release firmware](https://github.com/Bastardkb/qmk_userspace/releases/latest) builds.
2727

28+
If you are compiling for the Dilemma V3/Dilemma MAX V3, you can check the [specific instructions here][dilemma].
29+
2830
# Pre-requisites
2931

3032
## BastardKB userspace
@@ -71,7 +73,7 @@ By using github actions, you can have Github compile your firmware without havin
7173

7274
If you want to use Github actions to compile your firmware (rather than doing it locally in the console), you will need to:
7375

74-
- fork the BastardKB QMK Userspace repository
76+
- fork the [BastardKB QMK userspace repository][bkbus]
7577
- **in the `Actions` tab, enable workflows**
7678

7779

@@ -171,11 +173,6 @@ qmk compile -c -kb bastardkb/{keyboard} -km {keymap}
171173

172174
If you followed the instructions until now, it would be `my-keymap`.
173175

174-
# Contributing your own keymap
175-
176-
If you are happy with your keymap and would like to share it, we would gladly review it!
177-
178-
Just PR your fork to the origin BastardKB Userspace repository.
179176

180177
# Flashing your keyboard
181178

@@ -188,3 +185,4 @@ For how to flash your keyboard, take a look at the [how to flash your keyboard p
188185

189186
[flashing]: {{site.baseurl}}/fw/flashing.html
190187
[bkbus]: https://github.com/Bastardkb/qmk_userspace
188+
[dilemma]: {{site.baseurl}}/fw/procyon-compile

‎fw/procyon-compile.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
---
2+
layout: default
3+
title: Compiling firmware for Dilemma/MAX V3
4+
nav_order: 2
5+
parent: Firmware
6+
---
7+
8+
# Table of contents
9+
10+
1. TOC
11+
{:toc}
12+
13+
# Introduction
14+
15+
The [BastardKB QMK repository](https://github.com/bastardkb/bastardkb-qmk) contains the behavioral firmware code and releases for the Bastard Keyboards Charybdis boards.
16+
17+
The keymaps are stored in the [BastardKB QMK userspace repository][bkbus].
18+
19+
The QMK repository repository is used as primary source of truth for Bastard Keyboards firmwares and contains the latest changes and improvements.
20+
The maintainers aim at upstreaming all those changes to the official [QMK repository](https://github.com/qmk/qmk_firmware).
21+
22+
This page details how to build your own firmware.
23+
Building from source is useful to people who want to customize their keyboard and keymaps beyond what Via offers.
24+
You will have to modify the keymap `C` code, and from there compile your firmware either using Github actions or the local command line.
25+
26+
If that seems too complicated, you can also use one of the [release firmware](https://github.com/Bastardkb/qmk_userspace/releases/tag/prerelease) builds.
27+
28+
Right now the code for the Dilemma V3 and Dilemma MAX V3 is not on the master branch of our QMK fork.
29+
This is because we are waiting for features to merge into the main QMK repository, and need to use the `bkb-develop` branch meanwhile.
30+
31+
Because of this, compiling your own image requires some additional steps. Otherwise, the process is quite similar to the regular one.
32+
33+
{: .note }
34+
In this page, we will compile a custom keymap for the `3x5_3` Dilemma V3. If you need to compile an image for the `4x6_4` Dilemma MAX V3, just change the options accordingly.
35+
36+
37+
# Pre-requisites
38+
39+
## BastardKB userspace
40+
41+
While the QMK repository contains the logic behind the keyboards, the keymaps are in the userspace repository.
42+
43+
**If you are going to create your own keymaps, the first step is to fork the [BastardKB QMK userspace repository][bkbus].**
44+
45+
46+
This way, you can:
47+
48+
- track changes
49+
- use Github actions to compile your keymap
50+
- (if relevant) contribute your keymap to the origin Bastard KB QMK Userspace
51+
52+
In a separate folder, clone the fork you just created, using either Github desktop or the command line. Then, switch to the `bkb-develop` branch:
53+
54+
55+
```shell
56+
git clone https://github.com/my_username/qmk_userspace
57+
cd qmk_userspace
58+
git checkout -b bkb-develop origin/bkb-develop
59+
```
60+
61+
# Creating your keymap
62+
63+
If you want to create your own keymap, **make sure you have forked the [BastardKB QMK userspace repository][bkbus]**, and switched to the `bkb-develop` branch.
64+
65+
Create a separate folder in the relevant folder, eg:
66+
67+
```
68+
keyboards/bastardkb/dilemma/3x5_3_procyon/my-keymap
69+
```
70+
71+
72+
{: .note }
73+
By convention, your keymap name must be all lowercase, without spaces.
74+
75+
Then, the easiest is to copy over an existing keymap (eg. `vendor`) over, and modify from there.
76+
77+
# Compiling your firmware using Github actions
78+
79+
By using github actions, you can have Github compile your firmware without having to bother with a local QMK installation and console commands.
80+
81+
## Pre-requisites {#actions-requirements}
82+
83+
If you want to use Github actions to compile your firmware (rather than doing it locally in the console), you will need to:
84+
85+
- fork the [BastardKB QMK userspace repository][bkbus]
86+
- switch to the `bkb-develop` branch
87+
- **in the `Actions` tab, enable workflows**
88+
89+
If you switched to the `bkb-develop` branch, then your userspace is already pointing to the `bkb-develop` branch of our QMK fork. This is where the code for the Dilemma/MAX V3 is stored.
90+
91+
## Compiling your firmware
92+
93+
First, make sure you have gone through the [Github actions requirements section above](#actions-requirements).
94+
95+
After cloning the BastardKB userspace repository, it is already configured to work with the BastardKB QMK fork - so no need for additional configuration on that side.
96+
97+
Once you created your own keymap, you will need to add it to the list of keymaps to be compiled in `qmk.json`, for example:
98+
99+
```shell
100+
{
101+
"userspace_version": "1.0",
102+
"build_targets": [
103+
["bastardkb/dilemma/3x5_3_procyon", "my-keymap"]
104+
]
105+
}
106+
```
107+
108+
We also recommend deleting the other keymaps if you don't use them, as it'll make the action run faster.
109+
110+
Then,
111+
112+
1. Push your changes above to your forked GitHub repository
113+
1. Look at the GitHub Actions for a new actions run
114+
1. Wait for the actions run to complete
115+
1. Inspect the Releases tab on your repository for the latest firmware build
116+
117+
118+
# Compiling your firmware using the local command line
119+
120+
You can also compile your firmware through your local command line. This requires you to be familiar with the console, and doing some additional configuration.
121+
122+
## Pre-requisites
123+
124+
### Working QMK environment
125+
126+
Make sure you have a functional QMK environment. See [QMK Docs](https://docs.qmk.fm/#/newbs) for details. At this point, **you don't need** to run `qmk setup`.
127+
128+
### BastardKB QMK fork
129+
130+
Clone the BKB QMK repository, using either github desktop or the command line, and switch to the `bkb-develop` branch:
131+
132+
```shell
133+
git clone https://github.com/bastardkb/bastardkb-qmk
134+
cd bastardkb-qmk
135+
git checkout -b bkb-develop origin/bkb-develop
136+
qmk git-submodule
137+
```
138+
139+
Now that you've cloned the repository, set it as the default local QMK repository. You also need to do this if you had a previous, separate QMK installation.
140+
141+
```shell
142+
qmk config user.qmk_home="$(realpath .)"
143+
```
144+
145+
{: .info }
146+
If you have multiple QMK installations, you will need to manually set the qmk home path again to use the other ones.
147+
148+
That's all you needed to do with the QMK repository.
149+
From here on, **we will only focus on the userspace repository.**
150+
151+
### QMK Userspace
152+
153+
Next, `cd` into your userspace fork and enable userspace:
154+
155+
```shell
156+
qmk config user.overlay_dir="$(realpath .)"
157+
```
158+
159+
## Compiling your firmware
160+
161+
Once in the QMK userspace repository, compiling a keymap works the same as normal. For example:
162+
163+
```shell
164+
qmk compile -c -kb bastardkb/dilemma/3x5_3_procyon -km my_keymap
165+
```
166+
167+
# Flashing your keyboard
168+
169+
Once you compiled your `uf2` image, you can flash your keyboard.
170+
171+
For how to flash your keyboard, take a look at the [how to flash your keyboard page][flashing].
172+
173+
----
174+
175+
[githubactions]: {{site.baseurl}}/fw/compile-firmware.html#compiling-your-firmware-using-github-actions
176+
[flashing]: {{site.baseurl}}/fw/flashing.html
177+
[bkbus]: https://github.com/Bastardkb/qmk_userspace
178+
[dilemma]: {{site.baseurl}}/fw/procyon-compile

0 commit comments

Comments
 (0)