feature(hold-tap): Retro tapping

app/dts/bindings/behaviors/zmk,behavior-hold-tap.yaml

@@ -28,3 +28,5 @@ properties:
       - "hold-preferred"
       - "balanced"
       - "tap-preferred"
+  retro-tap:
+    type: boolean

app/src/behaviors/behavior_hold_tap.c

@@ -57,6 +57,7 @@ struct behavior_hold_tap_config {
     char *tap_behavior_dev;
     int quick_tap_ms;
     enum flavor flavor;
+    bool retro_tap;
 };
 
 // this data is specific for each hold-tap
@@ -382,6 +383,29 @@ static void decide_hold_tap(struct active_hold_tap *hold_tap,
     release_captured_events();
 }
 
+static void decide_retro_tap(struct active_hold_tap *hold_tap) {
+    if (!hold_tap->config->retro_tap) {
+        return;
+    }
+    if (hold_tap->status == STATUS_HOLD_TIMER) {
+        release_binding(hold_tap);
+        LOG_DBG("%d retro tap", hold_tap->position);
+        hold_tap->status = STATUS_TAP;
+        press_binding(hold_tap);
+        return;
+    }
+}
+
+static void update_hold_status_for_retro_tap(uint32_t position) {
+    for (int i = 0; i < ZMK_BHV_HOLD_TAP_MAX_HELD; i++) {
+        struct active_hold_tap *hold_tap = &active_hold_taps[i];
+        if (hold_tap->position != position && hold_tap->status == STATUS_HOLD_TIMER) {
+            LOG_DBG("Update hold tap %d status to hold-interrupt", hold_tap->position);
+            hold_tap->status = STATUS_HOLD_INTERRUPT;
+        }
+    }
+}
+
 static int on_hold_tap_binding_pressed(struct zmk_behavior_binding *binding,
                                        struct zmk_behavior_binding_event event) {
     const struct device *dev = device_get_binding(binding->behavior_dev);
@@ -434,6 +458,7 @@ static int on_hold_tap_binding_released(struct zmk_behavior_binding *binding,
     }
 
     decide_hold_tap(hold_tap, HT_KEY_UP);
+    decide_retro_tap(hold_tap);
     release_binding(hold_tap);
 
     if (work_cancel_result == -EINPROGRESS) {
@@ -457,6 +482,8 @@ static const struct behavior_driver_api behavior_hold_tap_driver_api = {
 static int position_state_changed_listener(const zmk_event_t *eh) {
     struct zmk_position_state_changed *ev = as_zmk_position_state_changed(eh);
 
+    update_hold_status_for_retro_tap(ev->position);
+
     if (undecided_hold_tap == NULL) {
         LOG_DBG("%d bubble (no undecided hold_tap active)", ev->position);
         return ZMK_EV_EVENT_BUBBLE;
@@ -564,6 +591,7 @@ static struct behavior_hold_tap_data behavior_hold_tap_data;
         .tap_behavior_dev = DT_LABEL(DT_INST_PHANDLE_BY_IDX(n, bindings, 1)),                      \
         .quick_tap_ms = DT_INST_PROP(n, quick_tap_ms),                                             \
         .flavor = DT_ENUM_IDX(DT_DRV_INST(n), flavor),                                             \
+        .retro_tap = DT_INST_PROP(n, retro_tap),                                                   \
     };                                                                                             \
     DEVICE_AND_API_INIT(behavior_hold_tap_##n, DT_INST_LABEL(n), behavior_hold_tap_init,           \
                         &behavior_hold_tap_data, &behavior_hold_tap_config_##n, APPLICATION,       \

app/tests/hold-tap/balanced/6-retro-tap/events.patterns

@@ -0,0 +1,6 @@
+s/.*hid_listener_keycode/kp/p
+s/.*mo_keymap_binding/mo/p
+s/.*on_hold_tap_binding/ht_binding/p
+s/.*decide_hold_tap/ht_decide/p
+s/.*update_hold_status_for_retro_tap/update_hold_status_for_retro_tap/p
+s/.*decide_retro_tap/decide_retro_tap/p

app/tests/hold-tap/balanced/6-retro-tap/keycode_events.snapshot

@@ -0,0 +1,21 @@
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided tap (balanced decision moment key-up)
+kp_pressed: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided hold-timer (balanced decision moment timer)
+kp_pressed: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+decide_retro_tap: 0 retro tap
+kp_pressed: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided hold-timer (balanced decision moment timer)
+kp_pressed: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+update_hold_status_for_retro_tap: Update hold tap 0 status to hold-interrupt
+kp_pressed: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap

app/tests/hold-tap/balanced/6-retro-tap/native_posix.keymap

@@ -0,0 +1,45 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan_mock.h>
+
+/ {
+	behaviors {
+		ht_bal: behavior_balanced {
+			compatible = "zmk,behavior-hold-tap";
+			label = "MOD_TAP";
+			#binding-cells = <2>;
+			flavor = "balanced";
+			tapping_term_ms = <300>;
+			bindings = <&kp>, <&kp>;
+			retro-tap;
+		};
+	};
+
+	keymap {
+		compatible = "zmk,keymap";
+		label ="Default keymap";
+
+		default_layer {
+			bindings = <
+				&ht_bal LEFT_SHIFT F &none
+				&kp D &none>;
+		};
+	};
+};
+
+
+&kscan {
+	events = <
+		/* tap */
+		ZMK_MOCK_PRESS(0,0,10) 
+		ZMK_MOCK_RELEASE(0,0,10) 
+		/* retro tap */
+		ZMK_MOCK_PRESS(0,0,400)
+		ZMK_MOCK_RELEASE(0,0,10) 
+		/* hold  */
+		ZMK_MOCK_PRESS(0,0,400)
+		ZMK_MOCK_PRESS(1,0,10)
+		ZMK_MOCK_RELEASE(1,0,10)
+		ZMK_MOCK_RELEASE(0,0,10) 
+	>;
+};

app/tests/hold-tap/hold-preferred/6-retro-tap/events.patterns

@@ -0,0 +1,6 @@
+s/.*hid_listener_keycode/kp/p
+s/.*mo_keymap_binding/mo/p
+s/.*on_hold_tap_binding/ht_binding/p
+s/.*decide_hold_tap/ht_decide/p
+s/.*update_hold_status_for_retro_tap/update_hold_status_for_retro_tap/p
+s/.*decide_retro_tap/decide_retro_tap/p

app/tests/hold-tap/hold-preferred/6-retro-tap/keycode_events.snapshot

@@ -0,0 +1,21 @@
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided tap (hold-preferred decision moment key-up)
+kp_pressed: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided hold-timer (hold-preferred decision moment timer)
+kp_pressed: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+decide_retro_tap: 0 retro tap
+kp_pressed: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided hold-timer (hold-preferred decision moment timer)
+kp_pressed: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+update_hold_status_for_retro_tap: Update hold tap 0 status to hold-interrupt
+kp_pressed: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap

app/tests/hold-tap/hold-preferred/6-retro-tap/native_posix.keymap

@@ -0,0 +1,45 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan_mock.h>
+
+/ {
+	behaviors {
+		hp: behavior_hold_preferred {
+			compatible = "zmk,behavior-hold-tap";
+			label = "MOD_TAP";
+			#binding-cells = <2>;
+			flavor = "hold-preferred";
+			tapping_term_ms = <300>;
+			bindings = <&kp>, <&kp>;
+			retro-tap;
+		};
+	};
+
+	keymap {
+		compatible = "zmk,keymap";
+		label ="Default keymap";
+
+		default_layer {
+			bindings = <
+				&hp LEFT_SHIFT F &none
+				&kp D &none>;
+		};
+	};
+};
+
+
+&kscan {
+	events = <
+		/* tap */
+		ZMK_MOCK_PRESS(0,0,10) 
+		ZMK_MOCK_RELEASE(0,0,10) 
+		/* retro tap */
+		ZMK_MOCK_PRESS(0,0,400)
+		ZMK_MOCK_RELEASE(0,0,10) 
+		/* hold  */
+		ZMK_MOCK_PRESS(0,0,400)
+		ZMK_MOCK_PRESS(1,0,10)
+		ZMK_MOCK_RELEASE(1,0,10)
+		ZMK_MOCK_RELEASE(0,0,10) 
+	>;
+};

app/tests/hold-tap/tap-preferred/6-retro-tap/events.patterns

@@ -0,0 +1,6 @@
+s/.*hid_listener_keycode/kp/p
+s/.*mo_keymap_binding/mo/p
+s/.*on_hold_tap_binding/ht_binding/p
+s/.*decide_hold_tap/ht_decide/p
+s/.*update_hold_status_for_retro_tap/update_hold_status_for_retro_tap/p
+s/.*decide_retro_tap/decide_retro_tap/p

app/tests/hold-tap/tap-preferred/6-retro-tap/keycode_events.snapshot

@@ -0,0 +1,21 @@
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided tap (tap-preferred decision moment key-up)
+kp_pressed: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided hold-timer (tap-preferred decision moment timer)
+kp_pressed: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+decide_retro_tap: 0 retro tap
+kp_pressed: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x09 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap
+ht_binding_pressed: 0 new undecided hold_tap
+ht_decide: 0 decided hold-timer (tap-preferred decision moment timer)
+kp_pressed: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+update_hold_status_for_retro_tap: Update hold tap 0 status to hold-interrupt
+kp_pressed: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0x07 implicit_mods 0x00 explicit_mods 0x00
+kp_released: usage_page 0x07 keycode 0xe1 implicit_mods 0x00 explicit_mods 0x00
+ht_binding_released: 0 cleaning up hold-tap

app/tests/hold-tap/tap-preferred/6-retro-tap/native_posix.keymap

@@ -0,0 +1,45 @@
+#include <dt-bindings/zmk/keys.h>
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/kscan_mock.h>
+
+/ {
+	behaviors {
+		tp: behavior_tap_preferred {
+			compatible = "zmk,behavior-hold-tap";
+			label = "MOD_TAP";
+			#binding-cells = <2>;
+			flavor = "tap-preferred";
+			tapping_term_ms = <300>;
+			bindings = <&kp>, <&kp>;
+			retro-tap;
+		};
+	};
+
+	keymap {
+		compatible = "zmk,keymap";
+		label ="Default keymap";
+
+		default_layer {
+			bindings = <
+				&tp LEFT_SHIFT F &none
+				&kp D &none>;
+		};
+	};
+};
+
+
+&kscan {
+	events = <
+		/* tap */
+		ZMK_MOCK_PRESS(0,0,10) 
+		ZMK_MOCK_RELEASE(0,0,10) 
+		/* retro tap */
+		ZMK_MOCK_PRESS(0,0,400)
+		ZMK_MOCK_RELEASE(0,0,10) 
+		/* hold  */
+		ZMK_MOCK_PRESS(0,0,400)
+		ZMK_MOCK_PRESS(1,0,10)
+		ZMK_MOCK_RELEASE(1,0,10)
+		ZMK_MOCK_RELEASE(0,0,10) 
+	>;
+};

docs/docs/behaviors/hold-tap.md

@@ -47,6 +47,18 @@ If you press a tapped hold-tap again within `quick_tap_ms` milliseconds, it will
 
 In QMK, unlike ZMK, this functionality is enabled by default, and you turn it off using `TAPPING_FORCE_HOLD`.
 
+#### `retro-tap`
+
+If retro tap is enabled, the tap behavior is triggered when releasing the hold-tap key if no other key was pressed in the meantime.
+
+For example, if you press `&mt LEFT_SHIFT A` for a long time and then release it without pressing another key in the meantime, it will output `a`. (Actually, `LEFT_SHIFT` will be pressed when the tapping term expires, which is released just before the `a` is tapped.
+
+```
+&mt {
+	retro-tap;
+}
+```
+
 #### Home row mods
 
 This example configures a hold-tap that works well for homerow mods: