IdleLEDs: Optional support for EEPROM-Storage & Focus

Having to recompile and re-flash firmware to set the idle timeout of the plugin
isn't a fun or desired experience. It's fine when one already figured out the
timeout they want, and have no desire to change it. For everyone else, being
able to configure it at run-time via Focus, and have it persist to EEPROM is a
much nicer experience.

This change adds an alternative version of the plugin, `PersistentIdleLEDs`, a
subclass of the original one. This one provides the focus command and
persistence. It's a child class, because that results in a smaller footprint
than a separate plugin that calls the `IdleLEDs` object.

The code borrows from - but is not wire-compatible with - Dygma's implementation
by @mattvenn.

Signed-off-by: Gergely Nagy <algernon@keyboard.io>

doc/plugin/IdleLEDs.md

@@ -34,10 +34,35 @@ Because the plugin needs to know about key events, it is best to make it one of
 the first plugins, so it can catch all of them, before any other plugin would
 have a chance to consume key events.
 
+It is also possible to enable run-time configuration via he `Focus` plugin, and
+persistent storage of such settings. To do that, one has to use the
+`PersistentIdleLEDs` object instead, provided by the plugin:
+
+```c++
+#include <Kaleidoscope.h>
+#include <Kaleidoscope-LEDControl.h>
+#include <Kaleidoscope-LEDEffect-Rainbow.h>
+#include <Kaleidoscope-EEPROM-Settings.h>
+#include <Kaleidoscope-FocusSerial.h>
+#include <Kaleidoscope-IdleLEDs.h>
+
+KALEIDOSCOPE_INIT_PLUGINS(
+  EEPROMSettings,
+  Focus,
+  LEDControl,
+  PersistentIdleLEDs,
+  LEDEffectRainbowWave
+);
+
+void setup (void) {
+  Kaleidoscope.setup ();
+}
+```
+
 ## Plugin Properties
 
-The plugin provides a single object, `IdleLEDs`, with the following properties
+The plugin provides two objects, `IdleLEDs`, and `PersistentIdleLEDs`, both with
-and methods.
+the following properties and methods.
 
 ### `.idle_time_limit`
 
@@ -48,7 +73,9 @@ and methods.
 > Defaults to 600000 milliseconds (10 minutes).
 
 > Provided for compatibility reasons. It is recommended to use one of the
-> methods below instead of setting this property directly.
+> methods below instead of setting this property directly. If using
+> `PersistentIdleLEDs`, setting this property will not persist the value to
+> storage. Use `.seetIdleTimeoutSeconds()` if persistence is desired.
 
 ### `.idleTimeoutSeconds()`
 
@@ -61,10 +88,27 @@ and methods.
 > Sets the amount of time (in seconds) that can pass without a single key being
 > pressed before the plugin considers the keyboard idle and turns off the LEDs.
 
+## Focus commands
+
+The plugin provides a single [Focus][FocusSerial] command, but only when using
+the `PersistentIdleLEDs` variant:
+
+ [FocusSerial]: FocusSerial.md
+
+### `idleleds.time_limit [seconds]`
+
+> Sets the idle time limit to `seconds`, when called with an argument. Returns
+> the current limit (in seconds) when called without any.
+
 ## Dependencies
 
 * [Kaleidoscope-LEDControl](LEDControl.md)
 
+### Optional dependencies
+
+* [Kaleidoscope-EEPROM-Settings](EEPROM-Settings.md)
+* [FocusSerial](FocusSerial.md)
+
 ## Further reading
 
 Starting from the [example][plugin:example] is the recommended way of getting

examples/LEDs/IdleLEDs/IdleLEDs.ino

@@ -1,6 +1,6 @@
 /* -*- mode: c++ -*-
  * Kaleidoscope-Idle-LEDs -- Turn off the LEDs when the keyboard's idle
- * Copyright (C) 2018  Keyboard.io, Inc
+ * Copyright (C) 2018, 2019  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
@@ -18,6 +18,8 @@
 #include <Kaleidoscope.h>
 #include <Kaleidoscope-LEDControl.h>
 #include <Kaleidoscope-LEDEffect-Rainbow.h>
+#include <Kaleidoscope-EEPROM-Settings.h>
+#include <Kaleidoscope-FocusSerial.h>
 #include <Kaleidoscope-IdleLEDs.h>
 
 // *INDENT-OFF*
@@ -43,14 +45,18 @@ KEYMAPS(
 // *INDENT-ON*
 
 KALEIDOSCOPE_INIT_PLUGINS(LEDControl,
-                          IdleLEDs,
+                          EEPROMSettings,
+                          Focus,
+                          PersistentIdleLEDs,
                           LEDRainbowWaveEffect,
                           LEDOff);
 
 void setup() {
+  KeyboardHardware.serialPort().begin(9600);
+
   Kaleidoscope.setup();
 
-  IdleLEDs.setIdleTimeoutSeconds(300); // 5 minutes
+  PersistentIdleLEDs.setIdleTimeoutSeconds(300); // 5 minutes
 
   LEDRainbowWaveEffect.activate();
 }

src/kaleidoscope/plugin/IdleLEDs.cpp

@@ -1,6 +1,7 @@
 /* -*- mode: c++ -*-
  * Kaleidoscope-Idle-LEDs -- Turn off the LEDs when the keyboard's idle
- * Copyright (C) 2018  Keyboard.io, Inc
+ * Copyright (C) 2018, 2019  Keyboard.io, Inc
+ * Copyright (C) 2019  Dygma, 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
@@ -17,6 +18,8 @@
 
 #include <Kaleidoscope-IdleLEDs.h>
 #include <Kaleidoscope-LEDControl.h>
+#include <Kaleidoscope-EEPROM-Settings.h>
+#include <Kaleidoscope-FocusSerial.h>
 
 namespace kaleidoscope {
 namespace plugin {
@@ -56,7 +59,49 @@ EventHandlerResult IdleLEDs::onKeyswitchEvent(Key &mapped_key, KeyAddr key_addr,
   return EventHandlerResult::OK;
 }
 
+uint16_t PersistentIdleLEDs::settings_base_;
+
+EventHandlerResult PersistentIdleLEDs::onSetup() {
+  settings_base_ = ::EEPROMSettings.requestSlice(sizeof(uint16_t));
+
+  // If idleTime is max, assume that EEPROM is uninitialized, and store the
+  // defaults.
+  uint16_t idle_time;
+  KeyboardHardware.storage().get(settings_base_, idle_time);
+  if (idle_time == 0xffff) {
+    KeyboardHardware.storage().put(settings_base_, idle_time_limit);
+  }
+  setIdleTimeoutSeconds(idle_time);
+
+  return EventHandlerResult::OK;
+}
+
+void PersistentIdleLEDs::setIdleTimeoutSeconds(uint32_t new_limit) {
+  IdleLEDs::setIdleTimeoutSeconds(new_limit);
+  KeyboardHardware.storage().put(settings_base_, (uint16_t)new_limit);
+}
+
+EventHandlerResult PersistentIdleLEDs::onFocusEvent(const char *command) {
+  const char *cmd = PSTR("idleleds.time_limit");
+
+  if (::Focus.handleHelp(command, cmd))
+    return EventHandlerResult::OK;
+
+  if (strcmp_P(command, cmd) != 0)
+    return EventHandlerResult::OK;
+
+  if (::Focus.isEOL()) {
+    ::Focus.send(idleTimeoutSeconds());
+  } else {
+    uint16_t idle_time;
+    ::Focus.read(idle_time);
+    setIdleTimeoutSeconds(idle_time);
+  }
+  return EventHandlerResult::EVENT_CONSUMED;
+}
+
 }
 }
 
 kaleidoscope::plugin::IdleLEDs IdleLEDs;
+kaleidoscope::plugin::PersistentIdleLEDs PersistentIdleLEDs;

src/kaleidoscope/plugin/IdleLEDs.h

@@ -1,6 +1,7 @@
 /* -*- mode: c++ -*-
  * Kaleidoscope-Idle-LEDs -- Turn off the LEDs when the keyboard's idle
- * Copyright (C) 2018  Keyboard.io, Inc
+ * Copyright (C) 2018, 2019  Keyboard.io, Inc
+ * Copyright (C) 2019  Dygma, 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
@@ -37,7 +38,19 @@ class IdleLEDs: public kaleidoscope::Plugin {
  private:
   static uint32_t start_time_;
 };
+
+class PersistentIdleLEDs : public IdleLEDs {
+ public:
+  EventHandlerResult onSetup();
+  EventHandlerResult onFocusEvent(const char *command);
+
+  static void setIdleTimeoutSeconds(uint32_t new_limit);
+ private:
+  static uint16_t settings_base_;
+};
+
 }
 }
 
 extern kaleidoscope::plugin::IdleLEDs IdleLEDs;
+extern kaleidoscope::plugin::PersistentIdleLEDs PersistentIdleLEDs;