1LIRC(4)                    Linux Programmer's Manual                   LIRC(4)
2
3
4

NAME

6       lirc - lirc devices
7

DESCRIPTION

9       The  /dev/lirc* character devices provide a low-level bidirectional in‐
10       terface to infra-red (IR) remotes.  Most of these devices can  receive,
11       and some can send.  When receiving or sending data, the driver works in
12       two different modes depending on the underlying hardware.
13
14       Some hardware (typically TV-cards) decodes the IR signal internally and
15       provides  decoded  button presses as scancode values.  Drivers for this
16       kind of hardware work in LIRC_MODE_SCANCODE mode.  Such  hardware  usu‐
17       ally  does  not support sending IR signals.  Furthermore, such hardware
18       can only decode a limited set of IR protocols, usually only the  proto‐
19       col  of  the  specific remote which is bundled with, for example, a TV-
20       card.
21
22       Other hardware provides a stream of pulse/space durations.  Such  driv‐
23       ers  work  in  LIRC_MODE_MODE2  mode.  Sometimes, this kind of hardware
24       also supports sending IR data.  Such hardware can be used with (almost)
25       any  kind  of  remote.   This  type  of  hardware  can  also be used in
26       LIRC_MODE_SCANCODE mode, in which case the kernel IR decoders will  de‐
27       code  the  IR.   These  decoders  can  be  written in extended BPF (see
28       bpf(2)) and attached to the lirc device.
29
30       The LIRC_GET_FEATURES ioctl (see below) allows probing for whether  re‐
31       ceiving  and  sending  is  supported, and in which modes, amongst other
32       features.
33
34   Reading input with the LIRC_MODE_MODE2 mode
35       In the LIRC_MODE_MODE2 mode, the  data  returned  by  read(2)  provides
36       32-bit  values  representing  a space or a pulse duration.  The time of
37       the duration (microseconds) is encoded in the lower 24 bits.  The upper
38       8 bits indicate the type of package:
39
40       LIRC_MODE2_SPACE
41           Value reflects a space duration (microseconds).
42
43       LIRC_MODE2_PULSE
44           Value reflects a pulse duration (microseconds).
45
46       LIRC_MODE2_FREQUENCY
47           Value  reflects  a  frequency  (Hz);  see the LIRC_SET_MEASURE_CAR‐
48           RIER_MODE ioctl.
49
50       LIRC_MODE2_TIMEOUT
51           Value reflects a space duration (microseconds).   The  package  re‐
52           flects a timeout; see the LIRC_SET_REC_TIMEOUT_REPORTS ioctl.
53
54   Reading input with the LIRC_MODE_SCANCODE mode
55       In  the  LIRC_MODE_SCANCODE mode, the data returned by read(2) reflects
56       decoded button presses, in the struct lirc_scancode.  The  scancode  is
57       stored  in  the  scancode  field,  and  the  IR  protocol  is stored in
58       rc_proto.  This field has one the values of the enum rc_proto.
59
60   Writing output with the LIRC_MODE_PULSE mode
61       The  data  written  to  the  character  device  using  write(2)  is   a
62       pulse/space  sequence  of  integer  values.  Pulses and spaces are only
63       marked implicitly by their position.  The data must start and end  with
64       a  pulse,  thus  it  must always include an odd number of samples.  The
65       write(2) function blocks until the data has  been  transmitted  by  the
66       hardware.   If  more  data  is provided than the hardware can send, the
67       write(2) call fails with the error EINVAL.
68
69   Writing output with the LIRC_MODE_SCANCODE mode
70       The data written to the character  devices  must  be  a  single  struct
71       lirc_scancode.   The  scancode  and rc_proto fields must filled in, all
72       other fields must be 0.  The kernel IR encoders will convert the  scan‐
73       code to pulses and spaces.  The protocol or scancode is invalid, or the
74       lirc device cannot transmit.
75

IOCTL COMMANDS

77       The LIRC device's ioctl definition is bound by the ioctl function defi‐
78       nition  of  struct file_operations, leaving us with an unsigned int for
79       the ioctl command and an unsigned long for the argument.  For the  pur‐
80       poses  of  ioctl  portability  across  32-bit and 64-bit architectures,
81       these values are capped to their 32-bit sizes.
82
83       #include <linux/lirc.h>    /* But see BUGS */
84       int ioctl(int fd, int cmd, ...);
85
86       The following ioctls can be used to probe or change specific lirc hard‐
87       ware settings.  Many require a third argument, usually an int, referred
88       to below as val.
89
90   Always Supported Commands
91       /dev/lirc* devices always support the following commands:
92
93       LIRC_GET_FEATURES (void)
94           Returns a bit mask of combined features bits; see FEATURES.
95
96       If a device returns an error code for LIRC_GET_FEATURES, it is safe  to
97       assume it is not a lirc device.
98
99   Optional Commands
100       Some  lirc devices support the commands listed below.  Unless otherwise
101       stated, these fail with the error ENOTTY if the  operation  isn't  sup‐
102       ported,  or  with  the error EINVAL if the operation failed, or invalid
103       arguments were provided.  If a driver does not announce support of cer‐
104       tain features, invoking the corresponding ioctls will fail with the er‐
105       ror ENOTTY.
106
107       LIRC_GET_REC_MODE (void)
108              If the lirc device has no receiver, this  operation  fails  with
109              the error ENOTTY.  Otherwise, it returns the receive mode, which
110              will be one of:
111
112              LIRC_MODE_MODE2
113                     The driver returns a sequence of pulse/space durations.
114
115              LIRC_MODE_SCANCODE
116                     The driver returns struct lirc_scancode values,  each  of
117                     which represents a decoded button press.
118
119       LIRC_SET_REC_MODE (int)
120              Set  the  receive  mode.   val  is  either LIRC_MODE_SCANCODE or
121              LIRC_MODE_MODE2.  If the lirc device has no receiver, this oper‐
122              ation fails with the error ENOTTY.
123
124       LIRC_GET_SEND_MODE (void)
125              Return  the send mode.  LIRC_MODE_PULSE or LIRC_MODE_SCANCODE is
126              supported.  If the lirc device cannot send, this operation fails
127              with the error ENOTTY.
128
129       LIRC_SET_SEND_MODE (int)
130              Set   the  send  mode.   val  is  either  LIRC_MODE_SCANCODE  or
131              LIRC_MODE_PULSE.  If the lirc device cannot send, this operation
132              fails with the error ENOTTY.
133
134       LIRC_SET_SEND_CARRIER (int)
135              Set  the  modulation  frequency.   The argument is the frequency
136              (Hz).
137
138       LIRC_SET_SEND_DUTY_CYCLE (int)
139              Set the carrier duty cycle.   val  is  a  number  in  the  range
140              [0,100]  which  describes the pulse width as a percentage of the
141              total cycle.  Currently, no special meaning is defined for 0  or
142              100, but the values are reserved for future use.
143
144       LIRC_GET_MIN_TIMEOUT (void), LIRC_GET_MAX_TIMEOUT (void)
145              Some  devices  have  internal  timers that can be used to detect
146              when there has been no IR activity for a long  time.   This  can
147              help lircd(8) in detecting that an IR signal is finished and can
148              speed up the decoding process.  These operations return  integer
149              values  with  the  minimum/maximum  timeout that can be set (mi‐
150              croseconds).  Some devices have a fixed timeout.  For such driv‐
151              ers,  LIRC_GET_MIN_TIMEOUT  and  LIRC_GET_MAX_TIMEOUT  will fail
152              with the error ENOTTY.
153
154       LIRC_SET_REC_TIMEOUT (int)
155              Set the integer value for IR inactivity timeout  (microseconds).
156              To  be  accepted, the value must be within the limits defined by
157              LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT.  A value of 0 (if
158              supported  by  the  hardware) disables all hardware timeouts and
159              data should be reported as soon as possible.  If the exact value
160              cannot  be  set,  then  the next possible value greater than the
161              given value should be set.
162
163       LIRC_GET_REC_TIMEOUT (void)
164              Return the current inactivity timeout (microseconds).  Available
165              since Linux 4.18.
166
167       LIRC_SET_REC_TIMEOUT_REPORTS (int)
168              Enable  (val  is  1)  or  disable (val is 0) timeout packages in
169              LIRC_MODE_MODE2.  The behavior  of  this  operation  has  varied
170              across kernel versions:
171
172              *  Since  Linux 4.16: each time the lirc device is opened, time‐
173                 out reports are by default enabled for the resulting file de‐
174                 scriptor.   The LIRC_SET_REC_TIMEOUT operation can be used to
175                 disable (and, if desired, to later re-enable) the timeout  on
176                 the file descriptor.
177
178              *  In  Linux  4.15  and earlier: timeout reports are disabled by
179                 default, and enabling them (via LIRC_SET_REC_TIMEOUT) on  any
180                 file  descriptor  associated with the lirc device has the ef‐
181                 fect of enabling timeouts for all file descriptors  referring
182                 to that device (until timeouts are disabled again).
183
184       LIRC_SET_REC_CARRIER (int)
185              Set  the upper bound of the receive carrier frequency (Hz).  See
186              LIRC_SET_REC_CARRIER_RANGE.
187
188       LIRC_SET_REC_CARRIER_RANGE (int)
189              Sets the lower bound of the receive carrier frequency (Hz).  For
190              this  to  take  affect,  first  set  the  lower  bound using the
191              LIRC_SET_REC_CARRIER_RANGE ioctl, and then the upper bound using
192              the LIRC_SET_REC_CARRIER ioctl.
193
194       LIRC_SET_MEASURE_CARRIER_MODE (int)
195              Enable  (val  is  1) or disable (val is 0) the measure mode.  If
196              enabled, from the next  key  press  on,  the  driver  will  send
197              LIRC_MODE2_FREQUENCY packets.  By default, this should be turned
198              off.
199
200       LIRC_GET_REC_RESOLUTION (void)
201              Return the driver resolution (microseconds).
202
203       LIRC_SET_TRANSMITTER_MASK (int)
204              Enable the set of transmitters specified in val, which  contains
205              a  bit  mask  where  each enabled transmitter is a 1.  The first
206              transmitter is encoded by the least significant bit, and so  on.
207              When an invalid bit mask is given, for example a bit is set even
208              though the device does not have so many transmitters, this oper‐
209              ation  returns  the  number  of  available transmitters and does
210              nothing otherwise.
211
212       LIRC_SET_WIDEBAND_RECEIVER (int)
213              Some devices are equipped with  a  special  wide  band  receiver
214              which  is intended to be used to learn the output of an existing
215              remote.  This ioctl can be used to enable (val equals 1) or dis‐
216              able  (val  equals  0) this functionality.  This might be useful
217              for devices that otherwise have narrow band receivers that  pre‐
218              vent  them to be used with certain remotes.  Wide band receivers
219              may also be more precise.  On the other hand, their disadvantage
220              usually is reduced range of reception.
221
222              Note: wide band receiver may be implicitly enabled if you enable
223              carrier reports.  In that case, it will be disabled as  soon  as
224              you  disable carrier reports.  Trying to disable a wide band re‐
225              ceiver while carrier reports are active will do nothing.
226

FEATURES

228       the LIRC_GET_FEATURES ioctl returns a bit mask describing  features  of
229       the driver.  The following bits may be returned in the mask:
230
231       LIRC_CAN_REC_MODE2
232              The driver is capable of receiving using LIRC_MODE_MODE2.
233
234       LIRC_CAN_REC_SCANCODE
235              The driver is capable of receiving using LIRC_MODE_SCANCODE.
236
237       LIRC_CAN_SET_SEND_CARRIER
238              The  driver  supports  changing  the  modulation frequency using
239              LIRC_SET_SEND_CARRIER.
240
241       LIRC_CAN_SET_SEND_DUTY_CYCLE
242              The   driver   supports   changing   the   duty   cycle    using
243              LIRC_SET_SEND_DUTY_CYCLE.
244
245       LIRC_CAN_SET_TRANSMITTER_MASK
246              The  driver  supports  changing  the active transmitter(s) using
247              LIRC_SET_TRANSMITTER_MASK.
248
249       LIRC_CAN_SET_REC_CARRIER
250              The driver supports setting the receive carrier frequency  using
251              LIRC_SET_REC_CARRIER.   Any  lirc  device since the drivers were
252              merged in kernel release 2.6.36 must have  LIRC_CAN_SET_REC_CAR‐
253              RIER_RANGE set if LIRC_CAN_SET_REC_CARRIER feature is set.
254
255       LIRC_CAN_SET_REC_CARRIER_RANGE
256              The driver supports LIRC_SET_REC_CARRIER_RANGE.  The lower bound
257              of the carrier must first be  set  using  the  LIRC_SET_REC_CAR‐
258              RIER_RANGE ioctl, before using the LIRC_SET_REC_CARRIER ioctl to
259              set the upper bound.
260
261       LIRC_CAN_GET_REC_RESOLUTION
262              The driver supports LIRC_GET_REC_RESOLUTION.
263
264       LIRC_CAN_SET_REC_TIMEOUT
265              The driver supports LIRC_SET_REC_TIMEOUT.
266
267       LIRC_CAN_MEASURE_CARRIER
268              The driver supports measuring of the modulation frequency  using
269              LIRC_SET_MEASURE_CARRIER_MODE.
270
271       LIRC_CAN_USE_WIDEBAND_RECEIVER
272              The  driver  supports  learning mode using LIRC_SET_WIDEBAND_RE‐
273              CEIVER.
274
275       LIRC_CAN_SEND_PULSE
276              The   driver   supports   sending   using   LIRC_MODE_PULSE   or
277              LIRC_MODE_SCANCODE
278

BUGS

280       Using  these  devices  requires  the  kernel source header file lirc.h.
281       This file is not available before kernel release 4.6.  Users  of  older
282       kernels could use the file bundled in ⟨http://www.lirc.org⟩.
283

SEE ALSO

285       ir-ctl(1), lircd(8), bpf(2)
286
287       https://www.kernel.org/doc/html/latest/media/uapi/rc/lirc-dev.html
288

COLOPHON

290       This  page  is  part of release 5.12 of the Linux man-pages project.  A
291       description of the project, information about reporting bugs,  and  the
292       latest     version     of     this    page,    can    be    found    at
293       https://www.kernel.org/doc/man-pages/.
294
295
296
297Linux                             2019-03-06                           LIRC(4)
Impressum