Ubuntu Manpage: lirc - lirc devices

NAME

       lirc - lirc devices

DESCRIPTION

       The  /dev/lirc* 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.

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

       Other hardware  provides  a  stream  of  pulse/space  durations.   Such  drivers  work  in
       LIRC_MODE_MODE2  mode.   Such hardware can be used with (almost) any kind of remote.  This
       type of hardware can also be used in LIRC_MODE_SCANCODE mode, in which case the kernel  IR
       decoders  will  decode the IR.  These decoders can be written in extended BPF (see bpf(2))
       and attached to the lirc device.  Sometimes, this kind of hardware also  supports  sending
       IR data.

       The  LIRC_GET_FEATURES  ioctl (see below) allows probing for whether receiving and sending
       is supported, and in which modes, amongst other features.

   Reading input with the LIRC_MODE_MODE2 mode
       In the  LIRC_MODE_MODE2  mode,  the  data  returned  by  read(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.  Pulse  (also  known  as  flash)  indicates  a  duration  of
       infrared  light being detected, and space (also known as gap) indicates a duration with no
       infrared.  If the duration of space exceeds the  inactivity  timeout,  a  special  timeout
       package  is  delivered,  which  marks the end of a message.  The upper 8 bits indicate 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
           Value reflects a space duration (microseconds).  The package reflects a  timeout;  see
           the LIRC_SET_REC_TIMEOUT_REPORTS ioctl.

       LIRC_MODE2_OVERFLOW
           The  IR receiver encountered an overflow, and as a result data is missing (since Linux
           5.18).

   Reading input with the LIRC_MODE_SCANCODE mode
       In the LIRC_MODE_SCANCODE mode, the data  returned  by  read(2)  reflects  decoded  button
       presses,  in  the struct lirc_scancode.  The scancode is stored in the scancode field, and
       the IR protocol is stored in rc_proto.   This  field  has  one  the  values  of  the  enum
       rc_proto.

   Writing output with the LIRC_MODE_PULSE mode
       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.

   Writing output with the LIRC_MODE_SCANCODE mode
       The data written to the character devices must be  a  single  struct  lirc_scancode.   The
       scancode  and  rc_proto  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 lirc device cannot transmit.

IOCTL COMMANDS

#include <linux/lirc.h> /* But see BUGS */

int ioctl(int fd, int cmd, int *val);

The following ioctl(2) operations are provided by the lirc character device to probe or
change specific lirc hardware settings.

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.

If a device returns an error code for LIRC_GET_FEATURES, it is safe to assume it is not a
lirc device.

Optional Commands
Some lirc devices support the commands listed below. Unless otherwise stated, these fail
with the error ENOTTY if the operation isn't supported, or with the error EINVAL 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
ENOTTY.

LIRC_GET_REC_MODE (void)
If the lirc device has no receiver, this operation fails with the error ENOTTY.
Otherwise, it returns the receive mode, which will be one of:

LIRC_MODE_MODE2
The driver returns a sequence of pulse/space durations.

LIRC_MODE_SCANCODE
The driver returns struct lirc_scancode values, each of which represents a
decoded button press.

LIRC_SET_REC_MODE (int)
Set the receive mode. val is either LIRC_MODE_SCANCODE or LIRC_MODE_MODE2. If the
lirc device has no receiver, this operation fails with the error ENOTTY.

LIRC_GET_SEND_MODE (void)
Return the send mode. LIRC_MODE_PULSE or LIRC_MODE_SCANCODE is supported. If the
lirc device cannot send, this operation fails with the error ENOTTY.

LIRC_SET_SEND_MODE (int)
Set the send mode. val is either LIRC_MODE_SCANCODE or LIRC_MODE_PULSE. If the
lirc device cannot send, this operation fails with the error ENOTTY.

LIRC_SET_SEND_CARRIER (int)
Set the modulation frequency. The argument is the frequency (Hz).

LIRC_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 has been 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 fail with the error ENOTTY.

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_GET_REC_TIMEOUT (void)
Return the current inactivity timeout (microseconds). Available since Linux 4.18.

LIRC_SET_REC_TIMEOUT_REPORTS (int)
Enable (val is 1) or disable (val is 0) timeout packages in LIRC_MODE_MODE2. The
behavior of this operation has varied across kernel versions:

• Since Linux 5.17: timeout packages are always enabled and this ioctl is a no-op.

• Since Linux 4.16: timeout packages are enabled by default. Each time the lirc
device is opened, the LIRC_SET_REC_TIMEOUT operation can be used to disable
(and, if desired, to later re-enable) the timeout on the file descriptor.

• In Linux 4.15 and earlier: timeout packages are disabled by default, and
enabling them (via LIRC_SET_REC_TIMEOUT) on any file descriptor associated with
the lirc device has the effect of enabling timeouts for all file descriptors
referring to that device (until timeouts are disabled again).

LIRC_SET_REC_CARRIER (int)
Set the upper bound of the receive carrier frequency (Hz). See
LIRC_SET_REC_CARRIER_RANGE.

LIRC_SET_REC_CARRIER_RANGE (int)
Sets the lower bound of the receive carrier frequency (Hz). For this to take
affect, first set the lower bound using the LIRC_SET_REC_CARRIER_RANGE ioctl, and
then the upper bound using the LIRC_SET_REC_CARRIER ioctl.

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_SET_TRANSMITTER_MASK (int)
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, their 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.

FEATURES

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_MODE2
The driver is capable of receiving using LIRC_MODE_MODE2.

LIRC_CAN_REC_SCANCODE
The driver is capable of receiving using LIRC_MODE_SCANCODE.

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. Any lirc device since the drivers were merged in Linux
2.6.36 must have LIRC_CAN_SET_REC_CARRIER_RANGE set if LIRC_CAN_SET_REC_CARRIER
feature is set.

LIRC_CAN_SET_REC_CARRIER_RANGE
The driver supports LIRC_SET_REC_CARRIER_RANGE. The lower bound of the carrier
must first be set using the LIRC_SET_REC_CARRIER_RANGE ioctl, before using the
LIRC_SET_REC_CARRIER ioctl to set the upper bound.

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_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_SEND_PULSE
The driver supports sending using LIRC_MODE_PULSE or LIRC_MODE_SCANCODE

BUGS

       Using these devices requires the kernel source header  file  lirc.h.   This  file  is  not
       available  before  Linux  4.6.   Users  of  older  kernels  could  use the file bundled in
       ⟨http://www.lirc.org⟩.

NAME

DESCRIPTION

IOCTL COMMANDS

FEATURES

BUGS

SEE ALSO