[wip] New plugin: CustomKeyLabels

Modeled after LayerNames, this plugin lets Chrysalis use custom key labels for
any key we can put on the keymap.

Addresses the Kaleidoscope part of keyboardio/Chrysalis#983.

Signed-off-by: Gergely Nagy <[email protected]>

plugins/Kaleidoscope-CustomKeyLabels/README.md

@@ -0,0 +1,75 @@
+# CustomKeyLabels
+
+This plugin provides a [Focus][plugin:focus]-based interface for storing custom
+key labels, to be used by software such as [Chrysalis][chrysalis]. The firmware
+itself does nothing with the labels, it is purely for use by applications on the
+host side.
+
+ [chrysalis]: https://github.com/keyboardio/Chrysalis
+
+## Using the plugin
+
+To use the plugin, we need to include the header, initialize the plugin with
+`KALEIDOSCOPE_INIT_PLUGINS()`, and reserve storage space for the labels. This is
+best illustrated with an example:
+
+```c++
+#include <Kaleidoscope.h>
+#include <Kaleidoscope-EEPROMSettings.h>
+#include <Kaleidoscope-FocusSerial.h>
+#include <Kaleidoscope-CustomKeyLabels.h>
+
+KALEIDOSCOPE_INIT_PLUGINS(
+  EEPROMSettings,
+  Focus,
+  CustomKeyLabels
+);
+
+void setup() {
+  Kaleidoscope.setup();
+
+  CustomKeyLabels.reserve_storage(1024);
+}
+```
+
+## Plugin methods
+
+The plugin provides a `CustomKeyLabels` object, with the following method available:
+
+### `.reserve_storage(size)`
+
+> Reserves `size` bytes of storage for custom key labels. This must be called
+> from the `setup()` method of your sketch.
+
+## Focus commands
+
+The plugin provides a single Focus command: `keymap.labels`.
+
+### `keymap.labels [name_length key_code labelJSON]...`
+
+> Without arguments, displays all the stored custom key labels. Each label is
+> printed on its own line, preceded by its length and the key code the label is
+> for. At the end the plugin will also print an extra line with name length and
+> key code set to zero, followed by the string "size=", and then the total size
+> of the storage reserved for custom labels.
+>
+> To set custom labels, a list of length, keycode & label triplets must be
+> given. The plugin stops processing arguments when it encounters a name length
+> of 0.
+
+#### Example
+
+```
+> keymap.labels
+< 14 4 {"base":"foo"}
+< 0 0 size=1024
+< .
+
+> keymap.labels 14 4 {"base":"foo"}
+< .
+```
+
+## Dependencies
+
+* [Kaleidoscope-EEPROM-Settings](Kaleidoscope-EEPROM-Settings.md)
+* [Kaleidoscope-FocusSerial](Kaleidoscope-FocusSerial.md)

plugins/Kaleidoscope-CustomKeyLabels/library.properties

@@ -0,0 +1,7 @@
+name=Kaleidoscope-CustomKeyLabels
+version=0.0.0
+sentence=Kaleidoscope plugin that lets one set custom key labels
+maintainer=Kaleidoscope's Developers <[email protected]>
+url=https://github.com/keyboardio/Kaleidoscope
+author=Keyboardio
+paragraph=

plugins/Kaleidoscope-CustomKeyLabels/src/Kaleidoscope-CustomKeyLabels.h

@@ -0,0 +1,19 @@
+/* Kaleidoscope - Firmware for computer input devices
+ * Copyright (C) 2022  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/CustomKeyLabels.h"  // IWYU pragma: export

plugins/Kaleidoscope-CustomKeyLabels/src/kaleidoscope/plugin/CustomKeyLabels.cpp

@@ -0,0 +1,107 @@
+/* Kaleidoscope - Firmware for computer input devices
+ * Copyright (C) 2022  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/plugin/CustomKeyLabels.h"
+
+#include <Arduino.h>                   // for delay, PSTR, strcmp_P, F, __FlashStri...
+#include <Kaleidoscope-FocusSerial.h>  // for Focus, FocusSerial
+
+#include "kaleidoscope/Runtime.h"                 // for Runtime, Runtime_
+#include "kaleidoscope/plugin/EEPROM-Settings.h"  // for EEPROMSettings
+
+namespace kaleidoscope {
+namespace plugin {
+
+// =============================================================================
+
+EventHandlerResult CustomKeyLabels::onNameQuery() {
+  return ::Focus.sendName(F("CustomKeyLabels"));
+}
+
+EventHandlerResult CustomKeyLabels::onFocusEvent(const char *command) {
+  if (::Focus.handleHelp(command, PSTR("keymap.labels")))
+    return EventHandlerResult::OK;
+
+  if (strcmp_P(command, PSTR("keymap.labels")) != 0)
+    return EventHandlerResult::OK;
+
+  if (::Focus.isEOL()) {
+    uint16_t pos = 0;
+    while (pos < storage_size_) {
+      uint8_t name_size = Runtime.storage().read(storage_base_ + pos++);
+
+      if (name_size == 0 || name_size == 255) break;
+
+      uint16_t key_code;
+      Runtime.storage().get(storage_base_ + pos, key_code);
+      pos += 2;
+
+      ::Focus.send(name_size, key_code);
+
+      for (uint8_t i = 0; i < name_size; i++) {
+        uint8_t b = Runtime.storage().read(storage_base_ + pos++);
+        ::Focus.sendRaw(static_cast<char>(b));
+      }
+      ::Focus.sendRaw(::Focus.NEWLINE);
+    }
+    ::Focus.sendRaw(0, ::Focus.SEPARATOR, 0, ::Focus.SEPARATOR, F("size="), storage_size_);
+  } else {
+    uint16_t pos = 0;
+
+    while (pos < storage_size_) {
+      uint8_t name_size;
+      ::Focus.read(name_size);
+
+      // size is followed by a space, ignore that.
+      char spc;
+      ::Focus.read(spc);
+
+      Runtime.storage().update(storage_base_ + pos++, name_size);
+
+      if (name_size == 0 ||
+          name_size == ::EEPROMSettings.EEPROM_UNINITIALIZED_BYTE)
+        break;
+
+      uint16_t key_code;
+      ::Focus.read(key_code);
+      Runtime.storage().put(storage_base_ + pos, key_code);
+      pos += 2;
+
+      ::Focus.read(spc);
+
+      for (uint8_t i = 0; i < name_size; i++) {
+        char c;
+        ::Focus.read(c);
+
+        Runtime.storage().update(storage_base_ + pos++, c);
+      }
+    }
+    Runtime.storage().commit();
+  }
+
+  return EventHandlerResult::EVENT_CONSUMED;
+}
+
+// public
+void CustomKeyLabels::reserve_storage(uint16_t size) {
+  storage_base_ = ::EEPROMSettings.requestSlice(size);
+  storage_size_ = size;
+}
+
+}  // namespace plugin
+}  // namespace kaleidoscope
+
+kaleidoscope::plugin::CustomKeyLabels CustomKeyLabels;

plugins/Kaleidoscope-CustomKeyLabels/src/kaleidoscope/plugin/CustomKeyLabels.h

@@ -0,0 +1,42 @@
+/* Kaleidoscope - Firmware for computer input devices
+ * Copyright (C) 2022  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 <stdint.h>  // for uint16_t, uint8_t
+
+#include "kaleidoscope/event_handler_result.h"  // for EventHandlerResult
+#include "kaleidoscope/plugin.h"                // for Plugin
+
+namespace kaleidoscope {
+namespace plugin {
+
+class CustomKeyLabels : public kaleidoscope::Plugin {
+ public:
+  EventHandlerResult onNameQuery();
+  EventHandlerResult onFocusEvent(const char *command);
+
+  void reserve_storage(uint16_t size);
+
+ private:
+  uint16_t storage_base_;
+  uint16_t storage_size_;
+};
+
+}  // namespace plugin
+}  // namespace kaleidoscope
+
+extern kaleidoscope::plugin::CustomKeyLabels CustomKeyLabels;