Ubuntu Manpage: lircd-uinput - Forward lirc button presses as uinput events

NAME

       lircd-uinput - Forward lirc button presses as uinput events

SYNOPSIS

       lircd-uinput [options]... [lircd output socket]
       lircd-uinput [options]... [file]

DESCRIPTION

       lircd-uinput  reads  decoded button press events from a lircd(8) output socket and injects
       these as key events to the kernel uinput device.  The kernel makes these events  available
       to other applications on a /dev/input/event device, just as for regular input hardware.

       lircd-uinput is designed to run as a systemd service.

       The  lircd  output  socket  argument  is  an optional path to the lircd output socket.  It
       defaults to the output value in the [lircd]  section  of  the  lirc_options  config  file,
       falling back to /var/run/lirc/lircd.

       If a plain file is given instead of a socket it is supposed to contain button press events
       formatted as documented in lircd(8) .  lircd-uinput will in this case send  the  codes  in
       this file and exit.

       In order to work, release events must be sent to the uinput device.  See REPEAT HANDLING.

       lircd-uinput  can  only  handle  button  events  named using the official namespace i. e.,
       buttons known to the kernel. See NOTES.

       Unless the /dev/uinput default permissions are changed lirc-uinput needs to run  as  root.
       See NOTES.

       The  /dev/input/event  device  created  by  the kernel can be tricky to locate, and is not
       stable.  See NOTES.

OPTIONS

-u --uinput <device>
uinput kernel device, defaults to /dev/uinput.

-r --release-suffix <suffix>
lircd-uinput generates different events depending on if the button name ends with
the release-suffix or not. Defaults to _EVUP . See REPEAT HANDLING

-R --repeat <delay[,period] | ,period>
Set kernel autorepeat parameters of the created /dev/input/event device. delay is
the time before repeating a key event, period is the time between repeated key
events. Both values are in milliseconds, separated by a comma. Any value can be
omitted or set to 0 in which case the kernel/system defaults are used. See REPEAT
HANDLING.

-a --add-release-events
Generate synthetic release events. This option is mandatory unless lircd is using
the deprecated --release option. The timeout used can be modified using the
release-timeout key in the lircd-uinput section of the lirc_options.conf file.
Useless if used with a text file as input. . See REPEAT HANDLING

-d --disabled <disabled buttons file path>
The path of a file which contains name of buttons to be disabled, one per line. By
default, lircd-uinput sends all buttons found in input. See NOTES.

-O --options-file <path>
Options file holding default values. Defaults to /etc/lircd/lirc_options.conf

-L, --logfile <logfile path>
Select the log file, either the string 'syslog' indicating that syslog(1) should be
used or a log file path. The default is to use syslog.

-D, --loglevel [level]
Determine the amount of logging information. level can be a symbolic syslog level:
'error','warning, 'info', 'notice' or ´debug'. lircd-uinput also defines three
additional levels 'trace', 'trace1' and 'trace2' which gives even more messages
('trace2' bringing the most). However, in the log these messages are marked as
'debug'.

-h --help
Display usage summary.

-v --version
Display version info.

REPEAT HANDLING

After receiving a keypress event the kernel will start emitting repeat events to
applications until lircd-uinput emits a corresponding release event. The release events
could be created by lircd(8) using the deprecated --release option. Such events typically
has an _EVUP suffix appended to the original keypress event.

The preferred way is that lircd-uinput creates release events using the --add-release-
events option. Combining both of these options might give unexpected results.

Note that the linux kernel uses the suffix _UP (which was used py lircd prior to 0.10.0)
for other purposes since 4.7.

In any case, the repeat events generated by the kernel can be tweaked using the --repeat
option. This can set the time between the keypress event and the first repeat event and
the time between each repeat event. The --repeat option should only be used if no other
program or udev rule is automatically setting up key repeat parameters. By design the
repeat parameters can't be set in an atomic way during input device registration so this
option is prone to race conditions.

Note that the lircd-uinput repeat-event handling differs from lircd(8) which implements
(emulates) hardware autorepeat in the events sent to uinput (event.value == 2). lircd-
uinput only sends keypress and release events, trusting the kernel autorepeat support.

NOTES

By default, the dev/uinput device is not writable for regular users. Thus lircd-uinput
needs to run as root unless these permissions are changed.

One way to achieve this is an udev rule. The lirc distribution contains an example rule
which makes the lircd-uinput device writable for users in the group lirc. Another way is
to use lircd-setup(8) to change the permissions. As distributed, the lirc_options.conf
file contains an commented example using setfacl(1) .

lircd-uinput can only forward lircd button events with names from the legal namespace
defined by the kernel. A complete list of possible button names is available in
/usr/include/linux/input-event-codes.h and also using irrecord -l . Other button names
are silently dropped.

The event keycode depends on the name that was given a button in the lircd config file
e.g., if the button is named KEY_1 the keycode 1 will be generated.

The kernel makes the events generated by lircd-uinput available on a /dev/input device
like /dev/input/event12. This device name is not stable and typically varies after a
reboot. The lirc distribution contains a udev rule which if installed creates a device
link named /dev/lircd-uinput which always can be used.

lircd-uinput is designed to replace the currently deprecated --uinput option to lircd(8).
However, lircd-uinput forwards all events unless blocked by the --disabled option. On the
other hand, lircd --uinput does not forward all events - the heuristics used has been
changed over versions.

BUGS

       Since the device name is fixed, only one instance of lircd-uinput can run on a system.