[Chordal Hold] can't get it working on Keebio Iris Rev8 keyboard

[padd1er]

Greetings @getreuer and fellow community members,

I'm currently experimenting with the Chordal Hold feature on my Keebio Iris Rev8 keyboard, and I've encountered a discrepancy between the observed behavior and the documented functionality. I've chosen to post this discussion within @getreuer's repository, given his role as the feature's author, in hopes of gaining some clarification.

Environment:

• Keyboard: Keebio Iris Rev8 (https://github.com/qmk/qmk_firmware/tree/master/keyboards/keebio/iris/rev8)
• Keymap: Custom userspace keymap (minimal reproducible example: https://github.com/padd1er/qmk_userspace/tree/main/keyboards/keebio/iris/rev8/keymaps/mvp), utilizing the Colemak-DH layout.
• QMK Firmware: Current master branch, specifically commit (a70288bc4a22385325eaaec081bd4139b5b56f90).
• config.h settings:

  #define TAPPING_TERM 225
  #define PERMISSIVE_HOLD
  #define CHORDAL_HOLD

Observed Issue:

According to the Chordal Hold documentation (https://docs.qmk.fm/tap_hold#chordal-hold), the following key sequence should yield "nu":

1. RSFT_T(KC_N) press (right hand)
2. KC_U press (right hand)
3. KC_U release (right hand)
4. RSFT_T(KC_N) release (right hand)

However, my tests consistently produce "U" instead of the expected "nu".

Inquiries:

1. Could there be a potential conflict arising from the Iris Rev8's default configuration or my specific keymap that is contributing to this discrepancy?
2. Are there any recommended debugging procedures or configuration adjustments that might assist in resolving this issue?

I've provided a minimal reproducible example within my userspace repository to facilitate troubleshooting. Any insights or suggestions would be greatly appreciated.

[getreuer]

@padd1er thanks for the report. Yes, what you describe really should work to produce "nu". I looked at your example and all appears correctly configured.

On my keymap, the HRMs layout and config are very close to this set up. I don't mean to dismiss this as "but it works on my keyboard," but to say this is a critical use case.

Are there any recommended debugging procedures or configuration adjustments that might assist in resolving this issue?

Yes, there is a way to get additional debug logging from Chordal Hold. This does require going through some hoops. First set up console logging:

1. Enable the Console feature: in rules.mk, add CONSOLE_ENABLE = yes.
2. Add a DB_TOGG key somewhere in your keymap.
3. Software is needed on the host computer to listen for the console messages. One way is "qmk console". You may need some system configuration to get this to work, e.g. a udev rule on Linux (troubleshooting tips).

With console set, up turn on the action debug logging. This is the essential bit. In your config.h, add

#define ACTION_DEBUG

Build and flash, start the console listener with "qmk console", and tap the DB_TOGG key. You should immediately start seeing a verbose amount of output in the console, produced by the core action_tapping code, including Chordal Hold, of incoming key events and how they influence the tap-hold decision state.

It would be helpful if you could press the "nu" key sequence as you described above and share the console log output that results. This will show how the tapping logic is interpreting this input. Hopefully that will clear up what is going on.

[padd1er]

Indeed, I have followed your instructions (all changes are reflected in my mvp example). Below you will find the output from the qmk console, as requested:

fsh ❯ qmk console
Looking for devices...
Ψ Console Connected: Keebio Iris Rev. 8 (CB10:8256:1)
Keebio:Iris Rev. 8:1: DEBUG: enabled.
Keebio:Iris Rev. 8:1: processed: 0403d(21052):0
Keebio:Iris Rev. 8:1:
Keebio:Iris Rev. 8:1:
Keebio:Iris Rev. 8:1: ---- action_exec: start -----
Keebio:Iris Rev. 8:1: EVENT: 0403u(21133)
Keebio:Iris Rev. 8:1: ACTION: ACT_LMODS[0:00] layer_state: 00000000(0) default_layer_state: 00000001(0)
Keebio:Iris Rev. 8:1: processed: 0403u(21133):0
Keebio:Iris Rev. 8:1:
Keebio:Iris Rev. 8:1:
Keebio:Iris Rev. 8:1: ---- action_exec: start -----
Keebio:Iris Rev. 8:1: EVENT: 0704d(24961)
Keebio:Iris Rev. 8:1: Tapping: Start(Press tap key).
Keebio:Iris Rev. 8:1: TAPPING_KEY=0704d(24961):0
Keebio:Iris Rev. 8:1: processed: 0704d(24961):0
Keebio:Iris Rev. 8:1:
Keebio:Iris Rev. 8:1: Tapping: End. Timeout. Not tap(0): 0000u(25186)
Keebio:Iris Rev. 8:1: ACTION: ACT_RMODS_TAP[2:11] layer_state: 00000000(0) default_layer_state: 00000001(0)
Keebio:Iris Rev. 8:1: MODS_TAP: No tap: add_mods
Keebio:Iris Rev. 8:1: TAPPING_KEY=0000u(0):0
Keebio:Iris Rev. 8:1:
Keebio:Iris Rev. 8:1: ---- action_exec: start -----
Keebio:Iris Rev. 8:1: EVENT: 0603d(25377)
UKeebio:Iris Rev. 8:1: ACTION: ACT_LMODS[0:18] layer_state: 00000000(0) default_layer_state: 00000001(0)
Keebio:Iris Rev. 8:1: processed: 0603d(25377):0
Keebio:Iris Rev. 8:1:
Keebio:Iris Rev. 8:1:
Keebio:Iris Rev. 8:1: ---- action_exec: start -----
Keebio:Iris Rev. 8:1: EVENT: 0603u(25452)
Keebio:Iris Rev. 8:1: ACTION: ACT_LMODS[0:18] layer_state: 00000000(0) default_layer_state: 00000001(0)
Keebio:Iris Rev. 8:1: processed: 0603u(25452):0
Keebio:Iris Rev. 8:1:
Keebio:Iris Rev. 8:1:
Keebio:Iris Rev. 8:1: ---- action_exec: start -----
Keebio:Iris Rev. 8:1: EVENT: 0704u(25672)
Keebio:Iris Rev. 8:1: ACTION: ACT_RMODS_TAP[2:11] layer_state: 00000000(0) default_layer_state: 00000001(0)
Keebio:Iris Rev. 8:1: MODS_TAP: No tap: add_mods
Keebio:Iris Rev. 8:1: processed: 0704u(25672):0
Keebio:Iris Rev. 8:1:
Keebio:Iris Rev. 8:1:
Keebio:Iris Rev. 8:1: ---- action_exec: start -----
Keebio:Iris Rev. 8:1: EVENT: 0704d(31249)
Keebio:Iris Rev. 8:1: Tapping: Start(Press tap key).
Keebio:Iris Rev. 8:1: TAPPING_KEY=0704d(31249):0
Keebio:Iris Rev. 8:1: processed: 0704d(31249):0
Keebio:Iris Rev. 8:1:
Keebio:Iris Rev. 8:1: Tapping: End. Timeout. Not tap(0): 0000u(31474)
Keebio:Iris Rev. 8:1: ACTION: ACT_RMODS_TAP[2:11] layer_state: 00000000(0) default_layer_state: 00000001(0)
Keebio:Iris Rev. 8:1: MODS_TAP: No tap: add_mods
Keebio:Iris Rev. 8:1: TAPPING_KEY=0000u(0):0
Keebio:Iris Rev. 8:1:
Keebio:Iris Rev. 8:1: ---- action_exec: start -----
Keebio:Iris Rev. 8:1: EVENT: 0603d(31638)
UKeebio:Iris Rev. 8:1: ACTION: ACT_LMODS[0:18] layer_state: 00000000(0) default_layer_state: 00000001(0)
Keebio:Iris Rev. 8:1: processed: 0603d(31638):0
Keebio:Iris Rev. 8:1:
Keebio:Iris Rev. 8:1:
Keebio:Iris Rev. 8:1: ---- action_exec: start -----
Keebio:Iris Rev. 8:1: EVENT: 0603u(31719)
Keebio:Iris Rev. 8:1: ACTION: ACT_LMODS[0:18] layer_state: 00000000(0) default_layer_state: 00000001(0)
Keebio:Iris Rev. 8:1: processed: 0603u(31719):0
Keebio:Iris Rev. 8:1:
Keebio:Iris Rev. 8:1:
Keebio:Iris Rev. 8:1: ---- action_exec: start -----
Keebio:Iris Rev. 8:1: EVENT: 0704u(31924)
Keebio:Iris Rev. 8:1: ACTION: ACT_RMODS_TAP[2:11] layer_state: 00000000(0) default_layer_state: 00000001(0)
Keebio:Iris Rev. 8:1: MODS_TAP: No tap: add_mods
Keebio:Iris Rev. 8:1: processed: 0704u(31924):0
Keebio:Iris Rev. 8:1:
^C⏎      

I hope this log will provide the necessary insights to identify the source of the issue. Should further information be required, please do not hesitate to ask.

[getreuer]

Thanks, that was fast! What this shows is the RSFT_T(KC_N) key is being held longer than the 225 ms tapping term before the KC_U is pressed, at least in these two inputs captured in the log. For me, 225 ms is a fairly quick time to input a one-handed "nested press" like this, I can't do it reliably myself.

In detail, here is what the log shows:

• (Ignore the very first "EVENT: 0403u(21133)," this is DB_TOGG being released.)
• Time 24961 ms: RSFT_T(KC_N) was pressed down.
• Time 25186 ms: The tapping term expired (25186 - 24961 = TAPPING_TERM). The key was settled as held, and right shift was sent (ACTION: ACT_RMODS_TAP[2:11]).
• Time 25377 ms: KC_U was pressed down.
• Time 25452 ms: KC_U was released.
• Time 25672 ms: RSFT_T(KC_N) was released.

Then ~5 seconds later, the above sequence repeats.

My impression is that it would be a good move to raise the tapping term a bit, say 300 ms, for a longer period of roll protection. The good thing about Permissive Hold (+ Chordal Hold) is that you'll still be able to use the mod functions within the tapping term by a cross-handed nested press. Example: input "LSFT_T(KC_T) ↓, KC_U ↓, KC_U ↑, LSFT_T(KC_T) ↑" within the tapping term produces "U".

Or if only for the sake of troubleshooting, temporarily raise the tapping term to the maximum of 500 ms.

[padd1er]

Ah, yes, thank you. You are quite correct. Increasing the tapping term, as you suggested, has indeed resolved the issue. I will experiment further with a dynamic tapping term to determine the optimal value for my usage.

Once again, I wish to express my gratitude for this excellent feature. Previously, I was utilizing a "flow" implementation - a time-limited one-shot layer - to access modifier keys. However, with the introduction of Chordal Hold, coupled with the insights gleaned from qmk/qmk_firmware#24262 (comment), I can now enjoy a more streamlined hold-tap HRM experience, effectively eliminating the need for extraneous keys.

[getreuer]

Wonderful! Glad to hear that worked out. And great to see folks are using filterpaper's trick for require-prior-idle behavior, it's a remarkably elegant implementation.

[NikGovorov]

@getreuer Have you tried using pre_process_record_user for forced tap with Chordal Hold? I've been using it successfully with Achordion for about a year and find it essential. Since pre_process_record_user executes before tap-hold decision, I assume it should be safe to upgrade from Achordion to Chordal Hold without unexpected behavior. Could you please confirm if my assumption is correct? Are there any edge cases I should be aware of?

[getreuer]

@padd1er @NikGovorov following up on require-prior-idle behavior, I just pushed a new module Tap Flow for require-prior-idle in QMK, disabling HRMs during fast typing. It is based on filterpaper's approach through pre_process_record_user.

@NikGovorov you are correct, the filterpaper pre_process_record_user approach can be used in combination with Chordal Hold. The clever thing is that when a tap-hold key event is rewritten as a tap, it does so in a way that it bypasses the rest of the tap-hold logic. Chordal Hold is within QMK's core tap-hold logic, which runs after pre_process_record_user, so it never even considers the rewritten event. I've been testing out Tap Flow + Chordal Hold for the past few days and all is working.

[NikGovorov]

Awesome! Thank you so much for your response and for all your contributions to QMK core and user space. I'll see if I can replace my custom (and admittedly ugly) pre_process_record_user handler with the Tap Flow module after upgrading to Chordal Hold.

bool pre_process_record_user(uint16_t keycode, keyrecord_t *record) {
    static bool inter_thumbs_pressed    = false;
    static bool is_lt_sym_ent_pressed   = false;
    static bool skip_instant_tap_checks = false;
    static bool is_pressed[UINT8_MAX];
    bool        pressed = record->event.pressed;

    const uint8_t tap_keycode = QK_MOD_TAP_GET_TAP_KEYCODE(keycode);

    if (keycode == LT_NAV_SPC) {
        if (pressed) {
            total_pointer_movement = (total_mouse_pointer_t){.x = 0, .y = 0, .timer = 0};
        }
        is_lt_nav_spc_pressed = pressed;
    }

    if (keycode == LT_SYM_ENT) {
        is_lt_sym_ent_pressed = pressed;
    }

    if (pressed) {
        if (is_hrm_instant_tap_enabled && !is_lt_nav_spc_pressed && !is_lt_sym_ent_pressed) {
            // don't force-tap if pressing a key after a Layer key
            if (!IS_QK_LAYER_TAP(inter_keycode) && !IS_QK_MOMENTARY(inter_keycode) &&
                !IS_QK_TOGGLE_LAYER(inter_keycode) && !IS_QK_TO(inter_keycode)) {
                bool tapped = false;
                // do force-tap if pressing a key that is an hrm
                if (((record->event.key.row == 1 || record->event.key.row == 5) && IS_QK_MOD_TAP(keycode))) {
                    // don't force-tap if pressing a key on the same row as the previous hrm key and it is not the same
                    // key and we are not skipping instant tap checks (streak)
                    if (!(inter_record.event.key.row == record->event.key.row && IS_QK_MOD_TAP(inter_keycode)) ||
                        keycode == inter_keycode || skip_instant_tap_checks) {
                        // don't force-tap if pressing lcontrol and rcontrol, lshift and rshift, lalt and ralt  and
                        // we are not skipping instant tap checks (streak)
                        if ((!(keycode == MTC_T && inter_keycode == MTC_N) &&
                             !(keycode == MTC_N && inter_keycode == MTC_T) &&
                             !(keycode == MTS_S && inter_keycode == MTS_E) &&
                             !(keycode == MTS_E && inter_keycode == MTS_S) &&
                             !(keycode == MTA_R && inter_keycode == MTA_I) &&
                             !(keycode == MTA_I && inter_keycode == MTA_R)) ||
                            skip_instant_tap_checks) {
                            // don't force-tap if the previous pressed key was a moded key (detected later in the
                            // pipeline)
                            if (!has_hrm_instant_tap_mods) {
                                const uint32_t last_input_activity = last_input_activity_elapsed();
                                const uint8_t  last_keycode        = (uint8_t)inter_keycode;
                                // do force-tap if
                                // pressing the same hrm(quick_tap_term emulation)
                                // or
                                // pressing an hrm after an alpha key
                                // within 160ms (100ms for S(lshift) and E(rshift))
                                //
                                if (!inter_thumbs_pressed && (keycode == inter_keycode || (last_keycode <= KC_Z)) &&
                                    (last_input_activity < (((keycode == MTS_S || keycode == MTS_E)) ? 100 : 160))) {
                                    tapped                  = true;
                                    is_pressed[tap_keycode] = true;
                                    record->keycode         = tap_keycode;
                                }
                            }
                        }
                    }
                }
                if (tapped) {
                    skip_instant_tap_checks = true;
                } else {
                    skip_instant_tap_checks = keycode <= KC_Z;
                }
            } else {
                skip_instant_tap_checks = false;
            }
        }

        // Cache incoming input for in-progress and subsequent tap-hold decisions
        inter_keycode        = keycode;
        inter_thumbs_pressed = is_lt_nav_spc_pressed || is_lt_sym_ent_pressed;
        inter_record         = *record;
    } else {
        if (is_hrm_instant_tap_enabled) {
            // Release the tap keycode if pressed
            if (is_pressed[tap_keycode]) {
                is_pressed[tap_keycode] = false;
                record->keycode         = tap_keycode;
            }
        }
    }

    return true;
}