triggerhappy global hotkey daemon

thd [--help] [--user name] [--listevents] [--dump] [--socket socket] [--triggers config] [--daemon] [--pidfile file] [--uinput device][--ignore event] [--deviceglob pattern] [devices...]

Hotkey daemon operates on a system wide scale, watchiing configured input devices for key, switch or button events and can launch arbitrary commands. In contrast to hotkey services provided by desktop environments, Triggerhappy is especially suited to hardware related switches like volume or wifi control. Works independently from a specific user being logged in and is also suitable for embedded systems that do not a graphical user interface.

--listevents displays a list of known event names.
--triggers conf Read trigger definitions from conf, a file or directory.
If a directory is specified, all its files matching the pattern *.conf are loaded.
--dump /dev/input/event* Dump events to STDOUT. Can be used to create a skeleton trigger configuration.
--socket file Open a unix domain socket at file; to send commands to the running daemon (by using the program th-cmd), 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.


Configuring event handlers

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

The event names can be identified by operating the desired key or switch while running the daemon with the --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. Include the full path

The fields are separated by whitespace while anything following a # is ignored.


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


triggerhappy commander

th-cmd--socket socket [--passfd] [--tag foo]
[--clear|--enable|--disable|--mode mode|--quit|--udev|--add devices …|--remove devices …]

Issues commands to a running triggerhappy daemon. It utilizes an unix domain socket bound by the daemon.

--socket socket socket opened by the running daemon .
--add devices … Instruct the running daemon to open the input devices
--remove devices … Remove devices from the running daemon.
--clear Remove all devices
--udev Deduce operation and device name from udev environment (for use in udev rules).
--disable Disable the execution of triggers.
--enable Re-enable the execution of triggers.
--mode newmode Change the mode of the triggerhappy daemon to newmode. If newmode is not specified, the daemon switches to default mode.
--passfd Instead of instructing the daemon to open the device, open the device and pass the file descriptor to the daemon. This allows the adding of new devices to a daemon having dropped its privileges, must have access to the device .
--grab Grab the device; the daemon will get exclusive access to the device, other applications will not receive the events emitted by it.
--tag foo Label the added device with the tag foo; used to limit the scope of event handlers to a subset of input devices.

see WAS used by raspberry's raspi=config
 log_daemon_msg "Checking if shift key is held down"
    if [ -x /usr/sbin/thd ] && timeout 1 thd --dump /dev/input/event* | grep -q "LEFTSHIFT\|RIGHTSHIFT"; then
      printf " Yes. Not enabling ondemand scaling governor"
      log_end_msg 0