Kaleidoscope upgrade notes
==========================
Noteworthy features
-------------------
### New plugin API
A new plugin API was introduced in May 2018, which replaces the old system
(which still continues to work, but see below). The new system is hopefully
easier to use and develop for:
- It does not require one to register / use hooks anymore. Implementing the
interface provided by `kaleidoscope::Plugin` is all that is required.
- The new system has more hook points, and the method names are much more clear
now.
### Bidirectional communication for plugins
Formerly the `Kaleidoscope-Focus` plugin implemented a way for plugins to
register hooks that respond to commands sent from the host. A part of this has
been pulled into Kaleidoscope itself, in the form of the new `onFocusEvent`
hook. For most intents and purposes, this hook works similar to how focus hooks
worked previously, but has the advantage of not having to explicitly register
them: if you use a plugin that supports this feature, and you have the new
`Kaleidoscope-FocusSerial` plugin enabled, the commands will be made available.
This drastically simplifies both the plugins that wish to implement this, and the user sketches, which no longer need to explicitly register the focus hooks.
### Kaleidoscope.millisAtCycleStart()
Many plugins use timers, and most of them will call `millis()` , which isn't
wrong, but isn't the most efficient either. While `millis()` isn't terribly
expensive, it's not cheap either. For most cases, we do not need an exact timer,
and one updated once per cycle is enough - which is what `.millisAtCycleStart()`
is. Having a timer that is consistent throughout the whole cycle may also be
beneficial.
While `millis()` should continue to work forever, plugins and user code should,
as a general rule, use `Kaleidoscope.millisAtCycleStart()` rather than
`millis()` .
### Kaleidoscope.detachFromHost() and Kaleidoscope.attachToHost()
These two require changes to the Hardware plugins, as they wrap functionality
provided by it. The intent of these methods is to allow one to apply some
configuration changes between detach and attach - because we only sever the link
between device and host, power remains connected, and the device does not
reboot. A quick way to re-initialize the endpoints.
See the [Kaleidoscope-USB-Quirks][plugin:USB-Quirks] plugin for a use-case.
[plugin:USB-Quirks]: https://github.com/keyboardio/Kaleidoscope-USB-Quirks
### The `RxCy` macros and peeking into the keyswitch state
The `RxCy` macros changed from being indexes into a per-hand bitmap to being an
index across the whole keyboard. This means they can no longer be `or` -ed
together to check against the keyswitch state of a given hand. Instead, the
`kaleidoscope::hid::getKeyswitchStateAtPosition()` method can be used to check
the state of a keyswitch at a given row and column; or at a given index.
### KALEIDOSCOPE_API_VERSION bump
`KALEIDOSCOPE_API_VERSION` has been bumped to **2** due to the plugin API
changes. It does not mean that version two of the API is final, though. The bump
is there so plugins can check it, and make compile-time decisions based on it.
Such as whether to compile for the version one, or for the version two API.
The API version will remain the same, even if we introduce breaking changes -
until a stable release is made from the v2 branch. From that point onwards, the
API version will change with further breaking changes.
Major redesign of the plugin and hooking interface
With this redesign, we introduce a new way to create plugins, which is easier to
extend with new hook points, provides a better interface, uses less memory, less
program space, and is a tiny bit faster too.
It all begins with `kaleidoscope::Plugin` being the base class, which provides
the hook methods plugins can implement. Plugins should be declared with
`KALEIDOSCOPE_INIT_PLUGINS` instead of `Kaleidoscope.use()`. Behind this macro
is a bit of magic (see the in-code documentation) that allows us to unroll the
hook method calls, avoid vtables, and so on. It creates an override for
`kaleidoscope::Hooks::*` methods, each of which will call the respective methods
of each initialized plugin.
With the new API come new names: all of the methods plugins can implement
received new, more descriptive names that all follow a similar pattern.
The old (dubbed V1) API still remains in place, although deprecated. One can
turn it off by setting the `KALEIDOSCOPE_ENABLE_V1_PLUGIN_API` define to zero,
while compiling the firmware.
This work is based on #276, written by @noseglasses. @obra and @algernon did
some cleaning up and applied a little naming treatment.
Signed-off-by: noseglasses <shinynoseglasses@gmail.com>
Signed-off-by: Jesse Vincent <jesse@keyboard.io>
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
7 years ago
Deprecated APIs and their replacements
--------------------------------------
Major redesign of the plugin and hooking interface
With this redesign, we introduce a new way to create plugins, which is easier to
extend with new hook points, provides a better interface, uses less memory, less
program space, and is a tiny bit faster too.
It all begins with `kaleidoscope::Plugin` being the base class, which provides
the hook methods plugins can implement. Plugins should be declared with
`KALEIDOSCOPE_INIT_PLUGINS` instead of `Kaleidoscope.use()`. Behind this macro
is a bit of magic (see the in-code documentation) that allows us to unroll the
hook method calls, avoid vtables, and so on. It creates an override for
`kaleidoscope::Hooks::*` methods, each of which will call the respective methods
of each initialized plugin.
With the new API come new names: all of the methods plugins can implement
received new, more descriptive names that all follow a similar pattern.
The old (dubbed V1) API still remains in place, although deprecated. One can
turn it off by setting the `KALEIDOSCOPE_ENABLE_V1_PLUGIN_API` define to zero,
while compiling the firmware.
This work is based on #276, written by @noseglasses. @obra and @algernon did
some cleaning up and applied a little naming treatment.
Signed-off-by: noseglasses <shinynoseglasses@gmail.com>
Signed-off-by: Jesse Vincent <jesse@keyboard.io>
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
7 years ago
As the firmware evolves, there are - and will be - APIs that we deprecate, and
eventually remove. This document is a short guide that lists the deprecations -
along with when it happened, and when the functionality will be removed -,
suggested upgrade paths, and any other information that may be useful.
If any of this does not make sense to you, or you have trouble updating your
.ino sketch, do not hesitate to write us at help@keyboard.io, we can help you
fix it.
Deprecated and removed APIs
---------------------------
### Removed on 2018-08-20
Major redesign of the plugin and hooking interface
With this redesign, we introduce a new way to create plugins, which is easier to
extend with new hook points, provides a better interface, uses less memory, less
program space, and is a tiny bit faster too.
It all begins with `kaleidoscope::Plugin` being the base class, which provides
the hook methods plugins can implement. Plugins should be declared with
`KALEIDOSCOPE_INIT_PLUGINS` instead of `Kaleidoscope.use()`. Behind this macro
is a bit of magic (see the in-code documentation) that allows us to unroll the
hook method calls, avoid vtables, and so on. It creates an override for
`kaleidoscope::Hooks::*` methods, each of which will call the respective methods
of each initialized plugin.
With the new API come new names: all of the methods plugins can implement
received new, more descriptive names that all follow a similar pattern.
The old (dubbed V1) API still remains in place, although deprecated. One can
turn it off by setting the `KALEIDOSCOPE_ENABLE_V1_PLUGIN_API` define to zero,
while compiling the firmware.
This work is based on #276, written by @noseglasses. @obra and @algernon did
some cleaning up and applied a little naming treatment.
Signed-off-by: noseglasses <shinynoseglasses@gmail.com>
Signed-off-by: Jesse Vincent <jesse@keyboard.io>
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
7 years ago
We aim at making a new release by mid-July, and APIs we deprecate now, will be
removed shortly after the major release, before the next point release. We may
deprecate further APIs during the next month (until mid-June), and those
deprecations will share the same removal date. We will try our best to minimize
deprecations, and do them as soon as possible, to give everyone at least a month
to prepare and update.
Major redesign of the plugin and hooking interface
With this redesign, we introduce a new way to create plugins, which is easier to
extend with new hook points, provides a better interface, uses less memory, less
program space, and is a tiny bit faster too.
It all begins with `kaleidoscope::Plugin` being the base class, which provides
the hook methods plugins can implement. Plugins should be declared with
`KALEIDOSCOPE_INIT_PLUGINS` instead of `Kaleidoscope.use()`. Behind this macro
is a bit of magic (see the in-code documentation) that allows us to unroll the
hook method calls, avoid vtables, and so on. It creates an override for
`kaleidoscope::Hooks::*` methods, each of which will call the respective methods
of each initialized plugin.
With the new API come new names: all of the methods plugins can implement
received new, more descriptive names that all follow a similar pattern.
The old (dubbed V1) API still remains in place, although deprecated. One can
turn it off by setting the `KALEIDOSCOPE_ENABLE_V1_PLUGIN_API` define to zero,
while compiling the firmware.
This work is based on #276, written by @noseglasses. @obra and @algernon did
some cleaning up and applied a little naming treatment.
Signed-off-by: noseglasses <shinynoseglasses@gmail.com>
Signed-off-by: Jesse Vincent <jesse@keyboard.io>
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
7 years ago
#### Kaleidoscope.use()
Major redesign of the plugin and hooking interface
With this redesign, we introduce a new way to create plugins, which is easier to
extend with new hook points, provides a better interface, uses less memory, less
program space, and is a tiny bit faster too.
It all begins with `kaleidoscope::Plugin` being the base class, which provides
the hook methods plugins can implement. Plugins should be declared with
`KALEIDOSCOPE_INIT_PLUGINS` instead of `Kaleidoscope.use()`. Behind this macro
is a bit of magic (see the in-code documentation) that allows us to unroll the
hook method calls, avoid vtables, and so on. It creates an override for
`kaleidoscope::Hooks::*` methods, each of which will call the respective methods
of each initialized plugin.
With the new API come new names: all of the methods plugins can implement
received new, more descriptive names that all follow a similar pattern.
The old (dubbed V1) API still remains in place, although deprecated. One can
turn it off by setting the `KALEIDOSCOPE_ENABLE_V1_PLUGIN_API` define to zero,
while compiling the firmware.
This work is based on #276, written by @noseglasses. @obra and @algernon did
some cleaning up and applied a little naming treatment.
Signed-off-by: noseglasses <shinynoseglasses@gmail.com>
Signed-off-by: Jesse Vincent <jesse@keyboard.io>
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
7 years ago
Deprecated in May 2018, this method is part of the old plugin API, replaced by
`KALEIDOSCOPE_INIT_PLUGINS` . To upgrade, you need to modify your .ino sketch
file, and replace the text `Kaleidoscope.use` with `KALEIDOSCOPE_INIT_PLUGINS` ,
then remove the `&` from all of the plugins inside it, and finally, move it
outside of `setup()` .
If your current sketch looks like this:
```c++
void setup() {
Kaleidoscope.use(& Plugin1, &Plugin2);
Kaleidoscope.setup();
}
```
You should change it so that it looks like this instead:
```c++
KALEIDOSCOPE_INIT_PLUGINS(Plugin1, Plugin2);
void setup() {
Kaleidoscope.setup();
}
```
#### The old-style (v1) plugin API
Major redesign of the plugin and hooking interface
With this redesign, we introduce a new way to create plugins, which is easier to
extend with new hook points, provides a better interface, uses less memory, less
program space, and is a tiny bit faster too.
It all begins with `kaleidoscope::Plugin` being the base class, which provides
the hook methods plugins can implement. Plugins should be declared with
`KALEIDOSCOPE_INIT_PLUGINS` instead of `Kaleidoscope.use()`. Behind this macro
is a bit of magic (see the in-code documentation) that allows us to unroll the
hook method calls, avoid vtables, and so on. It creates an override for
`kaleidoscope::Hooks::*` methods, each of which will call the respective methods
of each initialized plugin.
With the new API come new names: all of the methods plugins can implement
received new, more descriptive names that all follow a similar pattern.
The old (dubbed V1) API still remains in place, although deprecated. One can
turn it off by setting the `KALEIDOSCOPE_ENABLE_V1_PLUGIN_API` define to zero,
while compiling the firmware.
This work is based on #276, written by @noseglasses. @obra and @algernon did
some cleaning up and applied a little naming treatment.
Signed-off-by: noseglasses <shinynoseglasses@gmail.com>
Signed-off-by: Jesse Vincent <jesse@keyboard.io>
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
7 years ago
This includes using `KaleidoscopePlugin` , `Kaleidoscope.useEventHandlerHook` ,
`Kaleidoscope.replaceEventHandlerHook` , `Kaleidoscope.appendEventHandlerHook` ,
`Kaleidoscope.useLoopHook` , `Kaleidoscope.replaceLoopHook` ,
`Kaleidoscope.appendLoopHook` . They were deprecated in May 2017.
Their replacement is the new plugin API:
```c++
namespace kaleidoscope {
enum class EventHandlerResult {
OK,
EVENT_CONSUMED,
ERROR,
};
class Plugin {
public:
EventHandlerResult onSetup();
EventHandlerResult beforeEachCycle();
EventHandlerResult onKeyswitchEvent(Key & mapped_key, byte row, byte col, uint8_t key_state);
EventHandlerResult beforeReportingState();
EventHandlerResult afterEachCycle();
};
}
```
Plugins are supposed to implement this new API, and then be initialised via
`KALEIDOSCOPE_INIT_PLUGINS` .
Remove some long-deprecated methods and symbols
As per UPGRADE.md, remove `Kaleidoscope.setup(KEYMAP_SIZE)`,
`event_handler_hook_use`, `loop_hook_use`, `USE_PLUGINS`, `MOMENTARY_OFFSET`,
`key_was_pressed`, `key_is_pressed`, `key_toggled_on`, and `key_toggled_off`.
These were deprecated between July and October 2017, and have been marked for
deletion for over a month.
Also updated UPGRADE.md, moving the section about these to a new, "deprecated
and removed" section.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
7 years ago
#### Consumer_SNapshot
A key with a typo in its name, which was left in place after fixing the typo, so
as to not break any code that may be using it already, however unlikely.
Remove some long-deprecated methods and symbols
As per UPGRADE.md, remove `Kaleidoscope.setup(KEYMAP_SIZE)`,
`event_handler_hook_use`, `loop_hook_use`, `USE_PLUGINS`, `MOMENTARY_OFFSET`,
`key_was_pressed`, `key_is_pressed`, `key_toggled_on`, and `key_toggled_off`.
These were deprecated between July and October 2017, and have been marked for
deletion for over a month.
Also updated UPGRADE.md, moving the section about these to a new, "deprecated
and removed" section.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
7 years ago
### Removed on 2018-06-10 (originally scheduled for 2018-05-27)
These APIs and functions have been deprecated for a long time, and as far as we
can tell, aren't used by any third party or user code anymore. They were removed
as of the June 10th, 2018.
#### Kaleidoscope.setup(KEYMAP_SIZE)
The `Kaleidoscope.setup()` method is still around, and is **not** deprecated,
but the variant of it that takes a keymap size is, and has been since October
2017.
Instead, one should use the argument-less `Kaleidoscope.setup()` , and the new
`KEYMAP()` macros to define a keymap.
#### event_handler_hook_use, loop_hook_use, and USE_PLUGINS
Deprecated in October 2017, these are old aliases that should no longer be in
use. They were replaced by `Kaleidoscope.useEventHandlerHook` ,
`Kaleidoscope.useLoopHook` , and `Kaleidoscope.use` , respectively.
The replacements themselves are also deprecated - see below -, but their removal
will come at a later date.
#### MOMENTARY_OFFSET
Deprecated in October 2017, replaced by `LAYER_SHIFT_OFFSET` .
This symbol was meant to be used by plugins, not user code, and as far as we
know, no third party plugin ever used it.
#### key_was_pressed, key_is_pressed, key_toggled_on, key_toggled_off
Deprecated in July 2017, replaced by `keyWasPressed` , `keyIsPressed` ,
`keyToggledOn` , and `keyToggledOff` , respectively.
