lirc

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

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

       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_CAR-
           RIER_MODE ioctl.

       LIRC_MODE2_TIMEOUT.
           The   package   reflects  a  timeout;  see  the  LIRC_SET_REC_TIME-
           OUT_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  implic-
       itly 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 docu-
       mentation, 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 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 <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 hard-
       ware  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 oper-
       ation 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  sup-
              ported.

       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  sig-
              nal  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 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 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 brack-
              eting the actual  ioctl  calls  LIRC_SETUP_START  and  LIRC_SET-
              UP_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  parame-
              ter  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 sup-
              porting 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_WIDE-
              BAND_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>.

SEE ALSO
       lircd(8)

       https://www.kernel.org/doc/htmldocs/media_api/lirc_dev.html

COLOPHON
       This  page  is  part of release 4.15 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                             2016-07-17                           LIRC(4)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2022 Hurricane Electric. All Rights Reserved.