This repository contains the firmware code and releases for the Bastard Keyboards Charybdis boards, including builds for Elite-C, Blackpill, STeMCell, and RP2040-based controllers implementing the BKB standard pinout (eg. Splinky, Elite-Pi, etc…).
While this repository is used as primary source of truth for Bastard Keyboards firmwares, as it contains the latest changes and improvements, the maintainers aim at upstreaming all those changes to the official QMK repository.
The following section will guide you through downloading and installing the proper firmware on your Bastard Keyboard.
The latest releases of the firmware are available in the Releases section.
The format of the firmware file name is:
bastardkb_{keyboard}_{mcu-adapter}_{keymap}
{keyboard}
corresponds to the physical keyboard you are looking the firmware for. It can be one of the following:
skeletyl
: the 3x5+3 Skeletyltbkmini
: the 3x6+3 TBK Miniscylla
: the 4x6+5 Scyllacharybdis_3x5
: the 3x5+3 Charybdis Nanocharybdis_3x6
: the 3x6+3 Charybdis Minicharybdis_4x6
: the 4x6+5 Charybdisdilemma
: the 3x5+2 Dilemma
{mcu-adapter}
corresponds to the microcontroller (eg. Elite-C, Blackpill, …) that is installed in your keyboard, and optionally the revision of the adapter. It can be one of the following:
v1_elitec
v2_elitec
v2_splinky_v2
v2_splinky_v3
v2_stemcell
blackpill
The version of the adapter can also be checked directly on the adapter PCB.
If you have any doubts, feel free to reach out for help on the Discord.
{keymap}
corresponds to the keymap you want to use on your keyboard. It can be one of the following:
default
vial
Note that, in most cases, you will want to use the vial
keymap. The default
keymap is very barebones, and is meant to be used as a template to start developing your own.
The vial
keymap is compatible out-of-the-box with Vial.
The file extension is either .hex
, .bin
or .uf2
, depends on the microcontroller, and is irrelevant for this guide.
The process of installing the keymap on the keyboard is called "flashing". There's various ways to flash a firmware file onto a keyboard, one of which is to use QMK Toolbox.
To flash your keyboard:
- Download QMK Toolbox, and install the application
- Download the firmware file (see Releases section)
- Disconnect your keyboard (both host-to-keyboard USB cable, and keyboard halves TRS/TRRS cable)
- Open QMK Toolbox, and select the firmware you've just downloaded (see the QMK Toolbox documentation for more details)
- Plug in one half of the keyboards
- Press the
reset
button on your controller - Click "Flash" to start the flashing process. Do not disconnect the keyboard until the process is complete.
- Disconnect the first half, and connect the other one
- Repeat the steps to flash the second half
- Disconnect the keyboard
The new firmware is now installed on both halves. Close QMK Toolbox, connect the two halves with the TRS/TRRS cable, and connect one half to the PC/Mac.
If you have any questions, feel free to reach out for help on the Discord.
Vial is an open-source cross-platform (Windows, Linux and Mac) GUI and a QMK fork for configuring your keyboard in real time.
It is compatible with the vial
keymaps that can be downloaded from the Releases section.
Steps to use Vial:
- Download Vial from their website, install and open the application
- Plug your keyboard in
- PC/Mac will detect the keyboard automatically
- Use the Vial interface to edit your keymap. Changes are saved automatically.
If you have any questions, feel free to reach out for help on the Discord.
The following section is dedicated to advance users that want to customize their keyboard and keymap by building their own firmware. It contains information pertaining to the firmware development.
If you have any questions, feel free to reach out for help on the Discord.
Building from source is useful to people who want to customize their keyboard and keymaps beyond what Vial offers. This involves using a command-line interface, writing C code, and compiling this code into the final firmware file.
To build the firmware from source:
- Follow the QMK docs to setup your environment
- Checkout this repository
To build a firmware without Vial support, use the bkb-master
branch:
git checkout origin/bkb-master
qmk compile -c -kb {keyboard-arg} -km default
To build a firmware with Vial support, use the bkb-vial
branch:
git checkout origin/bkb-vial
qmk compile -c -kb {keyboard-arg} -km vial
See the {keyboard-arg}
section for possible values.
To flash the firmware from the command-line, replace compile
with flash
in the commands above:
qmk flash -c -kb bastardkb/{keyboard} -km default # On the bkb-master branch
qmk flash -c -kb bastardkb/{keyboard} -km vial # On the bkb-vial branch
After compilation, QMK waits for the keyboard to become available as a dfu device to upload firmware. Press the reset
button on the keyboard to complete the process.
The {keyboard-arg}
depends on the keyboard you are building the firmware for (eg. Skeletyl, TBK-Mini, etc…) and the controller you are targetting (eg. Elite-C, Blackpill, etc…).
The {keyboard-arg}
format is:
bastardkb/{keyboard}/{mcu-adapter}
{keyboard}
corresponds to the physical keyboard you are building the firmware for. It can be one of the following:
skeletyl
: the 3x5+3 Skeletyltbkmini
: the 3x6+3 TBK Miniscylla
: the 4x6+5 Scyllacharybdis/3x5
: the 3x5+3 Charybdis Nanocharybdis/3x6
: the 3x6+3 Charybdis Minicharybdis/4x6
: the 4x6+5 Charybdisdilemma/3x5_2
: the 3x5+2 Dilemmadilemma/3x5_3
: the 3x5+3 Dilemma
{mcu-adapter}
corresponds to the microcontroller (eg. Elite-C, Blackpill, …) that is installed in your keyboard, and optionally the revision of the adapter.
For the Dilemma 3x5_2, it can be one of the following:
splinky
: for the DIY version of the Dilemmaassembled
: for the pre-assembled version of the Dilemma
For all other boards, it can be one of the following:
v1/elitec
v2/elitec
v2/splinky_2
v2/splinky_3
v2/stemcell
blackpill
The version of the adapter can also be checked directly on the adapter PCB.
If you have any doubts, feel free to reach out for help on the Discord.
The changes on bkb-master
are meant to be upstreamed and merged into QMK's master
branch.
Vial, however, does not work out-of-the-box when using QMK's master
branch, and relies instead of some changes that have not been upstreamed yet. Because of this, this repository trackes Vial's master
branch (see below, qmk-vial-head
) and cherry-picks Bastard Keyboards related changes on top of it.
Note that Vial's master
usually lags a bit behind QMK's master
, so the latest changes to QMK might not be available when working on bkb-vial
.
Branch following QMK's master |
Parent | Description |
---|---|---|
bkb-master |
qmk/qmk_firmware/master |
Contains the latest sources for BastardKB's firmware |
Branch following Vial's master |
Parent | Description |
---|---|---|
bkb-vial |
qmk-vial-head |
Vial support on top of the changes in bkb-master |