keyd(1) # NAME *keyd* - A key remapping daemon. # SYNOPSIS *keyd* [options] # OPTIONS *-m, --monitor* Start keyd in monitor mode. Useful for discovering keycodes and device ids. *-e, --expression [...]* Modify bindings of the currently active keyboard. See _Expressions_ for details. *-l, --list-keys* List valid key names. *-v, --version* Print the current version and exit. *-h, --help* Print help and exit. # DESCRIPTION keyd is a system wide key remapping daemon which supports features like layering, oneshot modifiers, and macros. In its most basic form it can be used to define a custom key layout that persists across display server boundaries (e.g wayland/X/tty). The program runs in the foreground, printing diagnostic information to the standard output streams, and is intended to be run as a single instance managed by the init system. *NOTE:* Because keyd modifies your primary input device, it is possible to render your machine unusable with a bad config file. If you find yourself in this situation the panic sequence *++* will force keyd to terminate. # CONFIGURATION Configuration files are stored in _/etc/keyd/_ and are loaded upon initialization. Changes to these files can be realized by restarting the daemon, which is usually accomplished using your service manager. E.G sudo systemctl restart keyd A valid config file has the extension _.conf_ and *must* begin with an _[ids]_ section that has one of the following forms: ``` [ids] : : ... ``` or ``` [ids] * -: -: ... ``` The first form specifies a list of ids to be explicitly matched, while the second matches any id which has not been explicitly excluded. For example: ``` [ids] * -0123:4567 ``` Will match all devices which *do not*(2) have the id _0123:4567_, while: ``` [ids] 0123:4567 ``` will exclusively match any devices which do. Each subsequent section of the file corresponds to a _layer_ (with the exception of _[global]_ (see _GLOBALS_). Note: All keyboards defined within a given config file will share the same state. This is useful for linking separate input devices together (e.g foot pedals). Note 2: The wildcard will only match devices which keyd identifies as keyboards. keyd is also capable of *managing mice* (e.g to facilitate clearing of oneshot modifiers on click), but their ids must be explicitly listed. ## Layers A layer is a collection of _bindings_, each of which specifies the behaviour of a particular key. Multiple layers may be active at any given time, forming a stack of occluding keymaps consulted in activation order. The default layer is called _main_ and is where common bindings should be defined. For example, the following config snippet defines a layer called _nav_ and creates a toggle for it in the _main_ layer: ``` [main] capslock = layer(nav) [nav] h = left k = up j = down l = right ``` When capslock is held, the _nav_ layer occludes the _main_ layer causing _hjkl_ to function as the corresponding arrow keys. Unlike most other remapping tools, keyd provides first class support for modifiers. A layer name may optionally end with a ':' followed by a set of modifiers to emulate in the absence of an explicit mapping. These layers play nicely with other modifiers and preserve existing stacking semantics. For example: ``` [main] capslock = layer(capslock) [capslock:C] j = down ``` will cause _capslock_ to behave as _control_, except in the case of _control+j_, which will emit _down_. This makes it trivial to define custom modifiers which don't interfere with one another. Formally, each layer heading has the following form: ``` "[" [:] "]" ``` Where __ has the form: _[-]..._ and each modifier is one of: *C* - Control++ *M* - Meta/Super++ *A* - Alt++ *S* - Shift++ *G* - AltGr Finally, each layer heading is followed by a set of bindings which take the form: = || for a description of and see _ACTIONS_ and _MACROS_. By default, each key is bound to itself within the main layer. The exception to this are the modifier keys, which are instead bound to eponymously named layers with the corresponding modifiers. For example, _meta_ is acutally bound to _layer(meta)_, where _meta_ is internally defined as _meta:M_. A consequence of this is that overriding modifier keys is a simple matter of adding the desired bindings to appropriate pre-defined layer. Thus ``` [ids] * [control] j = down ``` is a completely valid config, which does what the benighted user might expect. Internally, the full config actually looks something like this: ``` [ids] * [main] leftcontrol = layer(control) rightcontrol = layer(control) [control:C] j = down ``` ## Composite Layers A special kind of layer called a *composite layer* can be defined by creating a layer with a name consisting of existing layers delimited by _+_. The resultant layer will be activated and given precedence when all of its constituents are activated. Composite layers always inherit the modifiers of their constituent layers and cannot be explicitly assigned. E.G ``` [main] capslock = layer(capslock) [capslock:C] [capslock+shift] h = left ``` Will cause the sequence _control+shift+h_ to produce _left_, while preserving the expected functionality of _capslock_ and _shift_ in isolation. *Note:* composite layers *must* always be defined _after_ the layers of which they are comprised. That is: ``` [layer1] [layer2] [layer1+layer2] ``` and not ``` [layer1+layer2] [layer1] [layer2] ``` ## Unicode Support If keyd encounters a valid UTF8 sequence as a right hand value, it will try and translate that sequence into a macro which emits a keyd-specific XKB sequence. In order for this to work, the sequences defined in the compose file shipped with keyd (_/usr/share/keyd/keyd.compose_) must be accessible. This can be achieved globally by copying the file to the appropriate location in _/usr/share/X11/locale_, or on a per-user basis by symlinking it to ~/.XCompose. E.G ln -s /usr/share/keyd/keyd.compose ~/.XCompose *Note:* You may have to restart your applications for this to take effect. ## File Inclusion Config files may include other files located within the config directory using the _include_ keyword. A line of the form *include * may appear at any point after the [ids] section. The resultant config will behave as though the contents of the included file appear in place of the include statement. Making strategic use of these statements makes it possible to share common functionality between configs. E.G ``` /etc/keyd/default.conf: [ids] * include common # Appends bindings to the main layer # defined in /etc/keyd/common (order matters) [main] include layouts/dvorak f11 = toggle(colemak) [colemak] include layouts/colemak capslock = backspace /etc/keyd/common: [main] rightmeta = layer(nav) [nav] h = left j = down k = up l = right /etc/keyd/layouts/dvorak: a = a s = o ... ``` Limitations: - All include statements should appear after the [ids] section in the including file. - Included files should not contain an ids section. - Included files should not include other files (inclusion is non-recursive). - Included files should not end in .conf. For convenience, keyd ships with a number of common letter layouts in /etc/keyd/layouts. Before including these, it is instructive to inspect them. Non-english layouts include a dedicated shift layer (making order of inclusion important) and *require the use of keyd's compose definitions* (see *Unicode Support*) # GLOBALS A special section called _[global]_ may be defined in the file and can contain any of the following options: *macro_timeout:* The time (in milliseconds) separating the initial execution of a macro sequence and the first repetition. (default: 600) *macro_repeat_timeout:* The time separating successive executions of a macro. (default: 50) *layer_indicator:* If set, this will turn the capslock light on whenever a layer with a non-empty modifier set is active. (default: 0) *Note:* Unicode characters and key sequences are treated as macros, and are consequently affected by the corresponding timeout options. # MACROS Various keyd actions accept macro expressions. A valid macro expression has one of the following forms: . macro() . [[-...]- Where __ has the form _ [...]_ and each token is one of: - a valid key code. - a type 2. macro. - a contiguous group of characters, each of which is a valid key code. - a group of key codes delimited by + to be depressed as a unit. - a timeout of the form _