From eaf6dc573848139a3dceb5a2f9aa876c027745e5 Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Sat, 13 Oct 2018 11:37:20 +0200 Subject: [PATCH] Rearrange the file layout in preparation of becoming a monorepo Move the documentation to `doc/plugin/EEPROM-Keymap.md`, sources under `src/kaleidoscope/plugin/` (appropriately namespaced). This is in preparation of merging plugins into a single monorepo. Signed-off-by: Gergely Nagy --- README.md | 64 +----------------- doc/plugin/EEPROM-Keymap.md | 65 +++++++++++++++++++ src/Kaleidoscope-EEPROM-Keymap.h | 2 +- .../plugin}/EEPROM-Keymap.cpp | 4 +- .../plugin}/EEPROM-Keymap.h | 6 +- 5 files changed, 74 insertions(+), 67 deletions(-) create mode 100644 doc/plugin/EEPROM-Keymap.md rename src/{Kaleidoscope => kaleidoscope/plugin}/EEPROM-Keymap.cpp (98%) rename src/{Kaleidoscope => kaleidoscope/plugin}/EEPROM-Keymap.h (95%) diff --git a/README.md b/README.md index 1a93a6ef..30fd6bda 100644 --- a/README.md +++ b/README.md @@ -5,66 +5,4 @@ [travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-EEPROM-Keymap.svg?branch=master [travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-EEPROM-Keymap -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 additional layers there. - -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 -#include -#include - -KALEIDOSCOPE_INIT_PLUGINS(EEPROMKeymap, - Focus); - -void setup() { - Kaleidoscope.setup(); - - EEPROMKeymap.setup(1); -} -``` - -## Plugin methods - -The plugin provides the `EEPROMKeymap` object, which has the following method: - -### `.setup(layers[, mode])` - -> Reserve space in EEPROM for up to `layers` layers, and set things up to work according to the specified `mode` (see below for a list of supported modes). To be called from the `setup` method of one's sketch. -> -> Supported modes are: -> - `EEPROMKeymap.Mode::EXTEND`: Extend the keymap with layers from EEPROM, treating them as extensions of the main keymap embedded in the firmware. The first layer in EEPROM will have a number one higher than the last layer in PROGMEM. In this case, the total number of layers will be the number of them in PROGMEM plus `layers`. -> - `EEPROMKeymap.Mode::CUSTOM`: For advanced use cases where the `EXTEND` mode is not appropriate. In this case, the plugin merely reserves a slice of EEPROM for the requested amount of layers, but does no other configuration - that's entirely up to the Sketch. - -## Focus commands - -The plugin provides the `keymap.map` and a `keymap.roLayers` commands. - -### `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 total amount of layers (that is, `layer_count`). - -### `keymap.roLayers` - -> Returns the number of read-only layers. This only makes sense for the `EEPROMKeymap.Mode::EXTEND` mode, where it returns the number of layers in PROGMEM. In any other case, it doesn't return anything, doing so is left for another event handler that understands what the correct value would be. - -## 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 +See [doc/plugin/EEPROM-Keymap.md](doc/plugin/EEPROM-Keymap.md) for documentation. diff --git a/doc/plugin/EEPROM-Keymap.md b/doc/plugin/EEPROM-Keymap.md new file mode 100644 index 00000000..3fc03667 --- /dev/null +++ b/doc/plugin/EEPROM-Keymap.md @@ -0,0 +1,65 @@ +# Kaleidoscope-EEPROM-Keymap + +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 additional layers there. + +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 +#include +#include + +KALEIDOSCOPE_INIT_PLUGINS(EEPROMKeymap, + Focus); + +void setup() { + Kaleidoscope.setup(); + + EEPROMKeymap.setup(1); +} +``` + +## Plugin methods + +The plugin provides the `EEPROMKeymap` object, which has the following method: + +### `.setup(layers[, mode])` + +> Reserve space in EEPROM for up to `layers` layers, and set things up to work according to the specified `mode` (see below for a list of supported modes). To be called from the `setup` method of one's sketch. +> +> Supported modes are: +> - `EEPROMKeymap.Mode::EXTEND`: Extend the keymap with layers from EEPROM, treating them as extensions of the main keymap embedded in the firmware. The first layer in EEPROM will have a number one higher than the last layer in PROGMEM. In this case, the total number of layers will be the number of them in PROGMEM plus `layers`. +> - `EEPROMKeymap.Mode::CUSTOM`: For advanced use cases where the `EXTEND` mode is not appropriate. In this case, the plugin merely reserves a slice of EEPROM for the requested amount of layers, but does no other configuration - that's entirely up to the Sketch. + +## Focus commands + +The plugin provides the `keymap.map` and a `keymap.roLayers` commands. + +### `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 total amount of layers (that is, `layer_count`). + +### `keymap.roLayers` + +> Returns the number of read-only layers. This only makes sense for the `EEPROMKeymap.Mode::EXTEND` mode, where it returns the number of layers in PROGMEM. In any other case, it doesn't return anything, doing so is left for another event handler that understands what the correct value would be. + +## 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 diff --git a/src/Kaleidoscope-EEPROM-Keymap.h b/src/Kaleidoscope-EEPROM-Keymap.h index 7b3b8af0..3dd4be9e 100644 --- a/src/Kaleidoscope-EEPROM-Keymap.h +++ b/src/Kaleidoscope-EEPROM-Keymap.h @@ -17,4 +17,4 @@ #pragma once -#include +#include diff --git a/src/Kaleidoscope/EEPROM-Keymap.cpp b/src/kaleidoscope/plugin/EEPROM-Keymap.cpp similarity index 98% rename from src/Kaleidoscope/EEPROM-Keymap.cpp rename to src/kaleidoscope/plugin/EEPROM-Keymap.cpp index 249f1790..bb415be2 100644 --- a/src/Kaleidoscope/EEPROM-Keymap.cpp +++ b/src/kaleidoscope/plugin/EEPROM-Keymap.cpp @@ -20,6 +20,7 @@ #include namespace kaleidoscope { +namespace plugin { EEPROMKeymap::Mode EEPROMKeymap::mode_; uint16_t EEPROMKeymap::keymap_base_; uint8_t EEPROMKeymap::max_layers_; @@ -148,6 +149,7 @@ EventHandlerResult EEPROMKeymap::onFocusEvent(const char *command) { return EventHandlerResult::EVENT_CONSUMED; } +} } -kaleidoscope::EEPROMKeymap EEPROMKeymap; +kaleidoscope::plugin::EEPROMKeymap EEPROMKeymap; diff --git a/src/Kaleidoscope/EEPROM-Keymap.h b/src/kaleidoscope/plugin/EEPROM-Keymap.h similarity index 95% rename from src/Kaleidoscope/EEPROM-Keymap.h rename to src/kaleidoscope/plugin/EEPROM-Keymap.h index 4cff00ea..ae72e8e9 100644 --- a/src/Kaleidoscope/EEPROM-Keymap.h +++ b/src/kaleidoscope/plugin/EEPROM-Keymap.h @@ -21,6 +21,7 @@ #include namespace kaleidoscope { +namespace plugin { class EEPROMKeymap : public kaleidoscope::Plugin { public: enum class Mode { @@ -53,6 +54,7 @@ class EEPROMKeymap : public kaleidoscope::Plugin { static Key parseKey(void); static void printKey(Key key); }; -}; +} +} -extern kaleidoscope::EEPROMKeymap EEPROMKeymap; +extern kaleidoscope::plugin::EEPROMKeymap EEPROMKeymap;