LIRC(4)                   (2019-03-06)                    LIRC(4)

     NAME
          lirc - lirc devices

     DESCRIPTION
          The /dev/lirc* character devices provide a low-level bidi-
          rectional interface to infra-red (IR) remotes.  Most of
          these devices can receive, and some can send.  When receiv-
          ing 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.  Sometimes, this
          kind of hardware also supports sending IR data.  Such hard-
          ware 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.

          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 dura-
          tion.  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_CARRIER_MODE ioctl.

          LIRC_MODE2_TIMEOUT

     Page 1                        Linux             (printed 5/24/22)

     LIRC(4)                   (2019-03-06)                    LIRC(4)

              Value reflects a space duration (microseconds).  The
              package reflects 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 scancode to pulses and spaces.
          The protocol or scancode is invalid, or the lirc device can-
          not transmit.

     IOCTL COMMANDS
          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 portabil-
          ity 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 hardware settings.  Many require a third argument, usu-
          ally an int. referred 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 FEA-
              TURES.

          If a device returns an error code for LIRC_GET_FEATURES, it

     Page 2                        Linux             (printed 5/24/22)

     LIRC(4)                   (2019-03-06)                    LIRC(4)

          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, invok-
          ing 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 dura-
                    tions.

               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 fre-
               quency (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 per-
               centage of the total cycle.  Currently, no special
               meaning is defined for 0 or 100, but the values are
               reserved for future use.

     Page 3                        Linux             (printed 5/24/22)

     LIRC(4)                   (2019-03-06)                    LIRC(4)

          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 pro-
               cess.  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 pack-
               ages in LIRC_MODE_MODE2.  The behavior of this opera-
               tion has varied across kernel versions:

               *  Since Linux 4.16: each time the lirc device is
                  opened, timeout reports are by default enabled for
                  the resulting file descriptor.  The
                  LIRC_SET_REC_TIMEOUT operation can be used to dis-
                  able (and, if desired, to later re-enable) the time-
                  out on the file descriptor.

               *  In Linux 4.15 and earlier: timeout reports are dis-
                  abled by default, and enabling them (via
                  LIRC_SET_REC_TIMEOUT) on any file descriptor associ-
                  ated 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

     Page 4                        Linux             (printed 5/24/22)

     LIRC(4)                   (2019-03-06)                    LIRC(4)

               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 sig-
               nificant 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 out-
               put 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.  Try-
               ing 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.

     Page 5                        Linux             (printed 5/24/22)

     LIRC(4)                   (2019-03-06)                    LIRC(4)

          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 fre-
               quency 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_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 fre-
               quency 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 kernel release
          4.6.  Users of older kernels could use the file bundled in

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

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

     Page 6                        Linux             (printed 5/24/22)

     LIRC(4)                   (2019-03-06)                    LIRC(4)

          dev.html

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

     Page 7                        Linux             (printed 5/24/22)