.. | ||
tests | ||
chord.py | ||
engine.part.1 | ||
engine.part.2 | ||
engine.part.3 | ||
keymap_def.schema.json | ||
parser.py | ||
README.md | ||
state_machine.dot | ||
state_machine.svg |
README
About
This is a custom combo engine. I call it chording engine mostly to differentiate it from QMK's combos. It is useful even if you are not using chording as a main input method to replace combos.
Why does this exist? Typing on tiny keyboards can be challenging and you will end up relying on dances and / or combos. Pure QMK combos can be insufficient as they do not really support overlapping combos. For example, if you define 3 combos (KC_Q, KC_W)
, (KC_Z, KC_X)
and (KC_Q, KC_W, KC_Z, KC_X)
and press Q, W, Z and X at the same time, all three combos will activate. Steno engines (and g Board Industries' custom steno inspired engine) solve this, however, they don't allow for comfortable typing in the traditional way. The steno chord activates only when all keys are lifted and makes it difficult to implement some advanced features. This engine treats each chord independently to allow for more comfortable typing experience.
TOC
Start here
This engine therefore uses python parser that translates a JSON definition of keyboard specific information and keymap definition and produces keymap.c
. Every function on this keymap is a chord (combo). The resulting keymap file is long and I do not encourage you to edit it. All you should have to edit is the JSON file. To produce the keymap file, run
./parser.py keymap_def.json keymap.c
To prepare the keymap JSON definition, you can use on of my keymaps as a starting point. I have on for butterstick and for georgi. There is also a JSON schema that has some examples and sane defaults. All details are explained in the next section. The parser tries to validate some of the things that the JSON schema can not. Finally there is a JSON in the tests folder that has at least one example of every feature.
Watch out, you can not name your JSON file keymap.json
if you place in the keymap folder. QMK creates keymap.json
as a part of compilation process and if you already have one, it gets confused.
Steps
When setting up a new keyboard, follow the steps:
- Make a new directory for your keymap as QMK's documentation describes.
- Write your JSON. Name it anything but
keymap.json
. - Depending on the keyboard / keymap, create
rules.mk
(follow QMK's documentation and note that if the keyboard'srules.mk
include custom source files, this is the place you can remove them). - Use my python parser to generate the
keymap.c
. Run it from the/users/dennytom/chording_engine
directory as it is using relative paths to some extra files. - Follow QMK's documentation to compile and flash your firmware.
Features
Chords
Once again, everything on this keymap is a chord. Even sending KC_Q
is done by pressing a single key chord. Chord gets activated after all it's keys get pressed. Only the longest chord gets activated. The order of the pressed keys does not matter, only the fact they have been pressed within the same time frame. An active chord gets deactivated if any of it's keys gets depressed. To activate the same single chord again, all it's keys have to be depressed and pressed again. With a few exceptions chords are independent of each other. No matter if some chords are currently active and some not, others can be activated or deactivated without affecting each other's state. If you press keys to belonging to multiple different, non-overlapping chords, all get activated in the order they are defined in the keymap.
Tap-Dance
To make it even stranger, all chords are technically tap-dance chords. They are relatively simple state machines that execute a specific function every time they change state. For simplicity and optimization purposes, there are a few prewritten functions that implement common features like "send a single key" or "lock". Any number of chords can be "in dance" at any given moment without affecting each other's state. Custom dances can be easily added. Check out the state_machine.png
to see all the states any chord can be in.
Pseudolayers
Only one QMK layer is used. Following the butterstick's default keymap's example, the chording engine is using pseudolayers. The main difference to QMK's layers is that only one pseudolayer can be active at each time (meaning you can not use KC_TRANS
, I actually don't know what will happen if you do). Chords can be activated only if they are on the currently active pseudolayer. Chords that are currently active do not get deactivated if the pseudolayer changes and will deactivate if any of their keys gets depressed even no matter the current pseudolayer. Locked chords (see below) and chords on the ALWAYS_ON
pseudolayer can be activated anytime.
Control chords
The engine implements a number of ways of changing how chords behave:
- Lock: Similarly to QMK's lock, the next chord activated after the Lock chord will not deactivate on release of any of its keys, it will deactivate when all its keys get pressed again. Any number of chords can be locked at the same time. To make sure a locked chord can be unlocked, it can activate no matter the current pseudolayer. A chord can be locked mid dance.
- One shots: Chords that send keycodes and chords that turn on pseudolayers can be one shots. If tapped, they will lock (stay active) until the next keycode gets sent, not necessarily when the next chord gets activated. If held, they will deactivate on release even if no keycode got sent.
- Tap-Hold: Also called key-layer dance and key-key dance. Either sends a defined keycode on tap and temporarily switches pseudolayer on hold or sends two different keycodes on tap and hold.
- Command mode: After getting activated for the first time, the keyboard switches to command mode. All keycodes that would get registered get buffered instead. After activating the Command mode chord for the second time, all buffered keycodes get released at the same time allowing for key combination that would be hard or impossible to press. The Command mode only affects keycodes. It is therefore possible to change pseudolayers or activate / deactivate other chords while in Command mode. While multiple Command mode chords can be defined, they would not be independent. The keyboard either is or is not in command mode and there is only one buffer.
- Leader key: Just like pure QMK's Leader key, this allows you to add functions that get executed if the Leader key and a specific sequence of keycodes gets registered in a predefined order in a short timeframe. For example
:wq
can sendCtrl+S
andCtrl+W
in a quick succession. While multiple Leader keys can be defined, they all would access the same list of sequences. - Dynamic macro: A sequence of keycodes can be recorded and stored in the RAM of the keyboard and replayed.
Settings up JSON definition
The JSON definition has 3 main sections. The elements keys
, parameters
and layers
teach the engine about the details of your keyboard and set its parameters. The elements pseudolayers
, leader_sequences
and chord_sets
define your keymap. Finally, the elements extra_code
and extra_dependencies
allow you to include more code to extend the capabilities of the engine.
Keyboard and engine parameters
I do not have experience with stenography, so the the steno keycodes are hard for me to remember. That is why the keymap is using new keycodes TOP1, TOP2, ... .
"keys": ["TOP1", "TOP2", "TOP3", ...]
You can name these however you like as long as they do not crash with QMK's keycodes.
The chording engine in it's current implementation can handle up to 64 keys. If you need to support more, contact me (email or u/DennyTom at Reddit).
All timings, maximum lengths for macros, command mode and leader function are defined in keyboard_parameters
field. Almost all should be pretty self-explanatory.
My keyboards are small, so I only use the engine, but you might want to use layers that combine chord-able keys and traditional QMK keys or layers with advanced keycodes, for example for stenography. The array layers
defines all the parser needs to know:
"layers": [
{
"type": "auto"
},
{
"type": "manual",
"keycodes": ["KC_1", "KC_2", "KC_3", "KC_4", "KC_5", "KC_6", "KC_7", "KC_8", "KC_9", "KC_0",
"KC_Q", "KC_W", "KC_E", "KC_R", "KC_T", "KC_Y", "KC_U", "KC_I", "KC_O", "KC_P"
]
},
{
"type": "manual",
"keycodes": ["KC_1", "KC_2", "KC_3", "KC_4", "KC_5", "KC_6", "KC_7", "KC_8", "KC_9", "KC_0",
"BOT1", "BOT2", "BOT3", "BOT4", "BOT5", "BOT6", "BOT7", "BOT8", "BOT9", "BOT0"]
}
]
This example defines 3 layers, one that is automatically populated with chording engine's internal keycodes, second that is populated with QMK's keycodes and third that uses both internal and QMK's keycodes. The layers do not have names, you have to access them with TO(1)
and TO(0)
.
Some keyboards mangle the order of keycodes when registering them in the layers. For that fill up the layout_function_name
with the name of function / macro. If your keyboard does not do it, leave that string empty.
Pseudolayers
Array pseudolayers
defines the keymap per pseudolayer. Each field has to contain the name for the layer and the list of chords.
"pseudolayers": [
{
"name": "QWERTY",
"chords": [
{
"type": "simple",
"keycode": "SPACE",
"chord": ["BOT1", "BOT0"]
},
{
"type": "visual",
"keycode": "CLEAR_KB",
"chord": [
"X", "", "", "", "", "", "", "", "", "X",
"X", "", "", "", "", "", "", "", "", "X",
]
},
{
"type": "visual_array",
"keys": ["TOP1", "TOP2", "TOP3"],
"dictionary": [
["X", "X", " ", "ESC"],
[" ", "X", "X", "TAB"],
["X", "X", "X", "ENTER"]
]
},
{
"type": "chord_set",
"set": "rows",
"keycodes": [
"Q", "W", "E", "R", "T", "Y", "U", "I", "O", "P",
"A", "S", "D", "F", "G", "H", "J", "K", "L", ";",
"Z", "X", "C", "V", "B", "N", "M", ",", ".", "/"
]
}
]
}
]
The array chord
defines chords. You can either use simple chord and list all the keys that have to pressed at the same time, or use the visual chord and place "X"
over keys that will be part of the chord. You can also use visual_array
to define a number of chords in a visual way on a subset of keys defined in the keys
array. Finally, you can use chord_set
to define a number of chords following a pattern that was set in the chord_sets
array in the root object like this:
"chord_sets": [
{
"name": "rows",
"chords": [
["TOP1"], ["TOP2"], ["TOP3"], ["TOP4"], ["TOP5"], ["TOP6"], ["TOP7"], ["TOP8"], ["TOP9"], ["TOP0"]
["TOP1", "BOT1"], ["TOP2", "BOT2"], ["TOP3", "BOT3"], ["TOP4", "BOT4"], ["TOP5", "BOT5"], ["TOP6", "BOT6"], ["TOP7", "BOT7"], ["TOP8", "BOT8"], ["TOP9", "BOT9"], ["TOP0", "BOT0"],
["BOT1"], ["BOT2"], ["BOT3"], ["BOT4"], ["BOT5"], ["BOT6"], ["BOT7"], ["BOT8"], ["BOT9"], ["BOT0"]
]
},
{
"name": "cols",
"chords": [
["TOP1", "TOP2"], ["TOP2", "TOP3"], ["TOP3", "TOP4"], ["TOP4", "TOP5"], ["TOP5", "TOP6"], ["TOP6", "TOP7"], ["TOP7", "TOP8"], ["TOP8", "TOP9"], ["TOP9", "TOP0"],
["TOP1", "TOP2", "BOT1", "BOT2"], ["TOP2", "TOP3", "BOT2", "BOT3"], ["TOP3", "TOP4", "BOT3", "BOT4"], ["TOP4", "TOP5", "BOT4", "BOT5"], ["TOP5", "TOP6", "BOT5", "BOT6"], ["TOP6", "TOP7", "BOT6", "BOT7"], ["TOP7", "TOP8", "BOT7", "BOT8"], ["TOP8", "TOP9", "BOT8", "BOT9"], ["TOP9", "TOP0", "BOT9", "BOT0"],
["BOT1", "BOT2"], ["BOT2", "BOT3"], ["BOT3", "BOT4"], ["BOT4", "BOT5"], ["BOT5", "BOT6"], ["BOT6", "BOT7"], ["BOT7", "BOT8"], ["BOT8", "BOT9"], ["BOT9", "BOT00"],
]
}
]
You might notice that the code tries to do a few clever things when parsing keycodes:
- If the keycode would be just a character basic keycode, it tries to allow the use of shortcuts.
Q
will get replaced withKC_Q
,,
becomesKC_COMMA
. This should work for all KC_ keycodes unless I missed some. MO()
andDF()
macros work the same way for pseudolayers as they would for layers in pure QMK.O()
is a shortcut forOSK()
orOSL()
.STR('...')
sends a string. Careful with quoting.- Special chords like Command mode have their own codes like
CMD
. - The empty strings get ignored.
Supported keycodes
-
X
orKC_X
: Send codeKC_X
just like a normal keyboard. -
STR("X")
: Send string "x" on each activation of the chord. Once again, watch out for quoting and escaping characters. If you want special characters (especially quotes) in your string, look up Python reference for string literals and experiment. Also, because of how the string gets parsed, it is not possible to use(
in the string. -
MO(X)
: Temporary switch to pseudolayerX
. Because only one pseudolayer can be active at any moment, this works by switching back to the pseudolayer the chord lives on on deactivation. If you chainMO()
s on multiple pseudolayers and deactivate them in a random order, you might end up stranded on a pseudolayer. I recommend addingCLEAR
somewhere onALWAYS_ON
pseudolayer just in case. -
MO(X,Y)
: Temporary switch to pseudolayerY
. Switches to pseudolayerX
on deactivation. Especially useful when you want to put theMO()
chord onALWAYS_ON
. -
DF(X)
: Permanent switch to pseudolayerX
. -
TO(X)
: Switches the QMK layer toX
. -
O(X)
: One-shot keyX
(ifX
starts with"KC_"
) or one-shot layerX
(otherwise) . Both have retro tapping enabled. -
Tap-holds
KK(X, Y)
: Pulses codeX
on tap and codeY
on hold.KL(X, Y)
: Pulses codeX
on tap and switches to pseudolayerY
on hold. If during the hold no key gets registered, the codeX
will get sent instead (similar to QMK's retro tapping).KM(X, Y)
: Same asKK()
but meant for modifiers on hold. Instead of a timer to figure out tap-hold, uses retro tapping like behavior just likeKL()
. This has issues with GUI and ALT as they often have a meaning.- The chording engine determines if you are holding a chord based on a global timer. If you start holding a tap-hold chord and very quickly start tapping other chords, the hold might not activate until a short moment after the last chord when the timer expires. If you are running into this, adjust timeouts or wait a brief moment after pressing the chord to make sure it switches into the hold state before pressing other chords.
-
Autoshift
AS(X)
: Pulses codeX
on tap and Pulses left shift +X
on hold.AT
: Toggles autoshift for all autoshift chords. If off, allAS
chords act likeKC
chords.
-
LOCK
: The lock key. Since tap-dances of chords are independent, it is possible to lock a chord anywhere in it's dance if you time it right!. If that happens, use theCLEAR
chord or restart your keeb. -
CMD
: The command mode. The number of keycodes that can be buffered is defined in incommand_max_length
. -
LEAD
: The leader key. The maximum length of the sequences needs to be defined inkeyboard_params
. You can useleader_sequences
array to add sequences:"leader_sequences": [ { "name": "fn_L1", "function": "void fn_L1(void) { SEND(KC_LCTL); SEND(KC_LALT); SEND(KC_DEL); }", "sequence": ["KC_Q", "KC_Z"] } ]
When the engine notices the sequence, it will call the function defined in the field
name
. You can either define it in thefunction
field, in the fieldextra_code
or in an external file that you then have to insert manually or using theextra_dependencies
array. The parser copy-pastes the contentsextra_code
of all files specified in theextra_dependencies
array in thekeymap.c
. -
M(X, VALUE1, VALUE2)
: A custom macro. Adds a chord that will use functionX
and withchord.value1 = VALUE1; chord.value2 = VALUE2;
. The functionX
can be arbitrary C function, go crazy. Just like with the leader sequences, you have to insert the code into the generatedkeymap.c
manually or throughextra_code
orextra_dependencies
. The following example defines a macro that acts exactly likeKC_MEH
(the chording engine should supportKC_MEH
, this is just an example):void fn_M1(const struct Chord* self) { switch (*self->state) { case ACTIVATED: key_in(KC_LCTL); key_in(KC_LSFT); key_in(KC_LALT); break; case DEACTIVATED: key_out(KC_LCTL); key_out(KC_LSFT); key_out(KC_LALT); break; case FINISHED: case FINISHED_FROM_ACTIVE: break; case RESTART: key_out(KC_LCTL); key_out(KC_LSFT); key_out(KC_LALT); break; default: break; } }
Since this feels like it would be the most common way to use this feature, I wrote a macro for this:
-
MK(X1, X2, ...)
: Acts likeKC()
except it registers / unregisters allX1
,X2
, ... codes at the same time. -
D(X1, X2, ...)
: A basic keycode dance. If tapped (or held), registersX1
. If tapped and then tapped again (or held), registersX2
, ... It cannot be combined with tap-hold, however holding will result in repeat. You can put in as many basic keycodes as you want, but the macro will break if you go beyond 256. It will try to expand shortened keycodes. Advanced keycodes are not supported. -
DM_RECORD
,DM_NEXT
,DM_END
,DM_PLAY
: Start recording a dynamic macro. Once you start recording, basic keycodes will get stored. When replaying the macro, all keys you press beforeDM_NEXT
orDM_END
will get pressed at the same time. For example the sequenceDM_RECORD
,KC_CTRL
,KC_A
,DM_NEXT
,KC_BSPC
,DM_END
will record a macro that when played will execute the sequence Ctrl+a, Backspace.dynamic_macro_max_length
defines the maximum length of the macro to be recorded. You can increase it for the price of RAM. The example above requires 4 units of length to be saved (Ctrl, A, next, Backspace). -
CLEAR_KB
: clears keyboard, sets all chords to the default state and switches the pseudolayer to the default one. Basically the emergency stop button. -
RESET
: Go to the DFU flashing mode.
Caveat of the current implementation is that the tap-hold, MK
and D
keycodes can not accept any of the keycodes that have some sort a function like dynamic macro specific chords, CLEAR_KB
, RESET
, LOCK
, AT
, ...
Leader Key
The sequences are not defined by the keys you press but by the keycodes that get intercepted. The length of the sequence must be equal or shorter than the maximum (defined in keyboard.inc
). Currently, the timeout for the leader sequence refreshes after each key pressed. If the sequence is not in the database, nothing will happen.
Extra code
Extra C code needed to define custom chords can be added by quoting in in the extra_code
element or by saving it in another header file and including it using the extra_dependencies
element:
{
"extra_code": "void double_dance(const struct Chord* self) { ... }\n",
"extra_dependencies": ["my_header.h"]
}
Further details
Implementation
The source files are split into several files. engine.part.1
, engine.part.2
and engine.part.3
contain C code that defines the Chord structure, implementations for all provided functions and the engine itself. parser.py
generates keyboard and keymap dependent code. The file chord.py
contains most of the logic required to properly translate chords from the JSON to the C code. I rarely write in python, if you have improvements, let me know, please.
Internal keycodes
When process_record_user()
gets one of the internal keycodes, it returns true
, completely bypassing keyboard's and QMK's process_record
functions. All other keycodes get passed down to QMK's standard processing.
Chords
Each chord is defined by a constant structure, a function and two non-constant int
variables keeping the track of the chord's state:
struct Chord {
uint32_t keycodes_hash;
uint8_t pseudolayer;
uint8_t* state;
uint8_t* counter;
uint16_t value1;
uint8_t value2;
void (*function) (const struct Chord*);
};
uint8_t state_0 = IDLE;
uint8_t counter_0 = 0;
void function_0(struct Chord* self) {
switch (*self->state) {
case ACTIVATED:
register_code(self->value1);
break;
case DEACTIVATED:
unregister_code(self->value1);
break;
case FINISHED:
case PRESS_FROM_ACTIVE:
break;
case RESTART:
unregister_code(self->value1);
break;
default:
break;
}
}
const struct Chord chord_0 PROGMEM = {H_TOP1, QWERTY, &state_0, &counter_0, KC_Q, 0, function_0};
All chords have to be added to list_of_chord
array that gets regularly scanned and processed. The function doesn't actually activate on all state changes, there are a few more like IDLE
(nothing is currently happening to the chord) or IN_ONE_SHOT
(the chord is one shot and is currently locked). Those are all necessary for internal use only. The ones you have to worry about are
ACTIVATED
: Analogous to a key being pressed (this includes repeated presses for tap-dance)DEACTIVATED
: Analogous to a key being depressed (also can be repeated)FINISHED
: Happens if the chord got deactivated and then the dance timer expired.PRESS_FROM_ACTIVE
: Happens if the chord was active when the dance timer expired. Meaning you at least once activated the chord and then kept holding it down. Useful to recognize taps and holds.FINISHED_FROM_ACTIVE
: Happens afterPRESS_FROM_HOLD
if the chord is still active when the dance timer expires for the second time. Can be combined with thecounter
to recognize even longer presses. Useful if you want to recognize long presses, for example for autoshift functionality. Inkeyboard.inc
you can setLONG_PRESS_MULTIPLIER
to set how many times does dance timer have to expire for the autoshift to trigger.RESTART
: The dance is done. Happens immediately afterFINISHED
or on chord deactivation fromFINISHED_FROM_ACTIVE
. Anything you have to do to get the chord intoIDLE
mode happens here.
The chords change states based on external and internal events. Anytime a chord's function is activated, it may change it's own state. Also, on certain events, the chording engine will trigger the functions of all chords in a specific state and if the chords' state hasn't changed it will then change it appropriately. The default behavior when a chord changes state is described by the following diagram:
The colors differentiate in which function the change happens, see
state_machine.dot
for a bit more detail. Black arrows happen in more than one function. Arrows without a label happen immediately.
You can see that the diagram is not exhaustive. For example nothing leads into IN_ONE_SHOT
. That is because the chord's function can change the chord's state. This is useful for some advanced chords that break the default behavir (one-shots) and for optimization (chords that just send KC_X
do not need to ever go into dance).
Caveats
Each chord stores as much as possible in PROGMEM
and unless it needs it, doesn't allocate counter
. However it still has to store it's state
and sometimes the counter
in RAM. If you keep adding more chords, at one point you will run out. If your firmware fits in the memory and your keyboard crashes, try optimizing your RAM usage.
Also, the code is not perfect. I keep testing it, but can not guarantee that it is stable. Some functions take (very short but still) time and if you happen to create keypress event when the keyboard can not see it, a chord can get stuck in a funny state. That is especially fun if the pseudolayer changes and you can not immediately press it again. Just restart the keyboard or push the key a few times.