History

Gergely Nagy 8ac4d9f5c1 A more efficient way to handle onFocusEvent commands In the past, we were using `Focus.handleHelp()` to see if we're handling a `help` command, and print the commands supported by the handler. We also used `strcmp_P` directly to compare (parts of) our input against command supported by the handler. This approach works, but had multiple major disadvantages: it duplicated strings between `handleHelp` and the `strcmp_P` calls, and it relied on fragile substring pointers to save space. To replace all that, this patch implements a different approach. Help handling is split between a check (`Focus.inputMatchesHelp()`) and a reply (`Focus.printHelp()`), the latter of which takes a list of `PSTR()` strings, rather than one single string. This allows us to reuse the same strings for comparing against the handler's input. The new approach no longer uses the fragile substring pointers, nor does it use `strcmp_P` directly, but goes through a wrapper (`Focus.inputMatchesCommand()`) instead. These changes lead to a more readable pattern. While we do use longer strings as a result, there is less duplication, and the new patterns also require less code, so we end up with saving space, at least on AVR devices. The old methods are still available and usable, but they're deprecated. Signed-off-by: Gergely Nagy <algernon@keyboard.io>		2 years ago
..
src	A more efficient way to handle onFocusEvent commands	2 years ago
README.md	Remove C-style `void` parameter for functions that don't take args	3 years ago
library.properties	More library tweaking to comply with arduino requirements	4 years ago

README.md

IdleLEDs

Having LED effects on the keyboard can be exceptionally helpful. However, having the effects - or lights, in general - on all the time, even when the keyboard is otherwise idle, is perhaps not the best. When one leaves the keyboard, locks the computer, what use are the LED effects then?

One could turn them off manually, but... that's too easy to forget, and why do something the firmware could do for us anyway? What if the LEDs turned themselves off after some configurable idle time? Say, if one did not press any keys for the past ten minutes, just shut 'em off.

This is exactly what the IdleLEDs plugin does.

Using the plugin

The plugin comes with reasonable defaults (see below), and can be used out of the box, without any further configuration:

#include <Kaleidoscope.h>
#include <Kaleidoscope-LEDControl.h>
#include <Kaleidoscope-LEDEffect-Rainbow.h>
#include <Kaleidoscope-IdleLEDs.h>

KALEIDOSCOPE_INIT_PLUGINS(LEDControl, IdleLEDs, LEDEffectRainbowWave);

void setup () {
  Kaleidoscope.setup ();
}

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:

#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 () {
  Kaleidoscope.setup ();
}

Plugin Properties

The plugin provides two objects, IdleLEDs, and PersistentIdleLEDs, both with the following properties and methods.

`.idle_time_limit`

Property storing the amount of time that can pass without a single key being pressed before the plugin considers the keyboard idle and turns off the LEDs. Value is expressed in milliseconds.

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. If using PersistentIdleLEDs, setting this property will not persist the value to storage. Use .setIdleTimeoutSeconds() if persistence is desired.

`.idleTimeoutSeconds()`

Returns 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.

`.setIdleTimeoutSeconds(uint32_t new_limit)`

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.

Setting the timeout to 0 will disable the plugin until it is set to a higher value.

Focus commands

The plugin provides a single Focus command, but only when using the PersistentIdleLEDs variant:

`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.

Setting the timeout to 0 will disable the plugin until it is set to a higher value.

Dependencies

Kaleidoscope-LEDControl