Actions and Keycodes

Keycodes

RPK supports most of the keycodes for the USB HID classes of keyboard, consumer control, system control, and mouse. The symbolic names of these keycodes vary and RPK supports some common aliases. To get a list of all the keycode names run the following command:

rpk-config list-keycodes

Try adding --help for extra features available for listing the codes.

Other pseudo keycodes are used to change the state of the keyboard.

These special keycodes are:

1. mouseaccel<n> where <n> is 1, 2, or 3. mouseaccel1 will change the mouse movement and scroll accelerations characteristics from the default mouseaccel2 as will mouseaccel3 usually 1 will be slower and 3 will be faster than the default.
2. stop_active will release any held keys and clear the modifier layers.
3. clear_layers will deactivate all layers expect the base layout.
4. clear_all will stop all actions/macros, clear all layers, restore the base layout to main, and release all keys.
5. reset_keyboard will restart the keyboard firmware as i f it had just been powered on.
6. reset_to_usb_boot will restart the keyboard in mass storage mode, if supported, which will allow a new firmware binary to be installed.

Actions

Actions allow for keyboard specific functions to be invoked that take one or more arguments.

layer(<layer>)

Activate the given layer for the duration of the key press.

oneshot(<layer>)

When tapped activate the layer for the next key press only.

setlayout(<layout>)

Replace the base layout.

toggle(<layer>)

Turn on a layer if inactive; otherwise turn off the layer.

delay(<milliseconds>)

Wait the given milliseconds before reporting the next keycode to the host computer.

dualaction(<hold-action>, <tap-action>[, <timeout1>[, <timeout2>]])

Run the <hold-acton> when held, execute the <tap-action> on tap. <timeout1> and <timeout2> override global.dual_action_timeout and global.dual_action_timeout2 respectively. A key is considered held if <timeout1> expired before no more than two other key events happen; or <timeout2> expires before more than two key events happen. <timeout2> starts running after two other key events are detected.

overload(<layer>, <action>[, <timeout1>[, <timeout2>]])

Overload is an alias for dualaction(layer(<layer>), <action>[, <timeout1>[, <timeout2>]]).

tapdance(<hold-acton>, <tap-action>[,<hold-acton>, <tap-action>]...)

Like dualaction¹ but optionally do other actions when tapped repeatedly faster than tapdance_tap_timeout. If another key is pressed or released then that will also trigger the action after the counted taps. So hold will do the first hold-action, tap will do the first tap-action, tap, hold will do the second hold-action, tap tap will do the second tap-action and so on.

Note: tapdance is not allowed within any macros.

tapdancet(<tap-timeout>, <hold-acton>, <tap-action>[,<hold-acton>, <tap-action>]...)

Like tapdance but use <tap-timeout> instead of global tapdance_tap_timeout.

Macros

Macro expressions are user defined actions that run a sequence of other actions/keycodes. The following forms are all valid macro expressions:

1. macro(<expr>)
2. hold(<expr>)
3. release(<expr>)
4. <modifier-list>-<keycode> (modifier-macro)
5. <unicode-char>
6. unicode(<hex-digits>)

<expr> has the form <token1> <token2>... where each token is one of:

• A valid keycode or action.
• A modifier-macro.
• A contiguous list of unicode characters.

macro() taps out the expression, hold() activates the keycodes on a key press and release() deactivates the keycodes on key release. macro(hold(<expr1>) release(<expr2>)) is a special form that will activate <expr1> on key press and deactivate <expr2> on key release.

<unicode-char> is a unicode character not in the basic keycode range; it is converted to unicode(<hex-digits>) which will invoke the global.unicode_prefix action, type out the hex-digits, and finally invoke the global.unicode_suffix action.

<modifier-list>-<keycode> is a list of modifier codes separated by a dash - followed by any valid keycode.

The following are all valid macro expressions:

• C-d
• hold(C-a)
• A-S-backspace
• macro(He llo space delay(500) 🌏)

Splitting into smaller tokens serves as an escaping mechainism: macro(space) inserts a space, macro(sp ace) writes “space”.

Modifier macros

Modifier macros report the given modifiers before reporting the keycode; for example S-1 produces a bang !. The modifiers are reported only when necessary. This makes them useful for keeping layer modifiers in place when defining keys on that layer.

Example

[nav:C]

j = left
u = C-left

Here when the nav layer is active holding j will result in reporting release leftcontrol followed by hold left to the host whereas holding u will result in just a hold left being reported.

1. tapdance is less nuanced than dual_action; it doesn’t interact as skillfully with other keys; any other key press immediately resolves the tap dance at whatever place it is at. ↩