pull/389/head
Gergely Nagy
6 years ago
commit
535f367f48
@ -0,0 +1,124 @@
|
||||
# Kaleidoscope-EEPROM-Keymap-Programmer
|
||||
|
||||
Inspired by a similar feature on other keyboards, the `EEPROM-Keymap-Programmer`
|
||||
plugin implements an on-device keymap re-arrangement / re-coding system. There
|
||||
are two modes of operation: in one, we need to press a key we want to change,
|
||||
then another to copy from. In the other, we press a key to change, and then
|
||||
input a key code (terminated by any non-number key).
|
||||
|
||||
## The two modes of operation
|
||||
|
||||
It is worth looking at the two separately, to better understand how they work,
|
||||
and what they accomplish:
|
||||
|
||||
### Copy mode
|
||||
|
||||
In `COPY` mode, the plugin will use both the built-in, default keymap, and the
|
||||
override stored in `EEPROM`. When we select a key to override, we need to tap
|
||||
another, which will be used as the source. The source key's code will be looked
|
||||
up from the built-in keymap. For example, lets say we want to swap `A` and `B`
|
||||
for some odd reason. We can do this by triggering the keymap programmer mode,
|
||||
then tapping `A` to select it as the destination, then `B` as the source. The
|
||||
plugin will look up the keycode in the built-in keymap for the key in `B`'s
|
||||
location, and replace the location of `A` in the override with it. Next, we
|
||||
press the `B` key to select it as the destination, and we press the key that
|
||||
used to be `A` (but is now `B` too) to select it as a source. Because source
|
||||
keys are looked up in the built-in keymap, the plugin will find it is `A`.
|
||||
|
||||
Obviously, this method only works if we have a built-in keymap, and it does not
|
||||
support copying from another layer. It is merely a way to rearrange simple
|
||||
things, like alphanumerics.
|
||||
|
||||
### Code mode
|
||||
|
||||
In `CODE` mode, instead of selecting a source key, we need to enter a code:
|
||||
press numbers to input the code, and any non-number key to end the sequence.
|
||||
Thus, when entering keymap programmer mode, and selecting, say, the `A` key,
|
||||
then tapping `5 SPACE` will set the key to `B` (which has the keycode of `5`).
|
||||
|
||||
This allows us to use keycodes not present on the built-in keymap, at the
|
||||
expense of having to know the keycode, and allowing no mistakes.
|
||||
|
||||
## Using the plugin
|
||||
|
||||
Adding the functionality of the plugin to a Sketch is easier the usage explained
|
||||
above, though it requires that the [EEPROM-Keymap][plugin:eeprom-keymap] plugin
|
||||
is also used, and set up appropriately.
|
||||
|
||||
Once the prerequisites are dealt with, all we need to do is to use the plugin,
|
||||
and find a way to trigger entering the keymap programmer mode. One such way is
|
||||
to use a macro, as in the example below:
|
||||
|
||||
```c++
|
||||
#include <Kaleidoscope.h>
|
||||
#include <Kaleidoscope-EEPROM-Keymap.h>
|
||||
#include <Kaleidoscope-EEPROM-Keymap-Programmer.h>
|
||||
#include <Kaleidoscope-EEPROM-Settings.h>
|
||||
#include <Kaleidoscope-Macros.h>
|
||||
|
||||
const macro_t *macroAction(uint8_t macroIndex, uint8_t keyState) {
|
||||
if (macroIndex == 0 && keyToggledOff(keyState)) {
|
||||
EEPROMKeymapProgrammer.activate();
|
||||
}
|
||||
|
||||
return MACRO_NONE;
|
||||
}
|
||||
|
||||
KALEIDOSCOPE_INIT_PLUGINS(EEPROMSettings,
|
||||
EEPROMKeymapProgrammer,
|
||||
EEPROMKeymap,
|
||||
Macros);
|
||||
|
||||
void setup() {
|
||||
Kaleidoscope.setup();
|
||||
|
||||
Layer.getKey = EEPROMKeymap.getKey;
|
||||
|
||||
EEPROMKeymap.max_layers(1);
|
||||
EEPROMSettings.seal();
|
||||
}
|
||||
```
|
||||
|
||||
The plugin should be used as early as possible, otherwise other plugins that
|
||||
hook into the event system may start processing events before the programmer can
|
||||
take over.
|
||||
|
||||
## Plugin methods
|
||||
|
||||
The plugin provides the `EEPROMKeymapProgrammer` object, which has the following
|
||||
methods and properties:
|
||||
|
||||
### `.activate()`
|
||||
|
||||
> Activates the keymap programmer. This is the function one needs to call from -
|
||||
> say - a macro, to enter the edit state.
|
||||
|
||||
### `.mode`
|
||||
|
||||
> Set this property to the mode to use for editing: either
|
||||
> `kaleidoscope::EEPROMKeymapProgrammer::COPY`, or
|
||||
> `kaleidoscope::EEPROMKeymapProgrammer::CODE`.
|
||||
>
|
||||
> Defaults to `kaleidoscope::EEPROMKeymapProgrammer::CODE`.
|
||||
|
||||
## Focus commands
|
||||
|
||||
The plugin provides a single `Focus` hook: `FOCUS_HOOK_KEYMAP_PROGRAMMER`, which
|
||||
in turn provides the following command:
|
||||
|
||||
### `keymap.toggleProgrammer`
|
||||
|
||||
> Toggles the programmer mode on or off.
|
||||
|
||||
## Dependencies
|
||||
|
||||
* [Kaleidoscope-EEPROM-Keymap][plugin:eeprom-keymap]
|
||||
|
||||
[plugin:eeprom-keymap]: EEPROM-Keymap.md
|
||||
|
||||
## Further reading
|
||||
|
||||
Starting from the [example][plugin:example] is the recommended way of getting
|
||||
started with the plugin.
|
||||
|
||||
[plugin:example]: ../../examples/EEPROM-Keymap-Programmer/EEPROM-Keymap-Programmer.ino
|
||||
@ -0,0 +1,71 @@
|
||||
/* -*- mode: c++ -*-
|
||||
* Kaleidoscope-EEPROM-Keymap-Programmer -- On-the-fly reprogrammable keymap.
|
||||
* Copyright (C) 2017, 2018 Keyboard.io, Inc
|
||||
*
|
||||
* 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, version 3.
|
||||
*
|
||||
* 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-EEPROM-Settings.h>
|
||||
#include <Kaleidoscope-EEPROM-Keymap.h>
|
||||
#include <Kaleidoscope-EEPROM-Keymap-Programmer.h>
|
||||
#include <Kaleidoscope-Macros.h>
|
||||
|
||||
// *INDENT-OFF*
|
||||
const Key keymaps[][ROWS][COLS] PROGMEM = {
|
||||
[0] = KEYMAP_STACKED
|
||||
(M(0), 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_NoKey,
|
||||
|
||||
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_NoKey),
|
||||
};
|
||||
// *INDENT-ON*
|
||||
|
||||
const macro_t *macroAction(uint8_t macroIndex, uint8_t keyState) {
|
||||
if (macroIndex == 0 && keyToggledOff(keyState)) {
|
||||
EEPROMKeymapProgrammer.activate();
|
||||
}
|
||||
|
||||
return MACRO_NONE;
|
||||
}
|
||||
|
||||
KALEIDOSCOPE_INIT_PLUGINS(EEPROMSettings,
|
||||
EEPROMKeymapProgrammer,
|
||||
EEPROMKeymap,
|
||||
Macros);
|
||||
|
||||
void setup() {
|
||||
Serial.begin(9600);
|
||||
|
||||
Kaleidoscope.setup();
|
||||
|
||||
Layer.getKey = EEPROMKeymap.getKey;
|
||||
|
||||
EEPROMKeymap.max_layers(1);
|
||||
EEPROMSettings.seal();
|
||||
}
|
||||
|
||||
void loop() {
|
||||
Kaleidoscope.loop();
|
||||
}
|
||||
@ -0,0 +1,20 @@
|
||||
/* -*- mode: c++ -*-
|
||||
* Kaleidoscope-EEPROM-Keymap-Programmer -- On-the-fly reprogrammable keymap.
|
||||
* Copyright (C) 2017 Keyboard.io, Inc
|
||||
*
|
||||
* 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, version 3.
|
||||
*
|
||||
* 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/EEPROM-Keymap-Programmer.h>
|
||||
@ -0,0 +1,119 @@
|
||||
/* -*- mode: c++ -*-
|
||||
* Kaleidoscope-EEPROM-Keymap-Programmer -- On-the-fly reprogrammable keymap.
|
||||
* Copyright (C) 2017, 2018 Keyboard.io, Inc
|
||||
*
|
||||
* 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, version 3.
|
||||
*
|
||||
* 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-EEPROM-Keymap-Programmer.h>
|
||||
#include <Kaleidoscope-FocusSerial.h>
|
||||
|
||||
namespace kaleidoscope {
|
||||
namespace plugin {
|
||||
uint16_t EEPROMKeymapProgrammer::update_position_;
|
||||
EEPROMKeymapProgrammer::state_t EEPROMKeymapProgrammer::state_;
|
||||
EEPROMKeymapProgrammer::mode_t EEPROMKeymapProgrammer::mode;
|
||||
Key EEPROMKeymapProgrammer::new_key_;
|
||||
|
||||
void EEPROMKeymapProgrammer::nextState(void) {
|
||||
switch (state_) {
|
||||
case INACTIVE:
|
||||
state_ = WAIT_FOR_KEY;
|
||||
break;
|
||||
case WAIT_FOR_KEY:
|
||||
if (mode == CODE)
|
||||
state_ = WAIT_FOR_CODE;
|
||||
else
|
||||
state_ = WAIT_FOR_SOURCE_KEY;
|
||||
break;
|
||||
case WAIT_FOR_CODE:
|
||||
case WAIT_FOR_SOURCE_KEY:
|
||||
::EEPROMKeymap.updateKey(update_position_, new_key_);
|
||||
cancel();
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
void EEPROMKeymapProgrammer::cancel(void) {
|
||||
update_position_ = 0;
|
||||
new_key_ = Key_NoKey;
|
||||
state_ = INACTIVE;
|
||||
}
|
||||
|
||||
EventHandlerResult EEPROMKeymapProgrammer::onKeyswitchEvent(Key &mapped_key, byte row, byte col, uint8_t key_state) {
|
||||
if (state_ == INACTIVE)
|
||||
return EventHandlerResult::OK;
|
||||
|
||||
if (state_ == WAIT_FOR_KEY) {
|
||||
if (keyToggledOn(key_state)) {
|
||||
update_position_ = Layer.top() * ROWS * COLS + row * COLS + col;
|
||||
}
|
||||
if (keyToggledOff(key_state)) {
|
||||
if ((uint16_t)(Layer.top() * ROWS * COLS + row * COLS + col) == update_position_)
|
||||
nextState();
|
||||
}
|
||||
return EventHandlerResult::EVENT_CONSUMED;
|
||||
}
|
||||
|
||||
if (state_ == WAIT_FOR_SOURCE_KEY) {
|
||||
if (keyToggledOn(key_state)) {
|
||||
new_key_ = Layer.getKeyFromPROGMEM(Layer.top(), row, col);
|
||||
}
|
||||
if (keyToggledOff(key_state)) {
|
||||
if (new_key_ == Layer.getKeyFromPROGMEM(Layer.top(), row, col))
|
||||
nextState();
|
||||
}
|
||||
return EventHandlerResult::EVENT_CONSUMED;
|
||||
}
|
||||
|
||||
// WAIT_FOR_CODE state
|
||||
|
||||
if (mapped_key < Key_1 || mapped_key > Key_0)
|
||||
return EventHandlerResult::OK;
|
||||
|
||||
if (!keyToggledOn(key_state)) {
|
||||
return EventHandlerResult::EVENT_CONSUMED;
|
||||
}
|
||||
|
||||
uint8_t n;
|
||||
if (mapped_key.keyCode == Key_0.keyCode)
|
||||
n = 0;
|
||||
else
|
||||
n = mapped_key.keyCode - Key_1.keyCode + 1;
|
||||
|
||||
new_key_.raw = new_key_.raw * 10 + n;
|
||||
|
||||
return EventHandlerResult::EVENT_CONSUMED;
|
||||
}
|
||||
|
||||
EventHandlerResult EEPROMKeymapProgrammer::onFocusEvent(const char *command) {
|
||||
const char *cmd = PSTR("keymap.toggleProgrammer");
|
||||
|
||||
if (::Focus.handleHelp(command, cmd))
|
||||
return EventHandlerResult::OK;
|
||||
|
||||
if (strcmp_P(command, cmd) != 0)
|
||||
return EventHandlerResult::OK;
|
||||
|
||||
if (state_ == INACTIVE)
|
||||
activate();
|
||||
else
|
||||
cancel();
|
||||
|
||||
return EventHandlerResult::EVENT_CONSUMED;
|
||||
}
|
||||
|
||||
}
|
||||
}
|
||||
|
||||
kaleidoscope::plugin::EEPROMKeymapProgrammer EEPROMKeymapProgrammer;
|
||||
@ -0,0 +1,59 @@
|
||||
/* -*- mode: c++ -*-
|
||||
* Kaleidoscope-EEPROM-Keymap-Programmer -- On-the-fly reprogrammable keymap.
|
||||
* Copyright (C) 2017, 2018 Keyboard.io, Inc
|
||||
*
|
||||
* 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, version 3.
|
||||
*
|
||||
* 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-EEPROM-Keymap.h>
|
||||
|
||||
namespace kaleidoscope {
|
||||
namespace plugin {
|
||||
class EEPROMKeymapProgrammer : public kaleidoscope::Plugin {
|
||||
public:
|
||||
typedef enum {
|
||||
CODE,
|
||||
COPY,
|
||||
} mode_t;
|
||||
static mode_t mode;
|
||||
|
||||
EEPROMKeymapProgrammer(void) {}
|
||||
|
||||
static void activate(void) {
|
||||
nextState();
|
||||
}
|
||||
static void nextState(void);
|
||||
static void cancel(void);
|
||||
|
||||
EventHandlerResult onKeyswitchEvent(Key &mapped_key, byte row, byte col, uint8_t key_state);
|
||||
EventHandlerResult onFocusEvent(const char *command);
|
||||
|
||||
private:
|
||||
typedef enum {
|
||||
INACTIVE,
|
||||
WAIT_FOR_KEY,
|
||||
WAIT_FOR_CODE,
|
||||
WAIT_FOR_SOURCE_KEY,
|
||||
} state_t;
|
||||
static state_t state_;
|
||||
|
||||
static uint16_t update_position_; // layer, row, col
|
||||
static Key new_key_;
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
extern kaleidoscope::plugin::EEPROMKeymapProgrammer EEPROMKeymapProgrammer;
|
||||
Loading…
Reference in new issue