man-pages/man4/lirc.4.html
2021-03-31 01:06:50 +01:00

648 lines
16 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML><HEAD><TITLE>Man page of LIRC</TITLE>
</HEAD><BODY>
<H1>LIRC</H1>
Section: Linux Programmer's Manual (4)<BR>Updated: 2019-03-06<BR><A HREF="#index">Index</A>
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
<A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2>
lirc - lirc devices
<A NAME="lbAC">&nbsp;</A>
<H2>DESCRIPTION</H2>
<P>
The
<I>/dev/lirc*</I>
character devices provide a low-level
bidirectional interface to infra-red (IR) remotes.
Most of these devices can receive, and some can send.
When receiving or sending 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 provides decoded button presses as scancode values.
Drivers for this kind of hardware work in
<B>LIRC_MODE_SCANCODE</B>
mode.
Such hardware usually does not support sending IR signals.
Furthermore, such hardware can only decode a limited set of IR protocols,
usually only the protocol of the 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
<B>LIRC_MODE_MODE2</B>
mode.
Sometimes, this kind of hardware also supports
sending IR data.
Such hardware can be used with (almost) any kind of remote.
This type of hardware can also be used in
<B>LIRC_MODE_SCANCODE</B>
mode, in which case the kernel IR decoders will decode the IR.
These decoders can be written in extended BPF (see
<B><A HREF="/cgi-bin/man/man2html?2+bpf">bpf</A></B>(2))
and attached to the
<B>lirc</B>
device.
<P>
The <B>LIRC_GET_FEATURES</B> ioctl (see below) allows probing for whether
receiving and sending is supported, and in which modes, amongst other
features.
<A NAME="lbAD">&nbsp;</A>
<H3>Reading input with the LIRC_MODE_MODE2 mode</H3>
<P>
In the <B>LIRC_MODE_MODE2 mode</B>, the data returned by
<B><A HREF="/cgi-bin/man/man2html?2+read">read</A></B>(2)
provides 32-bit values representing a space or a pulse duration.
The time of the duration (microseconds) is encoded in the lower 24 bits.
The upper 8 bits indicate the type of package:
<DL COMPACT>
<DT id="1"><B>LIRC_MODE2_SPACE</B>
<DD>
Value reflects a space duration (microseconds).
<DT id="2"><B>LIRC_MODE2_PULSE</B>
<DD>
Value reflects a pulse duration (microseconds).
<DT id="3"><B>LIRC_MODE2_FREQUENCY</B>
<DD>
Value reflects a frequency (Hz); see the
<B>LIRC_SET_MEASURE_CARRIER_MODE</B>
ioctl.
<DT id="4"><B>LIRC_MODE2_TIMEOUT</B>
<DD>
Value reflects a space duration (microseconds).
The package reflects a timeout; see the
<B>LIRC_SET_REC_TIMEOUT_REPORTS</B>
ioctl.
</DL>
<A NAME="lbAE">&nbsp;</A>
<H3>Reading input with the LIRC_MODE_SCANCODE mode</H3>
<P>
In the <B>LIRC_MODE_SCANCODE</B>
mode, the data returned by
<B><A HREF="/cgi-bin/man/man2html?2+read">read</A></B>(2)
reflects decoded button presses, in the struct <I>lirc_scancode</I>.
The scancode is stored in the <I>scancode</I> field, and the IR protocol
is stored in <I>rc_proto</I>.
This field has one the values of the <I>enum rc_proto</I>.
<A NAME="lbAF">&nbsp;</A>
<H3>Writing output with the LIRC_MODE_PULSE mode</H3>
<P>
The data written to the character device using
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(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
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2)
function blocks until the data has been transmitted by the
hardware.
If more data is provided than the hardware can send, the
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2)
call fails with the error
<B>EINVAL</B>.
<A NAME="lbAG">&nbsp;</A>
<H3>Writing output with the LIRC_MODE_SCANCODE mode</H3>
<P>
The data written to the character devices must be a single struct
<I>lirc_scancode</I>.
The <I>scancode</I> and <I>rc_proto</I> fields must
filled in, all other fields must be 0.
The kernel IR encoders will
convert the scancode to pulses and spaces.
The protocol or scancode is invalid, or the
<B>lirc</B>
device cannot transmit.
<A NAME="lbAH">&nbsp;</A>
<H2>IOCTL COMMANDS</H2>
<P>
The LIRC device's ioctl definition is bound by the ioctl function
definition of
<I>struct file_operations</I>,
leaving us with an
<I>unsigned int</I>
for the ioctl command and an
<I>unsigned long</I>
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.
<P>
<PRE>
#include &lt;<A HREF="file:///usr/include/linux/lirc.h">linux/lirc.h</A>&gt; /* But see BUGS */
int ioctl(int fd, int cmd, ...);
</PRE>
<P>
The following ioctls can be used to probe or change specific
<B>lirc</B>
hardware settings.
Many require a third argument, usually an
<I>int</I>.
referred to below as
<I>val</I>.
<A NAME="lbAI">&nbsp;</A>
<H3>Always Supported Commands</H3>
<P>
<I>/dev/lirc*</I> devices always support the following commands:
<DL COMPACT>
<DT id="5"><B>LIRC_GET_FEATURES</B> (<I>void</I>)
<DD>
Returns a bit mask of combined features bits; see FEATURES.
</DL>
<P>
If a device returns an error code for
<B>LIRC_GET_FEATURES</B>,
it is safe to assume it is not a
<B>lirc</B>
device.
<A NAME="lbAJ">&nbsp;</A>
<H3>Optional Commands</H3>
<P>
Some
<B>lirc</B>
devices support the commands listed below.
Unless otherwise stated, these fail with the error <B>ENOTTY</B> if the
operation isn't supported, or with the error <B>EINVAL</B> if the operation
failed, or invalid arguments were provided.
If a driver does not announce support of certain features, invoking
the corresponding ioctls will fail with the error
<B>ENOTTY</B>.
<DL COMPACT>
<DT id="6"><B>LIRC_GET_REC_MODE</B> (<I>void</I>)
<DD>
If the
<B>lirc</B>
device has no receiver, this operation fails with the error
<B>ENOTTY</B>.
Otherwise, it returns the receive mode, which will be one of:
<DL COMPACT><DT id="7"><DD>
<DL COMPACT>
<DT id="8"><B>LIRC_MODE_MODE2</B>
<DD>
The driver returns a sequence of pulse/space durations.
<DT id="9"><B>LIRC_MODE_SCANCODE</B>
<DD>
The driver returns struct
<I>lirc_scancode</I>
values, each of which represents
a decoded button press.
</DL>
</DL>
<DT id="10"><B>LIRC_SET_REC_MODE</B> (<I>int</I>)
<DD>
Set the receive mode.
<I>val</I>
is either
<B>LIRC_MODE_SCANCODE</B>
or
<B>LIRC_MODE_MODE2</B>.
If the
<B>lirc</B>
device has no receiver, this operation fails with the error
<B>ENOTTY.</B>
<DT id="11"><B>LIRC_GET_SEND_MODE</B> (<I>void</I>)
<DD>
Return the send mode.
<B>LIRC_MODE_PULSE</B>
or
<B>LIRC_MODE_SCANCODE</B>
is supported.
If the
<B>lirc</B>
device cannot send, this operation fails with the error
<B>ENOTTY.</B>
<DT id="12"><B>LIRC_SET_SEND_MODE</B> (<I>int</I>)
<DD>
Set the send mode.
<I>val</I>
is either
<B>LIRC_MODE_SCANCODE</B>
or
<B>LIRC_MODE_PULSE</B>.
If the
<B>lirc</B>
device cannot send, this operation fails with the error
<B>ENOTTY</B>.
<DT id="13"><B>LIRC_SET_SEND_CARRIER</B> (<I>int</I>)
<DD>
Set the modulation frequency.
The argument is the frequency (Hz).
<DT id="14"><B>LIRC_SET_SEND_DUTY_CYCLE</B> (<I>int</I>)
<DD>
Set the carrier duty cycle.
<I>val</I>
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.
<DT id="15"><DD>
<DT id="16"><B>LIRC_GET_MIN_TIMEOUT</B> (<I>void</I>),<B> LIRC_GET_MAX_TIMEOUT</B> (<I>void</I>)
<DD>
Some devices have internal timers that can be used to detect when
there has been no IR activity for a long time.
This can help
<B><A HREF="/cgi-bin/man/man2html?8+lircd">lircd</A></B>(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,
<B>LIRC_GET_MIN_TIMEOUT</B>
and
<B>LIRC_GET_MAX_TIMEOUT</B>
will fail with the error
<B>ENOTTY</B>.
<DT id="17"><B>LIRC_SET_REC_TIMEOUT</B> (<I>int</I>)
<DD>
Set the integer value for IR inactivity timeout (microseconds).
To be accepted, the value must be within the limits defined by
<B>LIRC_GET_MIN_TIMEOUT</B>
and
<B>LIRC_GET_MAX_TIMEOUT</B>.
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</I>
than the given value should be set.
<DT id="18"><B>LIRC_GET_REC_TIMEOUT</B> (<I>void</I>)
<DD>
Return the current inactivity timeout (microseconds).
Available since Linux 4.18.
<DT id="19"><B>LIRC_SET_REC_TIMEOUT_REPORTS</B> (<I>int</I>)
<DD>
Enable
(<I>val</I>
is 1) or disable
(<I>val</I>
is 0) timeout packages in
<B>LIRC_MODE_MODE2</B>.
The behavior of this operation has varied across kernel versions:
<DL COMPACT><DT id="20"><DD>
<DL COMPACT>
<DT id="21">*<DD>
Since Linux 4.16: each time the
<B>lirc device is opened,</B>
timeout reports are by default enabled for the resulting file descriptor.
The
<B>LIRC_SET_REC_TIMEOUT</B>
operation can be used to disable (and, if desired, to later re-enable)
the timeout on the file descriptor.
<DT id="22">*<DD>
In Linux 4.15 and earlier:
timeout reports are disabled by default, and enabling them (via
<B>LIRC_SET_REC_TIMEOUT</B>)
on any file descriptor associated with the
<B>lirc</B>
device has the effect of enabling timeouts for all file descriptors
referring to that device (until timeouts are disabled again).
</DL>
</DL>
<DT id="23"><B>LIRC_SET_REC_CARRIER</B> (<I>int</I>)
<DD>
Set the upper bound of the receive carrier frequency (Hz).
See
<B>LIRC_SET_REC_CARRIER_RANGE</B>.
<DT id="24"><B>LIRC_SET_REC_CARRIER_RANGE</B> (<I>int</I>)
<DD>
Sets the lower bound of the receive carrier frequency (Hz).
For this to take affect, first set the lower bound using the
<B>LIRC_SET_REC_CARRIER_RANGE</B>
ioctl, and then the upper bound using the
<B>LIRC_SET_REC_CARRIER</B>
ioctl.
<DT id="25"><B>LIRC_SET_MEASURE_CARRIER_MODE</B> (<I>int</I>)
<DD>
Enable
(<I>val</I>
is 1) or disable
(<I>val</I>
is 0) the measure mode.
If enabled, from the next key press on, the driver will send
<B>LIRC_MODE2_FREQUENCY</B>
packets.
By default, this should be turned off.
<DT id="26"><B>LIRC_GET_REC_RESOLUTION</B> (<I>void</I>)
<DD>
Return the driver resolution (microseconds).
<DT id="27"><B>LIRC_SET_TRANSMITTER_MASK</B> (<I>int</I>)
<DD>
Enable the set of transmitters specified in
<I>val</I>,
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.
<DT id="28"><B>LIRC_SET_WIDEBAND_RECEIVER</B> (<I>int</I>)
<DD>
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
(<I>val</I>
equals 1) or disable
(<I>val</I>
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, their disadvantage usually is reduced range of
reception.
<DT id="29"><DD>
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.
</DL>
<A NAME="lbAK">&nbsp;</A>
<H2>FEATURES</H2>
<P>
the
<B>LIRC_GET_FEATURES</B>
ioctl returns a bit mask describing features of the driver.
The following bits may be returned in the mask:
<DL COMPACT>
<DT id="30"><B>LIRC_CAN_REC_MODE2</B>
<DD>
The driver is capable of receiving using
<B>LIRC_MODE_MODE2</B>.
<DT id="31"><B>LIRC_CAN_REC_SCANCODE</B>
<DD>
The driver is capable of receiving using
<B>LIRC_MODE_SCANCODE</B>.
<DT id="32"><B>LIRC_CAN_SET_SEND_CARRIER</B>
<DD>
The driver supports changing the modulation frequency using
<B>LIRC_SET_SEND_CARRIER</B>.
<DT id="33"><B>LIRC_CAN_SET_SEND_DUTY_CYCLE</B>
<DD>
The driver supports changing the duty cycle using
<B>LIRC_SET_SEND_DUTY_CYCLE</B>.
<DT id="34"><B>LIRC_CAN_SET_TRANSMITTER_MASK</B>
<DD>
The driver supports changing the active transmitter(s) using
<B>LIRC_SET_TRANSMITTER_MASK</B>.
<DT id="35"><B>LIRC_CAN_SET_REC_CARRIER</B>
<DD>
The driver supports setting the receive carrier frequency using
<B>LIRC_SET_REC_CARRIER</B>.
Any
<B>lirc</B>
device since the drivers were merged in kernel release 2.6.36
must have
<B>LIRC_CAN_SET_REC_CARRIER_RANGE</B>
set if
<B>LIRC_CAN_SET_REC_CARRIER</B>
feature is set.
<DT id="36"><B>LIRC_CAN_SET_REC_CARRIER_RANGE</B>
<DD>
The driver supports
<B>LIRC_SET_REC_CARRIER_RANGE</B>.
The lower bound of the carrier must first be set using the
<B>LIRC_SET_REC_CARRIER_RANGE</B>
ioctl, before using the
<B>LIRC_SET_REC_CARRIER</B>
ioctl to set the upper bound.
<DT id="37"><B>LIRC_CAN_GET_REC_RESOLUTION</B>
<DD>
The driver supports
<B>LIRC_GET_REC_RESOLUTION</B>.
<DT id="38"><B>LIRC_CAN_SET_REC_TIMEOUT</B>
<DD>
The driver supports
<B>LIRC_SET_REC_TIMEOUT</B>.
<DT id="39"><B>LIRC_CAN_MEASURE_CARRIER</B>
<DD>
The driver supports measuring of the modulation frequency using
<B>LIRC_SET_MEASURE_CARRIER_MODE</B>.
<DT id="40"><B>LIRC_CAN_USE_WIDEBAND_RECEIVER</B>
<DD>
The driver supports learning mode using
<B>LIRC_SET_WIDEBAND_RECEIVER</B>.
<DT id="41"><B>LIRC_CAN_SEND_PULSE</B>
<DD>
The driver supports sending using
<B>LIRC_MODE_PULSE</B>
or
<B>LIRC_MODE_SCANCODE</B>
</DL>
<A NAME="lbAL">&nbsp;</A>
<H2>BUGS</H2>
Using these devices requires the kernel source header file
<I>lirc.h</I>.
This file is not available before kernel release 4.6.
Users of older kernels could use the file bundled in
<A NAME="lbAM">&nbsp;</A>
<H2>SEE ALSO</H2>
<B><A HREF="/cgi-bin/man/man2html?1+ir-ctl">ir-ctl</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?8+lircd">lircd</A></B>(8),&nbsp;<B><A HREF="/cgi-bin/man/man2html?2+bpf">bpf</A></B>(2)
<P>
<A HREF="https://www.kernel.org/doc/html/latest/media/uapi/rc/lirc-dev.html">https://www.kernel.org/doc/html/latest/media/uapi/rc/lirc-dev.html</A>
<A NAME="lbAN">&nbsp;</A>
<H2>COLOPHON</H2>
This page is part of release 5.05 of the Linux
<I>man-pages</I>
project.
A description of the project,
information about reporting bugs,
and the latest version of this page,
can be found at
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
<P>
<HR>
<A NAME="index">&nbsp;</A><H2>Index</H2>
<DL>
<DT id="42"><A HREF="#lbAB">NAME</A><DD>
<DT id="43"><A HREF="#lbAC">DESCRIPTION</A><DD>
<DL>
<DT id="44"><A HREF="#lbAD">Reading input with the LIRC_MODE_MODE2 mode</A><DD>
<DT id="45"><A HREF="#lbAE">Reading input with the LIRC_MODE_SCANCODE mode</A><DD>
<DT id="46"><A HREF="#lbAF">Writing output with the LIRC_MODE_PULSE mode</A><DD>
<DT id="47"><A HREF="#lbAG">Writing output with the LIRC_MODE_SCANCODE mode</A><DD>
</DL>
<DT id="48"><A HREF="#lbAH">IOCTL COMMANDS</A><DD>
<DL>
<DT id="49"><A HREF="#lbAI">Always Supported Commands</A><DD>
<DT id="50"><A HREF="#lbAJ">Optional Commands</A><DD>
</DL>
<DT id="51"><A HREF="#lbAK">FEATURES</A><DD>
<DT id="52"><A HREF="#lbAL">BUGS</A><DD>
<DT id="53"><A HREF="#lbAM">SEE ALSO</A><DD>
<DT id="54"><A HREF="#lbAN">COLOPHON</A><DD>
</DL>
<HR>
This document was created by
<A HREF="/cgi-bin/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 00:06:01 GMT, March 31, 2021
</BODY>
</HTML>