5.0 KiB
% WARP(1) % Raheman Vaiya
OVERVIEW
A system-wide key remapping daemon.
USAGE
keyd [-m] [-l]
ARGS
-m: Run in monitor mode. (ensure keyd is not running to see untranslated events).
-l: List all valid key names.
-d: Fork and run in the background.
OVERVIEW
keyd is intended to be run as system wide daemon managed by systemd. The default behaviour is to run the forground and print to stderr but it can also be run as a standalone daemon if -d is supplied, in which case log output will be stored in /var/log/keyd.log.
CONFIGURATION
All configuration files are stored in /etc/keyd. The name of each file should correspond to the device name to which it is to be applied followed by .cfg (e.g "/etc/keyd/Magic Keyboard.cfg"). Configuration files are loaded upon initialization and can be reified by reloading keyd (e.g sudo systemctl restart keyd).
The monitor flag (-m) can be used to obtain device and key names like so:
# sudo systemctl stop keyd
# sudo keyd -m
Magic Keyboard: capslock down
Magic Keyboard: capslock up
If no configuration file exists for a given keyboard 'default.cfg' is used as a fallback (if present).
Each line in a configuration file consists of a mapping of the following form:
<key> = <action>|<keyseq>
or else represents the beginning of a new layer. E.G:
[<layer name>]
Where <keyseq> has the form: [<modifier1>-[<modifier2>-]]<key>
and each modifier is one of:
\ C - Control
\ M - Meta/Super
\ A - Alt
\ S - Shift
\ I - AltGr (ISO_Level3_Shift)
In addition to simple key mappings keyd can remap keys to actions which can conditionally send keystrokes or transform the state of the keymap.
It is, for instance, possible to map a key to escape when tapped and control when held by assigning it to mods_on_hold(C, esc). A complete list of available actions can be found in ACTIONS.
LAYERS
Each configuration file consists of one or more layers. Each layer is a keymap unto itself and can be activated by a key mapped to the appropriate action (see ACTIONS).
The default layer is called 'default' and is used for mappings which are not explicitly assigned to a layer.
For example the following configuration creates a new layer called 'symbols' which is activated by the capslock key on the default layer.
capslock = layer(symbols)
[symbols]
f = S-grave
d = slash
Pressing capslock+f thus produces a tilde.
A layer may optionally have a parent from which mappings are drawn for keys
which are not explicitly mapped. By default layers do not have a parent, that
is, unmapped keys will have no effect. A parent is specified by appending
:<parent layer> to the layer name. This is particularly useful for custom
letter layouts like dvorak which remap a subset of keys but otherwise leave the
default mappings in tact.
ACTIONS
oneshot(mods): If tapped activate a modifier sequence for the next keypress, otherwise act as a normal modifier key when held.
mods_on_hold(mods, keyseq): Activates the given set of modifiers whilst held and emits keysequence when tapped.
layer_on_hold(layer, keyseq): Activates the given layer whilst held and emits keysequence when tapped.
layer_toggle(layer): Permanently activate a layer when tapped. Note: You will need to explicitly map a toggle in the destination layer if you wish to return.
layer(layer): Activate the given layer while the key is held down.
oneshot_layer(layer): If tapped activate a layer for the duration of the next keypress, otherwise act as a normal layer key when held.
Legend:
<mods>= A set of modifiers of the form:<mod1>[-<mod2>...](e.g C-M = control + meta).<keyseq>= A key sequence consisting of zero or more control characters and a key (e.g C-a = control+a).<layer>= The name of a layer.
Examples
Example 1
# Maps capslock to control when held and escape when tapped.
capslock = mods_on_hold(C, esc)
# Makes the shift key sticky for one keystroke.
leftshift = oneshot(S)
rightshift = oneshot(S)
Example 2
# Maps escape to the escape layer when held and the escape key when pressed
esc = layer_on_hold(escape_layer, esc)
[escape_layer]
1 = layer_toggle(dvorak)
2 = layer_toggle(default)
# Creates a dvorak layer which inherits from the default layer. Without
# explicitly inheriting from another layer unmapped keys would be ignored.
[dvorak:default]
q = apostrophe
w = comma
e = dot
r = p
t = y
y = f
u = g
i = c
o = r
p = l
a = a
s = o
d = e
f = u
g = i
h = d
j = h
k = t
l = n
semicolon = s
z = semicolon
x = q
c = j
v = k
b = x
n = b
m = m
comma = w
dot = v
slash = z
NOTES
- Because of the way keyd works it is possible to render your machine unusable with a bad config file. This can usually be resolved by plugging in a different keyboard, however if default.cfg has been misconfigured you will have to find an alternate way to kill the daemon (e.g SSH).
AUTHOR
- Written by Raheman Vaiya (2017-).
BUGS
Please file any bugs or feature requests at the following url: