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>
Use a timeout calculation method that is not affected by overflow, and also
requires 16 bits less.
This likely fixes#8.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
Ticks depend on the speed of the main loop, and as such, are not a reliable way
to time animations. For this reason, use proper timers instead.
The update delay is set to 40ms, which appears to be a slow, relaxing animation,
and should be roughly in the ballpark the tick-based timing was, before speeding
up the main loop considerably.
Fixes#3.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
This warp mode is similar to the navigation provided by some speech
recognition software. A 9-cell grid may provide more precision and
efficiency than the existing 4-cell warp mode. This adds some extra
key definitions to support the additional sectors and enables a user
to switch the grid size:
MouseKeys.setWarpGridSize(MOUSE_WARP_GRID_3X3);
Signed-off-by: Cy Rossignol <cy@rossignols.me>
With the previous algorithm, once every 65 seconds, there would be a significant jump in
the brightness of the "breathing" LEDs as the 16-bit value recorded from `millis()`
overflowed. Instead of dividing by 12, I changed it to a bit shift (4 bits; equivalent to
division by 16), so when the integer overflow occurs, the next value is what it should be.
This is a somewhat unwieldy fix for all the out of bounds (attempted) array addressing at
both ends. When `pos` goes out of bounds in either direction, the test is the same because
it's an unsigned integer. However, after the change of direction, the trailing LED will
still be out of bounds, so we check that every time we call `setCrgbAt()` for `pos2`.
It's rather ugly, but it does ensure that we don't call `setCrgbAt()` with an
out-of-bounds address.
Before this change, we couldn't use the full functionality of the plugin's
warp feature to drag an item (by holding down a mouse button key). The
plugin would reset the warp state during each scan cycle, so we could
only warp the pointer to a cell in the top-level grid. This fix enables
warping repeatedly into sub-cells while holding a mouse button.
This prevents an insignificant error, but it is more correct to handle the integer
overflow instead of ignoring it. I've also changed syncTimer from a 32-bit to 16-bit
integer, which results in a smaller code size, and changed the computation of the timeout
slightly, so the LED update interval is always the same (we add `syncDelay` to the
previous update's start time, not it's end time), rather than varying based on when
LEDControl's `loopHook()` function is called relative to the last timeout.
There already exist 2 rainbow LED effects, this adds a third, using
the LED-Stalker effect.
When you press a key, the LED on that key will cycle through all the
colors of the rainbow, independent of the colors of other keys.
Since keyboardio/Kaleidoscope-Hardware-Model01#23 we do not call
`handleKeyswitchEvent` for keys that are idle. Document this in the comments.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
When a keyswitch has been off in the previous cycle and is still off now, do not
call `handleKeyswitchEvent` on it. As an extension, when the whole column is
idle, skip the whole thing.
In practice, handling fully idle keys is not useful. There are many plugins
which explicitly look for this case and return early, because it isn't an
interesting event. As such, not calling the event handler in this case makes
sense, as we save not only a few needless checks in plugins, but our performance
improves greatly too.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
In `actOnMatrixScan`, there is no need to use temporary variables, we can just
pass the data directly to `actOnHalfRow`, and doing so makes the code easier to
follow.
In `actOnHalfRow`, we can further optimize things if instead of reading the Nth
bit, we always read the first, and shift the byte at the end.
All of these optimizations were done by @obra, I just wrote the commit message.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
When there are no state changes, and no keys pressed on a row, instead of
iterating through a byte bit-by-bit, just fire idle events without checking the
bits. In all other cases, do the bit-walking like we did before.
The reason this is useful is because bit-walking is costly, and slow. If we can
avoid that, we win quite a lot of performance. Since rows being idle is the most
common case on a keyboard, this is a huge net win. Even in the worst case, where
no rows are idle, this is just one byte comparison and a branch slower than our
previous implementation.
As part of this optimization, `actOnHalfRow` was lifted out into its own
function, to reduce code duplication.
Many thanks to @gedankenexperimenter for the original idea!
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
Allow user to specify custom boot greeting key by Key_* or by specific row and column. Add ability to define custom duration of boot greet breathing effect, and add ability to change color hue of breathing effect. Finally, rework logic that happens when plugin is loaded to allow all user custom settings to be properly read and applied as expected.
add hue to the header
Updated readme to support new features
astyle + change to allow custom settings
This avoids the OS being stuck with Numlock on, which leaves the LED on
if other keyboard are attached, and breaks FVWM.
See keyboardio/Model01-Firmware#42
These macros were copied and pasted, I'm guessing from the USB HID Usage Tables document,
where this keycode is identified with a parenthetical, unlike all of the others around it:
`AC Download (Save Target As)`. When automatically converted into a preprocessor macro, it
gets a trailing underscore and an argument, which is not what we want.
This change won't actually fix anything that's currently broken, but it might matter
someday.
Reset the bad key bitfields each time a test is started, so that each test starts from a clean slate. Without this, it was confusing to restart the test and get an ever-increasing number of keys to appear bad immediately.
Store any macros key events and play them after the event handler pass has finished, so we
don't have a problem when holding other keys that are handled after the macro key in a
pass. This fixes the problem where held modifiers wouldn't be applied to macros, and also
fast repeating of printing characters.
This change does introduce a limit (default: 8) on the number of concurrent macros that
can be played.
We are moving towards including the Adaptor from the Hardware library, so we
need not pull them in from user sketches (or from core).
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
Instead of pulling it in from the user sketch, do so from the hardware plugin.
The hardware and the adaptor are in close relationship anyway, and with
tweakable knobs, we do not need to use a different adaptor library in advanced
cases, either.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
Instead of implementing the HID adaptors within Kaleidoscope, provide an API
only (by marking the symbols `extern`). For the sake of backwards compatibility,
pull in `Kaleidoscope-HIDAdaptor-KeyboardioHID`, a new shim library implementing
the status quo.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
Instead of using `Keyboard.begin` directly, use
`kaleidoscope::hid::initializeKeyboard`. While there, also initialize
`ConsumerControl` and `SystemControl` the same way.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
Use `static_assert` instead of `#error` to report an API mismatch, resulting in
a much more informative error message.
Thanks to @cdisselkoen for the request, and @noseglasses for the `static_assert`
idea!
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
As we guarantee backwards compatibility throughout a major version, it helps if
we have that version available, so plugins / sketches can check if they are
compatible, and issue a helpful error if they are not. As further convenience,
defining `KALEIDOSCOPE_REQUIRED_API_VERSION` before including `Kaleidoscope.h`
will result in a check being done by Kaleidoscope, and an error printed if it
does not match the API shipped.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
As this is a generic plugin, for keyboards that do not have LEDs, don't tie it
to LEDControl, and don't provide a `toggleLEDs` method. Instead, show an example
how to achieve the same thing from the sketch.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
At least on Linux, for a device to be considered capable of waking the host up,
it must be a boot keyboard. As we do not (yet) support a boot keyboard, we fake
one. An USB node that does nothing else than report itself as a boot keyboard,
and does the minimum amount of work to get recognised as such.
Because of this, Linux - and hopefully the other OSes too - will consider the
whole device capable of waking up the host.
This addresses keyboardio/Kaleidoscope#237, if all goes well.
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
Add LEDControl.paused, which we use to pause LED mode updates if true (defaults
to false). This is useful when we want to stop LED modes from updating without
switching to another (like when the host goes to sleep, and we want to turn LEDs
off).
Signed-off-by: Gergely Nagy <algernon@keyboard.io>
This doesn't change behaviour at all; it's just a different way to do the computation,
which I think is much clearer. I also added an explanatory comment.
* It's now all bitwise operations, without arithemetic thrown in.
* It uses the same exact formula for finding bits on both sides of the keyboard.
* It saves 14 bytes in program memory.
The boolean wasOn was unnecessary, and there was no need to call
bitSet() (or bitClear(), in the case of Layer.off()) if the test
passed. Mostly, I just added a few explanatory comments.
(Aslo reversed the sense of the on/off test in Layer.on() and .off())
@algernon likes it better this way, and I agree.
`updateActiveLayers()` makes it impossible to turn off the default
layer, so there's no point searching past it for the highest layer,
and `defaultLayer` can be set to numbers higher than zero.
Now that `layer_count` is (potentially) available, we can start
looking for active layers at the top _defined_ layer instead of the
top _possible_ layer. This ought to be more efficient, especially for
sketches that don't have lots of layers defined.
Also introduced the `MAX_LAYERS` constant (#define).
Instead of discrete press & release tracking, press the mousekey when the
physical key is pressed, and like `Keyboard`, send & clear the report once per
cycle, instead on every action.
This fixes#10.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
Instead of sending a press & release for the consumer key when the physical key
is released, send a press each cycle it is held, a report along with the
keyboard report, and clear the consumer report each cycle too.
This will prevent these keys getting stuck, or sending multiple presses in the
same report.
Fixes#176.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
If we call updateLiveCompositeKeymap() on key release the keymap gets
updated before the release event occurs, and any ShiftToLayer(N) key
with a different definition on layer N won't work properly. Before its
release event is processed, it gets updated to the new value, and
layer N doesn't get turned off. If we only update the live keymap on
key press events, we don't have this problem.
replacing the Key_16bit macro with CONSUMER_KEY macro allowed us to
add the IS_CONSUMER and SYNTHETIC flags within the CONSUMER_KEY macro
and simplify the Consumer key definitions.
If it's an old sketch, LayerCount will default to 0, so in order for
Layer.on() to function, don't bother checking for out-of-bounds if
LayerCount == 0.
Declaring LayerCount as a weak symbol in layers.cpp lets us override
it if the CREATE_KEYMAP macro is used to define the keymap in the
sketch file, but still allows old sketch files to compile without
errors.
Still some changes necessary to allow old sketches to work
properly (Layer.on() will abort before doing anything).
This macro allows the definition of the LayerCount variable and the
keymaps[] array together. It shouldn't break old sketches, but this is
probably not all that's necessary; LayerCount still doesn't get
initialized outside the macro.
Update key_events.cpp (IS_INTERNAL Handling)
I'm merging this for now, even though I know it's not the 'right' solution. But I'd like Mute to work correctly for MP2 keyboards and we're on deadline
This file is meant to be included in sketch files in order to make
data available to Kaleidoscope functions. In particular, the size of
the keymaps[] array (i.e. the number of defined layers), which is
needed in order to prevent reading uninitialized memory past the end
of that array due to Key_KeymapNext_Momentary.
By moving the IS_CONSUMER flag to B00001000 instead of
B00000010 (swap with IS_INTERNAL) we can detect the if the key is a
consumer key and strip out the flags and use the full 10bit to send to
the hid report. This enable us to use all the Consumer_* keys
Reordered if chain in handleSyntheticKeyswitchEvent to fix a bug preventing some Consumer and System Control HID functions from being sent due to bit overload/collision with the IS_INTERNAL flag.
Instead of trying to track numlock ourselves, rely on the host telling us what
it thinks the state is. This is much more reliable than what we were doing, and
hopefully fixes most of - if not all - the issues we were having with NumLock.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
Make Kaleidoscope_ a friend class, so that it can access .begin. The
reason behind this is that .begin is an interface towards
Kaleidoscope.use(), and that function should be the only user. To
discourage its use, make it protected.
This does not break any existing - and valid - code, but allows us to
slowly migrate the plugins to a protected begin() method.
Fixes#177.
As discussed in #196, if we are making `KaleidoscopePlugin.begin` protected, we
might as well give it a better name. That name is `initialSetup`, and this
change is the first step towards the migration. It introduces `initialSetup`
which will call `begin` for now, and deprecate `begin`, which is no longer an
abstract function.
Once everyone migrated to the new name, we can remove `.begin`, and turn
`.initialSetup` into an abstract function.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
Intended to force-reactivate the current LED mode, in case we want to refresh
the whole board, and make sure we do so even if the current mode's update is a
no-op.
This can happen when we overrode some keys, and it becomes less costly to update
everything than to iterate over the updated keys.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
When implementing `.refreshAt` before, some dead code was left in
Kaleidoscope-LEDControl.cpp, code that is now implemented in the header.
As these are implemented elsewhere, and are `#if 0`'d out anyway, drop them.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
Make `Kaleidoscope_` a friend class, so that it can access `.begin`. The reason
behind this is that `.begin` is an interface towards `Kaleidoscope.use()`, and
that function should be the only user. To discourage its use, make it protected.
This does not break any existing - and valid - code, but allows us to slowly
migrate the plugins to a protected `begin()` method.
Fixes#177.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
`Kaleidoscope.use` is a much better interface, therefore deprecate USE_PLUGINS.
We do this by creating a wrapper function, `__USE_PLUGINS` that will call
`Kaleidoscope.use` under the hood, but has a deprecated attribute attached. We
then make the `USE_PLUGINS` macro call this function.
We do this because we want to make sure that the list is NULL-terminated, and
for that, we need the macro.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
This was only ever used for `Kaleidoscope.setup()`, and while the variant that
takes an argument is deprecated, and emits a warning already, we can do the same
for `KEYMAP_SIZE` too.
This does set the const to 0, so if used anywhere else than
`Kaleidoscope.setup()`, it will have undesired side-effects. But as far as I
saw, it was never used elsewhere, thus, this change should be safe.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
We do not use `keymap_count` anymore, so deprecate this variant of the setup
function, with a message that also tells the user that `KEYMAP_SIZE` is
deprecated too.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
Turn `event_handler_hook_use` and `loop_hook_use` into real functions, so that
we can apply a `deprecated` attribute, which in turn will emit a compile-time
warning when either of these functions are used.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
Neither of these are used in any plugin, within Arduino-Boards or outside of it.
We keep the `_hook_use` aliases, because there are a few users of it outside of
Arduino-Boards.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
Use `LAYER_SHIFT_OFFSET` instead of `MOMENTARY_OFFSET`, which will start
emitting compile-time warnings now.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
As discussed in #190, and later on IRC, this renames ToggleLayer to
LockLayer (updating the documentation at the same time), and introduces
the UnlockLayer alias, for clarity.
MomentaryLayer also got a new name: ShiftToLayer, and new documentation
to go with it.
Signed-off-by: Csilla Nagyné Martinák <csilla@csillger.hu>
This introduces `ToggleLayer(n)` and `MomentaryLayer(n)`, which make it
easier to switch to layers higher than five, and allow one to use enum
values in place of `n`, such as: `ToggleLayer(NUMPAD)`,
`MomentaryLayer(FUNCTION)`.
Signed-off-by: Csilla Nagyné Martinák <csilla@csillger.hu>
Requiring the end-user to use a macro to have the NumLock effect is a bit
confusing. We can do better than that, by using an event handler hook, and
catching `Keypad_NumLock` presses, and toggle on keypress.
This way, the macro is not necessary, and all the user has to do, is to use the
plugin, configure `numPadLayer`, and done.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
We want to start with a pre-cached state, so we have both less work to do when
keys are first pressed, and so that plugins that rely on the live composite
state will work reliably too.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
For all cases outside of Kaleidoscope itself, we are good with the value of
`highestLayer`, and do not need to re-scan the layer state. For this reason -
upon @obra's suggestion - rename `Layer.highest()` to `Layer.top()`, and the old
`Layer.top()` to `Layer.updateHighestLayer()`, and make the latter private, and
update the `highestLayer` member variable instead of returning the number.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
`layer_getKey` was introduced in 6d641e7fc5, by
mistake, it was never implemented. Remove it now to avoid any possible
confusion.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
Use `Kaleidoscope.useEventHandlerHook` and `Kaleidoscope.useLoopHook` instead of
the deprecated `event_handler_hook_use` and `loop_hook_use` interfaces.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
As `USE_PLUGINS` and `loop_hook_use` are getting deprecated, use the newer APIs:
`Kaleidoscope.use` and `Kaleidoscope.useLoopHook`.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
Use `Kaleidoscope.useEventHandlerHook` instead of `event_handler_hook_use`,
which is getting deprecated.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
Sometimes we would like to know the highest active layer, which is available in
the `highestLayer` private variable, and via `.top()` too. We do not want to
make `highestLayer` public, because we want to be the only ones changing it. And
while `top()` gets us roughly the same information, it does so at a cost. For a
lot of purposes, the cached `highestLayer` would be perfectly adequate.
The new `Layer.highest()` accessor does just this.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
There were a number of issues with the model we had before, namely that plugins
that changed LED colors outside of LED modes had no way to signal "go back to
whatever color this key was". To this end, the `LEDMode.refreshAt` method is
introduced, which these plugins can call to tell the mode to update a given key.
As part of this, the API was redesigned, with code that is common between all
LED modes moving to the base class, among other things, much better names, and a
flow of control that is easier to follow.
In the new setup, there are four methods a LED mode can implement:
- `setup()` to do boot-time initialization (registering hooks, etc).
- `onActivate()` called every time the mode is activated.
- `update()` called each cycle.
- `refreshAt()` may be called by other plugins to refresh a particular key.
All of these are protected methods, to be called via `LEDControl` only.
Much of the new API design was done by @cdisselkoen, huge thanks for his work!
Fixes#9.
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
For every key we press, we keep a map of its state each cycle (for 8 cycles).
When the key is released, we color it white if we had more than two state
changes (ie, chatter), otherwise we turn it blue (all is well).
Signed-off-by: Gergely Nagy <kaleidoscope@gergo.csillger.hu>
Refactor the momentary layer handling part of `handleKeymapKeyswitchEvent`.
Instead of a bunch of ifs that are increasingly hard to follow, use a switch
based on the target layer, and branch out depending on `keyState` from there.
Makes it easier to follow what happens.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
If we have two keys on our keymap that momentarily go to the same layer (which
is the case for the factory firmware), we hold both, and release one, we want
the layer to remain active still.
To this effect, in `handleKeymapKeyswitchEvent` we will handle the case when a
momentary layer key is pressed, but not toggled on (that is, it is held): if it
is not a next/previous switch, we re-activate the layer if it wasn't on.
This fixes#154, thanks to @ToyKeeper for the report.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
With the new implementation, there are two lookup functions, because we have two
caches, and different parts of the firmware will want to use either this or
that (or perhaps both, in rare cases).
First of all, we use caches because looking up a key through all the layers
is costy, and the cost increases dramatically the more layers we have.
Then, we have the `effectiveKeymapCache`, because to have layer behaviours
we want, that is, if you hold a key on a layer, release the layer key but
continue holding the other, we want for the layered keycode to continue
repeating. At the same time, we want other keys to not be affected by the
now-turned-off layer. So we update the keycode in the cache on-demand, when
the key is pressed or released. (see the top of `handleKeyswitchEvent`).
On the other hand, we also have plugins that scan the whole keymap, and do
things based on that information, such as highlighting keys that changed
between layers. These need to be able to look at a state of where the
keymap *should* be, not necessarily where it is. The `effectiveKeymapCache`
is not useful here. So we use a `keymapCache` which we update whenever
layers change (see `Layer.on` and `Layer.off`), and it updates the cache to
show how the keymap should look, without the `effectiveKeymapCache`-induced
behaviour.
Thus, if we are curious about what a given key will do, use `lookup`. If we
are curious what the active layer state describes the key as, use
`lookupUncached`.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
Only update the keymap cache if the layer state changed for real. If we turn a
layer that was already on, on again, we do not need to update. Same for turning
them off.
This results in a tiny speedup if we have code that calls `Layer.on()` or
`Layer.off()` often.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
When we change layers, we want to update the key cache for the whole keyboard,
so that LED modes and other things that depend on all keys being up-to-date will
work as expected.
Do the same at `Kaleidoscope.setup` time, so we start with a good state too.
This fixeskeyboardio/Kaleidoscope-Numlock#7.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
It may happen that we get passed an UNKNOWN_KEYSWITCH_LOCATION, which will
always be out of bounds. Lets not corrupt random memory when in this situation,
but instead, return quickly.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
Uses mickeys (1/16th subpixel units) now instead of pixels. Much smoother!
Added "speedLimit" config var to set maximum cursor speed.
Ensured default values are sane.
For some odd reason, initializing it there crashes the firmware early on. Until
I figure out how to fix this, lets default to an implicit false.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>
Switch from the masking behaviour to repeating the symbol the key had when first
pressed.
This - along with the previous changes - fixes#158.
Signed-off-by: Gergely Nagy <algernon@madhouse-project.org>