Remote calls - a simple, resource friendly communication interface

examples/Features/RemoteCall/RemoteCall.ino

@@ -0,0 +1,152 @@
+
+#include "Kaleidoscope.h"
+#include "Kaleidoscope-LEDControl.h"
+
+KEYMAPS(
+  [0] = KEYMAP_STACKED
+        (___,          Key_1, Key_2, Key_3, Key_4, Key_5, ___,
+         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_6, Key_7, Key_8,     Key_9,         Key_0,         ___,
+         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_RightAlt,  Key_N, Key_M, Key_Comma, Key_Period,    Key_Slash,     Key_Minus,
+         Key_RightShift, Key_LeftAlt, Key_Spacebar, Key_RightControl,
+         ___)
+)
+
+
+namespace kaleidoscope {
+namespace plugin {
+class MyPlugin_ : public kaleidoscope::Plugin {
+
+ public:
+  void doSomething() { /* do something */ }
+
+  EventHandlerResult onKeyswitchEvent(Key &mapped_key, KeyAddr key_addr, uint8_t key_state) {
+    return (EventHandlerResult)(a_ + b_);
+  }
+
+  int a_;
+  int b_;
+};
+
+MyPlugin_ MyPlugin;
+}
+}
+
+
+KALEIDOSCOPE_INIT_PLUGINS(
+  kaleidoscope::plugin::MyPlugin
+)
+
+void setup() {
+  Kaleidoscope.setup();
+}
+
+void loop() {
+  Kaleidoscope.loop();
+}
+
+void updateMyPlugin() {
+  kaleidoscope::plugin::MyPlugin.doSomething();
+}
+
+void someFunc() {}
+void someFunc1() {}
+void someFunc2() {}
+
+uint8_t r = 2, g = 3, b = 4, y = 5;
+
+KALEIDOSCOPE_REMOTE_CALL(
+
+  KRC_ROOT_PACKAGE(Package1,
+                   KRC_FUNCTION(setAllLEDs,
+                                KRC_ARGUMENTS(
+                                  (uint8_t, red, KRC_DESCRIPTION("Red portion.")),
+                                  (uint8_t, green, KRC_DESCRIPTION("Green portion.")),
+                                  (uint8_t, blue, KRC_DESCRIPTION("Blue portion."))
+                                )
+                                KRC_RESULTS(
+                                  (uint8_t, res, KRC_DESCRIPTION("Results description."))
+                                )
+                                KRC_FUNCTION_BODY(
+                                  auto args = KRC_ACCESS_ARGS();
+
+                                  using namespace kaleidoscope::plugin;
+                                  LEDControl::set_all_leds_to(args->red, args->green, args->blue);
+                                  LEDControl::syncLeds();
+
+                                  auto results = KRC_ACCESS_RESULTS();
+
+                                  results->res = 42;
+                                )
+                               )
+                  )
+
+  KRC_ROOT_PACKAGE(Level1,
+                   KRC_DESCRIPTION("Level1 description")
+                   // Default update function of package Level1
+                   //
+                   KRC_UPDATE_THROUGH_GLOBAL_FUNCTION(::someFunc2)
+
+                   // A package that exports member variables of a plugin. The update
+                   // functions are expected to be called after the member variable has been
+                   // changed in order for the changes to take effect.
+                   //
+                   // A plugin package is a package that is build around a plugin object.
+                   // The object is used whenever one of the plugin's members is
+                   // accessed through KRC_MEMBER.
+                   //
+                   KRC_PLUGIN(MyPlugin, kaleidoscope::plugin::MyPlugin,
+                              KRC_DESCRIPTION("MyPlugin description")
+                              KRC_MEMBER(a, a_,
+                                  KRC_DESCRIPTION("a issetetdtwdtwdtwdtwset ...")
+                                  // No update function. Will use ::someFunc2 specified by package
+                                  // Level1.
+                                        )
+                              KRC_MEMBER(b, b_,
+                                  KRC_DESCRIPTION("b is ...")
+                                  KRC_UPDATE_THROUGH_GLOBAL_FUNCTION(::updateMyPlugin)
+                                        )
+                             )
+
+                   // Packages can be nested. Here it is Level1::Level2.
+                   //
+                   KRC_PACKAGE(Level2,
+                               KRC_DESCRIPTION("Level2 description.")
+                               KRC_GLOBAL(red, ::r,
+                                   KRC_DESCRIPTION("Red color.")
+                                   // No update function specified. Will use ::someFunc2 from
+                                   // next higher package level Level1.
+                                         )
+                              )
+
+                   // Packages can be continued at any point.
+                   //
+                   KRC_PACKAGE(Level2,
+
+                               // Default update function of package Level1::Level2
+                               //
+                               KRC_UPDATE_THROUGH_GLOBAL_FUNCTION(::someFunc)
+                               KRC_GLOBAL(green, ::g,
+                                   KRC_DESCRIPTION("Green color")
+                                   KRC_UPDATE_THROUGH_GLOBAL_FUNCTION(::someFunc)
+                                         )
+                               KRC_GLOBAL(blue, ::b,
+                                   KRC_DESCRIPTION("Blue color")
+                                   // No update function specified. Will use ::someFunc from
+                                   // next higher package level Level1::Level2.
+                                         )
+                               KRC_GLOBAL(yellow, ::y,
+                                   KRC_DESCRIPTION("Yellow color")
+                                   KRC_NO_UPDATE // Suppresses update function inheritance.
+                                   // yellow does not require an update function.
+                                         )
+                              )
+                  )
+)

src/Kaleidoscope-RemoteCall.h

@@ -0,0 +1,21 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-RemoteCall
+ * Copyright (C) 2016-2020  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/plugin/RemoteCall.h"

src/Kaleidoscope.h

@@ -36,6 +36,11 @@ void setup();
 #include <math.h>
 #include <stdint.h>
 
+// Important: Leave the remote_call header to be the first one in the
+//            include list as other headers might depend upon it.
+//
+#include "kaleidoscope/remote_call.h"
+
 #include "kaleidoscope/version.h"
 #include "kaleidoscope/device/device.h"
 #include "kaleidoscope/device/key_indexes.h"
@@ -121,3 +126,40 @@ typedef kaleidoscope::Runtime_  Kaleidoscope_;
 // Kaleidoscope in global namespace.
 //
 extern kaleidoscope::Runtime_ &Kaleidoscope;
+
+// Have a list of plugins that are always added.
+// Those plugins might be configured by macros defined at the top of the sketch.
+// Plugins can thus be turned into complete no-ops.
+
+// For the sketch compilation unit, we pretend that there is a NoOpPlugin
+// symbol. This is intented to be passed to the KALEIDOSCOPE_INIT_PLUGINS(...)
+// function macro. As no existing non-inline functions of this macro are called
+// for this plugin instance, it does not hurt that the instance is not
+// actually instanciated in no other compilation unit.
+//
+#ifdef KALEIDOSCOPE_SKETCH
+namespace kaleidoscope {
+extern Plugin NoOpPlugin; // This is on purpose not instanciated in any
+// compilation unit.
+} // namespace kaleidoscope
+#endif
+
+// Have a list of plugins that are always added.
+// Those plugins might be configured by macros defined at the top of the sketch.
+// Plugins can thus be turned into complete no-ops.
+//
+#include "kaleidoscope/plugin/RemoteCall.h"
+
+
+// Plugins leading the list passed to KALEIDOSCOPE_INIT_PLUGINS
+//
+#define KALEIDOSCOPE_STANDARD_PLUGINS_START RemoteCall
+
+// Plugins trailing the list passed to KALEIDOSCOPE_INIT_PLUGINS
+//
+// Note: As long as we do not actually pass a plugin to
+//       KALEIDOSCOPE_STANDARD_PLUGINS_END, we need to pass at least
+//       a no-op plugin to satisfy the interface. The NoOpPlugin
+//       can be replaced as soon as other plugins are added.
+//
+#define KALEIDOSCOPE_STANDARD_PLUGINS_END kaleidoscope::NoOpPlugin

src/kaleidoscope/Runtime.cpp

@@ -17,6 +17,7 @@
 #include "kaleidoscope/Runtime.h"
 #include "kaleidoscope/layers.h"
 #include "kaleidoscope/keyswitch_state.h"
+#include "kaleidoscope/remote_call.h"
 
 namespace kaleidoscope {
 
@@ -47,6 +48,10 @@ Runtime_::setup(void) {
   for (auto key_addr : KeyAddr::all()) {
     Layer.updateLiveCompositeKeymap(key_addr);
   }
+
+  // Export any symbols required for remote calls.
+  //
+  _KRC_EXPORT_SYMBOLS
 }
 
 void

src/kaleidoscope/layers.h

@@ -22,6 +22,7 @@
 #include "kaleidoscope/device/device.h"
 #include "kaleidoscope_internal/device.h"
 #include "kaleidoscope_internal/sketch_exploration/sketch_exploration.h"
+#include "kaleidoscope/remote_call.h"
 #include "kaleidoscope_internal/shortname.h"
 
 // Macro for defining the keymap. This should be used in the sketch
@@ -145,3 +146,28 @@ class Layer_ {
 }
 
 extern kaleidoscope::Layer_ Layer;
+
+KALEIDOSCOPE_REMOTE_CALL(
+  KRC_ROOT_PACKAGE(Layer,
+                   KRC_F(activate, KRC_NO_RESULTS, ((uint8_t, layer)),
+                         (Layer.activate(args->layer);),
+                         KRC_DESCRIPTION("Activates a specific layer")
+                        )
+                   KRC_F(deactivate, KRC_NO_RESULTS, ((uint8_t, layer)),
+                         (Layer.deactivate(args->layer);),
+                         KRC_DESCRIPTION("Deactivates a specific layer")
+                        )
+                   KRC_F(activateNext, KRC_NO_RESULTS, KRC_NO_ARGS,
+                         (Layer.activateNext();),
+                         KRC_DESCRIPTION("Activates the next layer")
+                        )
+                   KRC_F(deactivateTop, KRC_NO_RESULTS, KRC_NO_ARGS,
+                         (Layer.deactivateTop();),
+                         KRC_DESCRIPTION("Deactivates top layer")
+                        )
+                   KRC_F(move, KRC_NO_RESULTS, ((uint8_t, layer)),
+                         (Layer.move(args->layer);),
+                         KRC_DESCRIPTION("Moves to layer")
+                        )
+                  )
+)

src/kaleidoscope/plugin/LED-Palette-Theme.cpp

@@ -84,6 +84,13 @@ const cRGB LEDPaletteTheme::lookupPaletteColor(uint8_t color_index) {
   return color;
 }
 
+void LEDPaletteTheme::setPaletteColor(uint8_t palette_index, cRGB color) {
+  color.r ^= 0xff;
+  color.g ^= 0xff;
+  color.b ^= 0xff;
+  Runtime.storage().put(palette_base_ + palette_index * sizeof(color), color);
+}
+
 void LEDPaletteTheme::updateColorIndexAtPosition(uint16_t map_base, uint16_t position, uint8_t color_index) {
   uint8_t indexes;
 

src/kaleidoscope/plugin/LED-Palette-Theme.h

@@ -19,6 +19,7 @@
 
 #include "kaleidoscope/Runtime.h"
 #include <Kaleidoscope-LEDControl.h>
+#include "kaleidoscope/remote_call.h"
 
 namespace kaleidoscope {
 namespace plugin {
@@ -39,6 +40,7 @@ class LEDPaletteTheme : public kaleidoscope::Plugin {
   static void updateColorIndexAtPosition(uint16_t theme_base, uint16_t position, uint8_t color_index);
 
   static const cRGB lookupPaletteColor(uint8_t palette_index);
+  static void setPaletteColor(uint8_t palette_index, cRGB color);
 
   EventHandlerResult onFocusEvent(const char *command);
   EventHandlerResult themeFocusEvent(const char *command,
@@ -53,3 +55,38 @@ class LEDPaletteTheme : public kaleidoscope::Plugin {
 }
 
 extern kaleidoscope::plugin::LEDPaletteTheme LEDPaletteTheme;
+
+KALEIDOSCOPE_REMOTE_CALL(
+  KRC_ROOT_PACKAGE(plugin,
+                   KRC_PACKAGE(LEDPaletteTheme,
+                               KRC_F(getPaletteColor,
+                                     ((uint8_t, red), (uint8_t, green), (uint8_t, blue)),
+                                     ((uint8_t, palette_index)),
+                                     (
+                                       cRGB color;
+                                       color = LEDPaletteTheme.lookupPaletteColor(args->palette_index);
+                                       results->red = color.r;
+                                       results->green = color.g;
+                                       results->blue = color.b;
+                                     ),
+                                     KRC_DESCRIPTION("Retrieves the RGB value of a palette color")
+                                    )
+                               KRC_F(setPaletteColor, KRC_NO_RESULTS,
+                                     ((uint8_t, palette_index), (uint8_t, red), (uint8_t, green), (uint8_t, blue)),
+                                     (
+                                       LEDPaletteTheme.setPaletteColor(args->palette_index,
+                                           cRGB{args->red, args->green, args->blue});
+                                     ),
+                                     KRC_DESCRIPTION("Sets the RGB value of a palette color")
+                                    )
+                               KRC_F(commitPalette, KRC_NO_RESULTS, KRC_NO_ARGS,
+                                     (
+                                       Runtime.storage().commit();
+                                       ::LEDControl.refreshAll();
+                                     ),
+                                     KRC_DESCRIPTION("Sets the RGB value of a palette color")
+                                    )
+                              )
+                  )
+)
+

src/kaleidoscope/plugin/LEDControl.h

@@ -18,6 +18,7 @@
 
 #include "kaleidoscope/Runtime.h"
 #include "kaleidoscope/plugin/LEDMode.h"
+#include "kaleidoscope/remote_call.h"
 
 #define LED_TOGGLE   B00000001  // Synthetic, internal
 
@@ -176,3 +177,25 @@ class FocusLEDCommand : public Plugin {
 
 extern kaleidoscope::plugin::LEDControl LEDControl;
 extern kaleidoscope::plugin::FocusLEDCommand FocusLEDCommand;
+
+KALEIDOSCOPE_REMOTE_CALL(
+  KRC_ROOT_PACKAGE(plugin,
+                   KRC_PACKAGE(LEDControl,
+                               KRC_F(setCrgbAt, KRC_NO_RESULTS,
+                                     ((uint8_t, row), (uint8_t, col),
+                                      (uint8_t, red), (uint8_t, green), (uint8_t, blue)),
+                                     (LEDControl.setCrgbAt(KeyAddr{args->row, args->col},
+                                         CRGB(args->red, args->green, args->blue));),
+                                     KRC_DESCRIPTION("Sets the LED color of a single key")
+                                    )
+                               KRC_F(setMode, KRC_NO_RESULTS, ((uint8_t, mode_id)),
+                                     (LEDControl.set_mode(args->mode_id);),
+                                     KRC_DESCRIPTION("Sets the LED mode")
+                                    )
+                               KRC_F(getMode, ((uint8_t, mode_id)), KRC_NO_ARGS,
+                                     (results->mode_id = LEDControl.get_mode_index();),
+                                     KRC_DESCRIPTION("Queries the LED mode")
+                                    )
+                              )
+                  )
+)