Remove the legacy keyboard.debug_enabled flag and document the debu…

…g utility proper
KMKfw · Nov 19, 2024 · 9dd3af2 · 9dd3af2
1 parent cacf8a1
commit 9dd3af2
Show file tree

Hide file tree

Showing 14 changed files with 34 additions and 35 deletions.
diff --git a/boards/atreus62/main.py b/boards/atreus62/main.py
@@ -32,7 +32,6 @@
 keyboard.modules = [layers, encoder, macros]
 
 keyboard.tap_time = 250
-keyboard.debug_enabled = False
 
 
 # custom keys

diff --git a/boards/crowboard/main.py b/boards/crowboard/main.py
@@ -85,7 +85,5 @@
 #                      ((KC.VOLD, KC.VOLU),(KC.VOLD, KC.VOLU),), # Layer 4
 #                      ]
 
-# keyboard.debug_enabled = True
-
 if __name__ == '__main__':
     keyboard.go()
diff --git a/boards/fingerpunch/ffkb/nice_nano/main.py b/boards/fingerpunch/ffkb/nice_nano/main.py
@@ -4,7 +4,7 @@
 from kmk.modules.combos import Combos, Sequence
 from kmk.modules.dynamic_sequences import DynamicSequences
 from kmk.modules.layers import Layers
-from kmk.modules.oneshot import OneShot
+from kmk.modules.sticky_keys import StickyKeys
 
 combos = Combos()
 dyn_seq = DynamicSequences(
@@ -14,11 +14,10 @@
     use_recorded_speed=False,  # Whether to play the sequence at the speed it was typed
 )
 layers = Layers()
-oneshot = OneShot()
+sticky_keys = StickyKeys()
 
 keyboard = kb.KMKKeyboard()
-keyboard.modules = [combos, dyn_seq, layers, oneshot]
-keyboard.debug_enabled = False
+keyboard.modules = [combos, dyn_seq, layers, sticky_keys]
 
 # Convenience variables for the Keymap
 _______ = KC.TRNS
@@ -27,7 +26,7 @@
 L1_TAB = KC.LT(1, KC.TAB, prefer_hold=True)
 L2_ENT = KC.LT(2, KC.ENT, prefer_hold=True)
 
-OS_LSFT = KC.OS(KC.LSFT)
+SK_LSFT = KC.SK(KC.LSFT)
 
 SEQ_REC = KC.RECORD_SEQUENCE()
 SEQ_STP = KC.STOP_SEQUENCE()
@@ -48,7 +47,7 @@
         KC.ESC,  KC.Q,    KC.W,    KC.F,    KC.P,     KC.B,             KC.J,    KC.L,     KC.U,    KC.Y,    KC.SCLN, KC.LEADER,
         KC.LCTL, KC.A,    KC.R,    KC.S,    KC.T,     KC.G,    xxxxxxx, KC.M,    KC.N,     KC.E,    KC.I,    KC.O,    KC.QUOT,
         KC.LALT, KC.Z,    KC.X,    KC.C,    KC.D,     KC.V,             KC.K,    KC.H,     KC.COMM, KC.DOT,  KC.SLSH, KC.BSLS,
-                 xxxxxxx,          KC.LGUI, OS_LSFT,  KC.BSPC,          L1_TAB,  KC.SPACE, L2_ENT,             xxxxxxx,
+                 xxxxxxx,          KC.LGUI, SK_LSFT,  KC.BSPC,          L1_TAB,  KC.SPACE, L2_ENT,             xxxxxxx,
     ],
     [  # 1: Nav & Numbers
         KC.TAB,  KC.N1,   KC.N2,   KC.N3,   KC.N4,    KC.N5,            KC.N6,   KC.N7,    KC.N8,   KC.N9,   KC.N0,   KC.DEL,

diff --git a/boards/fingerpunch/ffkb/other_pro_micro/main.py b/boards/fingerpunch/ffkb/other_pro_micro/main.py
@@ -12,7 +12,6 @@
 
 keyboard = KMKKeyboard()
 keyboard.tap_time = 150
-keyboard.debug_enabled = False
 
 # Cleaner key names
 _______ = KC.TRNS

diff --git a/boards/keebio/iris/main.py b/boards/keebio/iris/main.py
@@ -7,7 +7,6 @@
 
 keyboard = KMKKeyboard()
 
-keyboard.debug_enabled = False
 keyboard.tap_time = 750
 
 _______ = KC.TRNS

diff --git a/boards/kyria/main.py b/boards/kyria/main.py
@@ -9,7 +9,6 @@
 from kmk.modules.split import Split, SplitType
 
 keyboard = KMKKeyboard()
-keyboard.debug_enabled = True
 
 keyboard.modules.append(Layers())
 keyboard.modules.append(HoldTap())

diff --git a/boards/splitkb/aurora/lily58/main.py b/boards/splitkb/aurora/lily58/main.py
@@ -10,7 +10,6 @@
 from kmk.modules.split import Split
 
 keyboard = KMKKeyboard()
-# keyboard.debug_enabled = True
 
 # Adding modules
 # Using drive names (LILY58L, LILY58R) to recognize sides; use split_side arg if you're not doing it

diff --git a/docs/en/config_and_keymap.md b/docs/en/config_and_keymap.md
@@ -82,10 +82,6 @@ keyboard.keymap = [[KC.A, KC.B]]
 
 You can further define a bunch of other stuff:
 
-- `keyboard.debug_enabled` which will spew a ton of debugging information to the serial
-  console. This is very rarely needed, but can provide very valuable information
-  if you need to open an issue.
-
 - `keyboard.tap_time` which defines how long `KC.TT` and `KC.LT` will wait before
   considering a key "held" (see `layers.md`).
 
diff --git a/docs/en/debugging.md b/docs/en/debugging.md
@@ -1,13 +1,33 @@
 # Debugging
+
 KMK's debug output is written to CircuitPython's serial console -- the one that's
 used for the REPL -- and is automatically enabled if it detects a connection to
 that console.
 It can also be enabled manually, though that shouldn't be necessary in
-general:
+general.
+
+## KMK's Debug Utility
+
+KMK has a convenient debug utility that adds a timestamp in milliseconds since boot and a message origin to distinguish subsystems to debug statements.
+
 ```python
-keyboard.debug_enabled = True
+from kmk.utils import Debug
+
+# Create a debug source with the current file as message origin
+debug = Debug(__name__)
+
+# For completeness: Force enable/disable debug output. This is handled
+# automatically -- you will most likely never have to use this:
+# debug.enabled = True/False
+
+# KMK idiomatic debug with guard clause
+var = 'concatenate'
+if debug.enabled:
+    debug('Arguments ', var, '!')
 ```
 
+## Connecting to the Serial Console
+
 Follow for example Adafruit's beginners guide on [how to connect to the serial console](https://learn.adafruit.com/welcome-to-circuitpython/kattni-connecting-to-the-serial-console).
 For Linux users, we recommend [picocom](https://github.com/npat-efault/picocom)
 or [screen](https://www.gnu.org/software/screen/manual/screen.html)
diff --git a/docs/en/encoder.md b/docs/en/encoder.md
@@ -148,7 +148,6 @@ keyboard.diode_orientation = DiodeOrientation.COLUMNS
 encoder_handler.pins = ((board.GP17, board.GP15, board.GP14, False),)
 
 keyboard.tap_time = 250
-keyboard.debug_enabled = False
 
 
 # Filler keys

diff --git a/docs/en/extension_stringy_keymaps.md b/docs/en/extension_stringy_keymaps.md
@@ -22,14 +22,10 @@ keyboard.keymap = [[ 'A' , 'B', 'RESET' ]]
 
 stringyKeymaps = StringyKeymaps()
 
-# Enabling debug will show each replacement or failure.
-# This is recommended during the initial development of a keyboard.
-# stringyKeymaps.debug_enable = True
-
 keyboard.extensions.append(stringyKeymaps)
 ```
 
 It should be noted that these are **not** ASCII. The string is **not** what
 will be sent to the computer. The examples above have no functional difference.
 
-When utilizing argumented keys, such as `KC.MO(layer)`, it's not possible to use a string like `'MO(layer)'` instead employ the standard notation of e.g. `KC.MO(1)` in your keymap.
+When utilizing argumented keys, such as `KC.MO(layer)`, it's not possible to use a string like `'MO(layer)'` instead employ the standard notation of e.g. `KC.MO(1)` in your keymap.
diff --git a/docs/en/keycodes.md b/docs/en/keycodes.md
@@ -162,7 +162,7 @@
 |-------------------------|------------------------------------------------------------------------|
 | `KC.RESET`              | Restarts the keyboard                                                  |
 | `KC.RELOAD`, `KC.RLD`   | Reloads the keyboard software, preserving any serial connections       |
-| `KC.DEBUG`              | Toggle `debug_enabled`, which enables log spew to serial console       |
+| `KC.DEBUG`              | Toggle `debug.enabled`, which enables log spew to serial console       |
 | `KC.ANY`                | Any key between `A` and `/`                                            |
 | `KC.GESC`               | Escape when tapped, <code>&#96;</code> when pressed with Shift or GUI  |
 | `KC.BKDL`               | Backspace when tapped, Delete when pressed with GUI                    |

diff --git a/kmk/kmk_keyboard.py b/kmk/kmk_keyboard.py
@@ -185,14 +185,6 @@ def _process_resume_buffer(self):
 
         self._resume_buffer_x = buffer
 
-    @property
-    def debug_enabled(self) -> bool:
-        return debug.enabled
-
-    @debug_enabled.setter
-    def debug_enabled(self, enabled: bool):
-        debug.enabled = enabled
-
     def pre_process_key(
         self,
         key: Key,

diff --git a/tests/keyboard_test.py b/tests/keyboard_test.py
@@ -9,6 +9,9 @@
 from kmk.kmk_keyboard import KMKKeyboard
 from kmk.scanners import DiodeOrientation
 from kmk.scanners.digitalio import MatrixScanner
+from kmk.utils import Debug
+
+debug = Debug(__name__)
 
 
 class DigitalInOut(Mock):
@@ -39,7 +42,8 @@ def __init__(
         self.debug_enabled = debug_enabled
 
         self.keyboard = KMKKeyboard()
-        self.keyboard.debug_enabled = keyboard_debug_enabled
+        if keyboard_debug_enabled:
+            debug.enabled = True
 
         self.keyboard.modules = modules
         self.keyboard.extensions = extensions