man-pages/man4/lirc.4

.TH LIRC 4 "Aug 2015" "Linux" "Linux Programmer's Manual"


.\" Copyright (c) 2015, Alec Leamas
.\"
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, see
.\" <http://www.gnu.org/licenses/>.
.\" %%%LICENSE_END
.SH NAME
lirc \- lirc devices
.SH DESCRIPTION
.P
\fB/dev/lirc*\fR are character devices providing 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.
.P
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
.BR LIRC_MODE_LIRCCODE .
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.
.P
Other hardware provides a stream of pulse/space durations.
Such drivers work in
.BR LIRC_MODE_MODE2 .
Sometimes, this kind of hardware also supports
sending IR data.
Such hardware can be used with (almost) any kind of remote.
.P
The \fBLIRC_GET_REC_MODE\fR ioctl (see below) allows probing for the
mode.

.SS Reading input with the LIRC_MODE_MODE2 drivers
.P
In the \fBLIRC_MODE_MODE2 mode\fR, the data returned by
.BR read (2)
provides 32-bit values representing a space or a pulse duration, by
convention typed as
.IR lirc_t .
The time of the duration (microseonds) is encoded in the lower 24 bits.
The upper 8 bit reflects the type of package:
.TP 4
.BR LIRC_MODE2_SPACE .
Value reflects a space duration (microseconds).
.TP 4
.BR LIRC_MODE2_PULSE .
Value reflects a pulse duration (microseconds).
.TP 4
.BR LIRC_MODE2_FREQUENCY .
Value reflects a frequency (hz), see the
.B LIRC_SET_MEASURE_CARRIER
ioctl.
.TP 4
.BR LIRC_MODE2_TIMEOUT .
The package reflects a timeout, see the
.B LIRC_SET_REC_TIMEOUT_REPORTS
ioctl.

.SS Reading input with the
.B LIRC_MODE_LIRCCODE
drivers
.P
In the \fBLIRC_MODE_LIRCCODE\fR
mode, the data returned by
.BR read2()
reflects decoded button presses.
The length of each packet can be retrieved using
the \fBLIRC_GET_LENGTH\fR ioctl.
Reads must be done in blocks matching
the bit count returned by the \fBLIRC_GET_LENGTH\fR ioctl, rounded
up so it matches full bytes.

.SS Sending data
.P
When sending data, only the \fBLIRC_MODE_PULSE\fR
mode is supported.
The data written to the character device using
.BR 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
.BR write(2)
function blocks until the data has been transmitted by the
hardware.
If more data is provided than the hardware can send, the
.BR write(2)
call fails with the error
.BR EINVAL

.SH SUPPORTED IOCTL COMMANDS
.P
.nf
#include " (\fIlirc/include/media/lirc.h\fP) " /* But see BUGS */
int ioctl(int fd, int cmd, ...);
.fi
.P
The following ioctls can be used to probe or change specific lirc
hardware settings.
Many require a third argument, usually an
.IR int .
referred to below as
.I val .
.P
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 userspace, so that every application
opening the device can rely on working with the default settings
initially.

.BR
.SS Always Supported Commands
.P
\fI/dev/lirc*\fR devices always support the following commands:
.TP 4
.BR LIRC_GET_FEATURES " (\fIvoid\fP)"
Returns a bitmask of combined features bits, see FEATURES.
Some drivers have dynamic features which are not updated until after
an init() command.
.TP
.BR LIRC_GET_REC_MODE ,
Returns the receive mode, which will be one of:
.RS 4
.TP
.BR LIRC_MODE_MODE2 " (\fIvoid\fP)"
Driver returns a sequence of pulse/space durations.
.TP
.BR LIRC_MODE_LIRCCODE
Driver returns integer values, each of which represents a decoded
button press.
.RE
.P
If a device returns an error code for
.BR LIRC_GET_REC_MODE
it is safe to assume it is not a lirc device.

.SS Optional Commands
.P
Some lirc devices support commands listed below.
Unless otherwise stated, these fail with the error \fBENOIOCTLCMD\fR
or with the error \fBENOSYS\fR if the operation
isn't supported, or with the error \fBEINVAL\fR if the operation
failed.
.TP
.BR LIRC_SET_REC_MODE " (\fIint\fP)"
Set the receive mode.
.IR val
is either
.BR LIRC_MODE_LIRCCODE
or
.BR LIRC_MODE_MODE2 .

.TP
.BR LIRC_GET_LENGTH " (\fIvoid\fP)"
Return the length of the returned codes for
.BR LIRC_LIRCCODE
type
drivers, otherwise fail with the error
.BR ENOIOCTLCMD .
.TP
.BR LIRC_GET_SEND_MODE " (\fIvoid\fP)"
Returns the send mode; currently only
.BR LIRC_MODE_PULSE
is supported.
.TP
.BR LIRC_SET_SEND_MODE " (\fIint\fP)"
Set the send mode.
Currently serves no purpose since only
.BR LIRC_MODE_PULSE
is supported.
.TP
.BR LIRC_SET_SEND_CARRIER " (\fIint\fP)"
Set the modulation frequency. The argument is the frequency (Hz).
.TP
.BR SET_SEND_DUTY_CYCLE " (\fIint\fP)"
Set the carrier duty cycle.
The argument is an int (0 < value < 100) which
describes the pulse width in percent of the total cycle.
Currently, no special meaning is defined for 0 or 100, but the values
are reserved for future use.
.TP
.BR LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)", " "\
LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)"
Some devices have internal timers that can be used to detect when
there's no IR activity for a long time.
This can help
.BR lircd(8)
in detecting that an IR signal is finished and can speed up the
decoding process.
Returns an integer value with the minimum/maximum timeout that can be
set (microseconds).
Some devices have a fixed timeout. For such drivers,
.BR LIRC_GET_MIN_TIMEOUT
and
.BR LIRC_GET_MAX_TIMEOUT
will return the same value.
.TP
.BR LIRC_SET_REC_TIMEOUT " (\fIint\fP)"
Sets the integer value for IR inactivity timeout (microseconds).
To be accepted, the value must be within the limits defined by
.BR LIRC_GET_MIN_TIMEOUT
and
.BR 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
.I greater
than the given value should be set.
.TP
.BR LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)"
Enables
.RI ( val
is 1) or disables
.RI (val
is 0) timeout packages in
.BR LIRC_MODE_MODE2 .
By default, timeout reports should be turned off.
.TP
.BR LIRC_SET_REC_CARRIER " (\fIint\fP)"
Set the receive carrier frequency (Hz).
.TP
After opening device, the first use of
.BR LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)"
sets the lower bound of the carrier range, second time the upper
bound (Hz).
.TP
.BR LIRC_SET_MEASURE_CARRIER " (\fIint\fP)"
Enables
.RI ( val
is 1) or disables
.RI (val
is 0) the measure mode
If enabled, from the next key press on, the driver will send
.BR LIRC_MODE2_FREQUENCY
packets. By default this should be turned off.
.TP
.BR LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)"
Returns the driver resolution (microseconds).
.TP
.BR LIRC_GET_MIN_FILTER_PULSE " (\fIvoid\fP)", " " \
LIRC_GET_MAX_FILTER_PULSE " (\fIvoid\fP)"
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 derives the settings from all protocols definitions found in its
.BR lircd.conf (5)
config file.
.TP
.BR LIRC_GET_MIN_FILTER_SPACE " (\fIvoid\fP)", " " \
LIRC_GET_MAX_FILTER_SPACE " (\fIvoid\fP)"
See
.BR LIRC_GET_MIN_FILTER_PULSE .
.TP
.BR LIRC_SET_REC_FILTER " (\fIint\fP)"
Pulses/spaces shorter than this (microseconds) are filtered out by
hardware.
.TP
.BR LIRC_SET_REC_FILTER_PULSE " (\fIint\fP)", " " \
LIRC_SET_REC_FILTER_SPACE " (\fIint\fP)"
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
.BR LIRC_SET_REC_FILTER
should be used instead.
.TP
.BR LIRC_SET_TRANSMITTER_MASK
Enables the given set of transmitters.
.RI val
contains a bitmask where each enabled transmitter is a 1.
The first transmitter is encoded by the least significant bit, etc.
When an invalid bit mask is given, for example a bit is set even
though the device does not have so many transmitters, returns the
number of available transmitters and does nothing otherwise.
.TP
.BR LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)"
Some devices are equipped with a special wide band receiver which are
intended to be used to learn the output of an existing remote.
This ioctl can be used to enable
.RI ( val
equals 1) or disable
.RI ( 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.
.IP
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.

.TP
.BR LIRC_SETUP_START " (\fIvoid\fP)", " "LIRC_SETUP_END " (\fIvoid\fP)"
Setting of several driver parameters can be optimized by encapsulating
the actual ioctl calls with
.BR LIRC_SETUP_START/LIRC_SETUP_END .
When a driver receives a
.BR LIRC_SETUP_START
ioctl it can choose to not commit further setting changes to the
hardware until a
.BR 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
.BR LIRC_SETUP_START
and
.BR LIRC_SETUP_END .
Drivers can also choose to ignore these ioctls.

.TP
.BR LIRC_NOTIFY_DECODE " (\fIvoid\fP)"
This ioctl is called by
.BR 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.

.SH FEATURES
.P
The features returned by
.BR LIRC_GET_FEATURES
is a bitmask combining the following bits:
.TP 8
.BR LIRC_CAN_REC_RAW
The driver is capable of receiving using
.BR LIRC_MODE_RAW .
.TP 8
.BR LIRC_CAN_REC_PULSE
The driver is capable of receiving using
.BR LIRC_MODE_PULSE .
.TP 8
.BR LIRC_CAN_REC_MODE2
The driver is capable of receiving using
.BR LIRC_MODE_MODE2 .
.TP 8
.BR LIRC_CAN_REC_LIRCCODE
The driver is capable of receiving using
.BR LIRC_MODE_LIRCCODE .
.TP 8
.BR LIRC_CAN_SET_SEND_CARRIER
Driver supports changing the modulation frequency using
.BR LIRC_SET_SEND_CARRIER .
.TP 8
.BR LIRC_CAN_SET_SEND_DUTY_CYCLE
Driver supports changing the duty cycle using
.BR LIRC_SET_SEND_DUTY_CYCLE .
.TP 8
.BR LIRC_CAN_SET_TRANSMITTER_MASK
Driver supports changing the active transmitter(s) using
.BR LIRC_SET_TRANSMITTER_MASK .
.TP 8
.BR LIRC_CAN_SET_REC_CARRIER
Driver supports setting the receive carrier frequency using
.BR LIRC_SET_REC_CARRIER .
.TP 8
.BR LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE
Driver supports
.BR LIRC_SET_REC_DUTY_CYCLE_RANGE .
.TP 8
.BR LIRC_CAN_SET_REC_CARRIER_RANGE
Driver supports
.BR LIRC_SET_REC_CARRIER_RANGE .
.TP 8
.BR LIRC_CAN_GET_REC_RESOLUTION
Driver supports
.BR LIRC_GET_REC_RESOLUTION .
.TP 8
.BR LIRC_CAN_SET_REC_TIMEOUT
Driver supports
.BR LIRC_SET_REC_TIMEOUT .
.TP 8
.BR LIRC_CAN_SET_REC_FILTER
Driver supports
.BR LIRC_SET_REC_FILTER .
.TP 8
.BR LIRC_CAN_MEASURE_CARRIER
Driver supports measuring of the modulation frequency using
.BR LIRC_MEASURE_CARRIER .
.TP 8
.BR LIRC_CAN_USE_WIDEBAND_RECEIVER
Driver supports learning mode using
.BR LIRC_SET_WIDEBAND_RECEIVER .
.TP 8
.BR LIRC_CAN_NOTIFY_DECODE
Driver supports
.BR LIRC_NOTIFY_DECODE .
.TP 8
.BR LIRC_CAN_SEND_RAW
Driver supports sending using
.BR LIRC_SEND_RAW .
.TP 8
.BR LIRC_CAN_SEND_PULSE
Driver supports sending using
.BR LIRC_MODE_PULSE .
.TP 8
.BR LIRC_CAN_SEND_MODE2
Driver supports sending using
.BR LIRC_SEND_MODE2 .
.TP 8
.BR LIRC_CAN_SEND_LIRCCODE
Driver supports sending.
.BR LIRC_SEND_LIRCCODE
(this is uncommon, since
.BR LIRCCODE
drivers reflect hardware like TV-cards which usually does not support
sending.)

.SH BUGS
.P
Using these devices requires the kernel source header file lirc.h.
This file not being public is a bug, see
https://bugzilla.kernel.org/show_bug.cgi?id=3D75751.
For the time being the file is bundled in the lirc package,
see http://www.lirc.org.


.SH SEE ALSO
.P
https://www.kernel.org/doc/htmldocs/media_api/lirc_dev.html