lirc(4)
NAME
lirc - lirc devices
DESCRIPTION
The /dev/lirc* character devices provide a low-level bi-directional interface to infra-red (IR) remotes. When receiving data, the driver works in two different modes depending on the underlying hardware. Some hardware (typically TV-cards) decodes the IR signal internally and just provides decoded button presses as integer values. Drivers for this kind of hardware work in LIRC_MODE_LIRCCODE mode. Such hardware usually does not support sending IR signals. Furthermore, it usually only works with a specific remote which is bundled with, for example, a TV-card. Other hardware provides a stream of pulse/space durations. Such drivers work in LIRC_MODE_MODE2 mode. Sometimes, this kind of hardware also supports sending IR data. Such hardware can be used with (almost) any kind of remote. The LIRC_GET_REC_MODE ioctl (see below) allows probing for the mode. Reading input with the LIRC_MODE_MODE2 drivers In the LIRC_MODE_MODE2 mode, the data returned by read(2) provides 32-bit values representing a space or a pulse duration, by convention typed as lirc_t. The time of the duration (microseconds) is encoded in the lower 24 bits. The upper 8 bit reflects the type of package: LIRC_MODE2_SPACE. Value reflects a space duration (microseconds). LIRC_MODE2_PULSE. Value reflects a pulse duration (microseconds). LIRC_MODE2_FREQUENCY. Value reflects a frequency (Hz); see the LIRC_SET_MEASURE_CARRIER_MODE ioctl. LIRC_MODE2_TIMEOUT. The package reflects a timeout; see the LIRC_SET_REC_TIMEOUT_REPORTS ioctl. Reading input with the LIRC_MODE_LIRCCODE drivers In the LIRC_MODE_LIRCCODE mode, the data returned by read(2) reflects decoded button presses. The length of each packet can be retrieved using the LIRC_GET_LENGTH ioctl. Reads must be done in blocks matching the bit count returned by the LIRC_GET_LENGTH ioctl, rounded up so it matches full bytes. Sending data When sending data, only the LIRC_MODE_PULSE mode is supported. The data written to the character device using write(2) is a pulse/space sequence of integer values. Pulses and spaces are only marked implicitly by their position. The data must start and end with a pulse, thus it must always include an odd number of samples. The write(2) function blocks until the data has been transmitted by the hardware. If more data is provided than the hardware can send, the write(2) call fails with the error EINVAL
IOCTL COMMANDS
The complete list of ioctl commands is maintained in the kernel
documentation, see SEE ALSO. The ioctl commands presented here is a
subset of the kernel documentation.
The LIRC device's ioctl definition is bound by the ioctl function
definition of struct file_operations, leaving us with an unsigned int
for the ioctl command and an unsigned long for the argument. For the
purposes of ioctl portability across 32-bit and 64-bit architectures,
these values are capped to their 32-bit sizes.
#include <lirc/include/media/lirc.h> /* But see BUGS */
int ioctl(int fd, int cmd, ...);
The following ioctls can be used to probe or change specific lirc
hardware settings. Many require a third argument, usually an int.
referred to below as val.
In general, each driver should have a default set of settings. The
driver implementation is expected to re-apply the default settings when
the device is closed by user space, so that every application opening
the device can rely on working with the default settings initially.
Always Supported Commands
/dev/lirc* devices always support the following commands:
LIRC_GET_FEATURES (void)
Returns a bit mask of combined features bits; see FEATURES. Some
drivers have dynamic features which are not updated until after an
init() command. If a driver does not announce support of certain
features, calling of the corresponding ioctls is undefined.
LIRC_GET_REC_MODE
Return the receive mode, which will be one of:
LIRC_MODE_MODE2 (void)
The driver returns a sequence of pulse/space durations.
LIRC_MODE_LIRCCODE
The driver returns integer values, each of which represents
a decoded button press.
If a device returns an error code for LIRC_GET_REC_MODE, it is safe to
assume it is not a lirc device.
Optional Commands
Some lirc devices support commands listed below. Unless otherwise
stated, these fail with the error ENOIOCTLCMD or with the error ENOSYS
if the operation isn't supported, or with the error EINVAL if the
operation failed.
LIRC_SET_REC_MODE (int)
Set the receive mode. val is either LIRC_MODE_LIRCCODE or
LIRC_MODE_MODE2.
LIRC_GET_LENGTH (void)
Return the length of the returned codes for LIRC_MODE_LIRCCODE-
type drivers, otherwise fail with the error ENOIOCTLCMD.
LIRC_GET_SEND_MODE (void)
Return the send mode. Currently, only LIRC_MODE_PULSE is
supported.
LIRC_SET_SEND_MODE (int)
Set the send mode. Currently serves no purpose since only
LIRC_MODE_PULSE is supported.
LIRC_GET_SEND_CARRIER (void)
Get the modulation frequency (Hz).
LIRC_SET_SEND_CARRIER (int)
Set the modulation frequency. The argument is the frequency
(Hz).
LIRC_GET_SEND_CARRIER (void)
Get the modulation frequency used when decoding (Hz).
SET_SEND_DUTY_CYCLE (int)
Set the carrier duty cycle. val is a number in the range
[0,100] which describes the pulse width as a percentage of the
total cycle. Currently, no special meaning is defined for 0 or
100, but the values are reserved for future use.
LIRC_GET_MIN_TIMEOUT (void), LIRC_GET_MAX_TIMEOUT (void)
Some devices have internal timers that can be used to detect
when there's no IR activity for a long time. This can help
lircd(8) in detecting that an IR signal is finished and can
speed up the decoding process. These operations return integer
values with the minimum/maximum timeout that can be set
(microseconds). Some devices have a fixed timeout. For such
drivers, LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT will
return the same value.
LIRC_SET_REC_TIMEOUT (int)
Set the integer value for IR inactivity timeout (microseconds).
To be accepted, the value must be within the limits defined by
LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT. A value of 0 (if
supported by the hardware) disables all hardware timeouts and
data should be reported as soon as possible. If the exact value
cannot be set, then the next possible value greater than the
given value should be set.
LIRC_SET_REC_TIMEOUT_REPORTS (int)
Enable (val is 1) or disable (val is 0) timeout packages in
LIRC_MODE_MODE2. By default, timeout reports should be turned
off.
LIRC_SET_REC_CARRIER (int)
Set the receive carrier frequency (Hz).
LIRC_SET_REC_CARRIER_RANGE (int)
After opening device, the first use of this operation sets the
lower bound of the carrier range, and the second use sets the
upper bound (Hz).
LIRC_SET_MEASURE_CARRIER_MODE (int)
Enable (val is 1) or disable (val is 0) the measure mode. If
enabled, from the next key press on, the driver will send
LIRC_MODE2_FREQUENCY packets. By default this should be turned
off.
LIRC_GET_REC_RESOLUTION (void)
Return the driver resolution (microseconds).
LIRC_GET_MIN_FILTER_PULSE (void), LIRC_GET_MAX_FILTER_PULSE (void)
Some devices are able to filter out spikes in the incoming
signal using given filter rules. These ioctls return the
hardware capabilities that describe the bounds of the possible
filters. Filter settings depend on the IR protocols that are
expected. lircd(8) derives the settings from all protocols
definitions found in its lircd.conf(5) config file.
LIRC_GET_MIN_FILTER_SPACE (void), LIRC_GET_MAX_FILTER_SPACE (void)
See LIRC_GET_MIN_FILTER_PULSE.
LIRC_SET_REC_FILTER (int)
Pulses/spaces shorter than this (microseconds) are filtered out
by hardware.
LIRC_SET_REC_FILTER_PULSE (int), LIRC_SET_REC_FILTER_SPACE (int)
Pulses/spaces shorter than this (microseconds) are filtered out
by hardware. If filters cannot be set independently for
pulse/space, the corresponding ioctls must return an error and
LIRC_SET_REC_FILTER should be used instead.
LIRC_SET_TRANSMITTER_MASK
Enable the set of transmitters specified in val, which contains
a bit mask where each enabled transmitter is a 1. The first
transmitter is encoded by the least significant bit, and so on.
When an invalid bit mask is given, for example a bit is set even
though the device does not have so many transmitters, this
operation returns the number of available transmitters and does
nothing otherwise.
LIRC_SET_WIDEBAND_RECEIVER (int)
Some devices are equipped with a special wide band receiver
which is intended to be used to learn the output of an existing
remote. This ioctl can be used to enable (val equals 1) or
disable (val equals 0) this functionality. This might be useful
for devices that otherwise have narrow band receivers that
prevent them to be used with certain remotes. Wide band
receivers may also be more precise. On the other hand its
disadvantage usually is reduced range of reception.
Note: wide band receiver may be implicitly enabled if you enable
carrier reports. In that case, it will be disabled as soon as
you disable carrier reports. Trying to disable a wide band
receiver while carrier reports are active will do nothing.
LIRC_SETUP_START (void), LIRC_SETUP_END (void)
Setting of several driver parameters can be optimized by
bracketing the actual ioctl calls LIRC_SETUP_START and
LIRC_SETUP_END. When a driver receives a LIRC_SETUP_START
ioctl, it can choose to not commit further setting changes to
the hardware until a LIRC_SETUP_END is received. But this is
open to the driver implementation and every driver must also
handle parameter changes which are not encapsulated by
LIRC_SETUP_START and LIRC_SETUP_END. Drivers can also choose to
ignore these ioctls.
LIRC_NOTIFY_DECODE (void)
This ioctl is called by lircd(8) whenever a successful decoding
of an incoming IR signal is possible. This can be used by
supporting hardware to give visual user feedback, for example by
flashing an LED.
FEATURES
The features returned by The LIRC_GET_FEATURES ioctl returns a bit mask
describing features of the driver. The following bits may be returned
in the mask:
LIRC_CAN_REC_RAW
The driver is capable of receiving using LIRC_MODE_RAW.
LIRC_CAN_REC_PULSE
The driver is capable of receiving using LIRC_MODE_PULSE.
LIRC_CAN_REC_MODE2
The driver is capable of receiving using LIRC_MODE_MODE2.
LIRC_CAN_REC_LIRCCODE
The driver is capable of receiving using LIRC_MODE_LIRCCODE.
LIRC_CAN_SET_SEND_CARRIER
The driver supports changing the modulation frequency using
LIRC_SET_SEND_CARRIER.
LIRC_CAN_SET_SEND_DUTY_CYCLE
The driver supports changing the duty cycle using
LIRC_SET_SEND_DUTY_CYCLE.
LIRC_CAN_SET_TRANSMITTER_MASK
The driver supports changing the active transmitter(s) using
LIRC_SET_TRANSMITTER_MASK.
LIRC_CAN_SET_REC_CARRIER
The driver supports setting the receive carrier frequency using
LIRC_SET_REC_CARRIER.
LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE
The driver supports LIRC_SET_REC_DUTY_CYCLE_RANGE.
LIRC_CAN_SET_REC_CARRIER_RANGE
The driver supports LIRC_SET_REC_CARRIER_RANGE.
LIRC_CAN_GET_REC_RESOLUTION
The driver supports LIRC_GET_REC_RESOLUTION.
LIRC_CAN_SET_REC_TIMEOUT
The driver supports LIRC_SET_REC_TIMEOUT.
LIRC_CAN_SET_REC_FILTER
The driver supports LIRC_SET_REC_FILTER.
LIRC_CAN_MEASURE_CARRIER
The driver supports measuring of the modulation frequency using
LIRC_SET_MEASURE_CARRIER_MODE.
LIRC_CAN_USE_WIDEBAND_RECEIVER
The driver supports learning mode using
LIRC_SET_WIDEBAND_RECEIVER.
LIRC_CAN_NOTIFY_DECODE
The driver supports LIRC_NOTIFY_DECODE.
LIRC_CAN_SEND_RAW
The driver supports sending using LIRC_MODE_RAW.
LIRC_CAN_SEND_PULSE
The driver supports sending using LIRC_MODE_PULSE.
LIRC_CAN_SEND_MODE2
The driver supports sending using LIRC_MODE_MODE2.
LIRC_CAN_SEND_LIRCCODE
The driver supports sending. (This is uncommon, since LIRCCODE
drivers reflect hardware like TV-cards which usually dos not
support sending.)
BUGS
Using these devices requires the kernel source header file lirc.h. This file is not available before kernel release 4.6. Users of older kernels could use the file bundled in http://www.lirc.org.
SEE ALSO
lircd(8) https://www.kernel.org/doc/htmldocs/media_api/lirc_dev.html
COLOPHON
This page is part of release 4.09 of the Linux man-pages project. A description of the project, information about reporting bugs, and the latest version of this page, can be found at https://www.kernel.org/doc/man-pages/.
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.
