Documentation/media/uapi/rc/lirc-dev-intro.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _lirc_dev_intro:
  11
  12 ************
  13 Introduction
  14 ************
  15
  16 LIRC stands for Linux Infrared Remote Control. The LIRC device interface is
  17 a bi-directional interface for transporting raw IR and decoded scancodes
  18 data between userspace and kernelspace. Fundamentally, it is just a chardev
  19 (/dev/lircX, for X = 0, 1, 2, ...), with a number of standard struct
  20 file_operations defined on it. With respect to transporting raw IR and
  21 decoded scancodes to and fro, the essential fops are read, write and ioctl.
  22
  23 Example dmesg output upon a driver registering w/LIRC:
  24
  25 .. code-block:: none
  26
  27     $ dmesg |grep lirc_dev
  28     rc rc0: lirc_dev: driver mceusb registered at minor = 0, raw IR receiver, raw IR transmitter
  29
  30 What you should see for a chardev:
  31
  32 .. code-block:: none
  33
  34     $ ls -l /dev/lirc*
  35     crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0
  36
  37 .. _lirc_modes:
  38
  39 **********
  40 LIRC modes
  41 **********
  42
  43 LIRC supports some modes of receiving and sending IR codes, as shown
  44 on the following table.
  45
  46 .. _lirc-mode-scancode:
  47 .. _lirc-scancode-flag-toggle:
  48 .. _lirc-scancode-flag-repeat:
  49
  50 ``LIRC_MODE_SCANCODE``
  51
  52     This mode is for both sending and receiving IR.
  53
  54     For transmitting (aka sending), create a ``struct lirc_scancode`` with
  55     the desired scancode set in the ``scancode`` member, :c:type:`rc_proto`
  56     set the IR protocol, and all other members set to 0. Write this struct to
  57     the lirc device.
  58
  59     For receiving, you read ``struct lirc_scancode`` from the lirc device,
  60     with ``scancode`` set to the received scancode and the IR protocol
  61     :c:type:`rc_proto`. If the scancode maps to a valid key code, this is set
  62     in the ``keycode`` field, else it is set to ``KEY_RESERVED``.
  63
  64     The ``flags`` can have ``LIRC_SCANCODE_FLAG_TOGGLE`` set if the toggle
  65     bit is set in protocols that support it (e.g. rc-5 and rc-6), or
  66     ``LIRC_SCANCODE_FLAG_REPEAT`` for when a repeat is received for protocols
  67     that support it (e.g. nec).
  68
  69     In the Sanyo and NEC protocol, if you hold a button on remote, rather than
  70     repeating the entire scancode, the remote sends a shorter message with
  71     no scancode, which just means button is held, a "repeat". When this is
  72     received, the ``LIRC_SCANCODE_FLAG_REPEAT`` is set and the scancode and
  73     keycode is repeated.
  74
  75     With nec, there is no way to distinguish "button hold" from "repeatedly
  76     pressing the same button". The rc-5 and rc-6 protocols have a toggle bit.
  77     When a button is released and pressed again, the toggle bit is inverted.
  78     If the toggle bit is set, the ``LIRC_SCANCODE_FLAG_TOGGLE`` is set.
  79
  80     The ``timestamp`` field is filled with the time nanoseconds
  81     (in ``CLOCK_MONOTONIC``) when the scancode was decoded.
  82
  83 .. _lirc-mode-mode2:
  84
  85 ``LIRC_MODE_MODE2``
  86
  87     The driver returns a sequence of pulse and space codes to userspace,
  88     as a series of u32 values.
  89
  90     This mode is used only for IR receive.
  91
  92     The upper 8 bits determine the packet type, and the lower 24 bits
  93     the payload. Use ``LIRC_VALUE()`` macro to get the payload, and
  94     the macro ``LIRC_MODE2()`` will give you the type, which
  95     is one of:
  96
  97     ``LIRC_MODE2_PULSE``
  98
  99         Signifies the presence of IR in microseconds.
 100
 101     ``LIRC_MODE2_SPACE``
 102
 103         Signifies absence of IR in microseconds.
 104
 105     ``LIRC_MODE2_FREQUENCY``
 106
 107         If measurement of the carrier frequency was enabled with
 108         :ref:`lirc_set_measure_carrier_mode` then this packet gives you
 109         the carrier frequency in Hertz.
 110
 111     ``LIRC_MODE2_TIMEOUT``
 112
 113         If timeout reports are enabled with
 114         :ref:`lirc_set_rec_timeout_reports`, when the timeout set with
 115         :ref:`lirc_set_rec_timeout` expires due to no IR being detected,
 116         this packet will be sent, with the number of microseconds with
 117         no IR.
 118
 119 .. _lirc-mode-pulse:
 120
 121 ``LIRC_MODE_PULSE``
 122
 123     In pulse mode, a sequence of pulse/space integer values are written to the
 124     lirc device using :ref:`lirc-write`.
 125
 126     The values are alternating pulse and space lengths, in microseconds. The
 127     first and last entry must be a pulse, so there must be an odd number
 128     of entries.
 129
 130     This mode is used only for IR send.
 131
 132
 133 **************************
 134 Remote Controller protocol
 135 **************************
 136
 137 An enum :c:type:`rc_proto` in the :ref:`lirc_header` lists all the
 138 supported IR protocols:
 139
 140 .. kernel-doc:: include/uapi/linux/lirc.h