lircd(8)
NAME
lircd - Decode infrared signals and provide them on a socket.
SYNOPSIS
lircd [options] [config file]
DESCRIPTION
The main task of lircd is to decode the infrared signals and provide an uniform interface for client applications. Clients can connect to lircd through a Unix domain socket, by default /var/run/lirc/lircd. Using this socket they will get the infrared codes received by lircd and they can send commands to lircd.
ARGUMENTS
config file
The configuration file, by default /etc/lirc/lircd.conf. A relative
path is interpreted from /etc/lirc. The default configuration file
includes all files in /etc/lircd.conf.d.
Each remote which should be decoded by lircd usually requires that
a specific file is used e. g., by copying it to
/etc/lirc/lirc.conf.d/. The format is described in lircd.conf(5).
Configuration files could be found using irdb-get(1) or lirc-
setup(1). It's also possible to generate a config file using
irrecord(1)
OPTIONS
Common options:
-d, --device <device>
Select the character device which lircd should read from. The
default is currently /dev/lirc0 on most systems.
When using the devinput driver, you can use name=STRING or
phys=STRING to select the device; lircd will look in /dev/input to
find a device with a matching description. This is useful in case
the device name isn't fixed. STRING may contain the '*' and '?'
wildcards and '\' to mark them as literal. Use dmesg(1) to find the
name and bus address (the names used under /dev/input/by-id are not
always usable).
-H, --driver <driver>
The driver to use. Using --driver help lists all available
drivers, see DRIVER LOADING below.
-h, --help
Displays short help message.
Other options:
-a, --allow-simulate
Enable the SIMULATE command which can be issued using irsend(1) or
the client API. This will allow simulating arbitrary IR events from
the command line. Use this option with caution because it will give
all users with access to the lircd socket wide control over the
system. E.g., if you have configured your system to shut down by a
button press on your remote control, everybody will be able to shut
down your system from the command line.
-c, --connect [host[:port]][,[host[:port]]]
Connects to other lircd servers that provide a network socket at
the given host and port number (see --listen). The number of such
connections is currently limited to 100. The connecting lircd
instance will receive IR events from the lircd instance it connects
to. To connect to multiple servers, add them as a comma separated
list.
-e, --effective-user <uid>
If started as user root, lircd drops it privileges and runs as user
<uid> after opening files etc.
-i, --immediate-init
Lircd normally initializes the driver when the first client
connects. If this option is selected, the driver is instead
initialized immediately at start.
-A, --driver-options key:value[|key:value...]
Set one or more options for the driver. The argument is a list of
key:value pairs delimited by '|'. The key can not contain spaces,
but such are allowed in the value part. Certain characters
including '#' and ';' are used as comment markers in the config
file and are not allowed anywhere.
-Y, --dynamic-codes [EXPERIMENTAL]
Allows use of codes which have been decoded for one remote but are
not defined in lircd.conf. New codes are dynamically created with
a default name. This feature is experimental and subject to all
sorts of changes. It has not ben tested thoroughly.
-l, --listen [[address:]port]]
Let lircd listen for network connections on the given address/port.
The default address is 0.0.0.0, which means that connections on all
network interfaces will be accepted. The default port is 8765. No
security checks are currently implemented. The listening lircd
instance will send all IR events to the connecting lircd instances.
-L, --logfile <logfile path>
Select the lircd daemon log file. logfile is 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 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'.
The level can also be an integer in the range 3 (almost no
messages) to 10.
-O, --options-file <path>
File containing default values for all options. A relative path is
interpreted from current directory. See [FILES] below.
-o, --output <output socket>
Select Unix domain socket, which lircd will write remote key codes
to. The default currently is /var/run/lirc/lircd.
-p, --permission <perm>
Gives the file permission of the output socket if it has to be
created in octal representation. See chmod(1). If no --permission
option is given when the socket is initially created the default is
to give all users read and write permissions (0666 in octal
representation). If the socket already exists this option has no
effect.
-p, --pidfile <path>
Select the lircd daemon pid file, defaults to
/var/run/lirc/lircd.pid.
-U --plugindir <path>
Sets the directory from which lircd loads it's userspace drivers.
These are *.so files, by default found as described under DRIVER
LOADING. The argument is a :-separated search path.
-r, --release [suffix]
Enables automatic generation of release events for each button
press. lircd will append the given suffix to the button name for
each release event. If no suffix is given the default suffix is
'_UP'.
-R, --repeat-max <limit>
Sets an upper limit to the number of repeats when sending a signal.
The current default is 600. A SEND_START request will repeat the
signal this many times. Also, if the number of repeats in a
SEND_ONCE request exceeds this number, it will be replaced by this
number.
-u, --uinput
[DEPRECATED] Enable automatic generation of Linux input events.
Obsoleted by the lircd-uinput(8) tool and the lircd-uinput.service
systemd service.
SOCKET BROADCAST MESSAGES FORMAT
When decoding a button press or receiving a SIGHUP signal lircd.conf
lircd broadcasts messages to all connected clients.
For each decoded button press a package is made available on the
socket. This is printable data formatted as:
<code> <repeat count> <button name> <remote control name>
e.g.,
0000000000f40bf0 00 KEY_UP ANIMAX
The fields are:
code
A 16 hexadecimal digits number encoding of the IR signal. It's
usage in applications is deprecated and it should be ignored.
repeat count
shows how long the user has been holding down a button. The counter
will start at 0 and increment each time a new IR signal has been
received.
button name
is the name of a key defined in the lircd.conf file.
remote control name
is the mandatory name attribute in the lircd.conf config file.
These packets are broadcasted to all clients. The only other situation
when lircd broadcasts to all clients is when it receives the SIGHUP
signal and successfully re-reads its config file. Then it will send a
SIGHUP packet to its clients indicating that its configuration might
have changed. The sighup packet is three lines
BEGIN
SIGHUP
END
SOCKET COMMAND INTERFACE
Applications can also send commands to lircd over the socket interface.
The most common task is sending data, but there are also other
commands. Each command is a single printable line, terminated with a
newline. For each command, lircd replies with a reply package.
Supported commands:
SEND_ONCE <remote control> <button name> [repeats]
Tell lircd to send the IR signal associated with the given remote
control and button name, and then repeat it repeats times. repeats
is a decimal number between 0 and repeat_max. The latter can be
given as a --repeat-max command line argument to lircd, and
defaults to 600. If repeats is not specified or is less than the
minimum number of repeats for the selected remote control, the
minimum value will be used.
SEND_START <remote control name> <button name>
Tell lircd to start repeating the given button until it receives a
SEND_STOP command. However, the number of repeats is limited to
repeat_max. lircd won't accept any new send commands while it is
repeating.
SEND_STOP <remote control name> <button name>
Tell lircd to abort a SEND_START command.
LIST [remote control]
Without arguments lircd replies with a list of all defined remote
controls. Given a remote control argument, lircd replies with a
list of all keys defined in the given remote.
SET_INPUTLOG [path]
Given a path, lircd will start logging all received data on that
file. The log is printable lines as defined in mode2(1) describing
pulse/space durations. Without a path, current logfile is closed
and the logging is stopped.
DRV_OPTION key value
Make lircd invoke the drvctl_func(DRVCTL_SET_OPTION, option) with
option being made up by the parsed key and value. The return
package reflects the outcome of the drvctl_func call.
SIMULATE key data
Given key data, instructs lircd to send this to all clients i. e.,
to simulate that this key has been decoded. The key data must be
formatted exactly as the packet described in [SOCKET BROADCAST
MESSAGES FORMAT], notably is the number of digits in code and
repeat count hardcoded. This command is only accepted if the
--allow-simulate command line option is active.
SET_TRANSMITTERS transmitter mask
Make lircd invoke the drvctl_func(LIRC_SET_TRANSMITTER_MASK,
&channels), where channels is the decoded value of transmitter
mask. See lirc(4) for more information.
VERSION
Tell lircd to send a version packet response.
The protocol guarantees that broadcasted messages won't interfere with
reply packets. But broadcasts may appear at any point between packets.
The only exception are SIGHUP packages. These may appear just after you
have sent a command to lircd, so you have to make sure you don't
confuse them with replies.
The format of the reply packet is
BEGIN
<command>
[SUCCESS|ERROR]
[DATA
n
n lines of data]
END
If the command was successful, data is only sent for the commands that
return some information. Note that a packet containing 0 lines of data
can be a valid reply.
RUNNING AS REGULAR USER
Traditionally lircd has been running as root since accessing kernel devices like /dev/lirc0 by default requires root privileges. However, running a long-running service like this is a major security issue. The lirc distribution contains example udev rules which makes /dev/lirc[0-9] , USB and serial devices accessible by the lirc user. Using these rules, it is possible to run lircd as a regular user and group such as lirc.
FILES
/etc/lirc/lircd.conf
Main config file, see lircd.conf(5).
/etc/lirc/lirc_options.conf
The options file. lircd handles the values under the [lircd]
section in this file. The location can be changed using the
-O/--options-file command-line option or using the environment
variable LIRC_OPTIONS_PATH. The values here are used as defaults
for any option not present on command line.
ENVIRONMENT
LIRC_OPTIONS_PATH
Options file path, see FILES.
LIRC_PLUGINDIR
Plugin load path, se DRIVER LOADING.
LIRC_DEBUG_OPTIONS
If set, enables debugging in early stages when the --debug option
is yet not parsed.
DRIVER LOADING
Drivers are loaded dynamically. This is done from a traditional *ux
:-separated path where each component in the path is searched
(leading part first, trailing last).
The path used for this is determined by (falling priority):
- The --plugindir option.
- The 'plugindir' entry in the [lircd] section of the
lirc_options.conf file.
- The environment variable LIRC_PLUGINDIR.
- A hardcoded default (/usr/lib/x86_64-linux-gnu/lirc/plugins).
SIGNALS
HUP On receiving SIGHUP lircd re-reads the lircd.conf configuration
file (but not lirc_options.conf) and adjusts itself if the file has
changed.
USR1
On receiving SIGUSR1 lircd makes a clean exit.
DAEMONS
lircd is a daemon. You should start it in some init script depending on your system. Besides the systemd setup which is installed by default there are also example scripts for other distros and init systems in the contrib directory.
SEE ALSO
irdb-get(1) lirc-setup(1) lircd.conf(5) irrecord(1) lirc(4) lircd-uinput(8)
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
