From b80ecfec7178d792330757f4c59d1f155b3ad948 Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Sat, 13 Oct 2018 12:25:47 +0200 Subject: [PATCH] Rearrange the file layout in preparation of becoming a monorepo Move the documentation to `doc/plugin/EEPROM-Settings.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 | 167 +---------------- doc/plugin/EEPROM-Settings.md | 168 ++++++++++++++++++ src/Kaleidoscope-EEPROM-Settings.h | 4 +- .../plugin}/EEPROM-Settings-Focus.cpp | 6 +- .../plugin}/EEPROM-Settings-Focus.h | 6 +- .../plugin}/EEPROM-Settings.cpp | 4 +- .../plugin}/EEPROM-Settings.h | 6 +- .../plugin}/crc.cpp | 0 .../plugin}/crc.h | 0 9 files changed, 186 insertions(+), 175 deletions(-) create mode 100644 doc/plugin/EEPROM-Settings.md rename src/{Kaleidoscope => kaleidoscope/plugin}/EEPROM-Settings-Focus.cpp (95%) rename src/{Kaleidoscope => kaleidoscope/plugin}/EEPROM-Settings-Focus.h (86%) rename src/{Kaleidoscope => kaleidoscope/plugin}/EEPROM-Settings.cpp (97%) rename src/{Kaleidoscope => kaleidoscope/plugin}/EEPROM-Settings.h (94%) rename src/{Kaleidoscope => kaleidoscope/plugin}/crc.cpp (100%) rename src/{Kaleidoscope => kaleidoscope/plugin}/crc.h (100%) diff --git a/README.md b/README.md index 685a8d9d..687b5684 100644 --- a/README.md +++ b/README.md @@ -5,169 +5,4 @@ [travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-EEPROM-Settings.svg?branch=master [travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-EEPROM-Settings -To be able to reliably store persistent configuration in `EEPROM`, we need to be -able to split up the available space for plugins to use. We also want to make -sure that we notice when the `EEPROM` contents and the firmware are out of sync. -This plugin provides the tools to do that. - -It does not guard against errors, it merely provides the means to discover them, -and let the firmware Sketch handle the case in whatever way it finds reasonable. -It's a building block, and not much else. All Kaleidoscope plugins that need to -store data in `EEPROM` are encouraged to make use of this library. - -## Using the plugin - -There are a few steps one needs to take to use the plugin: we must first -register it, then either let other plugins request slices of `EEPROM`, or do so -ourselves. And finally, seal it, to signal that we are done setting up. At that -point, we can verify whether the contents of the `EEPROM` agree with our -firmware. - -```c++ -#include -#include - -static uint16_t settingsBase; -static struct { - bool someSettingFlag; -} testSettings; - -KALEIDOSCOPE_INIT_PLUGINS(EEPROMSettings, /* Other plugins that use EEPROM... */); - -void setup () { - Kaleidoscope.setup(); - - settingsBase = EEPROMSettings.requestSlice(sizeof(testSettings)); - - EEPROMSettings.seal(); - - if (!EEPROMSettings.isValid()) { - // Handle the case where the settings are out of sync... - // Flash LEDs, for example. - - return; - } - - EEPROM.get(settingsBase, testSettings); -} -``` - -## Plugin methods - -The plugin provides the `EEPROMSettings` object, which has the following methods: - -### `requestSlice(size)` - -> Requests a slice of the `EEPROM`, and returns the starting address (or 0 on -> error, including when the request arrived after sealing the layout). -> -> Should only be called **before** calling `seal()`. - -### `default_layer([id])` - -> Sets (or returns, if called without an ID) the default layer. When the -> keyboard boots up, it will automatically switch to the configured layer - if -> any. -> -> This is the Focus counterpart of the `default_layer()` method documented -> above. - -### `seal()` - -> Seal the `EEPROM` layout, so no new slices can be requested. The CRC checksum -> is considered final at this time, and the `isValid()`, `crc()`, `used()` and -> `version()` methods can be used from this point onwards. -> -> If not called explicitly, the layout will be sealed automatically after -> `setup()` in the sketch finished. - -### `update()` - -> Updates the `EEPROM` header with the current status quo, including the version -> and the CRC checksum. -> -> This should be called when upgrading from one version to another, or when -> fixing up an out-of-sync case. - -### `isValid()` - -> Returns whether the `EEPROM` header is valid, that is, if it has the expected -> CRC checksum. -> -> Should only be called after calling `seal()`. - -### `invalidate()` - -> Invalidates the `EEPROM` header. Use when the version does not match what the -> firmware would expect. This signals to other plugins that the contents of -> `EEPROM` should not be trusted. - -### `version([newVersion])` - -> Sets or returns the version of the `EEPROM` layout. This is purely for use by -> the firmware, so it can attempt to upgrade the contents, if need be, or alert -> the user in there's a mismatch. Plugins do not use this property. -> -> Should only be called after calling `seal()`. - -### `crc()` - -> Returns the CRC checksum of the layout. Should only be used after calling -> `seal()`. - -### `used()` - -> Returns the amount of space requested so far. -> -> Should only be used after calling `seal()`. - -## Focus commands - -The plugin provides two - optional - [Focus][FocusSerial] command plugins: -`FocusSettingsCommand` and `FocusEEPROMCommand`. These must be explicitly added -to `KALEIDOSCOPE_INIT_PLUGINS` if one wishes to use them. They provide the -following commands: - - [FocusSerial]: https://github.com/keyboardio/Kaleidoscope-FocusSerial - -### `settings.defaultLayer` - -> Sets or returns (if called without arguments) the ID of the default layer. If -> set, the keyboard will automatically switch to the given layer when connected. -> Setting it to `255` disables the automatic switching. - -### `settings.crc` - -> Returns the actual, and the expected checksum of the settings. - -### `settings.valid?` - -> Returns either `true` or `false`, depending on whether the sealed settings are -> to be considered valid or not. - -### `settings.version` - -> Returns the (user-set) version of the settings. - -### `eeprom.contents` - -> Without argument, displays the full contents of the `EEPROM`, including the -> settings header. -> -> With arguments, the command updates as much of the `EEPROM` as arguments are -> provided. It will discard any unnecessary arguments. - -### `eeprom.free` - -> Returns the amount of free bytes in `EEPROM`. - -## Dependencies - -* [Kaleidoscope-FocusSerial][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-Settings/blob/master/examples/EEPROM-Settings/EEPROM-Settings.ino +See [doc/plugin/EEPROM-Settings.md](doc/plugin/EEPROM-Settings.md) for documentation. diff --git a/doc/plugin/EEPROM-Settings.md b/doc/plugin/EEPROM-Settings.md new file mode 100644 index 00000000..ccfb4955 --- /dev/null +++ b/doc/plugin/EEPROM-Settings.md @@ -0,0 +1,168 @@ +# Kaleidoscope-EEPROM-Settings + +To be able to reliably store persistent configuration in `EEPROM`, we need to be +able to split up the available space for plugins to use. We also want to make +sure that we notice when the `EEPROM` contents and the firmware are out of sync. +This plugin provides the tools to do that. + +It does not guard against errors, it merely provides the means to discover them, +and let the firmware Sketch handle the case in whatever way it finds reasonable. +It's a building block, and not much else. All Kaleidoscope plugins that need to +store data in `EEPROM` are encouraged to make use of this library. + +## Using the plugin + +There are a few steps one needs to take to use the plugin: we must first +register it, then either let other plugins request slices of `EEPROM`, or do so +ourselves. And finally, seal it, to signal that we are done setting up. At that +point, we can verify whether the contents of the `EEPROM` agree with our +firmware. + +```c++ +#include +#include + +static uint16_t settingsBase; +static struct { + bool someSettingFlag; +} testSettings; + +KALEIDOSCOPE_INIT_PLUGINS(EEPROMSettings, /* Other plugins that use EEPROM... */); + +void setup () { + Kaleidoscope.setup(); + + settingsBase = EEPROMSettings.requestSlice(sizeof(testSettings)); + + EEPROMSettings.seal(); + + if (!EEPROMSettings.isValid()) { + // Handle the case where the settings are out of sync... + // Flash LEDs, for example. + + return; + } + + EEPROM.get(settingsBase, testSettings); +} +``` + +## Plugin methods + +The plugin provides the `EEPROMSettings` object, which has the following methods: + +### `requestSlice(size)` + +> Requests a slice of the `EEPROM`, and returns the starting address (or 0 on +> error, including when the request arrived after sealing the layout). +> +> Should only be called **before** calling `seal()`. + +### `default_layer([id])` + +> Sets (or returns, if called without an ID) the default layer. When the +> keyboard boots up, it will automatically switch to the configured layer - if +> any. +> +> This is the Focus counterpart of the `default_layer()` method documented +> above. + +### `seal()` + +> Seal the `EEPROM` layout, so no new slices can be requested. The CRC checksum +> is considered final at this time, and the `isValid()`, `crc()`, `used()` and +> `version()` methods can be used from this point onwards. +> +> If not called explicitly, the layout will be sealed automatically after +> `setup()` in the sketch finished. + +### `update()` + +> Updates the `EEPROM` header with the current status quo, including the version +> and the CRC checksum. +> +> This should be called when upgrading from one version to another, or when +> fixing up an out-of-sync case. + +### `isValid()` + +> Returns whether the `EEPROM` header is valid, that is, if it has the expected +> CRC checksum. +> +> Should only be called after calling `seal()`. + +### `invalidate()` + +> Invalidates the `EEPROM` header. Use when the version does not match what the +> firmware would expect. This signals to other plugins that the contents of +> `EEPROM` should not be trusted. + +### `version([newVersion])` + +> Sets or returns the version of the `EEPROM` layout. This is purely for use by +> the firmware, so it can attempt to upgrade the contents, if need be, or alert +> the user in there's a mismatch. Plugins do not use this property. +> +> Should only be called after calling `seal()`. + +### `crc()` + +> Returns the CRC checksum of the layout. Should only be used after calling +> `seal()`. + +### `used()` + +> Returns the amount of space requested so far. +> +> Should only be used after calling `seal()`. + +## Focus commands + +The plugin provides two - optional - [Focus][FocusSerial] command plugins: +`FocusSettingsCommand` and `FocusEEPROMCommand`. These must be explicitly added +to `KALEIDOSCOPE_INIT_PLUGINS` if one wishes to use them. They provide the +following commands: + + [FocusSerial]: https://github.com/keyboardio/Kaleidoscope-FocusSerial + +### `settings.defaultLayer` + +> Sets or returns (if called without arguments) the ID of the default layer. If +> set, the keyboard will automatically switch to the given layer when connected. +> Setting it to `255` disables the automatic switching. + +### `settings.crc` + +> Returns the actual, and the expected checksum of the settings. + +### `settings.valid?` + +> Returns either `true` or `false`, depending on whether the sealed settings are +> to be considered valid or not. + +### `settings.version` + +> Returns the (user-set) version of the settings. + +### `eeprom.contents` + +> Without argument, displays the full contents of the `EEPROM`, including the +> settings header. +> +> With arguments, the command updates as much of the `EEPROM` as arguments are +> provided. It will discard any unnecessary arguments. + +### `eeprom.free` + +> Returns the amount of free bytes in `EEPROM`. + +## Dependencies + +* [Kaleidoscope-FocusSerial][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-Settings/blob/master/examples/EEPROM-Settings/EEPROM-Settings.ino diff --git a/src/Kaleidoscope-EEPROM-Settings.h b/src/Kaleidoscope-EEPROM-Settings.h index 123b49cc..a36d235e 100644 --- a/src/Kaleidoscope-EEPROM-Settings.h +++ b/src/Kaleidoscope-EEPROM-Settings.h @@ -17,5 +17,5 @@ #pragma once -#include -#include +#include +#include diff --git a/src/Kaleidoscope/EEPROM-Settings-Focus.cpp b/src/kaleidoscope/plugin/EEPROM-Settings-Focus.cpp similarity index 95% rename from src/Kaleidoscope/EEPROM-Settings-Focus.cpp rename to src/kaleidoscope/plugin/EEPROM-Settings-Focus.cpp index 56cc50a9..1f669f3b 100644 --- a/src/Kaleidoscope/EEPROM-Settings-Focus.cpp +++ b/src/kaleidoscope/plugin/EEPROM-Settings-Focus.cpp @@ -20,6 +20,7 @@ #include "crc.h" namespace kaleidoscope { +namespace plugin { namespace eeprom { EventHandlerResult FocusSettingsCommand::onFocusEvent(const char *command) { @@ -115,8 +116,9 @@ EventHandlerResult FocusEEPROMCommand::onFocusEvent(const char *command) { return EventHandlerResult::EVENT_CONSUMED; } +} } } -kaleidoscope::eeprom::FocusSettingsCommand FocusSettingsCommand; -kaleidoscope::eeprom::FocusEEPROMCommand FocusEEPROMCommand; +kaleidoscope::plugin::eeprom::FocusSettingsCommand FocusSettingsCommand; +kaleidoscope::plugin::eeprom::FocusEEPROMCommand FocusEEPROMCommand; diff --git a/src/Kaleidoscope/EEPROM-Settings-Focus.h b/src/kaleidoscope/plugin/EEPROM-Settings-Focus.h similarity index 86% rename from src/Kaleidoscope/EEPROM-Settings-Focus.h rename to src/kaleidoscope/plugin/EEPROM-Settings-Focus.h index bd0b659e..469e8db2 100644 --- a/src/Kaleidoscope/EEPROM-Settings-Focus.h +++ b/src/kaleidoscope/plugin/EEPROM-Settings-Focus.h @@ -20,6 +20,7 @@ #include namespace kaleidoscope { +namespace plugin { namespace eeprom { class FocusSettingsCommand : public kaleidoscope::Plugin { public: @@ -35,8 +36,9 @@ class FocusEEPROMCommand : public kaleidoscope::Plugin { EventHandlerResult onFocusEvent(const char *command); }; +} } } -extern kaleidoscope::eeprom::FocusSettingsCommand FocusSettingsCommand; -extern kaleidoscope::eeprom::FocusEEPROMCommand FocusEEPROMCommand; +extern kaleidoscope::plugin::eeprom::FocusSettingsCommand FocusSettingsCommand; +extern kaleidoscope::plugin::eeprom::FocusEEPROMCommand FocusEEPROMCommand; diff --git a/src/Kaleidoscope/EEPROM-Settings.cpp b/src/kaleidoscope/plugin/EEPROM-Settings.cpp similarity index 97% rename from src/Kaleidoscope/EEPROM-Settings.cpp rename to src/kaleidoscope/plugin/EEPROM-Settings.cpp index 3870187f..76058754 100644 --- a/src/Kaleidoscope/EEPROM-Settings.cpp +++ b/src/kaleidoscope/plugin/EEPROM-Settings.cpp @@ -19,6 +19,7 @@ #include "crc.h" namespace kaleidoscope { +namespace plugin { struct EEPROMSettings::settings EEPROMSettings::settings_; bool EEPROMSettings::is_valid_; @@ -113,6 +114,7 @@ void EEPROMSettings::version(uint8_t ver) { update(); } +} } -kaleidoscope::EEPROMSettings EEPROMSettings; +kaleidoscope::plugin::EEPROMSettings EEPROMSettings; diff --git a/src/Kaleidoscope/EEPROM-Settings.h b/src/kaleidoscope/plugin/EEPROM-Settings.h similarity index 94% rename from src/Kaleidoscope/EEPROM-Settings.h rename to src/kaleidoscope/plugin/EEPROM-Settings.h index 73d08636..0264ab3e 100644 --- a/src/Kaleidoscope/EEPROM-Settings.h +++ b/src/kaleidoscope/plugin/EEPROM-Settings.h @@ -21,6 +21,7 @@ #include namespace kaleidoscope { +namespace plugin { class EEPROMSettings : public kaleidoscope::Plugin { public: EEPROMSettings(void) {} @@ -52,6 +53,7 @@ class EEPROMSettings : public kaleidoscope::Plugin { uint16_t crc; } settings_; }; -}; +} +} -extern kaleidoscope::EEPROMSettings EEPROMSettings; +extern kaleidoscope::plugin::EEPROMSettings EEPROMSettings; diff --git a/src/Kaleidoscope/crc.cpp b/src/kaleidoscope/plugin/crc.cpp similarity index 100% rename from src/Kaleidoscope/crc.cpp rename to src/kaleidoscope/plugin/crc.cpp diff --git a/src/Kaleidoscope/crc.h b/src/kaleidoscope/plugin/crc.h similarity index 100% rename from src/Kaleidoscope/crc.h rename to src/kaleidoscope/plugin/crc.h