You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
100 lines
3.8 KiB
100 lines
3.8 KiB
# Kaleidoscope-EEPROM-Keymap
|
|
|
|
![status][st:stable] [![Build Status][travis:image]][travis:status]
|
|
|
|
[travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-EEPROM-Keymap.svg?branch=master
|
|
[travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-EEPROM-Keymap
|
|
|
|
[st:stable]: https://img.shields.io/badge/stable-✔-black.svg?style=flat&colorA=44cc11&colorB=494e52
|
|
[st:broken]: https://img.shields.io/badge/broken-X-black.svg?style=flat&colorA=e05d44&colorB=494e52
|
|
[st:experimental]: https://img.shields.io/badge/experimental----black.svg?style=flat&colorA=dfb317&colorB=494e52
|
|
|
|
While keyboards usually ship with a keymap programmed in, to be able to change
|
|
that keymap, without flashing new firmware, we need a way to place the keymap
|
|
into a place we can update at run-time, and which persists across reboots.
|
|
Fortunately, we have a bit of `EEPROM` on the keyboard, and can use it to store
|
|
either the full keymap (and saving space in the firmware then), or store an
|
|
overlay there. In the latter case, whenever there is a non-transparent key on
|
|
the overlay, we will use that instead of the keyboard default.
|
|
|
|
In short, this plugin allows us to change our keymaps, without having to compile
|
|
and flash new firmware. It does so through the use of the
|
|
[FocusSerial][plugin:focusSerial] plugin.
|
|
|
|
[plugin:focusSerial]: https://github.com/keyboardio/Kaleidoscope-FocusSerial
|
|
|
|
## Using the plugin
|
|
|
|
Using the plugin is reasonably simple: after including the header, enable the
|
|
plugin, and configure how many layers at most we want to store in `EEPROM`.
|
|
There are other settings one can tweak, but these two steps are enough to get
|
|
started with.
|
|
|
|
Once these are set up, we can update the keymap via [Focus][plugin:focusSerial].
|
|
|
|
```c++
|
|
#include <Kaleidoscope.h>
|
|
#include <Kaleidoscope-EEPROM-Keymap.h>
|
|
#include <Kaleidoscope-FocusSerial.h>
|
|
|
|
KALEIDOSCOPE_INIT_PLUGINS(EEPROMKeymap,
|
|
Focus,
|
|
FocusKeymapTransferCommand);
|
|
|
|
void setup() {
|
|
Kaleidoscope.setup();
|
|
|
|
EEPROMKeymap.max_layers(1);
|
|
}
|
|
```
|
|
|
|
## Plugin methods
|
|
|
|
The plugin provides the `EEPROMKeymap` object, which has the following methods:
|
|
|
|
### `.max_layers(max)`
|
|
|
|
> Tells the extension to reserve space in EEPROM for up to `max` layers. Can
|
|
> only be called once, any subsequent call will be a no-op.
|
|
> This should be set to the number of keymap layers you want to be
|
|
> able to program from EEPROM (probably the number of layers you have
|
|
> defined in your keymap).
|
|
|
|
## Focus commands
|
|
|
|
The plugin provides a `keymap.map` Focus command unconditionally, and a
|
|
`keymap.transfer` via the `FocusKeymapTransferCommand` object.
|
|
|
|
### `keymap.map [codes...]`
|
|
|
|
> Without arguments, displays the keymap currently in effect. Each key is
|
|
> printed as its raw, 16-bit keycode.
|
|
>
|
|
> With arguments, it stores as many keys as given. One does not need to set all
|
|
> keys, on all layers: the command will start from the first key on the first
|
|
> layer, and go on as long as it has input. It will not go past the layer set
|
|
> via the `.max_layers()` method.
|
|
|
|
### `keymap.transfer LAYER`
|
|
|
|
> Transfers the `LAYER` from the built-in memory of the keyboard into `EEPROM`
|
|
> storage.
|
|
>
|
|
> Useful mostly when one wants to remove the built-in keymap, and wants to
|
|
> easily transfer it into `EEPROM` first.
|
|
>
|
|
> This is generally not needed, and it is recommended to not enable this
|
|
> command, unless the feature this command implements is truly needed.
|
|
|
|
## Dependencies
|
|
|
|
* [Kaleidoscope-EEPROM-Settings](https://github.com/keyboardio/Kaleidoscope-EEPROM-Settings)
|
|
* [Kaleidoscope-FocusSerial](https://github.com/keyboardio/Kaleidoscope-FocusSerial)
|
|
|
|
## 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-EEPROM-Keymap/blob/master/examples/EEPROM-Keymap/EEPROM-Keymap.ino
|