lirc-dev-intro.rst 4.3 KB

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