Link

What is a Chord? What is a Combo?

There is a fundamental difference between the two! A Combo is a native QMK feature and only applies to multi-key sequences and SEND_STRING(). However it can’t handle layering, processing strokes in chords and many other things required on smaller or heavily chorded keyboards! The Chording engine is the solution to this, but only has limited interoperability with QMK.

If you are only using Combos for augmenting a keymap, don’t use the chording engine, use the Combos!

Function Docs

If you have not read the Combo Docs, give those a quick browse. The format used for these chords is similar. Back? Awesome.

There are four functions that you can call in a dictionary, they are

PRES(chord, keyOut) : Send a single QMK keycode
KEYS(chord, id, keys) : Send a sequence of keypresses
SUBS(chord, id, string) : Send Strings and sequences
SPEC(chord, func, arg) : Trigger Special functionality/QMK Interop

And you can use these to make any chorded dictionary!

Usage:

example.def (excerpts from en-keymap.def)

PRES(GA,                                  KC_P)                        // Send P
KEYS(GA|GO,        cmb_9df323cdb026f7ce,  {KC_LSFT, KC_9, COMBO_END})  // Send (
SUBS(GR|GI|GO|GP,  str_E21E9A5405E9A529,  "pool ")                     // "pool "
SPEC(GA|GT|GN|GP,  SPEC_STICKY,           NUM)                         // Activate StickyBit for NUM

Notes:

– Only QMK Basic Keycodes can be sent using this engine. For shifted stuff you must use KEYS()! – ID can be set to whatever, however it must be unique. If it’s not the compiler will yell at you – For KEYS the brackets must be included, or the compiler will yell at you.

SPEC()

There’s a few special things that can be done through this code that changes how the engine operates. Heres a table of the currently implemented stuff

KeyCodeArgFunction
SPEC_STICKYChordThis set’s/removes the specified bits from stickybits
SPEC_REPEATnoneToggle the repeat mode until toggled off
SPEC_CLICKKeycodeSend the specified mousekey to the mouse subsytem. Requires mousekeys
SPEC_SWITCHQMK LayerTurn on the given layer. The user is left to change back to the chorded layer

Chords

A chord is just a bitmask made by or’ing together keys. These keys are defined in your ENGINE_CONFIG
section. When the listed keys are pressed the action is run. The engine will match the longest chord possible!

The default engine mappings are below, if you’re doing a custom engine yours will be different. If you’re doing this on a normalish keyboard, just make a layout with the following keycode (using the function keys for your thumb keys!

QMK KeycodeChord Equivelent
KC_QGQ
KC_WGW
KC_EGE
KC_RGR
KC_TGT
KC_YGY
KC_UGU
KC_IGI
KC_OGO
KC_PGP
KC_AGA
KC_SGS
KC_DGD
KC_FGF
KC_GGG
KC_HGH
KC_JGJ
KC_KGK
KC_LGL
KC_SCLNGCL
KC_ZGZ
KC_XGX
KC_CGC
KC_VGV
KC_BGB
KC_NGN
KC_MGM
KC_COMMGLT
KC_DOTGGT
KC_SLSHGQU
KC_F1GL1
KC_F2GL2
KC_F3GL3
KC_F4GR3
KC_F5GR2
KC_F6GR1

Clear as mud? Good! Go take a look at some of the dictionaries, they’ll make more sense now :)

Custom Engines Managing Dicts