1LIRC(4) Linux Programmer's Manual LIRC(4)
2
6 lirc - lirc devices
7
9 The /dev/lirc* character devices provide a low-level bidirectional
10 interface to infra-red (IR) remotes. Most of these devices can
11 receive, and some can send. When receiving or sending data, the driver
12 works in two different modes depending on the underlying hardware.
13 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 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
27 decode the IR. These decoders can be written in extended BPF (see
28 bpf(2)) and attached to the lirc device.
29 The LIRC_GET_FEATURES ioctl (see below) allows probing for whether
31 receiving and sending is supported, and in which modes, amongst other
32 features.
33 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 LIRC_MODE2_SPACE
41 Value reflects a space duration (microseconds).
42 LIRC_MODE2_PULSE
44 Value reflects a pulse duration (microseconds).
45 LIRC_MODE2_FREQUENCY
47 Value reflects a frequency (Hz); see the LIRC_SET_MEASURE_CAR‐
48 RIER_MODE ioctl.
49 LIRC_MODE2_TIMEOUT
51 Value reflects a space duration (microseconds). The package
52 reflects a timeout; see the LIRC_SET_REC_TIMEOUT_REPORTS ioctl.
53 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 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 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
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 #include <linux/lirc.h> /* But see BUGS */
84 int ioctl(int fd, int cmd, ...);
85 The following ioctls can be used to probe or change specific lirc hard‐
87 ware settings. Many require a third argument, usually an int.
88 referred to below as val.
89 Always Supported Commands
91 /dev/lirc* devices always support the following commands:
92 LIRC_GET_FEATURES (void)
94 Returns a bit mask of combined features bits; see FEATURES.
95 If a device returns an error code for LIRC_GET_FEATURES, it is safe to
97 assume it is not a lirc device.
98 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
105 error ENOTTY.
106 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 LIRC_MODE_MODE2
113 The driver returns a sequence of pulse/space durations.
114 LIRC_MODE_SCANCODE
116 The driver returns struct lirc_scancode values, each of
117 which represents a decoded button press.
118 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 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 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 LIRC_SET_SEND_CARRIER (int)
135 Set the modulation frequency. The argument is the frequency
136 (Hz).
137 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 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
150 (microseconds). Some devices have a fixed timeout. For such
151 drivers, LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT will fail
152 with the error ENOTTY.
153 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 LIRC_GET_REC_TIMEOUT (void)
164 Return the current inactivity timeout (microseconds). Available
165 since Linux 4.18.
166 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 * Since Linux 4.16: each time the lirc device is opened, time‐
173 out reports are by default enabled for the resulting file
174 descriptor. The LIRC_SET_REC_TIMEOUT operation can be used
175 to disable (and, if desired, to later re-enable) the timeout
176 on the file descriptor.
177 * 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
181 effect of enabling timeouts for all file descriptors refer‐
182 ring to that device (until timeouts are disabled again).
183 LIRC_SET_REC_CARRIER (int)
185 Set the upper bound of the receive carrier frequency (Hz). See
186 LIRC_SET_REC_CARRIER_RANGE.
187 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 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 LIRC_GET_REC_RESOLUTION (void)
201 Return the driver resolution (microseconds).
202 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 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 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
225 receiver while carrier reports are active will do nothing.
226
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 LIRC_CAN_REC_MODE2
232 The driver is capable of receiving using LIRC_MODE_MODE2.
233 LIRC_CAN_REC_SCANCODE
235 The driver is capable of receiving using LIRC_MODE_SCANCODE.
236 LIRC_CAN_SET_SEND_CARRIER
238 The driver supports changing the modulation frequency using
239 LIRC_SET_SEND_CARRIER.
240 LIRC_CAN_SET_SEND_DUTY_CYCLE
242 The driver supports changing the duty cycle using
243 LIRC_SET_SEND_DUTY_CYCLE.
244 LIRC_CAN_SET_TRANSMITTER_MASK
246 The driver supports changing the active transmitter(s) using
247 LIRC_SET_TRANSMITTER_MASK.
248 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 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 LIRC_CAN_GET_REC_RESOLUTION
262 The driver supports LIRC_GET_REC_RESOLUTION.
263 LIRC_CAN_SET_REC_TIMEOUT
265 The driver supports LIRC_SET_REC_TIMEOUT.
266 LIRC_CAN_MEASURE_CARRIER
268 The driver supports measuring of the modulation frequency using
269 LIRC_SET_MEASURE_CARRIER_MODE.
270 LIRC_CAN_USE_WIDEBAND_RECEIVER
272 The driver supports learning mode using LIRC_SET_WIDE‐
273 BAND_RECEIVER.
274 LIRC_CAN_SEND_PULSE
276 The driver supports sending using LIRC_MODE_PULSE or
277 LIRC_MODE_SCANCODE
278
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
285 ir-ctl(1), lircd(8), bpf(2)
286 https://www.kernel.org/doc/html/latest/media/uapi/rc/lirc-dev.html
288
290 This page is part of release 5.07 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/.
294Linux 2019-03-06 LIRC(4)