lirc — lirc devices
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.
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.
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.
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
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 userspace, so that every application opening the device can rely on working with the default settings initially.
/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.
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
)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
)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
)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
),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.
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.)
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
This page is part of release 4.07 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/.
Copyright (c) 2015-2016, 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 |