sporq/kmk_firmware
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source 
Tap Dance: Part One
This commit is contained in:
Josh Klar 2018-11-05 22:04:40 -08:00 committed by GitHub
commit 6a82d3da7d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 249 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
docs/tapdance.md Normal file
View File

@ -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, ....], ....]
```

57
kmk/firmware.py
View File

@ -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()

160
kmk/internal_state.py
View File

@ -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 = []
macro_pending = None
macros_pending = []
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:
self.keys_pressed.add(kc_changed)
self.coord_keys_pressed[int_coord] = kc_changed
if self.tapping and not isinstance(kc_changed, TapDanceKeycode):
self._process_tap_dance(kc_changed, is_pressed)
else:
self.keys_pressed.discard(kc_changed)
self.keys_pressed.discard(self.coord_keys_pressed[int_coord])
self.coord_keys_pressed[int_coord] = None
if is_pressed:
self.coord_keys_pressed[int_coord] = kc_changed
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:
self._process_internal_key_event(
kc_changed,
is_pressed,
)
if self.config.leader_mode % 2 == 1:
self._process_leader_mode()
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):
self.keys_pressed.discard(keycode)
self.hid_pending = True
return self
def force_keycode_down(self, keycode):
def add_key(self, keycode):
# TODO Make this itself a macro keycode with a keyup handler
# rather than handling this inline here. Gross.
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):
popped = self.pending_keys.pop()
if self.config.debug_enabled:
print('Popped pending key: {}'.format(popped))
def tap_key(self, keycode):
self.add_key(keycode)
# On the next cycle, we'll remove the key. This is way more clean than
# the `pending_keys` implementation that we used to rely on in
# 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()

17
kmk/keycodes.py
View File

@ -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

22
user_keymaps/klardotsh/klarank_featherm4.py
View File

@ -9,9 +9,7 @@ keyboard = Firmware()
keyboard.debug_enabled = True
keyboard.unicode_mode = UnicodeModes.LINUX
_______ = KC.TRNS
xxxxxxx = KC.NO
keyboard.tap_time = 750
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.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.LCTL, KC.DBG, xxxxxxx, xxxxxxx, _______, _______, xxxxxxx, xxxxxxx, KC.MUTE, KC.VOLD, KC.VOLU, xxxxxxx],
[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.LGUI, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx, xxxxxxx],
[KC.LCTL, KC.DBG, HELLA_TD, xxxxxxx, _______, _______, xxxxxxx, xxxxxxx, KC.MUTE, KC.VOLD, KC.VOLU, xxxxxxx],
],
]