From 22213aae7649fc8eed90829829e80c3ed9f0bf38 Mon Sep 17 00:00:00 2001 From: Christoph Cullmann Date: Mon, 17 Oct 2022 23:29:33 +0200 Subject: [PATCH] add achordion to make home row keys really usable --- achordion.c | 225 ++++++++++++++++++++++++++++++++++++++++++++++++++++ achordion.h | 171 +++++++++++++++++++++++++++++++++++++++ config.h | 8 ++ keymap.c | 36 ++++++++- readme.md | 8 ++ rules.mk | 3 + 6 files changed, 450 insertions(+), 1 deletion(-) create mode 100644 achordion.c create mode 100644 achordion.h diff --git a/achordion.c b/achordion.c new file mode 100644 index 0000000..9c139f2 --- /dev/null +++ b/achordion.c @@ -0,0 +1,225 @@ +// Copyright 2022 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +/** + * @file achordion.c + * @brief Achordion implementation + * + * For full documentation, see + * + */ + +#include "achordion.h" + +// Copy of the `record` and `keycode` args for the current active tap-hold key. +static keyrecord_t tap_hold_record; +static uint16_t tap_hold_keycode = KC_NO; +// Timeout timer. When it expires, the key is considered held. +static uint16_t hold_timer = 0; +// Eagerly applied mods, if any. +static uint8_t eager_mods = 0; + +// Achordion's current state. +enum { + // A tap-hold key is pressed, but hasn't yet been settled as tapped or held. + STATE_UNSETTLED, + // Achordion is inactive. + STATE_RELEASED, + // Active tap-hold key has been settled as tapped. + STATE_TAPPING, + // Active tap-hold key has been settled as held. + STATE_HOLDING, + // This state is set while calling `process_record()`, which will recursively + // call `process_achordion()`. This state is checked so that we don't process + // events generated by Achordion and potentially create an infinite loop. + STATE_RECURSING, +}; +static uint8_t achordion_state = STATE_RELEASED; + +// Calls `process_record()` with state set to RECURSING. +static void recursively_process_record(keyrecord_t* record, uint8_t state) { + achordion_state = STATE_RECURSING; + process_record(record); + achordion_state = state; +} + +// Clears eagerly-applied mods. +static void clear_eager_mods(void) { + unregister_mods(eager_mods); + eager_mods = 0; +} + +// Sends hold press event and settles the active tap-hold key as held. +static void settle_as_hold(void) { + clear_eager_mods(); + // Create hold press event. + recursively_process_record(&tap_hold_record, STATE_HOLDING); +} + +bool process_achordion(uint16_t keycode, keyrecord_t* record) { + // Don't process events that Achordion generated. + if (achordion_state == STATE_RECURSING) { + return true; + } + + // Determine whether the current event is for a mod-tap or layer-tap key. + const bool is_mt = QK_MOD_TAP <= keycode && keycode <= QK_MOD_TAP_MAX; + const bool is_tap_hold = + is_mt || (QK_LAYER_TAP <= keycode && keycode <= QK_LAYER_TAP_MAX); + // Check key position to avoid acting on combos. + const bool is_physical_pos = + (record->event.key.row < 254 && record->event.key.col < 254); + + if (achordion_state == STATE_RELEASED) { + if (is_tap_hold && record->tap.count == 0 && record->event.pressed && + is_physical_pos) { + // A tap-hold key is pressed and considered by QMK as "held". + const uint16_t timeout = achordion_timeout(keycode); + if (timeout > 0) { + achordion_state = STATE_UNSETTLED; + // Save info about this key. + tap_hold_keycode = keycode; + tap_hold_record = *record; + hold_timer = record->event.time + timeout; + + if (is_mt) { // Apply mods immediately if they are "eager." + uint8_t mod = (tap_hold_keycode >> 8) & 0x1f; + if (achordion_eager_mod(mod)) { + eager_mods = ((mod & 0x10) == 0) ? mod : (mod << 4); + register_mods(eager_mods); + } + } + + dprintf("Achordion: Key 0x%04X pressed.%s\n", keycode, + eager_mods ? " Set eager mods." : ""); + return false; // Skip default handling. + } + } + + return true; // Otherwise, continue with default handling. + } + + if (keycode == tap_hold_keycode && !record->event.pressed) { + // The active tap-hold key is being released. + if (achordion_state == STATE_HOLDING) { + dprintln("Achordion: Key released. Plumbing hold release."); + tap_hold_record.event.pressed = false; + // Plumb hold release event. + recursively_process_record(&tap_hold_record, STATE_RELEASED); + } else { + dprintf("Achordion: Key released.%s\n", + eager_mods ? " Clearing eager mods." : ""); + if (is_mt) { + clear_eager_mods(); + } + } + + achordion_state = STATE_RELEASED; + return false; + } + + if (achordion_state == STATE_UNSETTLED && record->event.pressed) { + // Press event occurred on a key other than the active tap-hold key. + + // If the other key is *also* a tap-hold key and considered by QMK to be + // held, then we settle the active key as held. This way, things like + // chording multiple home row modifiers will work, but let's our logic + // consider simply a single tap-hold key as "active" at a time. + // + // Otherwise, we call `achordion_chord()` to determine whether to settle the + // tap-hold key as tapped vs. held. We implement the tap or hold by plumbing + // events back into the handling pipeline so that QMK features and other + // user code can see them. This is done by calling `process_record()`, which + // in turn calls most handlers including `process_record_user()`. + if (!is_physical_pos || (is_tap_hold && record->tap.count == 0) || + achordion_chord(tap_hold_keycode, &tap_hold_record, keycode, record)) { + dprintln("Achordion: Plumbing hold press."); + settle_as_hold(); + } else { + clear_eager_mods(); // Clear in case eager mods were set. + + dprintln("Achordion: Plumbing tap press."); + tap_hold_record.tap.count = 1; // Revise event as a tap. + tap_hold_record.tap.interrupted = true; + // Plumb tap press event. + recursively_process_record(&tap_hold_record, STATE_TAPPING); + +#if TAP_CODE_DELAY > 0 + wait_ms(TAP_CODE_DELAY); +#endif // TAP_CODE_DELAY > 0 + + dprintln("Achordion: Plumbing tap release."); + tap_hold_record.event.pressed = false; + // Plumb tap release event. + recursively_process_record(&tap_hold_record, STATE_TAPPING); + } + + recursively_process_record(record, achordion_state); // Re-process event. + return false; // Block the original event. + } + + return true; +} + +void achordion_task(void) { + if (achordion_state == STATE_UNSETTLED && + timer_expired(timer_read(), hold_timer)) { + dprintln("Achordion: Timeout. Plumbing hold press."); + settle_as_hold(); // Timeout expired, settle the key as held. + } +} + +// Returns true if `pos` on the left hand of the keyboard, false if right. +static bool on_left_hand(keypos_t pos) { +#ifdef SPLIT_KEYBOARD + return pos.row < MATRIX_ROWS / 2; +#else + return (MATRIX_COLS > MATRIX_ROWS) ? pos.col < MATRIX_COLS / 2 + : pos.row < MATRIX_ROWS / 2; +#endif +} + +bool achordion_opposite_hands(const keyrecord_t* tap_hold_record, + const keyrecord_t* other_record) { + return on_left_hand(tap_hold_record->event.key) != + on_left_hand(other_record->event.key); +} + +// By default, use the BILATERAL_COMBINATIONS rule to consider the tap-hold key +// "held" only when it and the other key are on opposite hands. +__attribute__((weak)) bool achordion_chord(uint16_t tap_hold_keycode, + keyrecord_t* tap_hold_record, + uint16_t other_keycode, + keyrecord_t* other_record) { + return achordion_opposite_hands(tap_hold_record, other_record); +} + +// By default, the timeout is 1000 ms for all keys. +__attribute__((weak)) uint16_t achordion_timeout(uint16_t tap_hold_keycode) { + return 1000; +} + +// By default, hold Shift and Ctrl mods eagerly. +__attribute__((weak)) bool achordion_eager_mod(uint8_t mod) { + switch (mod) { + case MOD_LSFT: + case MOD_RSFT: + case MOD_LCTL: + case MOD_RCTL: + return true; + + default: + return false; + } +} diff --git a/achordion.h b/achordion.h new file mode 100644 index 0000000..2968bdc --- /dev/null +++ b/achordion.h @@ -0,0 +1,171 @@ +// Copyright 2022 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +/** + * @file achordion.h + * @brief Achordion: Customizing the tap-hold decision. + * + * Overview + * -------- + * + * This library customizes when tap-hold keys are considered held vs. tapped + * based on the next pressed key, like Manna Harbour's Bilateral Combinations or + * ZMK's positional hold. The library works on top of QMK's existing tap-hold + * implementation. You define mod-tap and layer-tap keys as usual and use + * Achordion to fine-tune the behavior. + * + * When QMK settles a tap-hold key as held, Achordion intercepts the event. + * Achordion then revises the event as a tap or passes it along as a hold: + * + * * Chord condition: On the next key press, a customizable `achordion_chord()` + * function is called, which takes the tap-hold key and the next key pressed + * as args. When the function returns true, the tap-hold key is settled as + * held, and otherwise as tapped. + * + * * Timeout: If no other key press occurs within a timeout, the tap-hold key + * is settled as held. This is customizable with `achordion_timeout()`. + * + * Achordion only changes the behavior when QMK considered the key held. It + * changes some would-be holds to taps, but no taps to holds. + * + * @note Some QMK features handle events before the point where Achordion can + * intercept them, particularly: Combos, Key Lock, and Dynamic Macros. It's + * still possible to use these features and Achordion in your keymap, but beware + * they might behave poorly when used simultaneously with tap-hold keys. + * + * + * For full documentation, see + * + */ + +#pragma once + +#include "quantum.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * Handler function for Achordion. + * + * Call this function from `process_record_user()` as + * + * #include "features/achordion.h" + * + * bool process_record_user(uint16_t keycode, keyrecord_t* record) { + * if (!process_achordion(keycode, record)) { return false; } + * // Your macros... + * return true; + * } + */ +bool process_achordion(uint16_t keycode, keyrecord_t* record); + +/** + * Matrix task function for Achordion. + * + * Call this function from `matrix_scan_user()` as + * + * void matrix_scan_user(void) { + * achordion_task(); + * } + */ +void achordion_task(void); + +/** + * Optional callback to customize which key chords are considered "held". + * + * In your keymap.c, define the callback + * + * bool achordion_chord(uint16_t tap_hold_keycode, + * keyrecord_t* tap_hold_record, + * uint16_t other_keycode, + * keyrecord_t* other_record) { + * // Conditions... + * } + * + * This callback is called if while `tap_hold_keycode` is pressed, + * `other_keycode` is pressed. Return true if the tap-hold key should be + * considered held, or false to consider it tapped. + * + * @param tap_hold_keycode Keycode of the tap-hold key. + * @param tap_hold_record keyrecord_t from the tap-hold press event. + * @param other_keycode Keycode of the other key. + * @param other_record keyrecord_t from the other key's press event. + * @return True if the tap-hold key should be considered held. + */ +bool achordion_chord(uint16_t tap_hold_keycode, keyrecord_t* tap_hold_record, + uint16_t other_keycode, keyrecord_t* other_record); + +/** + * Optional callback to define a timeout duration per keycode. + * + * In your keymap.c, define the callback + * + * uint16_t achordion_timeout(uint16_t tap_hold_keycode) { + * // ... + * } + * + * The callback determines Achordion's timeout duration for `tap_hold_keycode` + * in units of milliseconds. The timeout be in the range 0 to 32767 ms (upper + * bound is due to 16-bit timer limitations). Use a timeout of 0 to bypass + * Achordion. + * + * @param tap_hold_keycode Keycode of the tap-hold key. + * @return Timeout duration in milliseconds in the range 0 to 32767. + */ +uint16_t achordion_timeout(uint16_t tap_hold_keycode); + +/** + * Optional callback defining which mods are "eagerly" applied. + * + * This callback defines which mods are "eagerly" applied while a mod-tap + * key is still being settled. This is helpful to reduce delay particularly when + * using mod-tap keys with an external mouse. + * + * Define this callback in your keymap.c. The default callback is + * + * bool achordion_eager_mod(uint8_t mod) { + * switch (mod) { + * case MOD_LSFT: + * case MOD_RSFT: + * case MOD_LCTL: + * case MOD_RCTL: + * return true; // Eagerly apply Shift and Ctrl mods. + * + * default: + * return false; + * } + * } + * + * @note `mod` should be compared with `MOD_` prefixed codes, not `KC_` codes. + * + * @param mod Modifier `MOD_` code. + * @return True if the modifier should be eagerly applied. + */ +bool achordion_eager_mod(uint8_t mod); + +/** + * Returns true if the args come from keys on opposite hands. + * + * @param tap_hold_record keyrecord_t from the tap-hold key's event. + * @param other_record keyrecord_t from the other key's event. + * @return True if the keys are on opposite hands. + */ +bool achordion_opposite_hands(const keyrecord_t* tap_hold_record, + const keyrecord_t* other_record); + +#ifdef __cplusplus +} +#endif diff --git a/config.h b/config.h index 506068b..fd4bdc0 100644 --- a/config.h +++ b/config.h @@ -19,6 +19,14 @@ // include miryoku defaults #include +// +// improve home row modifiers via achoridion +// + +// try to be more permissive with holds, allows to trigger modifiers faster +// achordion will avoid the worst +#define PERMISSIVE_HOLD + // // audio configuration // diff --git a/keymap.c b/keymap.c index 4b9fc57..5e1b7b3 100644 --- a/keymap.c +++ b/keymap.c @@ -63,6 +63,40 @@ KC_NO, KC_NO, K32, K33, K34, KC_NO, KC_NO, K35, K36, K37, KC_NO, KC_ // include miryoku defaults #include +// +// improve home row modifiers via achordion +// + +#include "achordion.h" + +bool process_record_user(uint16_t keycode, keyrecord_t* record) +{ + if (!process_achordion(keycode, record)) { + return false; + } + + return true; +} + +void matrix_scan_user(void) +{ + achordion_task(); +} + +bool achordion_chord(uint16_t tap_hold_keycode, + keyrecord_t* tap_hold_record, + uint16_t other_keycode, + keyrecord_t* other_record) +{ + // allow thumb key row to always work + if (other_record->event.key.row >= 3) { + return true; + } + + // Otherwise, follow the opposite hands rule. + return achordion_opposite_hands(tap_hold_record, other_record); +} + // // underglow configuration // @@ -101,7 +135,7 @@ const rgblight_segment_t PROGMEM fn_layer[] = RGBLIGHT_LAYER_SEGMENTS( const rgblight_segment_t * const PROGMEM my_rgb_layers[] = RGBLIGHT_LAYERS_LIST( [BASE] = qwerty_layer, - [NAV] = lower_layer, + [NAV] = cmd_layer, [MOUSE] = raise_layer, [MEDIA] = nav_layer, [NUM] = cmd_layer, diff --git a/readme.md b/readme.md index 87252e0..7a82ac3 100644 --- a/readme.md +++ b/readme.md @@ -1,3 +1,11 @@ # Christoph Cullmann's Layout Derived from the Miryoku layout. + +https://github.com/manna-harbour/miryoku + + +In addition features Achordion to improve the home row modifiers. + +https://getreuer.info/posts/keyboards/achordion/index.html + diff --git a/rules.mk b/rules.mk index 97fa048..02b8fb7 100644 --- a/rules.mk +++ b/rules.mk @@ -11,6 +11,9 @@ AUTO_SHIFT_ENABLE = yes # Auto Shift include users/manna-harbour_miryoku/custom_rules.mk include users/manna-harbour_miryoku/post_rules.mk +# add achordion to improve home row modifiers +SRC += achordion.c + # properly optimize LTO_ENABLE = yes