1 .\" Copyright (c) 2015-2016, Alec Leamas
3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
4 .\" This is free documentation; you can redistribute it and/or
5 .\" modify it under the terms of the GNU General Public License as
6 .\" published by the Free Software Foundation; either version 2 of
7 .\" the License, or (at your option) any later version.
9 .\" The GNU General Public License's references to "object code"
10 .\" and "executables" are to be interpreted as the output of any
11 .\" document formatting or typesetting system, including
12 .\" intermediate and printed output.
14 .\" This manual is distributed in the hope that it will be useful,
15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 .\" GNU General Public License for more details.
19 .\" You should have received a copy of the GNU General Public
20 .\" License along with this manual; if not, see
21 .\" <http://www.gnu.org/licenses/>.
23 .TH LIRC 4 2016-07-17 "Linux" "Linux Programmer's Manual"
30 character devices provide a low-level
31 bi-directional interface to infra-red (IR) remotes.
32 When receiving data, the driver works in two different modes depending
33 on the underlying hardware.
35 Some hardware (typically TV-cards) decodes the IR signal internally
36 and just provides decoded button presses as integer values.
37 Drivers for this kind of hardware work in
38 .BR LIRC_MODE_LIRCCODE
40 Such hardware usually does not support sending IR signals.
41 Furthermore, it usually only works with a specific remote which is
42 bundled with, for example, a TV-card.
44 Other hardware provides a stream of pulse/space durations.
48 Sometimes, this kind of hardware also supports
50 Such hardware can be used with (almost) any kind of remote.
52 The \fBLIRC_GET_REC_MODE\fR ioctl (see below) allows probing for the
55 .SS Reading input with the LIRC_MODE_MODE2 drivers
57 In the \fBLIRC_MODE_MODE2 mode\fR, the data returned by
59 provides 32-bit values representing a space or a pulse duration, by
62 The time of the duration (microseconds) is encoded in the lower 24 bits.
63 The upper 8 bit reflects the type of package:
65 .BR LIRC_MODE2_SPACE .
66 Value reflects a space duration (microseconds).
68 .BR LIRC_MODE2_PULSE .
69 Value reflects a pulse duration (microseconds).
71 .BR LIRC_MODE2_FREQUENCY .
72 Value reflects a frequency (Hz); see the
73 .B LIRC_SET_MEASURE_CARRIER_MODE
76 .BR LIRC_MODE2_TIMEOUT .
77 The package reflects a timeout; see the
78 .B LIRC_SET_REC_TIMEOUT_REPORTS
81 .SS Reading input with the
85 In the \fBLIRC_MODE_LIRCCODE\fR
86 mode, the data returned by
88 reflects decoded button presses.
89 The length of each packet can be retrieved using
90 the \fBLIRC_GET_LENGTH\fR ioctl.
91 Reads must be done in blocks matching
92 the bit count returned by the \fBLIRC_GET_LENGTH\fR ioctl, rounded
93 up so it matches full bytes.
97 When sending data, only the \fBLIRC_MODE_PULSE\fR
99 The data written to the character device using
101 is a pulse/space sequence of integer values.
102 Pulses and spaces are only marked implicitly by their position.
103 The data must start and end with a pulse, thus it must always include
104 an odd number of samples.
107 function blocks until the data has been transmitted by the
109 If more data is provided than the hardware can send, the
111 call fails with the error
116 The complete list of ioctl commands is maintained in the kernel
117 documentation, see SEE ALSO.
118 The ioctl commands presented here is a subset of the kernel
121 The LIRC device's ioctl definition is bound by the ioctl function
122 definition of struct file_operations, leaving us with an unsigned
123 int for the ioctl command and an unsigned long for the argument.
124 For the purposes of ioctl portability across 32-bit and 64-bit architectures,
125 these values are capped to their 32-bit sizes.
128 #include <lirc/include/media/lirc.h> /* But see BUGS */
129 int ioctl(int fd, int cmd, ...);
132 The following ioctls can be used to probe or change specific lirc
134 Many require a third argument, usually an
139 In general, each driver should have a default set of settings.
140 The driver implementation is expected to re-apply the default settings
141 when the device is closed by user space, so that every application
142 opening the device can rely on working with the default settings
145 .SS Always Supported Commands
147 \fI/dev/lirc*\fR devices always support the following commands:
149 .BR LIRC_GET_FEATURES " (\fIvoid\fP)"
150 Returns a bit mask of combined features bits; see FEATURES.
151 Some drivers have dynamic features which are not updated until after an
154 If a driver does not announce support of certain features, calling of
155 the corresponding ioctls is undefined.
157 .BR LIRC_GET_REC_MODE
158 Return the receive mode, which will be one of:
161 .BR LIRC_MODE_MODE2 " (\fIvoid\fP)"
162 The driver returns a sequence of pulse/space durations.
164 .BR LIRC_MODE_LIRCCODE
165 The driver returns integer values, each of which represents a decoded
169 If a device returns an error code for
170 .BR LIRC_GET_REC_MODE ,
171 it is safe to assume it is not a lirc device.
173 .SS Optional Commands
175 Some lirc devices support commands listed below.
176 Unless otherwise stated, these fail with the error \fBENOIOCTLCMD\fR
177 or with the error \fBENOSYS\fR if the operation
178 isn't supported, or with the error \fBEINVAL\fR if the operation
181 .BR LIRC_SET_REC_MODE " (\fIint\fP)"
182 Set the receive mode.
185 .BR LIRC_MODE_LIRCCODE
187 .BR LIRC_MODE_MODE2 .
189 .BR LIRC_GET_LENGTH " (\fIvoid\fP)"
190 Return the length of the returned codes for
191 .BR LIRC_MODE_LIRCCODE -type
192 drivers, otherwise fail with the error
195 .BR LIRC_GET_SEND_MODE " (\fIvoid\fP)"
196 Return the send mode.
201 .BR LIRC_SET_SEND_MODE " (\fIint\fP)"
203 Currently serves no purpose since only
207 .BR LIRC_GET_SEND_CARRIER " (\fIvoid\fP)"
208 Get the modulation frequency (Hz).
210 .BR LIRC_SET_SEND_CARRIER " (\fIint\fP)"
211 Set the modulation frequency.
212 The argument is the frequency (Hz).
214 .BR LIRC_GET_SEND_CARRIER " (\fIvoid\fP)"
215 Get the modulation frequency used when decoding (Hz).
217 .BR SET_SEND_DUTY_CYCLE " (\fIint\fP)"
218 Set the carrier duty cycle.
220 is a number in the range [0,100] which
221 describes the pulse width as a percentage of the total cycle.
222 Currently, no special meaning is defined for 0 or 100, but the values
223 are reserved for future use.
226 .BR LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)", " "\
227 LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)"
228 Some devices have internal timers that can be used to detect when
229 there's no IR activity for a long time.
232 in detecting that an IR signal is finished and can speed up the
235 return integer values with the minimum/maximum timeout that can be
237 Some devices have a fixed timeout.
239 .BR LIRC_GET_MIN_TIMEOUT
241 .BR LIRC_GET_MAX_TIMEOUT
242 will return the same value.
244 .BR LIRC_SET_REC_TIMEOUT " (\fIint\fP)"
245 Set the integer value for IR inactivity timeout (microseconds).
246 To be accepted, the value must be within the limits defined by
247 .BR LIRC_GET_MIN_TIMEOUT
249 .BR LIRC_GET_MAX_TIMEOUT .
250 A value of 0 (if supported by the hardware) disables all hardware
251 timeouts and data should be reported as soon as possible.
252 If the exact value cannot be set, then the next possible value
254 than the given value should be set.
256 .BR LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)"
261 is 0) timeout packages in
262 .BR LIRC_MODE_MODE2 .
263 By default, timeout reports should be turned off.
265 .BR LIRC_SET_REC_CARRIER " (\fIint\fP)"
266 Set the receive carrier frequency (Hz).
268 .BR LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)"
269 After opening device, the first use of this operation
270 sets the lower bound of the carrier range,
271 and the second use sets the upper bound (Hz).
273 .BR LIRC_SET_MEASURE_CARRIER_MODE " (\fIint\fP)"
278 is 0) the measure mode.
279 If enabled, from the next key press on, the driver will send
280 .BR LIRC_MODE2_FREQUENCY
282 By default this should be turned off.
284 .BR LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)"
285 Return the driver resolution (microseconds).
287 .BR LIRC_GET_MIN_FILTER_PULSE " (\fIvoid\fP)", " " \
288 LIRC_GET_MAX_FILTER_PULSE " (\fIvoid\fP)"
289 Some devices are able to filter out spikes in the incoming signal
290 using given filter rules.
291 These ioctls return the hardware capabilities that describe the bounds
292 of the possible filters.
293 Filter settings depend on the IR protocols that are expected.
295 derives the settings from all protocols definitions found in its
299 .BR LIRC_GET_MIN_FILTER_SPACE " (\fIvoid\fP)", " " \
300 LIRC_GET_MAX_FILTER_SPACE " (\fIvoid\fP)"
302 .BR LIRC_GET_MIN_FILTER_PULSE .
304 .BR LIRC_SET_REC_FILTER " (\fIint\fP)"
305 Pulses/spaces shorter than this (microseconds) are filtered out by
308 .BR LIRC_SET_REC_FILTER_PULSE " (\fIint\fP)", " " \
309 LIRC_SET_REC_FILTER_SPACE " (\fIint\fP)"
310 Pulses/spaces shorter than this (microseconds) are filtered out by
312 If filters cannot be set independently for pulse/space, the
313 corresponding ioctls must return an error and
314 .BR LIRC_SET_REC_FILTER
315 should be used instead.
317 .BR LIRC_SET_TRANSMITTER_MASK
318 Enable the set of transmitters specified in
320 which contains a bit mask where each enabled transmitter is a 1.
321 The first transmitter is encoded by the least significant bit, and so on.
322 When an invalid bit mask is given, for example a bit is set even
323 though the device does not have so many transmitters,
324 this operation returns the
325 number of available transmitters and does nothing otherwise.
327 .BR LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)"
328 Some devices are equipped with a special wide band receiver which is
329 intended to be used to learn the output of an existing remote.
330 This ioctl can be used to enable
334 equals 0) this functionality.
335 This might be useful for devices that otherwise have narrow band
336 receivers that prevent them to be used with certain remotes.
337 Wide band receivers may also be more precise.
338 On the other hand its disadvantage usually is reduced range of
341 Note: wide band receiver may be implicitly enabled if you enable
343 In that case, it will be disabled as soon as you disable carrier reports.
344 Trying to disable a wide band receiver while carrier reports are active
347 .BR LIRC_SETUP_START " (\fIvoid\fP), " LIRC_SETUP_END " (\fIvoid\fP)"
348 Setting of several driver parameters can be optimized by bracketing
349 the actual ioctl calls
353 When a driver receives a
355 ioctl, it can choose to not commit further setting changes to the
359 But this is open to the driver implementation and every driver
360 must also handle parameter changes which are not encapsulated by
364 Drivers can also choose to ignore these ioctls.
366 .BR LIRC_NOTIFY_DECODE " (\fIvoid\fP)"
367 This ioctl is called by
369 whenever a successful decoding of an incoming IR signal is possible.
370 This can be used by supporting hardware to give visual user
371 feedback, for example by flashing an LED.
375 The features returned by
377 .BR LIRC_GET_FEATURES
378 ioctl returns a bit mask describing features of the driver.
379 The following bits may be returned in the mask:
382 The driver is capable of receiving using
385 .BR LIRC_CAN_REC_PULSE
386 The driver is capable of receiving using
387 .BR LIRC_MODE_PULSE .
389 .BR LIRC_CAN_REC_MODE2
390 The driver is capable of receiving using
391 .BR LIRC_MODE_MODE2 .
393 .BR LIRC_CAN_REC_LIRCCODE
394 The driver is capable of receiving using
395 .BR LIRC_MODE_LIRCCODE .
397 .BR LIRC_CAN_SET_SEND_CARRIER
398 The driver supports changing the modulation frequency using
399 .BR LIRC_SET_SEND_CARRIER .
401 .BR LIRC_CAN_SET_SEND_DUTY_CYCLE
402 The driver supports changing the duty cycle using
403 .BR LIRC_SET_SEND_DUTY_CYCLE .
405 .BR LIRC_CAN_SET_TRANSMITTER_MASK
406 The driver supports changing the active transmitter(s) using
407 .BR LIRC_SET_TRANSMITTER_MASK .
409 .BR LIRC_CAN_SET_REC_CARRIER
410 The driver supports setting the receive carrier frequency using
411 .BR LIRC_SET_REC_CARRIER .
413 .BR LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE
415 .BR LIRC_SET_REC_DUTY_CYCLE_RANGE .
417 .BR LIRC_CAN_SET_REC_CARRIER_RANGE
419 .BR LIRC_SET_REC_CARRIER_RANGE .
421 .BR LIRC_CAN_GET_REC_RESOLUTION
423 .BR LIRC_GET_REC_RESOLUTION .
425 .BR LIRC_CAN_SET_REC_TIMEOUT
427 .BR LIRC_SET_REC_TIMEOUT .
429 .BR LIRC_CAN_SET_REC_FILTER
431 .BR LIRC_SET_REC_FILTER .
433 .BR LIRC_CAN_MEASURE_CARRIER
434 The driver supports measuring of the modulation frequency using
435 .BR LIRC_SET_MEASURE_CARRIER_MODE .
437 .BR LIRC_CAN_USE_WIDEBAND_RECEIVER
438 The driver supports learning mode using
439 .BR LIRC_SET_WIDEBAND_RECEIVER .
441 .BR LIRC_CAN_NOTIFY_DECODE
443 .BR LIRC_NOTIFY_DECODE .
445 .BR LIRC_CAN_SEND_RAW
446 The driver supports sending using
449 .BR LIRC_CAN_SEND_PULSE
450 The driver supports sending using
451 .BR LIRC_MODE_PULSE .
453 .BR LIRC_CAN_SEND_MODE2
454 The driver supports sending using
455 .BR LIRC_MODE_MODE2 .
457 .BR LIRC_CAN_SEND_LIRCCODE
458 The driver supports sending.
459 (This is uncommon, since
461 drivers reflect hardware like TV-cards which usually dos not support
465 Using these devices requires the kernel source header file
467 This file is not available before kernel release 4.6.
468 Users of older kernels could use the file bundled in
469 .UR http://www.lirc.org
475 https://www.kernel.org/doc/htmldocs/media_api/lirc_dev.html