NAME

       thd -- triggerhappy global hotkey daemon

SYNOPSIS

       thd [--help] [--user name] [--listevents] [--dump] [--socket socket] [--triggers config] [--daemon]
       [--pidfile file] [--uinput device][--ignore event] [--deviceglob pattern] [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.

       --normalize
           Normalize REL and ABS events. If this option is enabled, the values of axis movement events are
           mapped to the three values -1, 0 and 1, depending on the sign of the value reported by the kernel.

       --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.

       --deviceglob pattern
           Open device files matching the glob pattern.

       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>