From 7cf965b1782eaaae45a0af25b26d265163676c8f Mon Sep 17 00:00:00 2001 From: Charly Date: Mon, 29 Aug 2022 14:27:26 +0900 Subject: [PATCH] Update README --- readme.md | 102 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 69 insertions(+), 33 deletions(-) diff --git a/readme.md b/readme.md index f0c94f7217a5..9ec05494c16f 100644 --- a/readme.md +++ b/readme.md @@ -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 @@ -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. @@ -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 @@ -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` |