Configuring event handlers¶

The hotkey bindings used by Triggerhappy are set in the configuration file specified by --triggers. Each line consists of three segments: The symbolic name of the key or event name to react on, the value carried by the expected event, and of course the command to be launched.

The event names can be identified by operating the desired key or switch while running the triggerhappy daemon with the option --dump.

Key events carry the value 1 for a key being pressed and transmit the payload 0 when it is released; holding the key down constantly yields events with a value of 2.

The command can include any number of arguments. Please include the full path to avoid trouble through different $PATH settings for the daemon and your interactive session.

The three fields are separated by an arbitrary number of whitespaces, while anything behind a # character is ignored and considered a comment.

Starting the daemon¶

thd --dump /dev/input/event*

Dump all events processable by thd to the console; this is useful to find out the correct event name for a specific key.

thd --triggers /etc/triggerhappy/triggers.d/ /dev/input/event*

Read from all currently connected input devices and process events according to the files in /etc/triggerhappy/triggers.d/.

thd --triggers /etc/triggerhappy/triggers.conf --socket /var/run/thd.socket

Do not open any input devices yet, but bind the socket /var/run/thd.socket for th-cmd to connect to.

Configuration files¶

Any number of event handlers can be placed in the configuration file:

    # /etc/triggerhappy/triggers.d/suspend.conf
    #
    # Suspend the system
    KEY_SLEEP                   1       /usr/sbin/hibernate-ram
    KEY_SLEEP+KEY_LEFTSHIFT     1       /usr/sbin/hibernate-disk
    # /etc/triggerhappy/triggers.d/audio.conf
    # Change mixer volume when pressing the appropriate keys (or holding them)
    KEY_VOLUMEUP    1      /usr/bin/amixer set Master 5%+
    KEY_VOLUMEUP    2      /usr/bin/amixer set Master 5%+
    KEY_VOLUMEDOWN  1      /usr/bin/amixer set Master 5%-
    KEY_VOLUMEDOWN  2      /usr/bin/amixer set Master 5%-

In more complex situations, triggerhappy can provide multiple modes that map a single event to different keys; triggers are bound to a specific mode by appending its name to the event name:

    KEY_KPPLUS@media    1       /usr/bin/mpc next
    KEY_KPMINUS@media   1       /usr/bin/mpc prev

These two lines will only cause mpc to be called if the triggerhappy daemon is in "media" mode. Changing the mode can be achieved by placing a special trigger inside the configuration:

    KEY_F12@            1       @media
    KEY_F12@media       1       @

These two lines make the F12 key toggle between the (nameless) default mode and the newly defined media mode.

Triggers with "@" appended are only executed if the specified mode is active; all other triggers are enabled in every mode.

When launched with the option --uinput, triggerhappy can be used to generate synthetic events. A virtual input device is created which emits specified key presses once a special trigger is reached:

    KEY_KPASTERISK      1       <KEY_VOLUMEDOWN

By prepending a keycode with the special character '<', other applications will receive a press and release of the corresponding key. This is especially useful to remap or mirror events generated by devices exclusively serviced by the triggerhappy daemon.

It is possible to create handlers that only react to specific devices: to achieve such behaviour, add the input device using th-cmd and supply it with a tag; this tag can then be used to limit the scope of a trigger to this device:

    <remote>KEY_ENTER   1       /usr/bin/mpc stop

Defining the hotkey in this way will only trigger the handler if the event is received from a device tagged "remote".