Merge pull request #1206 from keyboardio/plugin/layernames

New plugin: LayerNames

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

@@ -94,6 +94,9 @@ class FocusSerial : public kaleidoscope::Plugin {
     color.g = Runtime.serialPort().parseInt();
     color.b = Runtime.serialPort().parseInt();
   }
+  void read(char &c) {
+    c = static_cast<char>(Runtime.serialPort().read());
+  }
   void read(uint8_t &u8) {
     u8 = Runtime.serialPort().parseInt();
   }

plugins/Kaleidoscope-LayerNames/README.md

@@ -0,0 +1,75 @@
+# LayerNames
+
+This plugin provides a [Focus][plugin:focus]-based interface for storing custom
+layer names, to be used by software such as [Chrysalis][chrysalis]. The firmware
+itself does nothing with the layer names, 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 names. This is
+best illustrated with an example:
+
+```c++
+#include <Kaleidoscope.h>
+#include <Kaleidoscope-EEPROMSettings.h>
+#include <Kaleidoscope-FocusSerial.h>
+#include <Kaleidoscope-LayerNames.h>
+
+KALEIDOSCOPE_INIT_PLUGINS(
+  EEPROMSettings,
+  Focus,
+  LayerNames
+);
+
+void setup() {
+  Kaleidoscope.setup();
+
+  LayerNames.reserve_storage(128);
+}
+```
+
+## Plugin methods
+
+The plugin provides a `LayerNames` object, with the following method available:
+
+### `.reserve_storage(size)`
+
+> Reserves `size` bytes of storage for layer names. This must be called from the
+> `setup()` method of your sketch.
+
+## Focus commands
+
+The plugin provides a single Focus command: `keymap.layerNames`.
+
+### `keymap.layerNames [name_length name]...`
+
+> Without arguments, displays all the stored layer names. Each layer is printed
+> on its own line, preceded by its length. At the end, the plugin will also
+> print an extra line with a name length of zero, followed by the string
+> "size=", and then the total size of the storage reserved for layer names.
+>
+> To set custom names, a list of length & name pairs must be given. The plugin
+> stops processing arguments when it encounters a name length of 0.
+
+#### Example
+
+```
+> keymap.layerNames
+< 6 Qwerty
+< 6 Numpad
+< 8 Function
+< 0 size=128
+< .
+
+> keymap.layerNames 6 Dvorak 6 Numpad 8 Function 0
+< .
+```
+
+## Dependencies
+
+* [Kaleidoscope-EEPROM-Settings](Kaleidoscope-EEPROM-Settings.md)
+* [Kaleidoscope-FocusSerial](Kaleidoscope-FocusSerial.md)

plugins/Kaleidoscope-LayerNames/library.properties

@@ -0,0 +1,7 @@
+name=Kaleidoscope-LayerNames
+version=0.0.0
+sentence=Kaleidoscope plugin that lets one set custom layer names
+maintainer=Kaleidoscope's Developers <jesse@keyboard.io>
+url=https://github.com/keyboardio/Kaleidoscope
+author=Keyboardio
+paragraph=

plugins/Kaleidoscope-LayerNames/src/Kaleidoscope-LayerNames.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/LayerNames.h"  // IWYU pragma: export

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

@@ -0,0 +1,96 @@
+/* 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/LayerNames.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 LayerNames::onNameQuery() {
+  return ::Focus.sendName(F("LayerNames"));
+}
+
+EventHandlerResult LayerNames::onFocusEvent(const char *command) {
+  if (::Focus.handleHelp(command, PSTR("keymap.layerNames")))
+    return EventHandlerResult::OK;
+
+  if (strcmp_P(command, PSTR("keymap.layerNames")) != 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;
+
+      ::Focus.send(name_size);
+
+      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, 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;
+
+      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 LayerNames::reserve_storage(uint16_t size) {
+  storage_base_ = ::EEPROMSettings.requestSlice(size);
+  storage_size_ = size;
+}
+
+}  // namespace plugin
+}  // namespace kaleidoscope
+
+kaleidoscope::plugin::LayerNames LayerNames;

plugins/Kaleidoscope-LayerNames/src/kaleidoscope/plugin/LayerNames.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 LayerNames : 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::LayerNames LayerNames;