diff --git a/README.md b/README.md index f2281792..7a4cc03b 100644 --- a/README.md +++ b/README.md @@ -5,78 +5,4 @@ [travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-GhostInTheFirmware.svg?branch=master [travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-GhostInTheFirmware -Born out of the desire to demo LED effects on the keyboard without having to -touch it by hand (which would obstruct the video), the `GhostInTheFirmware` -plugin allows one to inject events at various delays, by telling it which keys -to press. Unlike macros, these press keys at given positions, as if they were -pressed by someone typing on it - the firmware will not see the difference. - -Given a sequence (with press- and delay times), the plugin will walk through it -once activated, and hold the key for the specified amount, release it, and move -on to the next after the delay time. - -## Using the plugin - -To use the plugin, one needs to include the header, and configure it with a list -of key coordinates, a press time, and a delay time quartett. One also needs a -way to trigger starting the sequence, and a macro is the most convenient way for -that. - -```c++ -#include -#include -#include - -const macro_t *macroAction(uint8_t macro_index, uint8_t key_state) { - if (macro_index == 0 && keyToggledOn(key_state)) - GhostInTheFirmware.activate(); - - return MACRO_NONE; -} - -static const kaleidoscope::GhostInTheFirmware::GhostKey ghost_keys[] PROGMEM = { - {0, 0, 200, 50}, - {0, 0, 0} -}; - -KALEIDOSCOPE_INIT_PLUGINS(GhostInTheFirmware, - Macros); - -void setup() { - Kaleidoscope.setup (); - - GhostInTheFirmware.ghost_keys = ghost_keys; -} -``` - -The plugin won't be doing anything until its `activate()` method is called - -hence the macro. - -## Plugin methods - -The plugin provides the `GhostInTheFirmware` object, which has the following -methods and properties: - -### `.activate()` - -> Start playing back the sequence. Best called from a macro. - -### `.ghost_keys` - -> Set this property to the sequence of keys to press, by assigning a sequence to -> this variable. Each element is a quartett of `row`, `column`, a `pressTime`, -> and a `delay`. Each of these will be pressed in different cycles, unlike -> macros which play back within a single cycle. -> -> The key at `row`, `column` will be held for `pressTime` milliseconds, and -> after an additional `delay` milliseconds, the plugin will move on to the next -> entry in the sequence. -> -> The sequence *MUST* reside in `PROGMEM`. - -## Further reading - -Starting from the [example][plugin:example] is the recommended way of getting -started with the plugin. - - [plugin:example]: https://github.com/keyboardio/Kaleidoscope-GhostInTheFirmware/blob/master/examples/GhostInTheFirmware/GhostInTheFirmware.ino +See [doc/plugin/GhostInTheFirmware.md](doc/plugin/GhostInTheFirmware.md) for documentation. diff --git a/doc/plugin/GhostInTheFirmware.md b/doc/plugin/GhostInTheFirmware.md new file mode 100644 index 00000000..9005780c --- /dev/null +++ b/doc/plugin/GhostInTheFirmware.md @@ -0,0 +1,84 @@ +# Kaleidoscope-GhostInTheFirmware + +Born out of the desire to demo LED effects on the keyboard without having to +touch it by hand (which would obstruct the video), the `GhostInTheFirmware` +plugin allows one to inject events at various delays, by telling it which keys +to press. Unlike macros, these press keys at given positions, as if they were +pressed by someone typing on it - the firmware will not see the difference. + +Given a sequence (with press- and delay times), the plugin will walk through it +once activated, and hold the key for the specified amount, release it, and move +on to the next after the delay time. + +## Using the plugin + +To use the plugin, one needs to include the header, and configure it with a list +of key coordinates, a press time, and a delay time quartett. One also needs a +way to trigger starting the sequence, and a macro is the most convenient way for +that. + +```c++ +#include +#include +#include + +const macro_t *macroAction(uint8_t macro_index, uint8_t key_state) { + if (macro_index == 0 && keyToggledOn(key_state)) + GhostInTheFirmware.activate(); + + return MACRO_NONE; +} + +static const kaleidoscope::plugin::GhostInTheFirmware::GhostKey ghost_keys[] PROGMEM = { + {0, 0, 200, 50}, + {0, 0, 0} +}; + +KALEIDOSCOPE_INIT_PLUGINS(GhostInTheFirmware, + Macros); + +void setup() { + Kaleidoscope.setup (); + + GhostInTheFirmware.ghost_keys = ghost_keys; +} +``` + +The plugin won't be doing anything until its `activate()` method is called - +hence the macro. + +## Plugin methods + +The plugin provides the `GhostInTheFirmware` object, which has the following +methods and properties: + +### `.activate()` + +> Start playing back the sequence. Best called from a macro. + +### `.ghost_keys` + +> Set this property to the sequence of keys to press, by assigning a sequence to +> this variable. Each element is a quartett of `row`, `column`, a `pressTime`, +> and a `delay`. Each of these will be pressed in different cycles, unlike +> macros which play back within a single cycle. +> +> The key at `row`, `column` will be held for `pressTime` milliseconds, and +> after an additional `delay` milliseconds, the plugin will move on to the next +> entry in the sequence. +> +> The sequence *MUST* reside in `PROGMEM`. + +## Further reading + +Starting from the [example][plugin:example] is the recommended way of getting +started with the plugin. + + [plugin:example]: https://github.com/keyboardio/Kaleidoscope-GhostInTheFirmware/blob/master/examples/GhostInTheFirmware/GhostInTheFirmware.ino + +## Upgrading + +Previous versions of `GhostInTheFirmware` used +`kaleidoscope::GhostInTheFirmware::GhostKey` as a type for defining keys. In +newer versions, this is `kaleidoscope::plugin::GhostInTheFirmware::GhostKey`. +The old name still works, but will be removed by 2019-01-14. diff --git a/examples/GhostInTheFirmware/GhostInTheFirmware.ino b/examples/GhostInTheFirmware/GhostInTheFirmware.ino index b937bc8e..cae21b04 100644 --- a/examples/GhostInTheFirmware/GhostInTheFirmware.ino +++ b/examples/GhostInTheFirmware/GhostInTheFirmware.ino @@ -59,7 +59,7 @@ const macro_t *macroAction(uint8_t macro_index, uint8_t key_state) { return MACRO_NONE; } -static const kaleidoscope::GhostInTheFirmware::GhostKey ghost_keys[] PROGMEM = { +static const kaleidoscope::plugin::GhostInTheFirmware::GhostKey ghost_keys[] PROGMEM = { {0, 6, 200, 50}, {0, 5, 200, 50}, {0, 4, 200, 50}, diff --git a/src/Kaleidoscope-GhostInTheFirmware.h b/src/Kaleidoscope-GhostInTheFirmware.h index 7a212c77..1e904541 100644 --- a/src/Kaleidoscope-GhostInTheFirmware.h +++ b/src/Kaleidoscope-GhostInTheFirmware.h @@ -17,4 +17,4 @@ #pragma once -#include +#include diff --git a/src/Kaleidoscope/GhostInTheFirmware.cpp b/src/kaleidoscope/plugin/GhostInTheFirmware.cpp similarity index 96% rename from src/Kaleidoscope/GhostInTheFirmware.cpp rename to src/kaleidoscope/plugin/GhostInTheFirmware.cpp index c6cc5757..14566f19 100644 --- a/src/Kaleidoscope/GhostInTheFirmware.cpp +++ b/src/kaleidoscope/plugin/GhostInTheFirmware.cpp @@ -19,6 +19,7 @@ #include namespace kaleidoscope { +namespace plugin { const GhostInTheFirmware::GhostKey *GhostInTheFirmware::ghost_keys; bool GhostInTheFirmware::is_active_; bool GhostInTheFirmware::is_pressed_; @@ -69,6 +70,7 @@ EventHandlerResult GhostInTheFirmware::beforeReportingState() { return EventHandlerResult::OK; } -}; +} +} -kaleidoscope::GhostInTheFirmware GhostInTheFirmware; +kaleidoscope::plugin::GhostInTheFirmware GhostInTheFirmware; diff --git a/src/Kaleidoscope/GhostInTheFirmware.h b/src/kaleidoscope/plugin/GhostInTheFirmware.h similarity index 87% rename from src/Kaleidoscope/GhostInTheFirmware.h rename to src/kaleidoscope/plugin/GhostInTheFirmware.h index 68734051..d7eb28d2 100644 --- a/src/Kaleidoscope/GhostInTheFirmware.h +++ b/src/kaleidoscope/plugin/GhostInTheFirmware.h @@ -20,6 +20,7 @@ #include namespace kaleidoscope { +namespace plugin { class GhostInTheFirmware : public kaleidoscope::Plugin { public: typedef struct { @@ -48,4 +49,8 @@ class GhostInTheFirmware : public kaleidoscope::Plugin { }; } -extern kaleidoscope::GhostInTheFirmware GhostInTheFirmware; +// For backwards compatibility +typedef kaleidoscope::plugin::GhostInTheFirmware GhostInTheFirmware; +} + +extern kaleidoscope::plugin::GhostInTheFirmware GhostInTheFirmware;