diff --git a/.wordlist.txt b/.wordlist.txt index 248f272..3a3d006 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -60,7 +60,7 @@ TODO multimeter keypress MCU -!dilemma +Dilemma TRRS KiCad Millmax @@ -94,3 +94,44 @@ 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 + +erenatas +JLCPCB +DDCR +ROHS +olidacombe's +erenatas +Perixx +Aliexpress +Flexstrip +Microcontrollers +keebs +Hakko +GALLUNOPTIMAL +Pinecil +scotto +colemak +inorichi +petejohanson +erenata's +grassfedreeve +nicenano +SPDT +Erenata + +RMOD +noeeprom +eeprom +drgscrl +dragscroll +reflash + +hidraw +uaccess +udevadm \ No newline at end of file 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 56% rename from _includes/customize_keyboard.md rename to _includes/use_keyboard_chary.md index 2976ff7..75bad46 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,16 @@ 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). - -For how to flash your keyboard, take a look at the [how to flash your keyboard page][flashing]. +This is for advanced users. -For **advanced customization of the Charybdis and Charybdis Nano**, take a look at the [customize page][customize]. +- how to compile a custom hardware for your keyboard: [how to compile your own firmware][compile-firmware]. +- advanced customization of the Charybdis (and smaller variants): [customize your Charybdis][customize-chary]. +- advanced customization of the Dilemma (and smaller variants): [customize your Dilemma][customize-dilemma]. --- -[customize]: {{site.baseurl}}/fw/charybdis-features.html +[customize-chary]: {{site.baseurl}}/fw/charybdis-features.html +[customize-dilemma]: {{site.baseurl}}/fw/dilemma-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/assets/pics/bluetooth/battery.jpg b/assets/pics/bluetooth/battery.jpg new file mode 100644 index 0000000..6c88625 Binary files /dev/null and b/assets/pics/bluetooth/battery.jpg differ diff --git a/assets/pics/bluetooth/branch_names.png b/assets/pics/bluetooth/branch_names.png new file mode 100644 index 0000000..dfa45bb Binary files /dev/null and b/assets/pics/bluetooth/branch_names.png differ diff --git a/assets/pics/bluetooth/nano_holder.jpg b/assets/pics/bluetooth/nano_holder.jpg new file mode 100644 index 0000000..b6e1145 Binary files /dev/null and b/assets/pics/bluetooth/nano_holder.jpg differ 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/faq.md b/faq.md index d5ba780..788ff8c 100644 --- a/faq.md +++ b/faq.md @@ -66,4 +66,4 @@ You can get those from Drop, or any other website that offers them. --- [bluetooth]: {{site.baseurl}}/help/bluetooth.html -[customize]: {{site.baseurl}}/fw/customize-keyboard.html \ No newline at end of file +[customize]: {{site.baseurl}}/bg_charybdis/13customize.html diff --git a/fw/charybdis-features.md b/fw/charybdis-features.md index 453f492..8c84954 100644 --- a/fw/charybdis-features.md +++ b/fw/charybdis-features.md @@ -10,38 +10,40 @@ parent: Firmware 1. TOC {:toc} -All the features listed below are available in the Charybdis stock keymaps (built from the `via` keymap source). +# Introduction -The stock keymap aims at providing a consistent experience out of the box. Because some features can be mutually exclusives (e.g. [Auto sniping on layer](#auto-sniping-on-layer) and [Auto pointer layer](#auto-pointer-layer)), not all features are enabled by default. It may be necessary to rebuild the firmware to enable or disable some of the features listed below. +All the features listed below are available in the Charybdis `vendor` keymaps. + +The `vendor` keymap aims at providing a consistent experience out of the box. Because some features can be mutually exclusive (e.g. [Auto sniping on layer](#auto-sniping-on-layer) and [Auto pointer layer](#auto-pointer-layer)), not all features are enabled by default. It may be necessary to rebuild the firmware to enable or disable some of the features listed below. # Charybdis features ## Charybdis stock keymap -The stock keymap is built off the `via` keymap: - -- [Charybdis (4x6) `via` keymap](https://github.com/Bastardkb/bastardkb-qmk/tree/bkb-master/keyboards/bastardkb/charybdis/4x6/keymaps/via#layout) -- [Charybdis Nano (3x5) `via` keymap](https://github.com/Bastardkb/bastardkb-qmk/tree/bkb-master/keyboards/bastardkb/charybdis/3x5/keymaps/via#layout) +- the stock keymaps are built off the `vendor` keymaps, and come with VIA enabled +- you can find a visual reference of those keymaps on the [default keymaps page][keymaps] +- you can find instructions on how to compile your own firmware on the [how to compile your firmware page][compile] -A visual reference layout is provided for each of these keymap at the links above. +## Trackball related features -Those stock keymaps are compatible with [Via](https://www.caniusevia.com/) which enables on-the-fly configuration to a certain extent (i.e. keycodes, rotary encoders, RGB animations can be configured in just a few clicks from the UI). Some more advanced features, however, require manually updating the firmware. +Custom features were developed for the Charybdis, and have since been ported to QMK core. -### Trackball related features +For each feature, there are: -There's 2 features that are related to pointing devices available in the Charybdis firmware: +- custom keycodes you can implement in VIA or when [compiling your own firmware][compile] +- custom defines to change the behavior of the feature +- custom functions you can call to read or write options -- **Sniping**: temporarily reduces the sensitivity of the pointer for a more precise control. -- **Drag-scroll**: temporarily changes the behavior of the trackball into a scrolling device (in any direction). +Those are detailed below. ### DPI DPI (i.e. dots per linear inch), a.k.a. mouse sensitivity, can be controlled by the firmware. The Charybdis keymap offers 2 different DPI settings: -- **Default** DPI: the sensitivity of the pointer in normal (i.e. non-sniping) mode. -- **Sniping** DPI: the sensitivity of the pointer in sniping mode. +- **Default** DPI: the sensitivity of the pointer in normal mode. +- **Sniping** DPI: the sensitivity of the pointer in [sniping mode](#sniping) -For each mode, the firmware allows cycling through multiple pre-defined values: +For each mode, the firmware allows cycling through multiple pre-defined values. - Default mode: - Default value: 400 DPI @@ -56,72 +58,115 @@ For each mode, the firmware allows cycling through multiple pre-defined values: The firmware _cycles_ through these values, which means that, for example, incrementing the sniping DPI of `500` by 1 step will loop back to `200`. -These values can be changed by manually editing the firmware. See [Dynamic DPI scaling](#changing-dynamic-dpi-scaling-default-and-increment-values]. +You can cycle through those values by using custom keycodes (also present in the default keymap), and also [modify those values in your own firmware if needed.](#changing-dynamic-dpi-scaling-default-and-increment-values]. + +Custom keycodes: + +| Name | Description | +| ------ | ------------------------------------------------------------ | +| `DPI_MOD` | increase the sensitivity of the pointer movement by one step | +| `DPI_RMOD` | decrease the sensitivity of the pointer movement by one step | + + +Custom defines (with default values): + +``` +#define CHARYBDIS_MINIMUM_DEFAULT_DPI 400 +#define CHARYBDIS_DEFAULT_DPI_CONFIG_STEP 200 +``` + +Custom functions: + +```c +charybdis_cycle_pointer_default_dpi(bool forward) // cycle forward or backward the possible values +charybdis_cycle_pointer_default_dpi_noeeprom(bool forward) // cycle forward or backward the possible values without persisting the change to EEPROM +charybdis_get_pointer_default_dpi() // returns the current DPI value +``` -### Custom keycodes -The Charybdis firmware comes with a number of custom keycodes related to features that are specific to this keyboard. These keycodes are: +### Sniping -- Default DPI Increase (`DPI+`): increase the sensitivity of the pointer movement by one step (out of 16). -- Default DPI Decrease (`DPI-`): decrease the sensitivity of the pointer movement by one step (out of 16). -- Sniping DPI Increase (`Snp+`): increase the sensitivity of the pointer movement in sniping mode by one step (out of 4). -- Sniping DPI Decrease (`Snp-`): decrease the sensitivity of the pointer movement in sniping mode by one step (out of 4). -- Sniping Momentary (`Snp`): enable sniping mode as long as the key is pressed. -- Sniping Toggle (`SnpT`): toggle sniping mode on and off. -- Drag-scroll Momentary (`Drg`): enable drag-scroll mode as long as the key is pressed. -- Drag-scroll Toggle (`DrgT`): toggle drag-scroll mode on and off. +**Sniping mode** slows down the pointer for more precise gestures. It is useful when combined with a higher default DPI. Like the default pointer's DPI, the sniper mode DPI can be changed at runtime -### Charybdis 4x6 +Custom Keycodes: -- 3x5: heavily inspired by Miryoku - - Base layer - - Numbers layer - - Symbols layer - - Function layer - - Navigation layer - - Media layer - - Pointer layer -- 4x6: inspired from OG dactyl - - Base layer - - Lower layer - - Raise layer - - Pointer layer +| Name | Description | +| ------ | ---------------------------------------------------------------------------- | +| `S_D_MOD` | increase the sensitivity of the pointer movement in sniping mode by one step | +| `S_D_RMOD` | decrease the sensitivity of the pointer movement in sniping mode by one step | +| `SNIPING` | enable sniping mode as long as the key is pressed | +| `SNP_TOG` | toggle sniping mode on and off | -## Firmware configuration -{: .note } -This requires a firmware update. +Custom defines (with default values): -The following section explains how to update the firmware source code to fine-tune your experience. This requires a functional development environment for QMK (https://docs.qmk.fm/#/newbs) and, ideally, some prior experience in computer science and the C programming language. +``` +#define CHARYBDIS_MINIMUM_SNIPING_DPI 200 +#define CHARYBDIS_SNIPING_DPI_CONFIG_STEP 100 +``` -### Changing dynamic DPI scaling default and increment values +Custom functions: -{: .note } -This requires a firmware update. +```c +charybdis_set_pointer_sniping_enabled(bool enable) // enable/disable sniping mode +charybdis_get_pointer_sniping_enabled() // returns whether sniping mode is currently enabled +charybdis_cycle_pointer_sniping_dpi(bool forward) // cycle forward or backward the possible values +charybdis_cycle_pointer_sniping_dpi_noeeprom(bool forward) // cycle forward or backward the possible values without persisting the change to EEPROM +charybdis_get_pointer_sniping_dpi() // returns the current sniping mode DPI value +``` ### Auto sniping on layer -{: .note } -This requires a firmware update. +You can trigger sniping automatically when on a specific layer by adjusting the following in your keymap: + +``` +#define CHARYBDIS_AUTO_SNIPING_ON_LAYER LAYER_POINTER +``` ### Auto pointer layer -{: .note } -This requires a firmware update. +You can trigger the pointer layer automatically upon moving the trackball by adjusting the following in your keymap: + +``` +#define CHARYBDIS_AUTO_POINTER_LAYER_TRIGGER_ENABLE +#define CHARYBDIS_AUTO_POINTER_LAYER_TRIGGER_TIMEOUT_MS 1000 +``` + +### Drag-scroll + +**Drag-scroll** enables scrolling with the trackball. When drag-scroll is enabled, the trackball's `x` and `y` movements are converted into `h` (horizontal) and `v` (vertical) movement, effectively sending scroll instructions to the host system. + +Custom keycodes: + +| Name | Description | +| ------ | ----------------------------------------------------- | +| `DRGSCRL` | enable drag-scroll mode as long as the key is pressed | +| `DRG_TOG` | toggle drag-scroll mode on and off | + +Custom functions: + +```c +charybdis_set_pointer_dragscroll_enabled(bool enable) // enable/disable drag-scroll +charybdis_get_pointer_dragscroll_enabled() // returns whether drag-scroll mode is currently enabled +``` -### X/Y axis inversion +Custom defines: -{: .note } -This requires a firmware update. +``` +#define CHARYBDIS_DRAGSCROLL_REVERSE_X // inverts horizontal scrolling +#define CHARYBDIS_DRAGSCROLL_REVERSE_Y // inverts vertical scrolling +``` -### Extended mouse reports +## Configuration Syncing +If you want/need to enable syncing of the charybdis config, such as to read the sniping or drag scroll modes on the other half (e.g. for displaying the status via rgb matrix, or added on screens), you can enabled this. To do so, add this to your `config.h`: -{: .note } -This requires a firmware update. +```c +#define CHARYBDIS_CONFIG_SYNC +``` -By default, QMK reports the pointing device movement using numbers between `-127` and `128`. +Please note that you will need to reflash both sides when enabling this. -### Configuration sync between each half +---- -{: .note } -This requires a firmware update. +[keymaps]: {{site.baseurl}}/fw/default-keymaps.html +[compile]: {{site.baseurl}}/fw/compile-firmware.html \ 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/dilemma-features.md b/fw/dilemma-features.md new file mode 100644 index 0000000..ae77e16 --- /dev/null +++ b/fw/dilemma-features.md @@ -0,0 +1,163 @@ +--- +layout: default +title: Dilemma Features +nav_order: 2 +parent: Firmware +--- + +# Table of contents + +1. TOC +{:toc} + +# Introduction + +All the features listed below are available in the Dilemma `vendor` keymaps. + +The `vendor` keymap aims at providing a consistent experience out of the box. Because some features can be mutually exclusive (e.g. [Auto sniping on layer](#auto-sniping-on-layer) and [Auto pointer layer](#auto-pointer-layer)), not all features are enabled by default. It may be necessary to rebuild the firmware to enable or disable some of the features listed below. + +# Dilemma features + +## Dilemma stock keymap + +- the stock keymaps are built off the `vendor` keymaps, and come with VIA enabled +- you can find a visual reference of those keymaps on the [default keymaps page][keymaps] +- you can find instructions on how to compile your own firmware on the [how to compile your firmware page][compile] + +## Trackpad related features + +Custom features were developed for the Dilemma, and have since been ported to QMK core. + +For each feature, there are: + +- custom keycodes you can implement in VIA or when [compiling your own firmware][compile] +- custom defines to change the behavior of the feature +- custom functions you can call to read or write options + +Those are detailed below. + +### DPI + +DPI (i.e. dots per linear inch), a.k.a. mouse sensitivity, can be controlled by the firmware. The Dilemma keymap offers 2 different DPI settings: + +- **Default** DPI: the sensitivity of the pointer in normal mode. +- **Sniping** DPI: the sensitivity of the pointer in [sniping mode](#sniping) + +For each mode, the firmware allows cycling through multiple pre-defined values. + +- Default mode: + - Default value: 1000 DPI + - 16 steps available + - Increments of 200 DPI + - Total range from 400 to 3,400 (400 → 600 → 800 → … → 3,400) +- Sniping mode: + - Default value: 200 DPI + - 4 steps available + - Increments of 100 DPI + - Total range from 200 to 500 (200 → 300 → 400 → 500) + +The firmware _cycles_ through these values, which means that, for example, incrementing the sniping DPI of `500` by 1 step will loop back to `200`. + +You can cycle through those values by using custom keycodes (also present in the default keymap), and also [modify those values in your own firmware if needed.](#changing-dynamic-dpi-scaling-default-and-increment-values]. + +Custom keycodes: + +| Name | Description | +| ------ | ------------------------------------------------------------ | +| `DPI_MOD` | increase the sensitivity of the pointer movement by one step | +| `DPI_RMOD` | decrease the sensitivity of the pointer movement by one step | + + +Custom defines (with default values): + +``` +#define Dilemma_MINIMUM_DEFAULT_DPI 400 +#define Dilemma_DEFAULT_DPI_CONFIG_STEP 200 +``` + +Custom functions: + +```c +dilemma_cycle_pointer_default_dpi(bool forward) // cycle forward or backward the possible values +dilemma_cycle_pointer_default_dpi_noeeprom(bool forward) // cycle forward or backward the possible values without persisting the change to EEPROM +dilemma_get_pointer_default_dpi() // returns the current DPI value +``` + + +### Sniping + +**Sniping mode** slows down the pointer for more precise gestures. It is useful when combined with a higher default DPI. Like the default pointer's DPI, the sniper mode DPI can be changed at runtime + +Custom Keycodes: + +| Name | Description | +| ------ | ---------------------------------------------------------------------------- | +| `S_D_MOD` | increase the sensitivity of the pointer movement in sniping mode by one step | +| `S_D_RMOD` | decrease the sensitivity of the pointer movement in sniping mode by one step | +| `SNIPING` | enable sniping mode as long as the key is pressed | +| `SNP_TOG` | toggle sniping mode on and off | + + +Custom defines (with default values): + +``` +#define DILEMMA_MINIMUM_SNIPING_DPI 200 +#define DILEMMA_SNIPING_DPI_CONFIG_STEP 100 +``` + +Custom functions: + +```c +dilemma_set_pointer_sniping_enabled(bool enable) // enable/disable sniping mode +dilemma_get_pointer_sniping_enabled() // returns whether sniping mode is currently enabled +dilemma_cycle_pointer_sniping_dpi(bool forward) // cycle forward or backward the possible values +dilemma_cycle_pointer_sniping_dpi_noeeprom(bool forward) // cycle forward or backward the possible values without persisting the change to EEPROM +dilemma_get_pointer_sniping_dpi() // returns the current sniping mode DPI value +``` + +### Auto sniping on layer + +You can trigger sniping automatically when on a specific layer by adjusting the following in your keymap: + +``` +#define DILEMMA_AUTO_SNIPING_ON_LAYER LAYER_POINTER +``` + +### Auto pointer layer + +You can trigger the pointer layer automatically upon moving the trackpad by adjusting the following in your keymap: + +``` +#define DILEMMA_AUTO_POINTER_LAYER_TRIGGER_ENABLE +#define DILEMMA_AUTO_POINTER_LAYER_TRIGGER_TIMEOUT_MS 1000 +``` + +### Drag-scroll + +**Drag-scroll** enables scrolling with the trackpad. When drag-scroll is enabled, the trackpad's `x` and `y` movements are converted into `h` (horizontal) and `v` (vertical) movement, effectively sending scroll instructions to the host system. + +Custom keycodes: + +| Name | Description | +| ------ | ----------------------------------------------------- | +| `DRGSCRL` | enable drag-scroll mode as long as the key is pressed | +| `DRG_TOG` | toggle drag-scroll mode on and off | + +Custom functions: + +```c +dilemma_set_pointer_dragscroll_enabled(bool enable) // enable/disable drag-scroll +dilemma_get_pointer_dragscroll_enabled() // returns whether drag-scroll mode is currently enabled +``` + +Custom defines: + +``` +#define DILEMMA_DRAGSCROLL_REVERSE_X // inverts horizontal scrolling +#define DILEMMA_DRAGSCROLL_REVERSE_Y // inverts vertical scrolling +``` + +---- + +[keymaps]: {{site.baseurl}}/fw/default-keymaps.html +[compile]: {{site.baseurl}}/fw/compile-firmware.html \ 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 diff --git a/help/bluetooth.md b/help/bluetooth.md index 271e249..353a799 100644 --- a/help/bluetooth.md +++ b/help/bluetooth.md @@ -10,9 +10,14 @@ parent: Help 1. TOC {:toc} + # Introduction + +{: .warning } Wireless bluetooth capabilities are not supported officially on Bastard Keyboards. +**Follow at your own risk**, Bastard Keyboards, erenatas and 280Zo are not liable for anything that does not work. +As it's not an official supported build you will get limited help on the BK discord server. If you still wish to build one of the Charybdis or Dactyl keyboards, in this page is detailed a basic outline of the work needed. @@ -20,7 +25,15 @@ Before beginning, make sure you have some **good understanding of electronics an There is a video overview here made by EIGA: [youtube link](https://www.youtube.com/watch?v=Mks7QDxFreY). -Please note, **there is no official guide or video**, nor officially up-to-date, maintained repository. You will need to check out the links on this page and/or use the search function on discord to figure out the latest developments. + +This guide is based on the [erenatas build guide](https://github.com/erenatas/charybdis-wireless-3x6) and the [280Zo build guide](https://github.com/280Zo/charybdis-wireless-mini-3x6-build-guide). + +The purpose of it is to outline how to build a Wireless (Bluetooth) Charybdis. It is focused on how to build a 3x6 Charybdis Mini specifically. + +**Important notes:** +- As of writing this setup does not support RGB LEDs + + # Caveats @@ -40,53 +53,175 @@ Support: - When building one of the officially supported Bastard Keyboards, you can get online support through email or discord - When building this unsupported bluetooth keyboard, **you will only get very limited support** -# Custom hardware -A wireless Bastard Keyboard will use mostly the same Bill Of Materials as the wired ones. There are some custom PCBs and hardware you will need to get, you can read more below. +# Required Parts +## Flexible PCBs + +The exact PCBs you need will depend on which keyboard you are building, refer to the [official list for that](https://github.com/Bastardkb/Charybdis/blob/main/electronics_bom.md). + +Make sure to follow the recommendations for PCB thickness. + +## PMW3610 Breakout +[Link to Void's repo](https://github.com/victorlucachi/charybdis-pmw3610-breakout/tree/nicenano/production). + +For this PCB you will need to order it pre-assembled, and solder the PMW3610 sensor manually. The bill of materials and position files are in the repository. + +For the assembly, JLCPCB did not have `TCR2EF19` - but the part `TLV70018DDCR` is confirmed to work: +``` +#(Old) TCR2EF19: +73dB@(1kHz) 200mA Fixed 1.9V Positive 5.5V SOT-23-5 Linear Voltage Regulators (LDO) ROHS + + +#(New) TLV70018DDCR: +68dB@(1kHz) 200mA Fixed 1.8V Positive 5.5V SOT-23-5 Linear Voltage Regulators (LDO) ROHS +``` + +An alternative is the [BastardKB PMW3610 sensor PCB fork](https://github.com/Bastardkb/charybdis-pmw3610-breakout). + +## Nice!Nano Holder +[Link to olidacombe's repo](https://github.com/olidacombe/Elite-C-holder/tree/nicenano/adapter/production) + +This PCB Design supports having a power switch that makes use of audio jack hole. + +## 3D Prints + +Depending on which model of Charybdis you are printing, refer to the [list of required 3d parts on the original repo](https://github.com/Bastardkb/Charybdis/tree/main?tab=readme-ov-file#3d-prints---cases). + +For reverting the 3d files, you can do that directly in your slicer - or if you're using a print service, use Prusaslicer or Window's built-in 3d viewer app. + +## Electronic components + +In this section, we will go through each component that was used, and also give example links. Those are based on the original build from erenatas. + +This list is based on the electronics BOM present on the Charybdis repo as of writing, so double-check there that you're not missing anything. + +| Name | Count | Link | +| ---------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------- | +| Trackball | 1 | [Perixx Europe](https://eu.perixx.com/collections/accessory/products/18010) | +| nice!nano microcontroller* | 2 | [Splitkb.com](https://splitkb.com/collections/keyboard-parts/products/nice-nano) | +| (optional) mill max sockets | 2 | [Splitkb.com](https://splitkb.com/collections/keyboard-parts/products/mill-max-low-profile-sockets?variant=31945995845709) | +| SOD123 Diodes | 41 | [Splitkb.com](https://splitkb.com/collections/keyboard-parts/products/smd-diodes) | +| Button, 4x4x1.5 | 2 | [Aliexpress](https://www.aliexpress.com/item/4001046134819.html) | +| PMW3610 module | 1 | [Aliexpress](https://www.aliexpress.com/item/1005006208592770.html) | +| Mini Toggle Switch TS-6 SPDT | 2 | [Aliexpress](https://www.aliexpress.com/item/1005003684819561.html) | +| Batteries | 2 | [Aliexpress](https://nl.aliexpress.com/item/1005005348368664.html) | +| Ceramic Bearing Balls 2.5mm | 3 | [Aliexpress](https://www.aliexpress.com/item/1005004239319689.html) | +| Flexstrip Jumper Cables* | 2 | [Aliexpress](https://www.aliexpress.com/item/1005003498734969.html) | +| Key Switches | 41 | [Aliexpress](https://www.aliexpress.com/item/1005003761194503.html) | +| M3 5mm Brass Melt Nuts | | [Aliexpress](https://www.aliexpress.com/item/1005003582355741.html) | +| M4 5mm Brass Melt Nuts | | [Aliexpress](https://www.aliexpress.com/item/1005003582355741.html) | +| M3 8mm Torx Screws | | [Aliexpress](https://www.aliexpress.com/item/1005006115217679.html) | +| M4 8mm Torx Screws | | [Aliexpress](https://www.aliexpress.com/item/1005006115217679.html) | +| JST plug 2-pin | 2 | [Aliexpress](https://www.aliexpress.com/item/1005006115217679.html) | + +*Alternatively, you can use one of the alternatives documented on [this MCU wiki](https://github.com/joric/nrfmicro/wiki/Alternatives), like the [SuperMini NRF52840 Microcontrollers](https://www.aliexpress.us/item/3256805848952479.html?gatewayAdapt=glo2usa). + +### Notes -## Controllers +**Flexstrip Jumper Cables (Ribbon cables)**: -Like mentioned previously, at the moment only the nice!nano will work. -There are other existing BLE controllers like the open-source **mikoto** or the **SuperMini NRF52840** which could work but have not been tested yet. +You will need: -There have been a few builds that handwire a Xiao BLE, but you lose the convenience of the shield, and will need to do your own firmware. +- 72mm or more for the nice!nano holder +- 80mm or more for the thumb plate +- 100mm or more for the sensor PCB -## Sensor +If the cables snap or are hard to desolder, you can use 28AWG single-core wire instead. -If you are building a Charybdis, you will need a custom sensor PCB. If you are building a Dactyl, you can skip to the next section. +**Batteries**: -The sensor used in the regular Charybdis is a PMW3360, for a wireless build we will use instead a **PMW3610**. +One important part here is the battery. If you order a battery from Aliexpress to Europe, the order will be shipped with freight, meaning it will take ~2 months to arrive. -There is a PCB here: [PMW3610 breakout](https://github.com/Bastardkb/charybdis-pmw3610-breakout) +Due to this reason, if you reside within EU, you should try to source a battery of your choice within EU. -You will need to order the PCB factory-assembled, the release section contains the gerbers, BOM and POS files. +What needs to be considered before ordering any battery is to ensure that it is: -The PMW3610 sensor PCB connects in the same way as the regular sensor PCB. +- 3.7V +- more than 80mAh +- if you want to squeeze the battery between nice!nano and and the holder PCB, then you need to be careful of its size. At [42keebs.eu](https://42keebs.eu/shop/parts/lithium-polymer-battery/?attribute_size=301230%20(80%20mAh)), it states that you can fit `350926`, `301230`, `401030` underneath the nice!nano microcontroller +- again, if you would like to fit a battery underneath nice!nano, you may want to buy [Mill Max Low Profile Sockets with Headers](https://splitkb.com/collections/keyboard-parts/products/mill-max-low-profile-sockets?variant=47060695646555) in order to create the gap in between. Then you'll need to use a case with a raised USB-C hole (only available for certain keyboards) -## Shield PCB +For this build specifically, a JST plug was used to be able to take out the batteries without the need of desoldering. -If you are building a Dactyl, you can use the regular shield PCB. +# Assembly -If you are building a Charybdis, you will need a different shield PCB as: +Most of the steps are similar to building a Charybdis Nano. Below is an outline, with details on what needs to be done differently. -- the nice!nano does not have the bottom row of pins, which is where the SPI CS pin is routed for the trackball header -- the SPI pin positions on the elite-c map to low-frequency pins on the nice!nano +## Solder the PMW3610 to the sensor board -You can find it here: [Nice!Nano holder](https://github.com/victorlucachi/Elite-C-holder) +There is a single orientation to solder it. You can take out the sensor cap while doing any soldering to prevent touching it with the soldering iron. Also make sure to remove the kapton tape. -## Additional hardware +## Solder the nice!nano holder components -Here is a non-exhaustive list of additional required hardware (on top of a normal kit and all the custom hardware mentioned previously): -- battery and connector -- on/off switch +Solder on the power switches, and reset buttons to the left and right nano holder PCBs. Then solder on the JST female connectors. +Position this so the red wire on the male side would be the battery's positive connection, and the black wire the negative connection. +Solder the MCUs to the nano holders using the standard pin headers or the socketed pin headers, depending on what you chose to order to mount the MCU. -# Custom firmware +The MCUs should be face down (components facing towards the nano holder PCB), and the top through holes on either side of the USB connector will not have a spot on the nice!nano PCB. -At the moment, ZMK does not support input devices. +Do not set your soldering iron any higher than 300°C, as it might damage the nice!nano. + + +You can use [this video from Joe Scotto](https://youtu.be/l5kAx08Iom4) to help. + +![nice!nano installed](../assets/pics/bluetooth/nano_holder.jpg) + +Being careful to not short any connections, connect the JST battery connections, turn the switch to the on position, and confirm the MCU powers on. + +If all goes well, unplug the battery and continue the assembly. + +## Install the battery into the case + +You can either mount the battery between the MCU and holder PCB, or tape it to the case. + +![nice!nano installed](../assets/pics/bluetooth/battery.jpg) + +# Firmware + +The firmware can be downloaded from the [charybdis-wireless-mini-zmk-firmware repository](https://github.com/280Zo/charybdis-wireless-mini-zmk-firmware) by opening [the Actions tab](https://github.com/280Zo/charybdis-wireless-mini-zmk-firmware/actions), clicking on the latest successful run, then downloading the firmware file under Artifacts. + +The main branch builds firmware for the colemak dh key layout. The layouts/qwerty branch builds firmware for the qwerty layout. Make sure you pick the correct branch for your needs. + +![branch names](../assets/pics/bluetooth/branch_names.png) + +Customizing the firmware is pretty straight forward. Common changes might include swapping the central and peripheral halves, changing the keyboard name, or modifying the key bindings. See the firmware repo for details on how to make changes. + +Note that the official ZMK firmware doesn't support the PMW3610 or mouse movement keys, both of which are used in the firmware above. To get a working firmware I leveraged [the work of inorichi](https://github.com/inorichi) to get the PMW3610 driver, and [the work of petejohanson](https://github.com/petejohanson) for the driver to allow pointer movement and scrolling with keys. + +Official ZMK support for mouse keys [is being worked on](https://github.com/zmkfirmware/zmk/pull/778), and when it's merged I'll switch back to the official ZMK firmware for the builds. + +Additional links: + +- erenata's ZMK config: [https://github.com/erenatas/zmk-config-charybdis-mini-wireless](https://github.com/erenatas/zmk-config-charybdis-mini-wireless) +- EIGA's config: [[EIGA's config repo](https://github.com/erenatas/zmk-config)](https://github.com/erenatas/zmk-config) + +Erenata added scroll support via forking [@grassfedreeve](https://github.com/grassfedreeve)'s config and adapted it to 3x6 mini. + +## Flashing the firmware + +To flash each side of the keyboard, follow the steps below: + +- Unzip the firmware.zip file you downloaded +- Plug the right half info the computer through USB +- Double press the reset button you soldered onto the nano holder PCB +- The keyboard will mount as a removable storage device +- Copy the charybdis_right-nice_nano_v2-zmk.uf2 file into the NICENANO storage device. +- It will take a few seconds, then it will unmount and restart itself. +- Do the same with the left half, and copy the charybdis_left-nice_nano_v2-zmk.uf2 file. +- Both halves of the keyboard should now be flashed with the firmware. + +## Examples -There are some examples of configuration: - [https://github.com/ykz89/zmk-config](https://github.com/ykz89/zmk-config) - [https://github.com/0xcharly/zmk-config](https://github.com/0xcharly/zmk-config) - [https://github.com/bstiq/zmk-config](https://github.com/bstiq/zmk-config) - [https://github.com/grassfedreeve/Charybdis-ZMK-Config](https://github.com/grassfedreeve/Charybdis-ZMK-Config) + +# Credit + +This page is based on erenata's work and 280Zo's work. + +You can find the original repos here: +- [erenatas build guide](https://github.com/erenatas/charybdis-wireless-3x6) +- [280Zo build guide](https://github.com/280Zo/charybdis-wireless-mini-3x6-build-guide) \ No newline at end of file diff --git a/help/troubleshooting.md b/help/troubleshooting.md index d9ba031..6bfc75e 100644 --- a/help/troubleshooting.md +++ b/help/troubleshooting.md @@ -52,6 +52,36 @@ Since the LEDs are arranged in a chain, focus your efforts on the last LED that Please refer to the [diagnosing a broken trace](./diagnose_broken_trace.html#inspect-the-schematics) guide to learn how to inspect the schematics for your particular board. +# Flashing/Using Troubleshooting + +## Keyboard not recognized by VIA + +If your keyboard is not recognized by VIA, might be getting the following error: + +``` +Received invalid protocol version from device +``` + +Outlined below are some steps, in order of complexity: +- make sure you use a chromium-based browser like edge, google chrome +- flash the [latest firmware version](https://github.com/Bastardkb/bastardkb-qmk/releases/latest) + +### Custom udev rules + +If your keyboard is still not recognized and you are running a **Linux-based distribution**, you need to setup some custom udev rules to allow access to `hidraw` devices for regular users: + +First, write this text to `/etc/udev/rules.d/92-via.rules`: + +``` +KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0660", GROUP="users", TAG+="uaccess", TAG+="udev-acl" +``` + +Then, reload `udev` by running this command as `root`: + +``` +udevadm control --reload-rules && udevadm trigger +``` + # Glossary This section explains some of the terms used while troubleshooting in brief.