From d69644271c6730d3de76ceecb6eadca4c1304a33 Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Sat, 13 Oct 2018 12:29:05 +0200 Subject: [PATCH] Rearrange the file layout in preparation of becoming a monorepo Move the documentation to `doc/plugin/FocusSerial.md`, sources under `src/kaleidoscope/plugin/` (appropriately namespaced). This is in preparation of merging plugins into a single monorepo. This also merges the former `UPGRADING.md` into `doc/plugin/FocusSerial.md`. Signed-off-by: Gergely Nagy --- README.md | 98 +----------------- UPGRADING.md => doc/plugin/FocusSerial.md | 99 +++++++++++++++++++ src/Kaleidoscope-FocusSerial.h | 2 +- src/kaleidoscope/{ => plugin}/FocusSerial.cpp | 4 +- src/kaleidoscope/{ => plugin}/FocusSerial.h | 6 +- 5 files changed, 109 insertions(+), 100 deletions(-) rename UPGRADING.md => doc/plugin/FocusSerial.md (59%) rename src/kaleidoscope/{ => plugin}/FocusSerial.cpp (97%) rename src/kaleidoscope/{ => plugin}/FocusSerial.h (95%) diff --git a/README.md b/README.md index 1af8026d..027884b8 100644 --- a/README.md +++ b/README.md @@ -1,102 +1,8 @@ # Kaleidoscope-FocusSerial - [![Build Status][travis:image]][travis:status] +[![Build Status][travis:image]][travis:status] [travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-FocusSerial.svg?branch=master [travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-FocusSerial -Bidirectional communication for Kaleidoscope. With this plugin enabled, plugins that implement the `onFocusEvent` hook will start responding to Focus commands sent via `Serial`, allowing bidirectional communication between firmware and host. - -This plugin is an upgrade of the former [Kaleidoscope-Focus][kaleidoscope:focus] plugin. See [UPGRADING.md](UPGRADING.md) for information about how to transition to the new system. - - [kaleidoscope:focus]: https://github.com/keyboardio/Kaleidoscope-Focus - -## Using the plugin - -This plugin is **not** meant to be used by the end-user (apart from setting it up to use plugin-provided hooks), but by plugin authors instead. As an end user, you just need to use Focus-enabled plugins like you normally would, and once `FocusSerial` is enabled, their commands will be available too. - -Nevertheless, a very simple example is shown below: - -```c++ -#include -#include - -namespace kaleidoscope { -class FocusTestCommand : public Plugin { - public: - FocusTestCommand() {} - - EventHandlerResult onFocusEvent(const char *command) { - if (strcmp_P(command, PSTR("test")) != 0) - return EventHandlerResult::OK; - - Serial.println(F("Congratulations, the test command works!")); - return EventHandlerResult::EVENT_CONSUMED; - } -}; -} - -kaleidoscope::FocusTestCommand FocusTestCommand; - -KALEIDOSCOPE_INIT_PLUGINS(Focus, FocusTestCommand); - -void setup () { - Kaleidoscope.setup (); -} -``` - -## Plugin methods - -The plugin provides the `Focus` object, with a couple of helper methods aimed at developers. Documenting those is a work in progress for now. - -## Wire protocol - -`Focus` uses a simple, textual, request-response-based wire protocol. - -Each request has to be on one line, anything before the first space is the command part (if there is no space, just a newline, then the whole line will be considered a command), everything after are arguments. The plugin itself only parses until the end of the command part, argument parsing is left to the various hooks. If there is anything left on the line after hooks are done processing, it will be ignored. - -Responses can be multi-line, but most aren't. Their content is also up to the hooks, `Focus` does not enforce anything, except a trailing dot and a newline. Responses should end with a dot on its own line. - -Apart from these, there are no restrictions on what can go over the wire, but to make the experience consistent, find a few guidelines below: - -* Commands should be namespaced, so that the plugin name, or functionality comes first, then the sub-command or property. Such as `led.theme`, or `led.setAll`. -* One should not use setters and getters, but a single property command instead. One, which when called without arguments, will act as a getter, and as a setter otherwise. -* Namespaces should be lowercase, while the commands within them camel-case. -* Do as little work in the hooks as possible. While the protocol is human readable, the expectation is that tools will be used to interact with the keyboard. -* As such, keep formatting to the bare minimum. No fancy table-like responses. -* In general, the output of a getter should be copy-pasteable to a setter. - -These are merely guidelines, and there can be - and are - exceptions. Use your discretion when writing Focus hooks. - -### Example - -In the examples below, `<` denotes what the host sends to the keyboard, `>` what -the keyboard responds. - -``` -< test -> Congratulations, the test command works! -> . -``` - -``` -< help -> help -> test -> palette -> . -``` - -``` -< palette -> 0 0 0 128 128 128 255 255 255 -> . -< palette 0 0 0 128 128 128 255 255 255 -> . -``` - -## 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-FocusSerial/blob/master/examples/FocusSerial/FocusSerial.ino +See [doc/plugin/FocusSerial.md](doc/plugin/FocusSerial.md) for documentation. diff --git a/UPGRADING.md b/doc/plugin/FocusSerial.md similarity index 59% rename from UPGRADING.md rename to doc/plugin/FocusSerial.md index 351489a1..7680c73d 100644 --- a/UPGRADING.md +++ b/doc/plugin/FocusSerial.md @@ -1,3 +1,102 @@ +# Kaleidoscope-FocusSerial + +Bidirectional communication for Kaleidoscope. With this plugin enabled, plugins that implement the `onFocusEvent` hook will start responding to Focus commands sent via `Serial`, allowing bidirectional communication between firmware and host. + +This plugin is an upgrade of the former [Kaleidoscope-Focus][kaleidoscope:focus] plugin. See the [UPGRADING][upgrading] section for information about how to transition to the new system. + + [kaleidoscope:focus]: https://github.com/keyboardio/Kaleidoscope-Focus + [upgrading]: #upgrading-from-focus-to-onfocusevent--focusserial + +## Using the plugin + +This plugin is **not** meant to be used by the end-user (apart from setting it up to use plugin-provided hooks), but by plugin authors instead. As an end user, you just need to use Focus-enabled plugins like you normally would, and once `FocusSerial` is enabled, their commands will be available too. + +Nevertheless, a very simple example is shown below: + +```c++ +#include +#include + +namespace kaleidoscope { +class FocusTestCommand : public Plugin { + public: + FocusTestCommand() {} + + EventHandlerResult onFocusEvent(const char *command) { + if (strcmp_P(command, PSTR("test")) != 0) + return EventHandlerResult::OK; + + Serial.println(F("Congratulations, the test command works!")); + return EventHandlerResult::EVENT_CONSUMED; + } +}; +} + +kaleidoscope::FocusTestCommand FocusTestCommand; + +KALEIDOSCOPE_INIT_PLUGINS(Focus, FocusTestCommand); + +void setup () { + Kaleidoscope.setup (); +} +``` + +## Plugin methods + +The plugin provides the `Focus` object, with a couple of helper methods aimed at developers. Documenting those is a work in progress for now. + +## Wire protocol + +`Focus` uses a simple, textual, request-response-based wire protocol. + +Each request has to be on one line, anything before the first space is the command part (if there is no space, just a newline, then the whole line will be considered a command), everything after are arguments. The plugin itself only parses until the end of the command part, argument parsing is left to the various hooks. If there is anything left on the line after hooks are done processing, it will be ignored. + +Responses can be multi-line, but most aren't. Their content is also up to the hooks, `Focus` does not enforce anything, except a trailing dot and a newline. Responses should end with a dot on its own line. + +Apart from these, there are no restrictions on what can go over the wire, but to make the experience consistent, find a few guidelines below: + +* Commands should be namespaced, so that the plugin name, or functionality comes first, then the sub-command or property. Such as `led.theme`, or `led.setAll`. +* One should not use setters and getters, but a single property command instead. One, which when called without arguments, will act as a getter, and as a setter otherwise. +* Namespaces should be lowercase, while the commands within them camel-case. +* Do as little work in the hooks as possible. While the protocol is human readable, the expectation is that tools will be used to interact with the keyboard. +* As such, keep formatting to the bare minimum. No fancy table-like responses. +* In general, the output of a getter should be copy-pasteable to a setter. + +These are merely guidelines, and there can be - and are - exceptions. Use your discretion when writing Focus hooks. + +### Example + +In the examples below, `<` denotes what the host sends to the keyboard, `>` what +the keyboard responds. + +``` +< test +> Congratulations, the test command works! +> . +``` + +``` +< help +> help +> test +> palette +> . +``` + +``` +< palette +> 0 0 0 128 128 128 255 255 255 +> . +< palette 0 0 0 128 128 128 255 255 255 +> . +``` + +## 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-FocusSerial/blob/master/examples/FocusSerial/FocusSerial.ino + Upgrading from Focus to onFocusEvent + FocusSerial ================================================== diff --git a/src/Kaleidoscope-FocusSerial.h b/src/Kaleidoscope-FocusSerial.h index 02e24f80..7eab4ff4 100644 --- a/src/Kaleidoscope-FocusSerial.h +++ b/src/Kaleidoscope-FocusSerial.h @@ -17,4 +17,4 @@ #pragma once -#include +#include diff --git a/src/kaleidoscope/FocusSerial.cpp b/src/kaleidoscope/plugin/FocusSerial.cpp similarity index 97% rename from src/kaleidoscope/FocusSerial.cpp rename to src/kaleidoscope/plugin/FocusSerial.cpp index 4bd1f5f1..9c240963 100644 --- a/src/kaleidoscope/FocusSerial.cpp +++ b/src/kaleidoscope/plugin/FocusSerial.cpp @@ -22,6 +22,7 @@ #endif namespace kaleidoscope { +namespace plugin { char FocusSerial::command_[32]; @@ -103,6 +104,7 @@ void FocusSerial::readColor(cRGB &color) { color.b = Serial.parseInt(); } +} } -kaleidoscope::FocusSerial Focus; +kaleidoscope::plugin::FocusSerial Focus; diff --git a/src/kaleidoscope/FocusSerial.h b/src/kaleidoscope/plugin/FocusSerial.h similarity index 95% rename from src/kaleidoscope/FocusSerial.h rename to src/kaleidoscope/plugin/FocusSerial.h index 827a1340..3f600c54 100644 --- a/src/kaleidoscope/FocusSerial.h +++ b/src/kaleidoscope/plugin/FocusSerial.h @@ -20,6 +20,7 @@ #include namespace kaleidoscope { +namespace plugin { class FocusSerial : public kaleidoscope::Plugin { public: FocusSerial(void) {} @@ -49,6 +50,7 @@ class FocusSerial : public kaleidoscope::Plugin { static void drain(void); }; -}; +} +} -extern kaleidoscope::FocusSerial Focus; +extern kaleidoscope::plugin::FocusSerial Focus;