Provided by: triggerhappy_0.3.4-2_amd64 
NAME
thd -- triggerhappy global hotkey daemon
SYNOPSIS
thd [--help] [--user name] [--listevents] [--dump] [--socket socket] [--triggers config]
[--daemon] [--pidfile file] [--uinput device][--ignore event] [devices...]
DESCRIPTION
Triggerhappy is a hotkey daemon that operates on a system wide scale. It watches all
configured input devices for key, switch or button events and can launch arbitrary
commands specified by the administrator. In contrast to hotkey services provided by
desktop environments, Triggerhappy is especially suited to hardware related switches like
volume or wifi control; it works independently from a specific user being logged in and is
also suitable for embedded systems that do not a graphical user interface.
OPTIONS
--help
Shows usage instructions
--listevents
Prints a list of all known event names.
--triggers conf
Read trigger definitions from conf, which can either be a file or a directory. If a
directory is specified, all its files matching the pattern *.conf are loaded.
--dump
Dump all recognized events to STDOUT. This can also be utilized to create a skeleton
trigger configuration by redirecting the printed configuration lines to a
configuration file, adding the desired command and activating the generated line by
removing the comment mark "#" at its beginning:
thd --dump /dev/input/event* | grep ^# > /etc/triggerhappy/triggers.d/skeleton.conf
--socket file
Open a unix domain socket at file; this socket can be used to send commands to the
running daemon (by using the program th-cmd), e.g. for adding or removing devices.
--daemon
Run as a background daemon and detach from the terminal.
--pidfile file
Write PID to file.
--uinput device
Open uinput file (probably /dev/input/uinput) to generate synthetic events.
--ignore eventname
Ignore key and switch event labeled eventname. This can be used to suppress the FN key
on some notebooks which only generates events sometimes and might screw up key
combinations.
--user name
Change to user id name after opening files. This usually prevents thd from opening
additional input devices, unless they are opened by the th-cmd program and their file
descriptor are passed to the daemon.
Additional command line arguments are considered filenames of input devices.
CONFIGURATION
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.
EXAMPLE
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".
AUTHOR
Stefan Tomanek <stefan.tomanek+th@wertarbyte.de>