Debian Codegraph @

upstream/debian-unstable/man4/lirc.4

raw
1 .\" Copyright 2015-2016, Alec Leamas <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .TH lirc 4 2026-02-08 "Linux man-pages 6.18"
6 .SH NAME
7 lirc \- lirc devices
8 .SH DESCRIPTION
9 The
10 .I /dev/lirc*
11 character devices provide a low-level
12 bidirectional interface to infra-red (IR) remotes.
13 Most of these devices can receive, and some can send.
14 When receiving or sending data, the driver works in two different modes
15 depending on the underlying hardware.
16 .P
17 Some hardware (typically TV-cards) decodes the IR signal internally
18 and provides decoded button presses as scancode values.
19 Drivers for this kind of hardware work in
20 .B LIRC_MODE_SCANCODE
21 mode.
22 Such hardware usually does not support sending IR signals.
23 Furthermore, such hardware can only decode a limited set of IR protocols,
24 usually only the protocol of the specific remote which is
25 bundled with, for example, a TV-card.
26 .P
27 Other hardware provides a stream of pulse/space durations.
28 Such drivers work in
29 .B LIRC_MODE_MODE2
30 mode.
31 Such hardware can be used with (almost) any kind of remote.
32 This type of hardware can also be used in
33 .B LIRC_MODE_SCANCODE
34 mode, in which case the kernel IR decoders will decode the IR.
35 These decoders can be written in extended BPF (see
36 .BR bpf (2))
37 and attached to the
38 .B lirc
39 device.
40 Sometimes, this kind of hardware also supports
41 sending IR data.
42 .P
43 The
44 .B LIRC_GET_FEATURES
45 ioctl (see below) allows probing for whether
46 receiving and sending is supported, and in which modes, amongst other
47 features.
48 .\"
49 .SS Reading input with the LIRC_MODE_MODE2 mode
50 In the
51 .B LIRC_MODE_MODE2
52 mode,
53 the data returned by
54 .BR read (2)
55 provides 32-bit values representing a space or a pulse duration.
56 The time of the duration (microseconds) is encoded in the lower 24 bits.
57 Pulse (also known as flash)
58 indicates a duration of infrared light being detected,
59 and space (also known as gap) indicates a duration with no infrared.
60 If the duration of space exceeds the inactivity timeout,
61 a special timeout package is delivered,
62 which marks the end of a message.
63 The upper 8 bits indicate the type of package:
64 .TP 4
65 .B LIRC_MODE2_SPACE
66 Value reflects a space duration (microseconds).
67 .TP 4
68 .B LIRC_MODE2_PULSE
69 Value reflects a pulse duration (microseconds).
70 .TP 4
71 .B LIRC_MODE2_FREQUENCY
72 Value reflects a frequency (Hz);
73 see the
74 .B LIRC_SET_MEASURE_CARRIER_MODE
75 ioctl.
76 .TP 4
77 .B LIRC_MODE2_TIMEOUT
78 Value reflects a space duration (microseconds).
79 The package reflects a timeout;
80 see the
81 .B LIRC_SET_REC_TIMEOUT_REPORTS
82 ioctl.
83 .\"
84 .TP 4
85 .B LIRC_MODE2_OVERFLOW
86 The IR receiver encountered an overflow,
87 and as a result data is missing
88 (since Linux 5.18).
89 .SS Reading input with the LIRC_MODE_SCANCODE mode
90 In the
91 .B LIRC_MODE_SCANCODE
92 mode, the data returned by
93 .BR read (2)
94 reflects decoded button presses, in the struct
95 .IR lirc_scancode .
96 The scancode is stored in the
97 .I scancode
98 field, and the IR protocol
99 is stored in
100 .IR rc_proto .
101 This field has one the values of the
102 .IR enum\~rc_proto .
103 .\"
104 .SS Writing output with the LIRC_MODE_PULSE mode
105 The data written to the character device using
106 .BR write (2)
107 is a pulse/space sequence of integer values.
108 Pulses and spaces are only marked implicitly by their position.
109 The data must start and end with a pulse, thus it must always include
110 an odd number of samples.
111 The
112 .BR write (2)
113 function blocks until the data has been transmitted by the
114 hardware.
115 If more data is provided than the hardware can send, the
116 .BR write (2)
117 call fails with the error
118 .BR EINVAL .
119 .SS Writing output with the LIRC_MODE_SCANCODE mode
120 The data written to the character devices must be a single struct
121 .IR lirc_scancode .
122 The
123 .I scancode
124 and
125 .I rc_proto
126 fields must be
127 filled in, all other fields must be 0.
128 The kernel IR encoders will
129 convert the scancode to pulses and spaces.
130 The protocol or scancode is invalid, or the
131 .B lirc
132 device cannot transmit.
133 .SH IOCTL COMMANDS
134 .nf
135 #include <linux/lirc.h> /* But see BUGS */
136 \&
137 int ioctl(int fd, int cmd, int *val);
138 .fi
139 .P
140 The following
141 .BR ioctl (2)
142 operations are provided by the
143 .B lirc
144 character device to probe or change specific
145 .B lirc
146 hardware settings.
147 .SS Always Supported Commands
148 .IR /dev/lirc *
149 devices always support the following commands:
150 .TP 4
151 .BR LIRC_GET_FEATURES " (\f[I]void\f[])"
152 Returns a bit mask of combined features bits;
153 see FEATURES.
154 .P
155 If a device returns an error code for
156 .BR LIRC_GET_FEATURES ,
157 it is safe to assume it is not a
158 .B lirc
159 device.
160 .\"
161 .SS Optional Commands
162 Some
163 .B lirc
164 devices support the commands listed below.
165 Unless otherwise stated,
166 these fail with the error
167 .B ENOTTY
168 if the operation isn't supported,
169 or with the error
170 .B EINVAL
171 if the operation failed,
172 or invalid arguments were provided.
173 If a driver does not announce support of certain features, invoking
174 the corresponding ioctls will fail with the error
175 .BR ENOTTY .
176 .TP
177 .BR LIRC_GET_REC_MODE " (\f[I]void\f[])"
178 If the
179 .B lirc
180 device has no receiver, this operation fails with the error
181 .BR ENOTTY .
182 Otherwise, it returns the receive mode, which will be one of:
183 .RS
184 .TP
185 .B LIRC_MODE_MODE2
186 The driver returns a sequence of pulse/space durations.
187 .TP
188 .B LIRC_MODE_SCANCODE
189 The driver returns struct
190 .I lirc_scancode
191 values, each of which represents
192 a decoded button press.
193 .RE
194 .TP
195 .BR LIRC_SET_REC_MODE " (\f[I]int\f[])"
196 Set the receive mode.
197 .I val
198 is either
199 .B LIRC_MODE_SCANCODE
200 or
201 .BR LIRC_MODE_MODE2 .
202 If the
203 .B lirc
204 device has no receiver, this operation fails with the error
205 .B ENOTTY.
206 .TP
207 .BR LIRC_GET_SEND_MODE " (\f[I]void\f[])"
208 Return the send mode.
209 .B LIRC_MODE_PULSE
210 or
211 .B LIRC_MODE_SCANCODE
212 is supported.
213 If the
214 .B lirc
215 device cannot send, this operation fails with the error
216 .B ENOTTY.
217 .TP
218 .BR LIRC_SET_SEND_MODE " (\f[I]int\f[])"
219 Set the send mode.
220 .I val
221 is either
222 .B LIRC_MODE_SCANCODE
223 or
224 .BR LIRC_MODE_PULSE .
225 If the
226 .B lirc
227 device cannot send, this operation fails with the error
228 .BR ENOTTY .
229 .TP
230 .BR LIRC_SET_SEND_CARRIER " (\f[I]int\f[])"
231 Set the modulation frequency.
232 The argument is the frequency (Hz).
233 .TP
234 .BR LIRC_SET_SEND_DUTY_CYCLE " (\f[I]int\f[])"
235 Set the carrier duty cycle.
236 .I val
237 is a number in the range [0,100] which
238 describes the pulse width as a percentage of the total cycle.
239 Currently, no special meaning is defined for 0 or 100, but the values
240 are reserved for future use.
241 .TP
242 .BI LIRC_GET_MIN_TIMEOUT( void )
243 .TQ
244 .BI LIRC_GET_MAX_TIMEOUT( void )
245 Some devices have internal timers that can be used to detect when
246 there has been no IR activity for a long time.
247 This can help
248 .BR lircd (8)
249 in detecting that an IR signal is finished and can speed up the
250 decoding process.
251 These operations
252 return integer values with the minimum/maximum timeout that can be
253 set (microseconds).
254 Some devices have a fixed timeout.
255 For such drivers,
256 .B LIRC_GET_MIN_TIMEOUT
257 and
258 .B LIRC_GET_MAX_TIMEOUT
259 will fail with the error
260 .BR ENOTTY .
261 .TP
262 .BR LIRC_SET_REC_TIMEOUT " (\f[I]int\f[])"
263 Set the integer value for IR inactivity timeout (microseconds).
264 To be accepted, the value must be within the limits defined by
265 .B LIRC_GET_MIN_TIMEOUT
266 and
267 .BR LIRC_GET_MAX_TIMEOUT .
268 A value of 0 (if supported by the hardware) disables all hardware
269 timeouts and data should be reported as soon as possible.
270 If the exact value cannot be set, then the next possible value
271 .I greater
272 than the given value should be set.
273 .TP
274 .BR LIRC_GET_REC_TIMEOUT " (\f[I]void\f[])"
275 Return the current inactivity timeout (microseconds).
276 Available since Linux 4.18.
277 .TP
278 .BR LIRC_SET_REC_TIMEOUT_REPORTS " (\f[I]int\f[])"
279 Enable
280 .RI ( val
281 is 1) or disable
282 .RI ( val
283 is 0) timeout packages in
284 .BR LIRC_MODE_MODE2 .
285 The behavior of this operation has varied across kernel versions:
286 .RS
287 .IP \[bu] 3
288 Since Linux 5.17:
289 timeout packages are always enabled and this ioctl is a no-op.
290 .IP \[bu]
291 Since Linux 4.16:
292 timeout packages are enabled by default.
293 Each time the
294 .B lirc
295 device is opened, the
296 .B LIRC_SET_REC_TIMEOUT
297 operation can be used to disable (and, if desired, to later re-enable)
298 the timeout on the file descriptor.
299 .IP \[bu]
300 In Linux 4.15 and earlier:
301 timeout packages are disabled by default, and enabling them (via
302 .BR LIRC_SET_REC_TIMEOUT )
303 on any file descriptor associated with the
304 .B lirc
305 device has the effect of enabling timeouts for all file descriptors
306 referring to that device (until timeouts are disabled again).
307 .RE
308 .TP
309 .BR LIRC_SET_REC_CARRIER " (\f[I]int\f[])"
310 Set the upper bound of the receive carrier frequency (Hz).
311 See
312 .BR LIRC_SET_REC_CARRIER_RANGE .
313 .TP
314 .BR LIRC_SET_REC_CARRIER_RANGE " (\f[I]int\f[])"
315 Sets the lower bound of the receive carrier frequency (Hz).
316 For this to take affect, first set the lower bound using the
317 .B LIRC_SET_REC_CARRIER_RANGE
318 ioctl, and then the upper bound using the
319 .B LIRC_SET_REC_CARRIER
320 ioctl.
321 .TP
322 .BR LIRC_SET_MEASURE_CARRIER_MODE " (\f[I]int\f[])"
323 Enable
324 .RI ( val
325 is 1) or disable
326 .RI ( val
327 is 0) the measure mode.
328 If enabled, from the next key press on, the driver will send
329 .B LIRC_MODE2_FREQUENCY
330 packets.
331 By default, this should be turned off.
332 .TP
333 .BR LIRC_GET_REC_RESOLUTION " (\f[I]void\f[])"
334 Return the driver resolution (microseconds).
335 .TP
336 .BR LIRC_SET_TRANSMITTER_MASK " (\f[I]int\f[])"
337 Enable the set of transmitters specified in
338 .IR val ,
339 which contains a bit mask where each enabled transmitter is a 1.
340 The first transmitter is encoded by the least significant bit, and so on.
341 When an invalid bit mask is given, for example a bit is set even
342 though the device does not have so many transmitters,
343 this operation returns the
344 number of available transmitters and does nothing otherwise.
345 .TP
346 .BR LIRC_SET_WIDEBAND_RECEIVER " (\f[I]int\f[])"
347 Some devices are equipped with a special wide band receiver which is
348 intended to be used to learn the output of an existing remote.
349 This ioctl can be used to enable
350 .RI ( val
351 equals 1) or disable
352 .RI ( val
353 equals 0) this functionality.
354 This might be useful for devices that otherwise have narrow band
355 receivers that prevent them to be used with certain remotes.
356 Wide band receivers may also be more precise.
357 On the other hand, their disadvantage usually is reduced range of
358 reception.
359 .IP
360 Note: wide band receiver may be implicitly enabled if you enable
361 carrier reports.
362 In that case, it will be disabled as soon as you disable carrier reports.
363 Trying to disable a wide band receiver while carrier reports are active
364 will do nothing.
365 .\"
366 .SH FEATURES
367 the
368 .B LIRC_GET_FEATURES
369 ioctl returns a bit mask describing features of the driver.
370 The following bits may be returned in the mask:
371 .TP
372 .B LIRC_CAN_REC_MODE2
373 The driver is capable of receiving using
374 .BR LIRC_MODE_MODE2 .
375 .TP
376 .B LIRC_CAN_REC_SCANCODE
377 The driver is capable of receiving using
378 .BR LIRC_MODE_SCANCODE .
379 .TP
380 .B LIRC_CAN_SET_SEND_CARRIER
381 The driver supports changing the modulation frequency using
382 .BR LIRC_SET_SEND_CARRIER .
383 .TP
384 .B LIRC_CAN_SET_SEND_DUTY_CYCLE
385 The driver supports changing the duty cycle using
386 .BR LIRC_SET_SEND_DUTY_CYCLE .
387 .TP
388 .B LIRC_CAN_SET_TRANSMITTER_MASK
389 The driver supports changing the active transmitter(s) using
390 .BR LIRC_SET_TRANSMITTER_MASK .
391 .TP
392 .B LIRC_CAN_SET_REC_CARRIER
393 The driver supports setting the receive carrier frequency using
394 .BR LIRC_SET_REC_CARRIER .
395 Any
396 .B lirc
397 device since the drivers were merged in Linux 2.6.36
398 must have
399 .B LIRC_CAN_SET_REC_CARRIER_RANGE
400 set if
401 .B LIRC_CAN_SET_REC_CARRIER
402 feature is set.
403 .TP
404 .B LIRC_CAN_SET_REC_CARRIER_RANGE
405 The driver supports
406 .BR LIRC_SET_REC_CARRIER_RANGE .
407 The lower bound of the carrier must first be set using the
408 .B LIRC_SET_REC_CARRIER_RANGE
409 ioctl, before using the
410 .B LIRC_SET_REC_CARRIER
411 ioctl to set the upper bound.
412 .TP
413 .B LIRC_CAN_GET_REC_RESOLUTION
414 The driver supports
415 .BR LIRC_GET_REC_RESOLUTION .
416 .TP
417 .B LIRC_CAN_SET_REC_TIMEOUT
418 The driver supports
419 .BR LIRC_SET_REC_TIMEOUT .
420 .TP
421 .B LIRC_CAN_MEASURE_CARRIER
422 The driver supports measuring of the modulation frequency using
423 .BR LIRC_SET_MEASURE_CARRIER_MODE .
424 .TP
425 .B LIRC_CAN_USE_WIDEBAND_RECEIVER
426 The driver supports learning mode using
427 .BR LIRC_SET_WIDEBAND_RECEIVER .
428 .TP
429 .B LIRC_CAN_SEND_PULSE
430 The driver supports sending using
431 .B LIRC_MODE_PULSE
432 or
433 .B LIRC_MODE_SCANCODE
434 .\"
435 .SH BUGS
436 Using these devices requires the kernel source header file
437 .IR lirc.h .
438 This file is not available before Linux 4.6.
439 Users of older kernels could use the file bundled in
440 .UR http:\://www.lirc.org
441 .UE .
442 .\"
443 .SH SEE ALSO
444 .BR ir\-ctl (1),
445 .BR lircd (8),
446 .BR bpf (2)
447 .P
448 .UR https:\://www.kernel.org/\:doc/\:html/\:latest/\:userspace\-api/\:media/\:rc/\:lirc\-dev.html
449 .UE