Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@0xcharly
0xcharly committed Aug 29, 2022
1 parent 3a0f567 commit 7cf965b
Showing 1 changed file with 69 additions and 33 deletions.
102 changes: 69 additions & 33 deletions readme.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Bastard Keyboards firmwares

This repository contains the firmware code and releases for the Bastard Keyboards Charybdis boards, including builds for Elite-C and Blackpill.
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…).

This repository is used as primary source of truth for Bastard Keyboards firmwares.
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](https://github.com/qmk/qmk_firmware).

# Getting Started

Expand All @@ -22,18 +22,22 @@ 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 [Skeletyl](https://bastardkb.com/skeletyl/)
- `tbkmini`: the 3x6 [TBK Mini](https://bastardkb.com/tbk-mini/)
- `scylla`: the 4x6 [Scylla](https://bastardkb.com/scylla/)
- `charybdis_3x5`: the 3x5 [Charybdis Nano](https://bastardkb.com/charybdis-nano/)
- `charybdis_4x6`: the 4x6 [Charybdis](https://bastardkb.com/charybdis/)
- `skeletyl`: the 3x5+3 [Skeletyl](https://bastardkb.com/skeletyl/)
- `tbkmini`: the 3x6+3 [TBK Mini](https://bastardkb.com/tbk-mini/)
- `scylla`: the 4x6+5 [Scylla](https://bastardkb.com/scylla/)
- `charybdis_3x5`: the 3x5+3 [Charybdis Nano](https://bastardkb.com/charybdis-nano/)
- `charybdis_3x6`: the 3x6+3 Charybdis Mini
- `charybdis_4x6`: the 4x6+5 [Charybdis](https://bastardkb.com/charybdis/)
- `dilemma`: the 3x5+2 [Dilemma](https://bastardkb.com/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:

- `1.x_elitec`
- `2.x_elitec`
- `v1_elitec`
- `v2_elitec`
- `v2_splinky`
- `v2_stemcell`
- `blackpill`

The version of the adapter can also be checked directly on the adapter PCB.
Expand All @@ -53,7 +57,7 @@ The `vial` keymap is compatible out-of-the-box with [Vial](https://get.vial.toda

### Extension

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

## Installing the keymap

Expand Down Expand Up @@ -112,56 +116,88 @@ To build a firmware **without** Vial support, use the `bkb-master` branch:

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

To build a firmware **with** Vial support, use the `bkb-vial` branch:

```shell
git checkout origin/bkb-vial
qmk compile -j0 -c -kb bastardkb/{keyboard} -km vial
qmk compile -c -kb {keyboard-arg} -km vial
```

See [the `{keyboard}` section](#keyboard) for possible values.
See [the `{keyboard-arg}` section](#keyboard-arg) for possible values.

To flash the firmware from the command-line, replace `compile` with `flash` in the commands above:

```shell
qmk flash -j0 -c -kb bastardkb/{keyboard} -km default
qmk flash -c -kb bastardkb/{keyboard} -km default # On the bkb-master branch
```

```shell
qmk flash -j0 -c -kb bastardkb/{keyboard} -km vial
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.

### Why `bkb-master` and `bkb-vial`
### `{keyboard-arg}`

The changes on `bkb-master` are meant to be upstreamed and merged into QMK's `master` branch.
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…).

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.
The `{keyboard-arg}` format is:

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`.
```
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](https://bastardkb.com/skeletyl/)
- `tbkmini`: the 3x6+3 [TBK Mini](https://bastardkb.com/tbk-mini/)
- `scylla`: the 4x6+5 [Scylla](https://bastardkb.com/scylla/)
- `charybdis_3x5`: the 3x5+3 [Charybdis Nano](https://bastardkb.com/charybdis-nano/)
- `charybdis_3x6`: the 3x6+3 Charybdis Mini
- `charybdis_4x6`: the 4x6+5 [Charybdis](https://bastardkb.com/charybdis/)
- `dilemma`: the 3x5+2 [Dilemma](https://bastardkb.com/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.

## Pending PRs
For **the Dilemma**, it can be one of the following:

No PRs opened against upstream QMK at the moments.
- `splinky`: for the [DIY version of the Dilemma](https://github.com/bastardkb/dilemma)
- `assembled`: for the [pre-assembled version of the Dilemma](https://bastardkb.com/dilemma/)

## Branches
For **all other boards**, it can be one of the following:

### Tracking branches
- `v1_elitec`
- `v2_elitec`
- `v2_splinky`
- `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](https://bastardkb.com/discord).

### Why `bkb-master` and `bkb-vial`

The changes on `bkb-master` are meant to be upstreamed and merged into QMK's `master` branch.

| Branch | Tracking |
| --------------- | -------------------------------- |
| `qmk-vial-head` | Tracking `vial-kb/vial-qmk/vial` |
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`.

### Feature branches
## Feature branches

| Branch following QMK's `master` | Parent | Description |
| ------------------------------- | --------------------------------------- | ---------------------------------------------------- |
| `bkb-master` | `qmk/qmk_firmware/master` (QMK v0.16.0) | Contains the latest sources for BastardKB's firmware |
| Branch following QMK's `master` | Parent | Description |
| ------------------------------- | --------------------------- ---------------------------------------------------- |
| `bkb-master` | `qmk/qmk_firmware/master` | Contains the latest sources for BastardKB's firmware |
| `bkb-develop` | `qmk/qmk_firmware/develop` | Contains the latest sources for BastardKB's firmware |

| Branch following Vial's `master` | Parent | Description |
| -------------------------------- | ----------------------------- | -------------------------------------------------- |
| `bkb-vial` | `qmk-vial-head` (QMK v0.15.6) | Vial support on top of the changes in `bkb-master` |
| Branch following Vial's `master` | Parent | Description |
| -------------------------------- | ----------------| -------------------------------------------------- |
| `bkb-vial` | `qmk-vial-head` | Vial support on top of the changes in `bkb-master` |

0 comments on commit 7cf965b

Please sign in to comment.