diff --git a/.wordlist.txt b/.wordlist.txt index 248f272..11a4f25 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -60,7 +60,7 @@ TODO multimeter keypress MCU -!dilemma +Dilemma TRRS KiCad Millmax @@ -94,3 +94,9 @@ udev Singel LEBASTARD + +Alli # keeps getting detected as a word in youtube video id in embed +upstreaming +userspace +realpath +usevia # keeps being detected in the url diff --git a/_includes/use_keyboard.md b/_includes/use_keyboard.md new file mode 100644 index 0000000..2e04d08 --- /dev/null +++ b/_includes/use_keyboard.md @@ -0,0 +1,51 @@ +# Table of contents + +1. TOC +{:toc} + +# Introduction + +Congratulations on successfully building your keyboard! + +The Bastard Keyboards come with a range of features, and it's also easy to customize them. On this page you will find additional information on how to use them and make them your own. + +# Daily use + +## Default keymap + +You can find pictures of the default keymaps on the [default keymaps page][keymaps]. + +Alternatively, you can also plug in your keyboard and visualize the keymap using VIA (see VIA section). + +# Customization + +For customizing your keyboard, you can: + +- use VIA +- use QMK + +## Using VIA + +All Bastard Keyboards come flashed with a VIA-enabled firmware. VIA is an additional layer that comes on top of QMK, and comes with a handy graphical interface. While it's limited in features, it removes the need to manage a git repository, the console and a QMK installation. + +You can open the [VIA Web Interface through usevia.app](https://usevia.app/). At the moment, only WebHID-enabled browsers work (eg. Chrome and Chromium-based). + +You can check the following tutorial on how to use it: +{% include youtube.html id="cYICAlliJfU" %} + +Through VIA, you can customize: +- the keymap +- macros, layers +- RGB + +## Using QMK + +This is for advanced users. + +For how to compile a custom hardware for your keyboard, take a look at the [how to compile your own firmware page][compile-firmware]. + +--- + +[compile-firmware]: {{site.baseurl}}/fw/compile-firmware.html +[keymaps]: {{site.baseurl}}/fw/default-keymaps.html +[flashing]: {{site.baseurl}}/fw/flashing.html \ No newline at end of file diff --git a/_includes/customize_keyboard.md b/_includes/use_keyboard_chary.md similarity index 61% rename from _includes/customize_keyboard.md rename to _includes/use_keyboard_chary.md index 2976ff7..9ddf855 100644 --- a/_includes/customize_keyboard.md +++ b/_includes/use_keyboard_chary.md @@ -34,20 +34,23 @@ The most important ones are on the thumb cluster - it transforms into mouse butt ### Sniping -Sniping **slows down the trackball**. This way, you can move the cursor more precisely. +Sniping **slows down the trackball/trackpad**. This way, you can move the cursor more precisely. By default, Sniping mode is activated when you hold the `MOUSE + SNIP` keys at the same time. You can also configure qmk to have it activated automatically. -## Miryoku +# Customization -The 3x5 keyboards (Skeletyl, Charybdis Nano) come flashed with [Miryoku](https://github.com/manna-harbour/miryoku). On its github repository you will find useful information on the different layers available. +For customizing your keyboard, you can: -# Customization +- use VIA +- use QMK ## Using VIA -All Bastard Keyboards come flashed with VIA. You can open the [VIA Web Interface through use.via.app](https://usevia.app/). At the moment, only WebHID-enabled browsers work (eg. Chrome and Chromium-based). +All Bastard Keyboards come flashed with VIA. VIA is an additional layer that comes on top of QMK, and comes with a handy graphical interface. While it's limited in features, it removes the need to manage a git repository, the console and a QMK installation. + +You can open the [VIA Web Interface through usevia.app](https://usevia.app/). At the moment, only WebHID-enabled browsers work (eg. Chrome and Chromium-based). You can check the following tutorial on how to use it: {% include youtube.html id="cYICAlliJfU" %} @@ -59,14 +62,15 @@ Through VIA, you can customize: ## Using QMK -You can find the latest **default images** for all Bastard Keyboards in the release section of the [BastardKB QMK fork](https://github.com/Bastardkb/bastardkb-qmk/releases). +This is for advanced users. -For how to flash your keyboard, take a look at the [how to flash your keyboard page][flashing]. +For how to compile a custom hardware for your keyboard, take a look at the [how to compile your own firmware page][compile-firmware]. -For **advanced customization of the Charybdis and Charybdis Nano**, take a look at the [customize page][customize]. +For **advanced customization of the Charybdis and Charybdis Nano**, take a look at the [customize page][customize-chary]. --- -[customize]: {{site.baseurl}}/fw/charybdis-features.html +[customize-chary]: {{site.baseurl}}/fw/charybdis-features.html [keymaps]: {{site.baseurl}}/fw/default-keymaps.html -[flashing]: {{site.baseurl}}/fw/flashing.html \ No newline at end of file +[flashing]: {{site.baseurl}}/fw/flashing.html +[compile-firmware]: {{site.baseurl}}/fw/compile-firmware.html \ No newline at end of file diff --git a/bg_charybdis/13customize.md b/bg_charybdis/13customize.md index 7fb2ec4..fa5ad47 100644 --- a/bg_charybdis/13customize.md +++ b/bg_charybdis/13customize.md @@ -1,9 +1,9 @@ --- layout: default -title: Customizing your keyboard +title: Using your keyboard nav_order: 13 parent: Build guide - Charybdis --- -{% include customize_keyboard.md %} \ No newline at end of file +{% include use_keyboard_chary.md %} \ No newline at end of file diff --git a/bg_cnano/13customize.md b/bg_cnano/13customize.md index e50526e..d225d3a 100644 --- a/bg_cnano/13customize.md +++ b/bg_cnano/13customize.md @@ -1,9 +1,9 @@ --- layout: default -title: Customizing your keyboard +title: Using your keyboard nav_order: 13 parent: Build guide - Charybdis Nano --- -{% include customize_keyboard.md %} \ No newline at end of file +{% include use_keyboard_chary.md %} \ No newline at end of file diff --git a/bg_dilemma/customize.md b/bg_dilemma/customize.md new file mode 100644 index 0000000..28bf41b --- /dev/null +++ b/bg_dilemma/customize.md @@ -0,0 +1,9 @@ +--- +layout: default +title: Using your Dilemma +nav_order: 99 +parent: Build guide - Dilemma +--- + + +{% include use_keyboard_chary.md %} \ No newline at end of file diff --git a/bg_dilemma/intro.md b/bg_dilemma/intro.md index 753c510..32369c7 100644 --- a/bg_dilemma/intro.md +++ b/bg_dilemma/intro.md @@ -11,5 +11,7 @@ We recommend you start by reading the *required tools* section. There are written guides, and there are also video guides in the *video guides* section. +For building the Dilemma MAX, just follow the Dilemma instructions - it's the same keyboard, just bigger. + 1. TOC {:toc} diff --git a/bg_dilemma/max_v1.md b/bg_dilemma/max_v1.md deleted file mode 100644 index bc5490e..0000000 --- a/bg_dilemma/max_v1.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -layout: default -title: MAX build guide -nav_order: 7 -parent: Build guide - Dilemma ---- - -1. TOC -{:toc} - diff --git a/bg_dilemma/v1.md b/bg_dilemma/v1.md index cdbeccf..5289e79 100644 --- a/bg_dilemma/v1.md +++ b/bg_dilemma/v1.md @@ -108,6 +108,5 @@ Solder in your switches of preference. You're all done! -Head over to [bstkbd.com/custom](https://bstkbd.com/custom) to customize your keyboard to your needs. +Head over to [Customize your Dilemma firmware][use-dilemma] to customize your keyboard to your needs. -If you need any help with it, make sure to hop on the discord : [bstkbd.com/discord](https://www.bstkbd.com/discord) diff --git a/bg_dilemma/v2.md b/bg_dilemma/v2.md index 42fd162..c249501 100644 --- a/bg_dilemma/v2.md +++ b/bg_dilemma/v2.md @@ -120,6 +120,8 @@ Solder in your switches of preference. You're all done! -Head over to [bstkbd.com/custom](https://bstkbd.com/custom) to customize your keyboard to your needs. +Head over to [Customize your Dilemma firmware][use-dilemma] to customize your keyboard to your needs. -If you need any help with it, make sure to hop on the discord : [bstkbd.com/discord](https://www.bstkbd.com/discord) +--- + +[use-dilemma]: {{site.baseurl}}/bg_dilemma/customize.html \ No newline at end of file diff --git a/bg_scylla/13customize.md b/bg_scylla/13customize.md index d13928f..2acd04f 100644 --- a/bg_scylla/13customize.md +++ b/bg_scylla/13customize.md @@ -1,9 +1,9 @@ --- layout: default -title: Customizing your keyboard +title: Using your keyboard nav_order: 13 parent: Build guide - Scylla --- -{% include customize_keyboard.md %} \ No newline at end of file +{% include use_keyboard.md %} \ No newline at end of file diff --git a/bg_skeletyl/13customize.md b/bg_skeletyl/13customize.md index 7a3cf87..cd8ff65 100644 --- a/bg_skeletyl/13customize.md +++ b/bg_skeletyl/13customize.md @@ -1,9 +1,9 @@ --- layout: default -title: Customizing your keyboard +title: Using your keyboard nav_order: 13 parent: Build guide - Skeletyl --- -{% include customize_keyboard.md %} \ No newline at end of file +{% include use_keyboard.md %} \ No newline at end of file diff --git a/fw/compile-firmware.md b/fw/compile-firmware.md new file mode 100644 index 0000000..1278cca --- /dev/null +++ b/fw/compile-firmware.md @@ -0,0 +1,189 @@ +--- +layout: default +title: Compiling your firmware +nav_order: 99 +parent: Firmware +--- + +# Table of contents + +1. TOC +{:toc} + +# Introduction + +The [BastardKB QMK repository](https://github.com/bastardkb/bastardkb-qmk) contains the behavioral firmware code and releases for the Bastard Keyboards Charybdis boards. + +The keymaps are stored in the [BastardKB QMK userspace repository][bkbus]. + +The QMK repository repository is used as primary source of truth for Bastard Keyboards firmwares and contains the latest changes and improvements. +The maintainers aim at upstreaming all those changes to the official [QMK repository](https://github.com/qmk/qmk_firmware). + +This page details how to build your own firmware. +Building from source is useful to people who want to customize their keyboard and keymaps beyond what Via offers. +You will have to modify the keymap `C` code, and from there compile your firmware either using Github actions or the local command line. + +If that seems too complicated, you can also use one of the [release firmware](https://github.com/Bastardkb/bastardkb-qmk/releases/latest) builds. + +# Pre-requisites + +## BastardKB userspace + +While the QMK repository contains the logic behind the keyboards, the keymaps are in the userspace repository. + +**If you are going to create your own keymaps, the first step is to fork the [BastardKB QMK userspace repository][bkbus].** + + +This way, you can: + +- track changes +- use Github actions to compile your keymap +- (if relevant) contribute your keymap to the origin Bastard KB QMK Userspace + +In a separate folder, clone the fork you just created, using either Github desktop or the command line: + + +```shell +git clone https://github.com/my_username/qmk_userspace +``` + +# Creating your keymap + +If you want to create your own keymap, **make sure you have forked the [BastardKB QMK userspace repository][bkbus].** + +Create a separate folder in the relevant folder, eg: + +``` +keyboards/bastardkb/charybdis/4x6/keymaps/my-keymap/ +``` + + +{: .note } +By convention, your keymap name must be all lowercase, without spaces. + +Then, the easiest is to copy over an existing keymap (eg. `vendor`) over, and modify from there. + +# Compiling your firmware using Github actions + +By using github actions, you can have Github compile your firmware without having to bother with a local QMK installation and console commands. + +## Pre-requisites {#actions-requirements} + +If you want to use Github actions to compile your firmware (rather than doing it locally in the console), you will need to: + +- fork the BastardKB QMK Userspace repository +- **in the `Actions` tab, enable workflows** + + +## Compiling your firmware + +First, make sure you have gone through the [Github actions requirements section above](#actions-requirements). + +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. + +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: + +```shell +{ + "userspace_version": "1.0", + "build_targets": [ + ["bastardkb/charybdis/4x6", "my-keymap"] + ] +} +``` + +We also recommend deleting the other keymaps if you don't use them, as it'll make the action run faster. + +Then, + +1. Push your changes above to your forked GitHub repository +1. Look at the GitHub Actions for a new actions run +1. Wait for the actions run to complete +1. Inspect the Releases tab on your repository for the latest firmware build + + +# Compiling your firmware using the local command line + +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. + +## Pre-requisites + +### Working QMK environment + +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`. + +### BastardKB QMK fork + +Clone the BKB QMK repository, using either github desktop or the command line, and switch to the `bkb-master` branch: + +```shell +git clone https://github.com/bastardkb/bastardkb-qmk +cd bastardkb-qmk +git checkout -b bkb-master origin/bkb-master +``` + +Now that you've cloned the repository, `cd` into it and set it as the default local QMK repository. You also need to do this if you had a previous, separate QMK installation. + +```shell +qmk config user.qmk_home="$(realpath .)" +``` + +{: .info } +If you have multiple QMK installations, you will need to manually set the qmk home path again to use the other ones. + +That's all you needed to do with the QMK repository. +From here on, **we will only focus on the userspace repository.** + +### QMK Userspace + +Next, `cd` into your userspace fork and enable userspace: + +```shell +qmk config user.overlay_dir="$(realpath .)" +``` + +## Compiling your firmware + +Once in the QMK userspace repository, compiling a keymap works the same as normal: + +```shell +qmk compile -c -kb bastardkb/{keyboard} -km {keymap} +``` + +### `{keyboard}` argument + +`{keyboard}` corresponds to the physical keyboard you are building the firmware for. It can be one of the following: + +- `charybdis/4x6`: the 4x6+5 [Charybdis](https://github.com/bastardkb/charybdis/) +- `charybdis/3x5`: the 3x5+3 [Charybdis Nano](https://github.com/bastardkb/charybdis/) +- `charybdis/3x6`: the 3x6+3 [Charybdis Mini](https://github.com/bastardkb/charybdis/) +- `scylla`: the 4x6+5 [Scylla](https://github.com/Bastardkb/Scylla) +- `skeletyl`: the 3x5+3 [Skeletyl](https://github.com/Bastardkb/Skeletyl/) +- `tbkmini`: the 3x6+3 [TBK Mini](https://github.com/Bastardkb/TBK-Mini/) +- `dilemma/3x5_3`: the 3x5+3 [Dilemma](https://github.com/bastardkb/dilemma/) +- `dilemma/4x6_4`: the 4x6+4 [Dilemma Max](https://github.com/bastardkb/dilemma/) + +### `{keymap}` argument + + +`{keymap}` corresponds to the keymap that you created. + +If you followed the instructions until now, it would be `my-keymap`. + +# Contributing your own keymap + +If you are happy with your keymap and would like to share it, we would gladly review it! + +Just PR your fork to the origin BastardKB Userspace repository. + +# Flashing your keyboard + +Once you compiled your `uf2` image, you can flash your keyboard. + +For how to flash your keyboard, take a look at the [how to flash your keyboard page][flashing]. + + +--- + +[flashing]: {{site.baseurl}}/fw/flashing.html +[bkbus]: https://github.com/Bastardkb/qmk_userspace \ No newline at end of file diff --git a/fw/flashing.md b/fw/flashing.md index 17a4dec..c7ff664 100644 --- a/fw/flashing.md +++ b/fw/flashing.md @@ -34,6 +34,8 @@ To flash your new image, you will need to go through a few steps: Below is detailed the exact procedure to follow. You need to flash either the right side only, or the right and left side separately - this is also detailed below. +# Sourcing your firmware + Sourcing your firmware can be done in a couple ways: - downloading it from the [release section on github][releases] @@ -130,7 +132,7 @@ Unplug the USB connector and connect the other side, and then repeat the procedu If you use the `QK_BOOT` method, please note that your layout may now be mirrored! This is normal, ignore it and plug the USB back into the right side. ---- -[build]: https://github.com/Bastardkb/bastardkb-qmk?tab=readme-ov-file#building-from-source-advanced +[build]: {{site.baseurl}}/fw/compile-firmware.html [releases]: https://github.com/Bastardkb/bastardkb-qmk/releases [keymaps]: {{site.baseurl}}/fw/default-keymaps.html [splitkb-whentoflash]: https://docs.splitkb.com/hc/en-us/articles/360011949679-When-do-I-need-to-flash-my-microcontroller