alpha
/
Kaleidoscope
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'plugin/Steno/f/monorepo' into f/monorepo-stage2

Browse Source
pull/389/head
Gergely Nagy 6 years ago
parent 237ab5e286 c464a7bbe6
commit 54044b58d2
No known key found for this signature in database
GPG Key ID: AC1E90BAC433F68F
5 changed files with 339 additions and 0 deletions
Show Stats Download Patch File Download Diff File

96
doc/plugin/Steno.md
Unescape View File

@ -0,0 +1,96 @@
# Kaleidoscope-Steno
Stenography is a way to write in shorthand, a chorded input system that allows
very fast input (considerably higher than normal touch typing), by using
shorthand chords and a dictionary. This plugin implements the `GeminiPR`
protocol that supports a number of systems, including [Plover][plover].
[plover]: http://www.openstenoproject.org/plover/
While Plover supports a normal QWERTY keyboard too, having a dedicated plugin
comes with important advantages:
* No need to toggle Plover on and off, because the normal keys are not taken
over by Plover anymore.
* Easier toggling, because you only have to toggle the layer, not Plover too. If
you switch back to a keyboard layer, without toggling Plover off, nothing
unexpected will happen. Plover will not take over the keys.
* The `GeminiPR` protocol supports language systems other than English.
Do note that the `GeminiPR` protocol is implemented over the virtual serial
port, so any plugin that wants to use that port too, will run into
conflicts with the Steno plugin. In other words, don't use it together
with [Focus][k:focus].
[k:focus]: FocusSerial.md
## What is Steno? Why should I use it? How do I learn?
As mentioned above, steno (short for "stenography") is a shorthand, chorded
input system that allows very fast input - licensed stenographers are required
to type **225 WPM at 95% accuracy** to get their license. Although reaching that
speed typically takes 2-6 years of practice and training, lower speeds
comparable to or exceeding that of touch typing can reportedly be reached in
only a few months.
[This talk][stenotalk] (YouTube link) gives a brief introduction to Steno, how
it works, and why it is cool.
[stenotalk]: https://youtu.be/Wpv-Qb-dB6g
One recommend way to get started with learning Steno is with [Plover][plover].
Plover is software for your computer that will interpret the steno input from
your Model 01 (or other NKRO QWERTY keyboard); it is available for Windows,
macOS, and Linux. Plover's [Beginner's Guide][ploverguide] is a great place to
get started with Steno in general and Plover in particular.
[ploverguide]: https://github.com/openstenoproject/plover/wiki/Beginner's-Guide:-Get-Started-with-Plover
## Using the plugin
To use the plugin, simply include the header in your Sketch, tell the firmware
to use the `GeminiPR` object, and place Steno keys on your keymap. It is best
illustrated with an example:
```c++
#include <Kaleidoscope.h>
#include <Kaleidoscope-Steno.h>
// Somewhere in the keymap:
S(S1), S(S2), etc
KALEIDOSCOPE_INIT_PLUGINS(GeminiPR);
void setup() {
Kaleidoscope.setup();
}
```
## Keys provided by the plugin
The plugin provides a number of keys one can put on the keymap, that allow
correspond to various Steno keys. All of these must be used together with the
`S()` macro provided by the plugin, as can be seen in the example above.
The provided keys are: `FN`, `N1`, `N2`, `N3`, `N4`, `N5`, `N6`, `S1`, `S2`,
`TL`, `KL`, `PL`, `WL`, `HL`, `RL`, `A`, `O`, `ST1`, `ST2`, `RE1`, `RE2`, `PWR`,
`ST3`, `ST4`, `E`, `U`, `FR`, `RR`, `PR`, `BR`, `LR`, `GR`, `TR`, `SR`, `DR`,
`N7`, `N8`, `N9`, `NA`, `NB`, `NC`, `ZR`.
See the [example][plugin:example] for the default/suggested placements of each
of these keys.
## Plugin methods and properties
The plugin provides a `GeminiPR` object, with no public methods or properties.
## Dependencies
* [Kaleidoscope-Ranges](Ranges.md)
## Further reading
Starting from the [example][plugin:example] is the recommended way of getting
started with the plugin.
[plugin:example]: ../../examples/Steno/Steno.ino

70
examples/Steno/Steno.ino
Unescape View File

@ -0,0 +1,70 @@
/* -*- mode: c++ -*-
* Kaleidoscope-Steno -- Steno protocols for Kaleidoscope
* Copyright (C) 2017 Joseph Wasson
* Copyright (C) 2017, 2018 Gergely Nagy
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#include <Kaleidoscope.h>
#include <Kaleidoscope-Steno.h>
// *INDENT-OFF*
const Key keymaps[][ROWS][COLS] PROGMEM = {
[0] = KEYMAP_STACKED
(Key_NoKey, Key_1, Key_2, Key_3, Key_4, Key_5, Key_NoKey,
Key_Backtick, Key_Q, Key_W, Key_E, Key_R, Key_T, Key_Tab,
Key_PageUp, Key_A, Key_S, Key_D, Key_F, Key_G,
Key_PageDown, Key_Z, Key_X, Key_C, Key_V, Key_B, Key_Escape,
Key_LeftControl, Key_Backspace, Key_LeftGui, Key_LeftShift,
Key_Keymap1,
Key_skip, Key_6, Key_7, Key_8, Key_9, Key_0, Key_skip,
Key_Enter, Key_Y, Key_U, Key_I, Key_O, Key_P, Key_Equals,
Key_H, Key_J, Key_K, Key_L, Key_Semicolon, Key_Quote,
Key_skip, Key_N, Key_M, Key_Comma, Key_Period, Key_Slash, Key_Minus,
Key_RightShift, Key_RightAlt, Key_Spacebar, Key_RightControl,
Key_Keymap1),
[1] = KEYMAP_STACKED
(XXX, XXX, XXX, XXX, XXX, XXX, S(N6),
XXX, S(N1), S(N2), S(N3), S(N4), S(N5), S(ST1),
S(FN), S(S1), S(TL), S(PL), S(HL), S(ST1),
S(PWR), S(S2), S(KL), S(WL), S(RL), S(ST2), S(ST2),
S(RE1), XXX, S(A), S(O),
___,
S(N7), XXX, XXX, XXX, XXX, XXX, XXX,
S(ST3), S(N8), S(N9), S(NA), S(NB), S(NC), XXX,
S(ST3), S(FR), S(PR), S(LR), S(TR), S(DR),
S(ST4), S(ST4), S(RR), S(BR), S(GR), S(SR), S(ZR),
S(E), S(U), XXX, S(RE2),
___),
};
// *INDENT-ON*
KALEIDOSCOPE_INIT_PLUGINS(GeminiPR);
void setup() {
Serial.begin(9600);
Kaleidoscope.setup();
}
void loop() {
Kaleidoscope.loop();
}

21
src/Kaleidoscope-Steno.h
Unescape View File

@ -0,0 +1,21 @@
/* Kaleidoscope-Steno -- Steno protocols for Kaleidoscope
* Copyright (C) 2017 Joseph Wasson
* Copyright (C) 2017 Gergely Nagy
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#pragma once
#include <kaleidoscope/plugin/GeminiPR.h>

55
src/kaleidoscope/plugin/GeminiPR.cpp
Unescape View File

@ -0,0 +1,55 @@
/* Kaleidoscope-Steno -- Steno protocols for Kaleidoscope
* Copyright (C) 2017 Joseph Wasson
* Copyright (C) 2017, 2018 Gergely Nagy
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#include <Kaleidoscope-Steno.h>
namespace kaleidoscope {
namespace plugin {
namespace steno {
uint8_t GeminiPR::keys_held_;
uint8_t GeminiPR::state_[6];
EventHandlerResult GeminiPR::onKeyswitchEvent(Key &mapped_key, byte row, byte col, uint8_t keyState) {
if (mapped_key < geminipr::START ||
mapped_key > geminipr::END)
return EventHandlerResult::OK;
if (keyToggledOn(keyState)) {
uint8_t key = mapped_key.raw - geminipr::START;
++keys_held_;
state_[key / 7] |= 1 << (6 - (key % 7));
} else if (keyToggledOff(keyState)) {
--keys_held_;
if (keys_held_ == 0) {
state_[0] |= 0x80;
Serial.write(state_, sizeof(state_));
memset(state_, 0, sizeof(state_));
}
}
return EventHandlerResult::EVENT_CONSUMED;
}
}
}
}
kaleidoscope::plugin::steno::GeminiPR GeminiPR;

97
src/kaleidoscope/plugin/GeminiPR.h
Unescape View File

@ -0,0 +1,97 @@
/* Kaleidoscope-Steno -- Steno protocols for Kaleidoscope
* Copyright (C) 2017 Joseph Wasson
* Copyright (C) 2017, 2018 Gergely Nagy
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#pragma once
#include <Kaleidoscope.h>
#include <Kaleidoscope-Ranges.h>
#define S(n) (Key) {.raw = kaleidoscope::plugin::steno::geminipr::n }
namespace kaleidoscope {
namespace plugin {
namespace steno {
class GeminiPR : public kaleidoscope::Plugin {
public:
GeminiPR(void) {}
EventHandlerResult onKeyswitchEvent(Key &mapped_key, byte row, byte col, uint8_t keyState);
private:
static uint8_t keys_held_;
static uint8_t state_[6];
};
namespace geminipr {
enum {
START = kaleidoscope::ranges::STENO_FIRST,
FN = START,
NUM,
N1 = NUM,
N2,
N3,
N4,
N5,
N6,
SL,
S1 = SL,
S2,
TL,
KL,
PL,
WL,
HL,
RL,
A,
O,
STR,
ST1 = STR,
ST2,
RES1,
RE1 = RES1,
RES2,
RE2 = RES2,
PWR,
ST3,
ST4,
E,
U,
FR,
RR,
PR,
BR,
LR,
GR,
TR,
SR,
DR,
N7,
N8,
N9,
NA,
NB,
NC,
ZR,
END = ZR,
};
}
}
}
}
extern kaleidoscope::plugin::steno::GeminiPR GeminiPR;
Write Preview
Loading…
Cancel
Save