GENWiki

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