lirc

LIRC(4)                    Linux Programmer's Manual                   LIRC(4)

NAME
       lirc - lirc devices

DESCRIPTION
       The  /dev/lirc* character devices provide a low-level bidirectional in-
       terface 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  usu-
       ally  does  not support sending IR signals.  Furthermore, such hardware
       can only decode a limited set of IR protocols, usually only the  proto-
       col  of  the  specific remote which is bundled with, for example, a TV-
       card.

       Other hardware provides a stream of pulse/space durations.  Such  driv-
       ers  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.   This  type  of  hardware  can  also be used in
       LIRC_MODE_SCANCODE mode, in which case the kernel IR decoders will  de-
       code  the  IR.   These  decoders  can  be  written in extended BPF (see
       bpf(2)) and attached to the lirc device.

       The LIRC_GET_FEATURES ioctl (see below) allows probing for whether  re-
       ceiving  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.  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_CAR-
           RIER_MODE ioctl.

       LIRC_MODE2_TIMEOUT
           Value reflects a space duration (microseconds).   The  package  re-
           flects a timeout; see the LIRC_SET_REC_TIMEOUT_REPORTS ioctl.

   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  scan-
       code to pulses and spaces.  The protocol or scancode is invalid, or the
       lirc device cannot transmit.

IOCTL COMMANDS
       The LIRC device's ioctl definition is bound by the ioctl function defi-
       nition  of  struct file_operations, leaving us with an unsigned int for
       the ioctl command and an unsigned long for the argument.  For the  pur-
       poses  of  ioctl  portability  across  32-bit and 64-bit architectures,
       these values are capped to their 32-bit sizes.

       #include <linux/lirc.h>    /* But see BUGS */
       int ioctl(int fd, int cmd, ...);

       The following ioctls can be used to probe or change specific lirc hard-
       ware  settings.   Many  require  a third argument, usually an int.  re-
       ferred to below as val.

   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  sup-
       ported,  or  with  the error EINVAL if the operation failed, or invalid
       arguments were provided.  If a driver does not announce support of cer-
       tain features, invoking the corresponding ioctls will fail with the er-
       ror 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 oper-
              ation 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 (mi-
              croseconds).  Some devices have a fixed timeout.  For such driv-
              ers,  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 4.16: each time the lirc device is opened, time-
                 out reports are by default enabled for the resulting file de-
                 scriptor.   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 reports are disabled by
                 default, and enabling them (via LIRC_SET_REC_TIMEOUT) on  any
                 file  descriptor  associated with the lirc device has the ef-
                 fect 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 oper-
              ation  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 dis-
              able  (val  equals  0) this functionality.  This might be useful
              for devices that otherwise have narrow band receivers that  pre-
              vent  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 re-
              ceiver 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 kernel release 2.6.36 must have  LIRC_CAN_SET_REC_CAR-
              RIER_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_CAR-
              RIER_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_RE-
              CEIVER.

       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 kernel release 4.6.  Users  of  older
       kernels could use the file bundled in <http://www.lirc.org>.

SEE ALSO
       ir-ctl(1), lircd(8), bpf(2)

       https://www.kernel.org/doc/html/latest/media/uapi/rc/lirc-dev.html

COLOPHON
       This  page  is  part of release 5.05 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/.

Linux                             2019-03-06                           LIRC(4)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2024 Hurricane Electric. All Rights Reserved.