1lirc(4) Kernel Interfaces Manual lirc(4)
2
6 lirc - lirc devices
7
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 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. Such hardware can be used with (al‐
24 most) any kind of remote. This type of hardware can also be used in
25 LIRC_MODE_SCANCODE mode, in which case the kernel IR decoders will de‐
26 code the IR. These decoders can be written in extended BPF (see
27 bpf(2)) and attached to the lirc device. Sometimes, this kind of hard‐
28 ware also supports sending IR data.
29 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 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. Pulse
38 (also known as flash) indicates a duration of infrared light being de‐
39 tected, and space (also known as gap) indicates a duration with no in‐
40 frared. If the duration of space exceeds the inactivity timeout, a
41 special timeout package is delivered, which marks the end of a message.
42 The upper 8 bits indicate the type of package:
43 LIRC_MODE2_SPACE
45 Value reflects a space duration (microseconds).
46 LIRC_MODE2_PULSE
48 Value reflects a pulse duration (microseconds).
49 LIRC_MODE2_FREQUENCY
51 Value reflects a frequency (Hz); see the LIRC_SET_MEASURE_CAR‐
52 RIER_MODE ioctl.
53 LIRC_MODE2_TIMEOUT
55 Value reflects a space duration (microseconds). The package re‐
56 flects a timeout; see the LIRC_SET_REC_TIMEOUT_REPORTS ioctl.
57 LIRC_MODE2_OVERFLOW
59 The IR receiver encountered an overflow, and as a result data is
60 missing (since Linux 5.18).
61 Reading input with the LIRC_MODE_SCANCODE mode
63 In the LIRC_MODE_SCANCODE mode, the data returned by read(2) reflects
64 decoded button presses, in the struct lirc_scancode. The scancode is
65 stored in the scancode field, and the IR protocol is stored in
66 rc_proto. This field has one the values of the enum rc_proto.
67 Writing output with the LIRC_MODE_PULSE mode
69 The data written to the character device using write(2) is a
70 pulse/space sequence of integer values. Pulses and spaces are only
71 marked implicitly by their position. The data must start and end with
72 a pulse, thus it must always include an odd number of samples. The
73 write(2) function blocks until the data has been transmitted by the
74 hardware. If more data is provided than the hardware can send, the
75 write(2) call fails with the error EINVAL.
76 Writing output with the LIRC_MODE_SCANCODE mode
78 The data written to the character devices must be a single struct
79 lirc_scancode. The scancode and rc_proto fields must filled in, all
80 other fields must be 0. The kernel IR encoders will convert the scan‐
81 code to pulses and spaces. The protocol or scancode is invalid, or the
82 lirc device cannot transmit.
83
85 #include <linux/lirc.h> /* But see BUGS */
86 int ioctl(int fd, int cmd, int *val);
88 The following ioctl(2) operations are provided by the lirc character
90 device to probe or change specific lirc hardware settings.
91 Always Supported Commands
93 /dev/lirc* devices always support the following commands:
94 LIRC_GET_FEATURES (void)
96 Returns a bit mask of combined features bits; see FEATURES.
97 If a device returns an error code for LIRC_GET_FEATURES, it is safe to
99 assume it is not a lirc device.
100 Optional Commands
102 Some lirc devices support the commands listed below. Unless otherwise
103 stated, these fail with the error ENOTTY if the operation isn't sup‐
104 ported, or with the error EINVAL if the operation failed, or invalid
105 arguments were provided. If a driver does not announce support of cer‐
106 tain features, invoking the corresponding ioctls will fail with the er‐
107 ror ENOTTY.
108 LIRC_GET_REC_MODE (void)
110 If the lirc device has no receiver, this operation fails with
111 the error ENOTTY. Otherwise, it returns the receive mode, which
112 will be one of:
113 LIRC_MODE_MODE2
115 The driver returns a sequence of pulse/space durations.
116 LIRC_MODE_SCANCODE
118 The driver returns struct lirc_scancode values, each of
119 which represents a decoded button press.
120 LIRC_SET_REC_MODE (int)
122 Set the receive mode. val is either LIRC_MODE_SCANCODE or
123 LIRC_MODE_MODE2. If the lirc device has no receiver, this oper‐
124 ation fails with the error ENOTTY.
125 LIRC_GET_SEND_MODE (void)
127 Return the send mode. LIRC_MODE_PULSE or LIRC_MODE_SCANCODE is
128 supported. If the lirc device cannot send, this operation fails
129 with the error ENOTTY.
130 LIRC_SET_SEND_MODE (int)
132 Set the send mode. val is either LIRC_MODE_SCANCODE or
133 LIRC_MODE_PULSE. If the lirc device cannot send, this operation
134 fails with the error ENOTTY.
135 LIRC_SET_SEND_CARRIER (int)
137 Set the modulation frequency. The argument is the frequency
138 (Hz).
139 LIRC_SET_SEND_DUTY_CYCLE (int)
141 Set the carrier duty cycle. val is a number in the range
142 [0,100] which describes the pulse width as a percentage of the
143 total cycle. Currently, no special meaning is defined for 0 or
144 100, but the values are reserved for future use.
145 LIRC_GET_MIN_TIMEOUT (void), LIRC_GET_MAX_TIMEOUT (void)
147 Some devices have internal timers that can be used to detect
148 when there has been no IR activity for a long time. This can
149 help lircd(8) in detecting that an IR signal is finished and can
150 speed up the decoding process. These operations return integer
151 values with the minimum/maximum timeout that can be set (mi‐
152 croseconds). Some devices have a fixed timeout. For such driv‐
153 ers, LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT will fail
154 with the error ENOTTY.
155 LIRC_SET_REC_TIMEOUT (int)
157 Set the integer value for IR inactivity timeout (microseconds).
158 To be accepted, the value must be within the limits defined by
159 LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT. A value of 0 (if
160 supported by the hardware) disables all hardware timeouts and
161 data should be reported as soon as possible. If the exact value
162 cannot be set, then the next possible value greater than the
163 given value should be set.
164 LIRC_GET_REC_TIMEOUT (void)
166 Return the current inactivity timeout (microseconds). Available
167 since Linux 4.18.
168 LIRC_SET_REC_TIMEOUT_REPORTS (int)
170 Enable (val is 1) or disable (val is 0) timeout packages in
171 LIRC_MODE_MODE2. The behavior of this operation has varied
172 across kernel versions:
173 • Since Linux 5.17: timeout packages are always enabled and
175 this ioctl is a no-op.
176 • Since Linux 4.16: timeout packages are enabled by default.
178 Each time the lirc device is opened, the LIRC_SET_REC_TIMEOUT
179 operation can be used to disable (and, if desired, to later
180 re-enable) the timeout on the file descriptor.
181 • In Linux 4.15 and earlier: timeout packages are disabled by
183 default, and enabling them (via LIRC_SET_REC_TIMEOUT) on any
184 file descriptor associated with the lirc device has the ef‐
185 fect of enabling timeouts for all file descriptors referring
186 to that device (until timeouts are disabled again).
187 LIRC_SET_REC_CARRIER (int)
189 Set the upper bound of the receive carrier frequency (Hz). See
190 LIRC_SET_REC_CARRIER_RANGE.
191 LIRC_SET_REC_CARRIER_RANGE (int)
193 Sets the lower bound of the receive carrier frequency (Hz). For
194 this to take affect, first set the lower bound using the
195 LIRC_SET_REC_CARRIER_RANGE ioctl, and then the upper bound using
196 the LIRC_SET_REC_CARRIER ioctl.
197 LIRC_SET_MEASURE_CARRIER_MODE (int)
199 Enable (val is 1) or disable (val is 0) the measure mode. If
200 enabled, from the next key press on, the driver will send
201 LIRC_MODE2_FREQUENCY packets. By default, this should be turned
202 off.
203 LIRC_GET_REC_RESOLUTION (void)
205 Return the driver resolution (microseconds).
206 LIRC_SET_TRANSMITTER_MASK (int)
208 Enable the set of transmitters specified in val, which contains
209 a bit mask where each enabled transmitter is a 1. The first
210 transmitter is encoded by the least significant bit, and so on.
211 When an invalid bit mask is given, for example a bit is set even
212 though the device does not have so many transmitters, this oper‐
213 ation returns the number of available transmitters and does
214 nothing otherwise.
215 LIRC_SET_WIDEBAND_RECEIVER (int)
217 Some devices are equipped with a special wide band receiver
218 which is intended to be used to learn the output of an existing
219 remote. This ioctl can be used to enable (val equals 1) or dis‐
220 able (val equals 0) this functionality. This might be useful
221 for devices that otherwise have narrow band receivers that pre‐
222 vent them to be used with certain remotes. Wide band receivers
223 may also be more precise. On the other hand, their disadvantage
224 usually is reduced range of reception.
225 Note: wide band receiver may be implicitly enabled if you enable
227 carrier reports. In that case, it will be disabled as soon as
228 you disable carrier reports. Trying to disable a wide band re‐
229 ceiver while carrier reports are active will do nothing.
230
232 the LIRC_GET_FEATURES ioctl returns a bit mask describing features of
233 the driver. The following bits may be returned in the mask:
234 LIRC_CAN_REC_MODE2
236 The driver is capable of receiving using LIRC_MODE_MODE2.
237 LIRC_CAN_REC_SCANCODE
239 The driver is capable of receiving using LIRC_MODE_SCANCODE.
240 LIRC_CAN_SET_SEND_CARRIER
242 The driver supports changing the modulation frequency using
243 LIRC_SET_SEND_CARRIER.
244 LIRC_CAN_SET_SEND_DUTY_CYCLE
246 The driver supports changing the duty cycle using
247 LIRC_SET_SEND_DUTY_CYCLE.
248 LIRC_CAN_SET_TRANSMITTER_MASK
250 The driver supports changing the active transmitter(s) using
251 LIRC_SET_TRANSMITTER_MASK.
252 LIRC_CAN_SET_REC_CARRIER
254 The driver supports setting the receive carrier frequency using
255 LIRC_SET_REC_CARRIER. Any lirc device since the drivers were
256 merged in Linux 2.6.36 must have LIRC_CAN_SET_REC_CARRIER_RANGE
257 set if LIRC_CAN_SET_REC_CARRIER feature is set.
258 LIRC_CAN_SET_REC_CARRIER_RANGE
260 The driver supports LIRC_SET_REC_CARRIER_RANGE. The lower bound
261 of the carrier must first be set using the LIRC_SET_REC_CAR‐
262 RIER_RANGE ioctl, before using the LIRC_SET_REC_CARRIER ioctl to
263 set the upper bound.
264 LIRC_CAN_GET_REC_RESOLUTION
266 The driver supports LIRC_GET_REC_RESOLUTION.
267 LIRC_CAN_SET_REC_TIMEOUT
269 The driver supports LIRC_SET_REC_TIMEOUT.
270 LIRC_CAN_MEASURE_CARRIER
272 The driver supports measuring of the modulation frequency using
273 LIRC_SET_MEASURE_CARRIER_MODE.
274 LIRC_CAN_USE_WIDEBAND_RECEIVER
276 The driver supports learning mode using LIRC_SET_WIDEBAND_RE‐
277 CEIVER.
278 LIRC_CAN_SEND_PULSE
280 The driver supports sending using LIRC_MODE_PULSE or
281 LIRC_MODE_SCANCODE
282
284 Using these devices requires the kernel source header file lirc.h.
285 This file is not available before Linux 4.6. Users of older kernels
286 could use the file bundled in ⟨http://www.lirc.org⟩.
287
289 ir-ctl(1), lircd(8), bpf(2)
290 ⟨https://www.kernel.org/doc/html/latest/userspace-api/media/rc/
292 lirc-dev.html⟩
293Linux man-pages 6.05 2023-05-03 lirc(4)