update and add docs to serialace

docs/README.md

@@ -29,6 +29,7 @@
 - [Mouse keys](mouse_keys.md): Adds mouse keycodes
 - [OneShot](oneshot.md): Adds support for oneshot/sticky keys.
 - [Power](power.md): Power saving features. This is mostly useful when on battery power.
+- [SerialACE](serialace.md): Arbitrary Code Execution over the data serial.
 - [Split](split_keyboards.md): Keyboards split in two. Seems ergonomic!
 - [TapDance](tapdance.md): Different key actions depending on how often it is pressed.
 

docs/modules.md

@@ -16,6 +16,7 @@ when tapped, and modifier when held.
 - [OneShot](oneshot.md): Adds support for oneshot/sticky keys.
 - [Power](power.md): Power saving features. This is mostly useful when on battery power.
 - [Split](split_keyboards.md): Keyboards split in two. Seems ergonomic!
+- [SerialACE](serialace.md): Arbitrary Code Execution over the data serial.
 - [TapDance](tapdance.md): Different key actions depending on how often it is pressed.
 - [Dynamic Sequences](dynamic_sequences.md): Records a sequence of keypresses and plays it back.
 

docs/serialace.md

@@ -0,0 +1,51 @@
+# Serial ACE (Arbitrary Code Execution over serial interface)
+
+> Caution: This module allows unrestricted, arbitrary code execution on your KMK
+> device. That includes potential exploits, such as keyloggers, and unvetted
+> user code that may result in undesired behaviour and/or crashes.
+> This feature is purely experimental in the sense that you probably neither
+> want nor should use it in production.
+> Advanced knowledge of python and the serial console is required, and we will
+> not provide help or support in any way.
+
+This module provides an API to run any valid python code on your keyboard and
+return the result of that code via an additional serial consol (not the one you
+use for the circuitpython debugger).
+
+
+## Prerequisite
+
+Enable the data serial in `boot.py`:
+```python
+import usb_cdc
+usb_cdc.enable(data=True)
+```
+
+
+## Example
+
+Enable the module, just as any other module else:
+```
+from kmk.modules.serialace import SerialACE
+keyboard.modules.append(SerialACE())
+```
+
+Assume the data serial is on `/dev/ttyACM1`.
+Depending on your OS settings, it bay be necessary to explicitly set the serial
+device to raw transmission, no echo:
+```bash
+stty -F /dev/ttyACM1 raw -echo
+```
+
+### Get the List of Active Layers
+```bash
+$ echo "keyboard.active_layers" > /dev/ttyACM1
+$ cat /dev/ttyACM1
+[0]
+```
+
+### "Tap" a Key
+```bash
+$ echo "exec('from kmk.keys import KC; keyboard.tap_key(KC.Y)')" > /dev/ttyACM1
+$ y
+```

kmk/modules/serialace.py

@@ -1,8 +1,9 @@
 from usb_cdc import data
 
 from kmk.modules import Module
+from kmk.utils import Debug
 
-debug_enabled = False
+debug = Debug(__name__)
 
 
 class SerialACE(Module):
@@ -39,17 +40,18 @@ class SerialACE(Module):
         if idx == -1:
             return
 
-        # Split off command and evaluate
+        # Split off command and evaluate.
         line = self.buffer[:idx]
         self.buffer = self.buffer[idx + 1 :]
+
         try:
-            if debug_enabled:
+            if debug.enabled:
-                print(f'SerialACE eval({line})')
+                debug(f'eval({line})')
             ret = eval(line, {'keyboard': keyboard})
             data.write(bytearray(str(ret) + '\n'))
         except Exception as err:
-            if debug_enabled:
+            if debug.enabled:
-                print(f'SerialACE error({err})')
+                debug(f'error: {err}')
 
     def after_hid_send(self, keyboard):
         pass