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