# triggerhappy

The machine's hotkeys (novox/hq ADR 0212). triggerhappy is the daemon that sees the keys the window
manager never does, such as a laptop's vendor keys. This module holds `node-hotkeys` and owns the
daemon's configuration and service. The keys themselves belong to the modules they are for.

## What it owns

| | |
|---|---|
| `/etc/triggerhappy/triggers.d/mesh.conf` | every module's trigger lines, placed with `${contribution:node-hotkeys:trigger}` in module order, each module's under a `# <module>` line |
| `triggerhappy.service.d/mesh.conf` | the daemon reads only the mesh's file, and runs every trigger as the operator's account (`--user`), after opening the devices as root |
| `triggerhappy.service` | running and enabled; restarted when either file changes |

## How a module adds a key

A module declares a `contributions` entry with `seat` `node-hotkeys`, `kind` `trigger`, and as
`content` one or more trigger lines in triggerhappy's own grammar: the key, its state (`1` pressed,
`2` held, `0` released), and the command. The command runs as the operator's account. It needs no
`su` and should name the contributing module's own scripts. The contribution depends on this seat
(ADR 0210), so a module with keys is refused on a machine without a hotkey holder.

To find a key's name, press it while `triggerhappy_dump` listens.

## Tools

| tool | |
|---|---|
| `triggerhappy_keys` | every trigger in force: key, state, command, file and contributing module; warns about a key bound twice |
| `triggerhappy_devices` | the input devices, by name and event handler |
| `triggerhappy_dump` | listen for a few seconds and say which keys arrived (needs `sudo -n`) |
| `triggerhappy_check` | running, as the account, only the mesh's file, no duplicates |

## Installed as found

triggerhappy is not in the distribution's repositories, so the host cannot install it, and the module
declares no package. It depends on the machine having it: the service resource refuses loudly, by
name, on a machine without it. How software from the user repository reaches the mesh, as a pinned
archive (ADR 0205) or through a repository the mesh serves, is research 027's first question.

## Migration

On the laptop, the model's module wrote `asus-g14.conf` and its own drop-in. Both move here: the
model's module now contributes its keys. When it is pushed, the host gives back the original
`asus-g14.conf` it kept, which still calls the predecessor's `as-user` scripts. Delete that file
afterwards. The daemon reads only `mesh.conf` from then on, so the file would not fire, but
`triggerhappy_check` flags any file besides the mesh's.