some docs / comments

2 files changed, 83 insertions, 0 deletions

diff --git a/README.md b/README.md
index 46b7223..bb58bd2 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,67 @@
 # Dakkar's Keyboardio Model 01 Firmware
+
+This is mostly a stripped-down version of the official firmware, with
+custom keymaps and two custom plugins.
+
+## Keymaps
+
+The keymaps are in [`keymaps.h`](keymaps.h), which should not be
+included directly. [`#include "keymap-wrapper.h"`](keymap-wrapper.h)
+instead! The wrapper defines the (hacky) `ColorKeymaps` macro that
+transposes the array-of-pairs keymaps into pair-of-arrays (actual
+keymap, color map).
+
+This allows me to define, next to each key, what "class" of key it is,
+and therefore which colour its LED should light up. The classes are
+defined in [`key-classes.h`](key-classes.h), and the corresponding
+colours in [`color-themes.h`](color-themes.h).
+
+## Macros
+
+The only non-trivial macro is [`fvwmMacro`](macros.h): it selects the
+`FVWM` layer, and also acts as the `LeftAlt` key.
+
+This is because all the functions of my window manager (fvwm2) are
+accessed with key combinations using the left "alt" key, for which I
+have a dedicated layout, plus I need alt-tab to switch to a different
+window, and that needs left-alt to stay pressed.
+
+## Plugins
+
+### DakkarColor
+
+Source: [`DakkarColor.h`](DakkarColor.h)
+
+This plugin defines a `LEDMode` sub class, which uses a color map as
+built by `keymap-wrapper.h` to assign each key its color.
+
+In addition to simple colors, it allows you to set a function pointer
+(look at the `num-breathe()` function in `color-themes.h` for a
+minimal example).
+
+### ColorPicker
+
+Source [`color-picker.h`](color-picker.h)
+
+This plugin defines a `LEDMode` subclass that, when selected, takes
+over all key presses, and turns half the keyboard into a control panel
+to paint the other half.
+
+The Fn (palm) keys switch into editing mode, with that half housing
+the controls.
+
+The controls are:
+
+* the keys of the 2 outermost columns show the value of the 8 colors
+  in the palette; pressing one selects the color
+* 3 rows of 4 keys to change the selected color in the HSV space (one
+  row for H, one for S, one for V; in each row the keys do -10 -1 +1
+  +10)
+
+Pressing a key on the non-control half of the keyboard assigns the
+selected color to that key.
+
+The plugin also defines a Focus (serial control protocol) command
+`color-picker.dump` which prints the current values of the 8 colors,
+and a compact color map for the keys.
+
diff --git a/keymap-wrapper.h b/keymap-wrapper.h
index 87326ca..9418ebb 100644
--- a/keymap-wrapper.h
+++ b/keymap-wrapper.h
@@ -4,6 +4,23 @@
 #include "Kaleidoscope-MouseKeys.h"
 #include "keymap-layers.h"
 
+/* hack hack hack!
+
+   for each layer, we need 2 arrays: one for the keys, one for the
+   colours. But we want to defined each key next to its
+   colour. Therefore we write our keymap using the CK and ColorKeymaps
+   macros, and include this file.
+
+   First, we define CK as "return the first argument (the key)", and
+   ColorKeymaps as "a klaeidoscope keymap", and include our keymaps
+   definition.
+
+   Then, we *redefine* CK as "return the second argument (the colour)"
+   and ColorKeymaps as "a DakkarColor color map", and include our
+   keymaps definition *again* (make sure you don't add a `#pragma
+   "once"` in there!)
+ */
+
 #define CK(k,c) k
 
 #define ColorKeymaps(layers...) KEYMAPS(layers)