Debian Codegraph @

upstream/debian-trixie/man4/lirc.4

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