Bastard Keyboards firmwares

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.

Getting Started

The following section will guide you through downloading and installing the proper firmware on your Bastard Keyboard.

Releases

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

{keyboard} corresponds to the physical keyboard you are looking the firmware for. It can be one of the following:

• skeletyl: the 3x5+3 Skeletyl
• tbkmini: the 3x6+3 TBK Mini
• scylla: the 4x6+5 Scylla
• charybdis_3x5: the 3x5+3 Charybdis Nano
• charybdis_3x6: the 3x6+3 Charybdis Mini
• charybdis_4x6: the 4x6+5 Charybdis
• dilemma: the 3x5+2 Dilemma

Microcontroller/adapter

{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

{keymap} corresponds to the keymap you want to use on your keyboard. It can be one of the following:

• default
• via

Note that, in most cases, you will want to use the via keymap. The default keymap is very barebones, and is meant to be used as a template to start developing your own.

The via keymap is compatible out-of-the-box with Via.

Extension

The file extension is either .hex, .bin or .uf2, depends on the microcontroller, and is irrelevant for this guide.

Installing the keymap

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:

1. Download QMK Toolbox, and install the application
2. Download the firmware file (see Releases section)
3. Disconnect your keyboard (both host-to-keyboard USB cable, and keyboard halves TRS/TRRS cable)
4. Open QMK Toolbox, and select the firmware you've just downloaded (see the QMK Toolbox documentation for more details)
5. Plug in one half of the keyboards
6. Press the reset button on your controller
7. Click "Flash" to start the flashing process. Do not disconnect the keyboard until the process is complete.
8. Disconnect the first half, and connect the other one
9. Repeat the steps to flash the second half
10. 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.

Via

Via 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 via keymaps that can be downloaded from the Releases section.

Steps to use Via:

1. Open Via from their website, install and open the application
2. Plug your keyboard in
3. PC/Mac will detect the keyboard automatically
4. Use the Via interface to edit your keymap. Changes are saved automatically.

If you have any questions, feel free to reach out for help on the Discord.

Going further with QMK

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 (advanced)

Building from source is useful to people who want to customize their keyboard and keymaps beyond what Via 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:

1. Follow the QMK docs to setup your environment
2. Checkout this repository

To build a firmware without Via support, use the bkb-master branch:

git checkout origin/bkb-master
qmk compile -c -kb {keyboard-arg} -km default

To build a firmware with Via support, use the bkb-master branch:

git checkout origin/bkb-master
qmk compile -c -kb {keyboard-arg} -km via

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 via # On the bkb-master 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.

{keyboard-arg}

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}

{keyboard} corresponds to the physical keyboard you are building the firmware for. It can be one of the following:

• skeletyl: the 3x5+3 Skeletyl
• tbkmini: the 3x6+3 TBK Mini
• scylla: the 4x6+5 Scylla
• charybdis/3x5: the 3x5+3 Charybdis Nano
• charybdis/3x6: the 3x6+3 Charybdis Mini
• charybdis/4x6: the 4x6+5 Charybdis
• dilemma/3x5_2: the 3x5+2 Dilemma
• dilemma/3x5_3: the 3x5+3 Dilemma

Microcontroller/adapter

{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 Dilemma
• assembled: 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.