diff --git a/doc/plugin/IdleLEDs.md b/doc/plugin/IdleLEDs.md new file mode 100644 index 00000000..548df5da --- /dev/null +++ b/doc/plugin/IdleLEDs.md @@ -0,0 +1,58 @@ +# Kaleidoscope-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: + +```c++ +#include +#include +#include +#include + +KALEIDOSCOPE_INIT_PLUGINS(LEDControl, IdleLEDs, LEDEffectRainbowWave); + +void setup (void) { + 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. + +## Plugin properties + +The plugin provides a single object, `IdleLEDs`, with the following +properties. All times are in seconds. + +### `idle_time_limit` + +> The amount of time that can pass without a single key being pressed, before +> the plugin considers the keyboard idle, and turns the LEDs off. +> +> Defaults to 600 seconds (10 minutes). + +## Dependencies + +* [Kaleidoscope-LEDControl](LEDControl.md) + +## Further reading + +Starting from the [example][plugin:example] is the recommended way of getting +started with the plugin. + + [plugin:example]: ../../examples/IdleLEDs/IdleLEDs.ino diff --git a/examples/IdleLEDs/IdleLEDs.ino b/examples/IdleLEDs/IdleLEDs.ino new file mode 100644 index 00000000..704f499e --- /dev/null +++ b/examples/IdleLEDs/IdleLEDs.ino @@ -0,0 +1,60 @@ +/* -*- mode: c++ -*- + * Kaleidoscope-Idle-LEDs -- Turn off the LEDs when the keyboard's idle + * Copyright (C) 2018 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 . + */ + +#include +#include +#include +#include + +// *INDENT-OFF* +KEYMAPS( + [0] = KEYMAP_STACKED + ( + Key_LEDEffectNext, Key_1, Key_2, Key_3, Key_4, Key_5, Key_LEDEffectNext, + 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_NoKey, + + Key_skip, Key_6, Key_7, Key_8, Key_9, Key_0, Key_skip, + 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_skip, Key_N, Key_M, Key_Comma, Key_Period, Key_Slash, Key_Minus, + + Key_RightShift, Key_RightAlt, Key_Spacebar, Key_RightControl, + Key_NoKey), +) +// *INDENT-ON* + +KALEIDOSCOPE_INIT_PLUGINS(LEDControl, + IdleLEDs, + LEDRainbowWaveEffect, + LEDOff); + +void setup() { + Kaleidoscope.setup(); + + IdleLEDs.idle_time_limit = 300; // 5 minutes + + LEDRainbowWaveEffect.activate(); +} + +void loop() { + Kaleidoscope.loop(); +} diff --git a/src/Kaleidoscope-IdleLEDs.h b/src/Kaleidoscope-IdleLEDs.h new file mode 100644 index 00000000..b6199cfd --- /dev/null +++ b/src/Kaleidoscope-IdleLEDs.h @@ -0,0 +1,20 @@ +/* -*- mode: c++ -*- + * Kaleidoscope-Idle-LEDs -- Turn off the LEDs when the keyboard's idle + * Copyright (C) 2018 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 . + */ + +#pragma once + +#include diff --git a/src/kaleidoscope/plugin/IdleLEDs.cpp b/src/kaleidoscope/plugin/IdleLEDs.cpp new file mode 100644 index 00000000..fe9f9c30 --- /dev/null +++ b/src/kaleidoscope/plugin/IdleLEDs.cpp @@ -0,0 +1,56 @@ +/* -*- mode: c++ -*- + * Kaleidoscope-Idle-LEDs -- Turn off the LEDs when the keyboard's idle + * Copyright (C) 2018 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 . + */ + +#include +#include + +namespace kaleidoscope { +namespace plugin { + +uint16_t IdleLEDs::idle_time_limit = 600; // 10 minutes +uint32_t IdleLEDs::last_keypress_time_; + +EventHandlerResult IdleLEDs::beforeEachCycle() { + uint32_t idle_limit = idle_time_limit * 1000; + + if (!::LEDControl.paused && + Kaleidoscope.millisAtCycleStart() - last_keypress_time_ >= idle_limit) { + ::LEDControl.set_all_leds_to(CRGB(0, 0, 0)); + ::LEDControl.syncLeds(); + + ::LEDControl.paused = true; + } + + return EventHandlerResult::OK; +} + +EventHandlerResult IdleLEDs::onKeyswitchEvent(Key &mapped_key, byte row, byte col, uint8_t key_state) { + + if (::LEDControl.paused) { + ::LEDControl.paused = false; + ::LEDControl.refreshAll(); + } + + last_keypress_time_ = Kaleidoscope.millisAtCycleStart(); + + return EventHandlerResult::OK; +} + +} +} + +kaleidoscope::plugin::IdleLEDs IdleLEDs; diff --git a/src/kaleidoscope/plugin/IdleLEDs.h b/src/kaleidoscope/plugin/IdleLEDs.h new file mode 100644 index 00000000..edfa2826 --- /dev/null +++ b/src/kaleidoscope/plugin/IdleLEDs.h @@ -0,0 +1,44 @@ +/* -*- mode: c++ -*- + * Kaleidoscope-Idle-LEDs -- Turn off the LEDs when the keyboard's idle + * Copyright (C) 2018 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 . + */ + +#pragma once + +#include + +namespace kaleidoscope { +namespace plugin { + +class IdleLEDs: public kaleidoscope::Plugin { + public: + IdleLEDs(void) {} + + static uint16_t idle_time_limit; + + EventHandlerResult onSetup() { + last_keypress_time_ = millis(); + return EventHandlerResult::OK; + } + EventHandlerResult beforeEachCycle(); + EventHandlerResult onKeyswitchEvent(Key &mapped_key, byte row, byte col, uint8_t key_state); + + private: + static uint32_t last_keypress_time_; +}; +} +} + +extern kaleidoscope::plugin::IdleLEDs IdleLEDs;