Merge pull request #77 from KMKfw/topic-tap-dance

Tap Dance: Part One

docs/tapdance.md

@@ -0,0 +1,61 @@
+# Tap Dance
+
+Tap dance is a way to allow a single physical key to work as multple logical
+keys / actions without using layers. With basic tap dance, you can trigger these
+"nested" keys or macros through a series of taps of the physical key within a
+given timeout.
+
+The resulting "logical" action works just like any other key - it can be pressed
+and immediately released, or it can be held. For example, let's take a key
+`KC.TD(KC.A, KC.B)`. If the tap dance key is tapped and released once quickly,
+the letter "a" will be sent. If it is tapped and released twice quickly, the
+letter "b" will be sent. If it is tapped once and held, the letter "a" will be
+held down until the tap dance key is released. If it is tapped and released once
+quickly, then tapped and held (both actions within the timeout window), the
+letter "b" will be held down until the tap dance key is released.
+
+To use this, you may want to define a `tap_time` value in your keyboard
+configuration. This is an integer in milliseconds, and defaults to `300`. 
+
+You'll then want to create a sequence of keys using `KC.TD(KC.SOMETHING,
+KC.SOMETHING_ELSE, MAYBE_THIS_IS_A_MACRO, WHATEVER_YO)`, and place it in your
+keymap somewhere. The only limits on how many keys can go in the sequence are,
+theoretically, the amount of RAM your MCU/board has, and how fast you can mash
+the physical key. Here's your chance to use all that button-mash video game
+experience you've built up over the years.
+
+**NOTE**: Currently our basic tap dance implementation has some limitations that
+are planned to be worked around "eventually", but for now are noteworthy:
+
+- The behavior of momentary layer switching within a tap dance sequence is
+  currently "undefined" at best, and will probably crash your keyboard. For now,
+  we strongly recommend avoiding `KC.MO` (or any other layer switch keys that
+  use momentary switch behavior - `KC.LM`, `KC.LT`, and `KC.TT`)
+
+- Super fancy stuff like sending a keypress only when the leader key is released
+  (perhaps based on how long the leader key was held) is **unsupported** - an
+  example usecase might be "tap for Home, hold for Shift"
+
+Here's an example of all this in action:
+
+```python
+# user_keymaps/some_silly_example.py
+from kmk.boards.klarank import Firmware
+from kmk.keycodes import KC
+from kmk.macros.simple import send_string
+
+keyboard = Firmware()
+
+keyboard.tap_time = 750
+
+EXAMPLE_TD = KC.TD(
+    KC.A,  # Tap once for "a"
+    KC.B,  # Tap twice for "b"
+    # Tap three times to send a raw string via macro
+    send_string('macros in a tap dance? I think yes'),
+    # Tap four times to toggle layer index 1
+    KC.TG(1),
+)
+
+keyboard.keymap = [[ ...., EXAMPLE_TD, ....], ....]
+```

kmk/firmware.py

@@ -64,6 +64,7 @@ class Firmware:
     split_offsets = ()
     split_flip = False
     split_side = None
+    split_type = None
     split_master_left = True
     is_master = None
     uart = None
@@ -78,14 +79,14 @@ class Firmware:
 
     def _send_key(self, key):
         if not getattr(key, 'no_press', None):
-            self._state.force_keycode_down(key)
+            self._state.add_key(key)
             self._send_hid()
 
         if not getattr(key, 'no_release', None):
-            self._state.force_keycode_up(key)
+            self._state.remove_key(key)
             self._send_hid()
 
-    def _handle_update(self, update):
+    def _handle_matrix_report(self, update=None):
         '''
         Bulk processing of update code for each cycle
         :param update:
@@ -97,24 +98,6 @@ class Firmware:
                 update[2],
             )
 
-            if self._state.hid_pending:
-                self._send_hid()
-
-            if self.debug_enabled:
-                print('New State: {}'.format(self._state._to_dict()))
-
-        self._state.process_timeouts()
-
-        for key in self._state.pending_keys:
-            self._send_key(key)
-            self._state.pending_key_handled()
-
-        if self._state.macro_pending:
-            for key in self._state.macro_pending(self):
-                self._send_key(key)
-
-            self._state.resolve_macro()
-
     def _send_to_master(self, update):
         if self.split_master_left:
             update[1] += self.split_offsets[update[0]]
@@ -189,19 +172,45 @@ class Firmware:
             print("Firin' lazers. Keyboard is booted.")
 
         while True:
+            state_changed = False
+
             if self.split_type is not None and self._master_half:
                 update = self._receive_from_slave()
                 if update is not None:
-                    self._handle_update(update)
+                    self._handle_matrix_report(update)
+                    state_changed = True
 
             update = self.matrix.scan_for_changes()
 
             if update is not None:
                 if self._master_half():
-                    self._handle_update(update)
+                    self._handle_matrix_report(update)
-
+                    state_changed = True
                 else:
                     # This keyboard is a slave, and needs to send data to master
                     self._send_to_master(update)
 
+            if self._state.hid_pending:
+                self._send_hid()
+
+            old_timeouts_len = len(self._state.timeouts)
+            self._state.process_timeouts()
+            new_timeouts_len = len(self._state.timeouts)
+
+            if old_timeouts_len != new_timeouts_len:
+                state_changed = True
+
+            if self._state.macros_pending:
+                # Blindly assume macros are going to change state, which is almost
+                # always a safe assumption
+                state_changed = True
+                for macro in self._state.macros_pending:
+                    for key in macro(self):
+                        self._send_key(key)
+
+                    self._state.resolve_macro()
+
+            if self.debug_enabled and state_changed:
+                print('New State: {}'.format(self._state._to_dict()))
+
             gc.collect()

kmk/internal_state.py

@@ -1,5 +1,6 @@
 from kmk.consts import LeaderMode
-from kmk.keycodes import FIRST_KMK_INTERNAL_KEYCODE, Keycodes, RawKeycodes
+from kmk.keycodes import (FIRST_KMK_INTERNAL_KEYCODE, Keycodes, RawKeycodes,
+                          TapDanceKeycode)
 from kmk.kmktime import sleep_ms, ticks_diff, ticks_ms
 from kmk.util import intify_coordinate
 
@@ -12,8 +13,7 @@ GESC_TRIGGERS = {
 class InternalState:
     keys_pressed = set()
     coord_keys_pressed = {}
-    pending_keys = []
+    macros_pending = []
-    macro_pending = None
     leader_pending = None
     leader_last_len = 0
     hid_pending = False
@@ -28,6 +28,9 @@ class InternalState:
         'leader': None,
     }
     timeouts = {}
+    tapping = False
+    tap_dance_counts = {}
+    tap_side_effects = {}
 
     def __init__(self, config):
         self.config = config
@@ -45,6 +48,7 @@ class InternalState:
             Keycodes.KMK.KC_LEAD.code: self._kc_lead,
             Keycodes.KMK.KC_NO.code: self._kc_no,
             Keycodes.KMK.KC_DEBUG.code: self._kc_debug_mode,
+            RawKeycodes.KC_TAP_DANCE: self._kc_tap_dance,
         }
 
     def __repr__(self):
@@ -57,6 +61,9 @@ class InternalState:
             'leader_mode_history': self.leader_mode_history,
             'leader_mode': self.config.leader_mode,
             'start_time': self.start_time,
+            'tapping': self.tapping,
+            'tap_dance_counts': self.tap_dance_counts,
+            'timeouts': self.timeouts,
         }
 
         return ret
@@ -76,14 +83,26 @@ class InternalState:
             return layer_key
 
     def set_timeout(self, after_ticks, callback):
-        timeout_key = ticks_ms() + after_ticks
+        if after_ticks is False:
+            # We allow passing False as an implicit "run this on the next process timeouts cycle"
+            timeout_key = ticks_ms()
+        else:
+            timeout_key = ticks_ms() + after_ticks
+
         self.timeouts[timeout_key] = callback
         return self
 
     def process_timeouts(self):
+        if not self.timeouts:
+            return self
+
         current_time = ticks_ms()
 
-        for k, v in self.timeouts.items():
+        # cast this to a tuple to ensure that if a callback itself sets
+        # timeouts, we do not handle them on the current cycle
+        timeouts = tuple(self.timeouts.items())
+
+        for k, v in timeouts:
             if k <= current_time:
                 v()
                 del self.timeouts[k]
@@ -103,45 +122,52 @@ class InternalState:
             print('No key accessible for col, row: {}, {}'.format(row, col))
             return self
 
-        if is_pressed:
+        if self.tapping and not isinstance(kc_changed, TapDanceKeycode):
-            self.keys_pressed.add(kc_changed)
+            self._process_tap_dance(kc_changed, is_pressed)
-            self.coord_keys_pressed[int_coord] = kc_changed
         else:
-            self.keys_pressed.discard(kc_changed)
+            if is_pressed:
-            self.keys_pressed.discard(self.coord_keys_pressed[int_coord])
+                self.coord_keys_pressed[int_coord] = kc_changed
-            self.coord_keys_pressed[int_coord] = None
+                self.add_key(kc_changed)
+            else:
+                self.remove_key(kc_changed)
+                self.keys_pressed.discard(self.coord_keys_pressed.get(int_coord, None))
+                self.coord_keys_pressed[int_coord] = None
 
-        if kc_changed.code >= FIRST_KMK_INTERNAL_KEYCODE:
+            if self.config.leader_mode % 2 == 1:
-            self._process_internal_key_event(
+                self._process_leader_mode()
-                kc_changed,
+
-                is_pressed,
+        return self
-            )
+
+    def remove_key(self, keycode):
+        self.keys_pressed.discard(keycode)
+
+        if keycode.code >= FIRST_KMK_INTERNAL_KEYCODE:
+            self._process_internal_key_event(keycode, False)
         else:
             self.hid_pending = True
 
-        if self.config.leader_mode % 2 == 1:
-            self._process_leader_mode()
-
         return self
 
-    def force_keycode_up(self, keycode):
+    def add_key(self, keycode):
-        self.keys_pressed.discard(keycode)
+        # TODO Make this itself a macro keycode with a keyup handler
-        self.hid_pending = True
+        #      rather than handling this inline here. Gross.
-        return self
-
-    def force_keycode_down(self, keycode):
         if keycode.code == Keycodes.KMK.KC_MACRO_SLEEP_MS:
             sleep_ms(keycode.ms)
         else:
             self.keys_pressed.add(keycode)
-            self.hid_pending = True
+
+            if keycode.code >= FIRST_KMK_INTERNAL_KEYCODE:
+                self._process_internal_key_event(keycode, True)
+            else:
+                self.hid_pending = True
         return self
 
-    def pending_key_handled(self):
+    def tap_key(self, keycode):
-        popped = self.pending_keys.pop()
+        self.add_key(keycode)
-
+        # On the next cycle, we'll remove the key. This is way more clean than
-        if self.config.debug_enabled:
+        # the `pending_keys` implementation that we used to rely on in
-            print('Popped pending key: {}'.format(popped))
+        # firmware.py
+        self.set_timeout(False, lambda: self.remove_key(keycode))
 
         return self
 
@@ -153,7 +179,7 @@ class InternalState:
         if self.config.debug_enabled:
             print('Macro complete!')
 
-        self.macro_pending = None
+        self.macros_pending.pop()
         return self
 
     def _process_internal_key_event(self, changed_key, is_pressed):
@@ -214,7 +240,7 @@ class InternalState:
                 ticks_diff(ticks_ms(), self.start_time['lt']) < self.config.tap_time
             ):
                 self.hid_pending = True
-                self.pending_keys.append(changed_key.kc)
+                self.tap_key(changed_key.kc)
 
             self._layer_mo(changed_key, is_pressed)
             self.start_time['lt'] = None
@@ -274,10 +300,10 @@ class InternalState:
     def _kc_macro(self, changed_key, is_pressed):
         if is_pressed:
             if changed_key.keyup:
-                self.macro_pending = changed_key.keyup
+                self.macros_pending.append(changed_key.keyup)
         else:
             if changed_key.keydown:
-                self.macro_pending = changed_key.keydown
+                self.macros_pending.append(changed_key.keydown)
 
         return self
 
@@ -318,6 +344,68 @@ class InternalState:
 
         return self
 
+    def _kc_tap_dance(self, changed_key, is_pressed):
+        return self._process_tap_dance(changed_key, is_pressed)
+
+    def _process_tap_dance(self, changed_key, is_pressed):
+        if is_pressed:
+            if not isinstance(changed_key, TapDanceKeycode):
+                # If we get here, changed_key is not a TapDanceKeycode and thus
+                # the user kept typing elsewhere (presumably).  End ALL of the
+                # currently outstanding tap dance runs.
+                for k, v in self.tap_dance_counts.items():
+                    if v:
+                        self._end_tap_dance(k)
+
+                return self
+
+            if (
+                changed_key not in self.tap_dance_counts or
+                not self.tap_dance_counts[changed_key]
+            ):
+                self.tap_dance_counts[changed_key] = 1
+                self.set_timeout(self.config.tap_time, lambda: self._end_tap_dance(changed_key))
+                self.tapping = True
+            else:
+                self.tap_dance_counts[changed_key] += 1
+
+            if changed_key not in self.tap_side_effects:
+                self.tap_side_effects[changed_key] = None
+        else:
+            if (
+                self.tap_side_effects[changed_key] is not None or
+                self.tap_dance_counts[changed_key] == len(changed_key.codes)
+            ):
+                self._end_tap_dance(changed_key)
+
+        return self
+
+    def _end_tap_dance(self, td_key):
+        v = self.tap_dance_counts[td_key] - 1
+
+        if v >= 0:
+            if td_key in self.keys_pressed:
+                key_to_press = td_key.codes[v]
+                self.add_key(key_to_press)
+                self.tap_side_effects[td_key] = key_to_press
+                self.hid_pending = True
+            else:
+                if self.tap_side_effects[td_key]:
+                    self.remove_key(self.tap_side_effects[td_key])
+                    self.tap_side_effects[td_key] = None
+                    self.hid_pending = True
+                    self._cleanup_tap_dance(td_key)
+                else:
+                    self.tap_key(td_key.codes[v])
+                    self._cleanup_tap_dance(td_key)
+
+        return self
+
+    def _cleanup_tap_dance(self, td_key):
+        self.tap_dance_counts[td_key] = 0
+        self.tapping = any(count > 0 for count in self.tap_dance_counts.values())
+        return self
+
     def _begin_leader_mode(self):
         if self.config.leader_mode % 2 == 0:
             self.keys_pressed.discard(Keycodes.KMK.KC_LEAD)
@@ -333,7 +421,7 @@ class InternalState:
         lmh = tuple(self.leader_mode_history)
 
         if lmh in self.config.leader_dictionary:
-            self.macro_pending = self.config.leader_dictionary[lmh].keydown
+            self.macros_pending.append(self.config.leader_dictionary[lmh].keydown)
 
         return self._exit_leader_mode()
 

kmk/keycodes.py

@@ -80,6 +80,7 @@ class RawKeycodes:
 
     KC_MACRO = 1110
     KC_MACRO_SLEEP_MS = 1111
+    KC_TAP_DANCE = 1113
 
 
 # These shouldn't have all the fancy shenanigans Keycode allows
@@ -184,6 +185,13 @@ class Macro:
         return self.keyup() if self.keyup else None
 
 
+class TapDanceKeycode:
+    code = RawKeycodes.KC_TAP_DANCE
+
+    def __init__(self, *codes):
+        self.codes = codes
+
+
 class KeycodeCategory(type):
     @classmethod
     def to_dict(cls):
@@ -364,7 +372,7 @@ class ShiftedKeycodes(KeycodeCategory):
     KC_DOUBLE_QUOTE = KC_DQUO = KC_DQT = Modifiers.KC_LSHIFT(Common.KC_QUOTE)
     KC_LEFT_ANGLE_BRACKET = KC_LABK = Modifiers.KC_LSHIFT(Common.KC_COMMA)
     KC_RIGHT_ANGLE_BRACKET = KC_RABK = Modifiers.KC_LSHIFT(Common.KC_DOT)
-    KC_QUESTION = KC_QUES = Modifiers.KC_LSHIFT(Common.KC_DOT)
+    KC_QUESTION = KC_QUES = Modifiers.KC_LSHIFT(Common.KC_SLSH)
 
 
 class FunctionKeys(KeycodeCategory):
@@ -551,6 +559,13 @@ class KMK(KeycodeCategory):
     def KC_MACRO_SLEEP_MS(ms):
         return MacroSleepKeycode(RawKeycodes.KC_MACRO_SLEEP_MS, ms)
 
+    @staticmethod
+    def KC_TAP_DANCE(*args):
+        return TapDanceKeycode(*args)
+
+
+KMK.KC_TD = KMK.KC_TAP_DANCE
+
 
 class Layers(KeycodeCategory):
     @staticmethod

user_keymaps/klardotsh/klarank_featherm4.py

@@ -9,9 +9,7 @@ keyboard = Firmware()
 
 keyboard.debug_enabled = True
 keyboard.unicode_mode = UnicodeModes.LINUX
-
+keyboard.tap_time = 750
-_______ = KC.TRNS
-xxxxxxx = KC.NO
 
 emoticons = cuss({
     # Emojis
@@ -56,6 +54,16 @@ keyboard.leader_dictionary = {
     glds('cel'): emoticons.CELEBRATORY_GLITTER,
 }
 
+_______ = KC.TRNS
+xxxxxxx = KC.NO
+HELLA_TD = KC.TD(
+    KC.A,
+    KC.B,
+    send_string('macros in a tap dance? I think yes'),
+    KC.TG(1),
+)
+
+
 keyboard.keymap = [
     [
         [KC.GESC, KC.QUOT, KC.COMM,            KC.DOT,   KC.P,     KC.Y,    KC.F,    KC.G,     KC.C,    KC.R,    KC.L,  KC.BSPC],
@@ -79,10 +87,10 @@ keyboard.keymap = [
     ],
 
     [
-        [KC.GRV,  KC.EXLM, KC.AT,   KC.HASH, KC.DLR,  KC.PERC, KC.CIRC, KC.AMPR, KC.ASTR, KC.LPRN, KC.RPRN, KC.SLSH],
+        [KC.GRV,  KC.EXLM, KC.AT,    KC.HASH, KC.DLR,  KC.PERC, KC.CIRC, KC.AMPR, KC.ASTR, KC.LPRN, KC.RPRN, KC.SLSH],
-        [KC.TAB,  xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, KC.MINS],
+        [KC.TAB,  xxxxxxx, xxxxxxx,  xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, KC.MINS],
-        [KC.LGUI, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx],
+        [KC.LGUI, xxxxxxx, xxxxxxx,  xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx],
-        [KC.LCTL, KC.DBG,  xxxxxxx, xxxxxxx, _______, _______, xxxxxxx, xxxxxxx, KC.MUTE, KC.VOLD, KC.VOLU, xxxxxxx],
+        [KC.LCTL, KC.DBG,  HELLA_TD, xxxxxxx, _______, _______, xxxxxxx, xxxxxxx, KC.MUTE, KC.VOLD, KC.VOLU, xxxxxxx],
     ],
 ]