From 7e6b55a821a7f4d4834ae77a64b4ccb675eeb02f Mon Sep 17 00:00:00 2001 From: Quentin Date: Sun, 18 Aug 2024 18:30:01 +0200 Subject: [PATCH 01/11] Update charybdis-features.md --- fw/charybdis-features.md | 163 +++++++++++++++++++++++++-------------- 1 file changed, 104 insertions(+), 59 deletions(-) diff --git a/fw/charybdis-features.md b/fw/charybdis-features.md index 453f492..5dc0175 100644 --- a/fw/charybdis-features.md +++ b/fw/charybdis-features.md @@ -18,30 +18,30 @@ The stock keymap aims at providing a consistent experience out of the box. Becau ## Charybdis stock keymap -The stock keymap is built off the `via` 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] -- [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) +## Trackball related features -A visual reference layout is provided for each of these keymap at the links above. +Custom features were developed for the Charybdis, and have since been ported to QMK core. -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. +For each feature, there are: -### Trackball related features +- custom keycodes you can implement in VIA or when [compiling your own firmware][compile] +- custom defines to change the behaviour of the feature +- custom functions you can call to read or write options -There's 2 features that are related to pointing devices available in the Charybdis firmware: - -- **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 +56,117 @@ 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 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**: temporarily reduces the sensitivity of the pointer for a more precise control. -### Charybdis 4x6 +**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 -- 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 +Custom Keycodes: -## Firmware configuration +| 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 | -{: .note } -This requires a firmware update. -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. +Custom defines (with default values): -### Changing dynamic DPI scaling default and increment values +```c +#define CHARYBDIS_MINIMUM_SNIPING_DPI 200 +#define CHARYBDIS_SNIPING_DPI_CONFIG_STEP 100 +``` -{: .note } -This requires a firmware update. +Custom functions: + +```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: + +```c +#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: + +```c +#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 +``` + +Custom defines: + +```c +#define CHARYBDIS_DRAGSCROLL_REVERSE_X` // inverts horizontal scrolling +#define CHARYBDIS_DRAGSCROLL_REVERSE_Y` // inverts vertical scrolling +``` + +### Large mouse reports -### X/Y axis inversion +By default, the `x` and `y` motion for the pointing device/mouse reports is `-127` to `127`. If you hit the limit for that with the sensors, you can enable support for `-32767` to `32767` by adding this to your `config.h`: -{: .note } -This requires a firmware update. +```c +#define MOUSE_EXTENDED_REPORT +``` -### 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 (such as for displaying the status via rgb matrix, or added on screens, or what not), 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 From ebc02dd3970d9852417b975aee0c7cdc5929dd53 Mon Sep 17 00:00:00 2001 From: Quentin Date: Sun, 18 Aug 2024 18:37:02 +0200 Subject: [PATCH 02/11] Update charybdis-features.md --- fw/charybdis-features.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/fw/charybdis-features.md b/fw/charybdis-features.md index 5dc0175..de0f7ee 100644 --- a/fw/charybdis-features.md +++ b/fw/charybdis-features.md @@ -76,8 +76,6 @@ charybdis_get_pointer_default_dpi() // returns the current DPI value ### Sniping -**Sniping**: temporarily reduces the sensitivity of the pointer for a more precise control. - **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: From 3c9e529e01a2177b09c77926e14a0861cd40e2c8 Mon Sep 17 00:00:00 2001 From: Quentin Date: Wed, 21 Aug 2024 10:32:36 +0200 Subject: [PATCH 03/11] typos --- .wordlist.txt | 9 ++++++++- fw/charybdis-features.md | 2 +- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/.wordlist.txt b/.wordlist.txt index b18118e..4e01460 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -123,4 +123,11 @@ erenata's grassfedreeve nicenano SPDT -Erenata \ No newline at end of file +Erenata + +RMOD +noeeprom +eeprom +drgscrl +dragscroll +reflash \ No newline at end of file diff --git a/fw/charybdis-features.md b/fw/charybdis-features.md index de0f7ee..9300f77 100644 --- a/fw/charybdis-features.md +++ b/fw/charybdis-features.md @@ -29,7 +29,7 @@ Custom features were developed for the Charybdis, and have since been ported to For each feature, there are: - custom keycodes you can implement in VIA or when [compiling your own firmware][compile] -- custom defines to change the behaviour of the feature +- custom defines to change the behavior of the feature - custom functions you can call to read or write options Those are detailed below. From 3461d032bf271756e04c1169f515989fa51776e7 Mon Sep 17 00:00:00 2001 From: Quentin Date: Wed, 21 Aug 2024 10:34:36 +0200 Subject: [PATCH 04/11] missing title --- fw/charybdis-features.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/fw/charybdis-features.md b/fw/charybdis-features.md index 9300f77..eb90506 100644 --- a/fw/charybdis-features.md +++ b/fw/charybdis-features.md @@ -10,6 +10,8 @@ parent: Firmware 1. TOC {:toc} +# Introduction + All the features listed below are available in the Charybdis stock keymaps (built from the `via` keymap source). 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. From b5ca1963a31902f3a5380fbeb1c59012b21c4539 Mon Sep 17 00:00:00 2001 From: Quentin Date: Wed, 21 Aug 2024 10:35:50 +0200 Subject: [PATCH 05/11] via to vendor --- fw/charybdis-features.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fw/charybdis-features.md b/fw/charybdis-features.md index eb90506..2c1bc87 100644 --- a/fw/charybdis-features.md +++ b/fw/charybdis-features.md @@ -12,9 +12,9 @@ parent: Firmware # Introduction -All the features listed below are available in the Charybdis stock keymaps (built from the `via` keymap source). +All the features listed below are available in the Charybdis `vendor` keymaps. -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. +The `vendor` 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. # Charybdis features From ae8d5ff154c8b33ff6265444666984ca973196f2 Mon Sep 17 00:00:00 2001 From: Quentin Date: Wed, 21 Aug 2024 11:00:39 +0200 Subject: [PATCH 06/11] Update fw/charybdis-features.md Co-authored-by: burkfers --- fw/charybdis-features.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fw/charybdis-features.md b/fw/charybdis-features.md index 2c1bc87..ab4f221 100644 --- a/fw/charybdis-features.md +++ b/fw/charybdis-features.md @@ -14,7 +14,7 @@ parent: Firmware 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 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. +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 From 74f380e645108a35a91f5e3a46b1e6829f147e34 Mon Sep 17 00:00:00 2001 From: Quentin Date: Wed, 21 Aug 2024 11:03:15 +0200 Subject: [PATCH 07/11] Update charybdis-features.md --- fw/charybdis-features.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/fw/charybdis-features.md b/fw/charybdis-features.md index 2c1bc87..938e126 100644 --- a/fw/charybdis-features.md +++ b/fw/charybdis-features.md @@ -67,6 +67,14 @@ Custom keycodes: | `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): + +```c +#define CHARYBDIS_MINIMUM_DEFAULT_DPI 400 +#define CHARYBDIS_DEFAULT_DPI_CONFIG_STEP 200 +``` + Custom functions: ```c From e2eeb77b12bc5a2fe14b08f558f5f3cc88ef4a4a Mon Sep 17 00:00:00 2001 From: Quentin Date: Wed, 21 Aug 2024 11:05:00 +0200 Subject: [PATCH 08/11] more readable defines --- fw/charybdis-features.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/fw/charybdis-features.md b/fw/charybdis-features.md index 938e126..4e3f5f6 100644 --- a/fw/charybdis-features.md +++ b/fw/charybdis-features.md @@ -70,7 +70,7 @@ Custom keycodes: Custom defines (with default values): -```c +``` #define CHARYBDIS_MINIMUM_DEFAULT_DPI 400 #define CHARYBDIS_DEFAULT_DPI_CONFIG_STEP 200 ``` @@ -100,7 +100,7 @@ Custom Keycodes: Custom defines (with default values): -```c +``` #define CHARYBDIS_MINIMUM_SNIPING_DPI 200 #define CHARYBDIS_SNIPING_DPI_CONFIG_STEP 100 ``` @@ -119,7 +119,7 @@ charybdis_get_pointer_sniping_dpi() // returns the current sniping mode DPI valu You can trigger sniping automatically when on a specific layer by adjusting the following in your keymap: -```c +``` #define CHARYBDIS_AUTO_SNIPING_ON_LAYER LAYER_POINTER ``` @@ -127,7 +127,7 @@ You can trigger sniping automatically when on a specific layer by adjusting the You can trigger the pointer layer automatically upon moving the trackball by adjusting the following in your keymap: -```c +``` #define CHARYBDIS_AUTO_POINTER_LAYER_TRIGGER_ENABLE #define CHARYBDIS_AUTO_POINTER_LAYER_TRIGGER_TIMEOUT_MS 1000 ``` @@ -152,7 +152,7 @@ charybdis_get_pointer_dragscroll_enabled() // returns whether drag-scroll mode i Custom defines: -```c +``` #define CHARYBDIS_DRAGSCROLL_REVERSE_X` // inverts horizontal scrolling #define CHARYBDIS_DRAGSCROLL_REVERSE_Y` // inverts vertical scrolling ``` From fab1efae8eb75dbc43f11ec6a081a62b48ce1031 Mon Sep 17 00:00:00 2001 From: Quentin Date: Wed, 21 Aug 2024 11:06:49 +0200 Subject: [PATCH 09/11] Update fw/charybdis-features.md Co-authored-by: burkfers --- fw/charybdis-features.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fw/charybdis-features.md b/fw/charybdis-features.md index 2e13c8f..72e7213 100644 --- a/fw/charybdis-features.md +++ b/fw/charybdis-features.md @@ -153,8 +153,8 @@ charybdis_get_pointer_dragscroll_enabled() // returns whether drag-scroll mode i Custom defines: ``` -#define CHARYBDIS_DRAGSCROLL_REVERSE_X` // inverts horizontal scrolling -#define CHARYBDIS_DRAGSCROLL_REVERSE_Y` // inverts vertical scrolling +#define CHARYBDIS_DRAGSCROLL_REVERSE_X // inverts horizontal scrolling +#define CHARYBDIS_DRAGSCROLL_REVERSE_Y // inverts vertical scrolling ``` ### Large mouse reports From 241def9d2e6c7ad9c62328d44c773df9332b1fb0 Mon Sep 17 00:00:00 2001 From: Quentin Date: Wed, 21 Aug 2024 11:07:02 +0200 Subject: [PATCH 10/11] Update fw/charybdis-features.md Co-authored-by: burkfers --- fw/charybdis-features.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fw/charybdis-features.md b/fw/charybdis-features.md index 72e7213..36de458 100644 --- a/fw/charybdis-features.md +++ b/fw/charybdis-features.md @@ -166,7 +166,7 @@ By default, the `x` and `y` motion for the pointing device/mouse reports is `-12 ``` ## 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 (such as for displaying the status via rgb matrix, or added on screens, or what not), you can enabled this. To do so, add this to your `config.h`: +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`: ```c #define CHARYBDIS_CONFIG_SYNC From f5855a1a72602101f89ce9bb58813ce626cf733b Mon Sep 17 00:00:00 2001 From: Quentin Date: Wed, 21 Aug 2024 11:10:04 +0200 Subject: [PATCH 11/11] Update charybdis-features.md --- fw/charybdis-features.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/fw/charybdis-features.md b/fw/charybdis-features.md index 2e13c8f..9a91dcb 100644 --- a/fw/charybdis-features.md +++ b/fw/charybdis-features.md @@ -157,14 +157,6 @@ Custom defines: #define CHARYBDIS_DRAGSCROLL_REVERSE_Y` // inverts vertical scrolling ``` -### Large mouse reports - -By default, the `x` and `y` motion for the pointing device/mouse reports is `-127` to `127`. If you hit the limit for that with the sensors, you can enable support for `-32767` to `32767` by adding this to your `config.h`: - -```c -#define MOUSE_EXTENDED_REPORT -``` - ## 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 (such as for displaying the status via rgb matrix, or added on screens, or what not), you can enabled this. To do so, add this to your `config.h`: