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
+```