Ubuntu Manpage: lirc - lirc devices

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⟩.

COLOPHON