Merge remote-tracking branch 'plugin/EEPROM-Keymap-Programmer/f/monorepo' into f/monorepo-stage2

doc/plugin/EEPROM-Keymap-Programmer.md

@@ -0,0 +1,124 @@
+# Kaleidoscope-EEPROM-Keymap-Programmer
+
+Inspired by a similar feature on other keyboards, the `EEPROM-Keymap-Programmer`
+plugin implements an on-device keymap re-arrangement / re-coding system. There
+are two modes of operation: in one, we need to press a key we want to change,
+then another to copy from. In the other, we press a key to change, and then
+input a key code (terminated by any non-number key).
+
+## The two modes of operation
+
+It is worth looking at the two separately, to better understand how they work,
+and what they accomplish:
+
+### Copy mode
+
+In `COPY` mode, the plugin will use both the built-in, default keymap, and the
+override stored in `EEPROM`. When we select a key to override, we need to tap
+another, which will be used as the source. The source key's code will be looked
+up from the built-in keymap. For example, lets say we want to swap `A` and `B`
+for some odd reason. We can do this by triggering the keymap programmer mode,
+then tapping `A` to select it as the destination, then `B` as the source. The
+plugin will look up the keycode in the built-in keymap for the key in `B`'s
+location, and replace the location of `A` in the override with it. Next, we
+press the `B` key to select it as the destination, and we press the key that
+used to be `A` (but is now `B` too) to select it as a source. Because source
+keys are looked up in the built-in keymap, the plugin will find it is `A`.
+
+Obviously, this method only works if we have a built-in keymap, and it does not
+support copying from another layer. It is merely a way to rearrange simple
+things, like alphanumerics.
+
+### Code mode
+
+In `CODE` mode, instead of selecting a source key, we need to enter a code:
+press numbers to input the code, and any non-number key to end the sequence.
+Thus, when entering keymap programmer mode, and selecting, say, the `A` key,
+then tapping `5 SPACE` will set the key to `B` (which has the keycode of `5`).
+
+This allows us to use keycodes not present on the built-in keymap, at the
+expense of having to know the keycode, and allowing no mistakes.
+
+## Using the plugin
+
+Adding the functionality of the plugin to a Sketch is easier the usage explained
+above, though it requires that the [EEPROM-Keymap][plugin:eeprom-keymap] plugin
+is also used, and set up appropriately.
+
+Once the prerequisites are dealt with, all we need to do is to use the plugin,
+and find a way to trigger entering the keymap programmer mode. One such way is
+to use a macro, as in the example below:
+
+```c++
+#include <Kaleidoscope.h>
+#include <Kaleidoscope-EEPROM-Keymap.h>
+#include <Kaleidoscope-EEPROM-Keymap-Programmer.h>
+#include <Kaleidoscope-EEPROM-Settings.h>
+#include <Kaleidoscope-Macros.h>
+
+const macro_t *macroAction(uint8_t macroIndex, uint8_t keyState) {
+  if (macroIndex == 0 && keyToggledOff(keyState)) {
+    EEPROMKeymapProgrammer.activate();
+  }
+
+  return MACRO_NONE;
+}
+
+KALEIDOSCOPE_INIT_PLUGINS(EEPROMSettings,
+                          EEPROMKeymapProgrammer,
+                          EEPROMKeymap,
+                          Macros);
+
+void setup() {
+  Kaleidoscope.setup();
+
+  Layer.getKey = EEPROMKeymap.getKey;
+
+  EEPROMKeymap.max_layers(1);
+  EEPROMSettings.seal();
+}
+```
+
+The plugin should be used as early as possible, otherwise other plugins that
+hook into the event system may start processing events before the programmer can
+take over.
+
+## Plugin methods
+
+The plugin provides the `EEPROMKeymapProgrammer` object, which has the following
+methods and properties:
+
+### `.activate()`
+
+> Activates the keymap programmer. This is the function one needs to call from -
+> say - a macro, to enter the edit state.
+
+### `.mode`
+
+> Set this property to the mode to use for editing: either
+> `kaleidoscope::EEPROMKeymapProgrammer::COPY`, or
+> `kaleidoscope::EEPROMKeymapProgrammer::CODE`.
+>
+> Defaults to `kaleidoscope::EEPROMKeymapProgrammer::CODE`.
+
+## Focus commands
+
+The plugin provides a single `Focus` hook: `FOCUS_HOOK_KEYMAP_PROGRAMMER`, which
+in turn provides the following command:
+
+### `keymap.toggleProgrammer`
+
+> Toggles the programmer mode on or off.
+
+## Dependencies
+
+* [Kaleidoscope-EEPROM-Keymap][plugin:eeprom-keymap]
+
+  [plugin:eeprom-keymap]: EEPROM-Keymap.md
+
+## Further reading
+
+Starting from the [example][plugin:example] is the recommended way of getting
+started with the plugin.
+
+  [plugin:example]: ../../examples/EEPROM-Keymap-Programmer/EEPROM-Keymap-Programmer.ino

examples/EEPROM-Keymap-Programmer/EEPROM-Keymap-Programmer.ino

@@ -0,0 +1,71 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-EEPROM-Keymap-Programmer -- On-the-fly reprogrammable keymap.
+ * Copyright (C) 2017, 2018  Keyboard.io, Inc
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License as published by the Free Software
+ * Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include <Kaleidoscope.h>
+#include <Kaleidoscope-EEPROM-Settings.h>
+#include <Kaleidoscope-EEPROM-Keymap.h>
+#include <Kaleidoscope-EEPROM-Keymap-Programmer.h>
+#include <Kaleidoscope-Macros.h>
+
+// *INDENT-OFF*
+const Key keymaps[][ROWS][COLS] PROGMEM = {
+  [0] = KEYMAP_STACKED
+  (M(0),              Key_1, Key_2, Key_3, Key_4, Key_5, Key_NoKey,
+   Key_Backtick,      Key_Q, Key_W, Key_E, Key_R, Key_T, Key_Tab,
+   Key_PageUp,        Key_A, Key_S, Key_D, Key_F, Key_G,
+   Key_PageDown,      Key_Z, Key_X, Key_C, Key_V, Key_B, Key_Escape,
+
+   Key_LeftControl, Key_Backspace, Key_LeftGui, Key_LeftShift,
+   Key_NoKey,
+
+   Key_skip,  Key_6, Key_7, Key_8,     Key_9,      Key_0,         Key_skip,
+   Key_Enter, Key_Y, Key_U, Key_I,     Key_O,      Key_P,         Key_Equals,
+              Key_H, Key_J, Key_K,     Key_L,      Key_Semicolon, Key_Quote,
+   Key_skip,  Key_N, Key_M, Key_Comma, Key_Period, Key_Slash,     Key_Minus,
+
+   Key_RightShift, Key_RightAlt, Key_Spacebar, Key_RightControl,
+   Key_NoKey),
+};
+// *INDENT-ON*
+
+const macro_t *macroAction(uint8_t macroIndex, uint8_t keyState) {
+  if (macroIndex == 0 && keyToggledOff(keyState)) {
+    EEPROMKeymapProgrammer.activate();
+  }
+
+  return MACRO_NONE;
+}
+
+KALEIDOSCOPE_INIT_PLUGINS(EEPROMSettings,
+                          EEPROMKeymapProgrammer,
+                          EEPROMKeymap,
+                          Macros);
+
+void setup() {
+  Serial.begin(9600);
+
+  Kaleidoscope.setup();
+
+  Layer.getKey = EEPROMKeymap.getKey;
+
+  EEPROMKeymap.max_layers(1);
+  EEPROMSettings.seal();
+}
+
+void loop() {
+  Kaleidoscope.loop();
+}

src/Kaleidoscope-EEPROM-Keymap-Programmer.h

@@ -0,0 +1,20 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-EEPROM-Keymap-Programmer -- On-the-fly reprogrammable keymap.
+ * Copyright (C) 2017  Keyboard.io, Inc
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License as published by the Free Software
+ * Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include <kaleidoscope/plugin/EEPROM-Keymap-Programmer.h>

src/kaleidoscope/plugin/EEPROM-Keymap-Programmer.cpp

@@ -0,0 +1,119 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-EEPROM-Keymap-Programmer -- On-the-fly reprogrammable keymap.
+ * Copyright (C) 2017, 2018  Keyboard.io, Inc
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License as published by the Free Software
+ * Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include <Kaleidoscope-EEPROM-Keymap-Programmer.h>
+#include <Kaleidoscope-FocusSerial.h>
+
+namespace kaleidoscope {
+namespace plugin {
+uint16_t EEPROMKeymapProgrammer::update_position_;
+EEPROMKeymapProgrammer::state_t EEPROMKeymapProgrammer::state_;
+EEPROMKeymapProgrammer::mode_t EEPROMKeymapProgrammer::mode;
+Key EEPROMKeymapProgrammer::new_key_;
+
+void EEPROMKeymapProgrammer::nextState(void) {
+  switch (state_) {
+  case INACTIVE:
+    state_ = WAIT_FOR_KEY;
+    break;
+  case WAIT_FOR_KEY:
+    if (mode == CODE)
+      state_ = WAIT_FOR_CODE;
+    else
+      state_ = WAIT_FOR_SOURCE_KEY;
+    break;
+  case WAIT_FOR_CODE:
+  case WAIT_FOR_SOURCE_KEY:
+    ::EEPROMKeymap.updateKey(update_position_, new_key_);
+    cancel();
+    break;
+  }
+}
+
+void EEPROMKeymapProgrammer::cancel(void) {
+  update_position_ = 0;
+  new_key_ = Key_NoKey;
+  state_ = INACTIVE;
+}
+
+EventHandlerResult EEPROMKeymapProgrammer::onKeyswitchEvent(Key &mapped_key, byte row, byte col, uint8_t key_state) {
+  if (state_ == INACTIVE)
+    return EventHandlerResult::OK;
+
+  if (state_ == WAIT_FOR_KEY) {
+    if (keyToggledOn(key_state)) {
+      update_position_ = Layer.top() * ROWS * COLS + row * COLS + col;
+    }
+    if (keyToggledOff(key_state)) {
+      if ((uint16_t)(Layer.top() * ROWS * COLS + row * COLS + col) == update_position_)
+        nextState();
+    }
+    return EventHandlerResult::EVENT_CONSUMED;
+  }
+
+  if (state_ == WAIT_FOR_SOURCE_KEY) {
+    if (keyToggledOn(key_state)) {
+      new_key_ = Layer.getKeyFromPROGMEM(Layer.top(), row, col);
+    }
+    if (keyToggledOff(key_state)) {
+      if (new_key_ == Layer.getKeyFromPROGMEM(Layer.top(), row, col))
+        nextState();
+    }
+    return EventHandlerResult::EVENT_CONSUMED;
+  }
+
+  // WAIT_FOR_CODE state
+
+  if (mapped_key < Key_1 || mapped_key > Key_0)
+    return EventHandlerResult::OK;
+
+  if (!keyToggledOn(key_state)) {
+    return EventHandlerResult::EVENT_CONSUMED;
+  }
+
+  uint8_t n;
+  if (mapped_key.keyCode == Key_0.keyCode)
+    n = 0;
+  else
+    n = mapped_key.keyCode - Key_1.keyCode + 1;
+
+  new_key_.raw = new_key_.raw * 10 + n;
+
+  return EventHandlerResult::EVENT_CONSUMED;
+}
+
+EventHandlerResult EEPROMKeymapProgrammer::onFocusEvent(const char *command) {
+  const char *cmd = PSTR("keymap.toggleProgrammer");
+
+  if (::Focus.handleHelp(command, cmd))
+    return EventHandlerResult::OK;
+
+  if (strcmp_P(command, cmd) != 0)
+    return EventHandlerResult::OK;
+
+  if (state_ == INACTIVE)
+    activate();
+  else
+    cancel();
+
+  return EventHandlerResult::EVENT_CONSUMED;
+}
+
+}
+}
+
+kaleidoscope::plugin::EEPROMKeymapProgrammer EEPROMKeymapProgrammer;

src/kaleidoscope/plugin/EEPROM-Keymap-Programmer.h

@@ -0,0 +1,59 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-EEPROM-Keymap-Programmer -- On-the-fly reprogrammable keymap.
+ * Copyright (C) 2017, 2018  Keyboard.io, Inc
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License as published by the Free Software
+ * Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include <Kaleidoscope.h>
+#include <Kaleidoscope-EEPROM-Keymap.h>
+
+namespace kaleidoscope {
+namespace plugin {
+class EEPROMKeymapProgrammer : public kaleidoscope::Plugin {
+ public:
+  typedef enum {
+    CODE,
+    COPY,
+  } mode_t;
+  static mode_t mode;
+
+  EEPROMKeymapProgrammer(void) {}
+
+  static void activate(void) {
+    nextState();
+  }
+  static void nextState(void);
+  static void cancel(void);
+
+  EventHandlerResult onKeyswitchEvent(Key &mapped_key, byte row, byte col, uint8_t key_state);
+  EventHandlerResult onFocusEvent(const char *command);
+
+ private:
+  typedef enum {
+    INACTIVE,
+    WAIT_FOR_KEY,
+    WAIT_FOR_CODE,
+    WAIT_FOR_SOURCE_KEY,
+  } state_t;
+  static state_t state_;
+
+  static uint16_t update_position_;  // layer, row, col
+  static Key new_key_;
+};
+}
+}
+
+extern kaleidoscope::plugin::EEPROMKeymapProgrammer EEPROMKeymapProgrammer;