1LIRC(4) Linux Programmer's Manual LIRC(4)
2
6 lirc - lirc devices
7
9 The /dev/lirc* character devices provide a low-level bi-directional
10 interface to infra-red (IR) remotes. When receiving data, the driver
11 works in two different modes depending on the underlying hardware.
12 Some hardware (typically TV-cards) decodes the IR signal internally and
14 just provides decoded button presses as integer values. Drivers for
15 this kind of hardware work in LIRC_MODE_LIRCCODE mode. Such hardware
16 usually does not support sending IR signals. Furthermore, it usually
17 only works with a specific remote which is bundled with, for example, a
18 TV-card.
19 Other hardware provides a stream of pulse/space durations. Such driv‐
21 ers work in LIRC_MODE_MODE2 mode. Sometimes, this kind of hardware
22 also supports sending IR data. Such hardware can be used with (almost)
23 any kind of remote.
24 The LIRC_GET_REC_MODE ioctl (see below) allows probing for the mode.
26 Reading input with the LIRC_MODE_MODE2 drivers
28 In the LIRC_MODE_MODE2 mode, the data returned by read(2) provides
29 32-bit values representing a space or a pulse duration, by convention
30 typed as lirc_t. The time of the duration (microseconds) is encoded in
31 the lower 24 bits. The upper 8 bit reflects the type of package:
32 LIRC_MODE2_SPACE.
34 Value reflects a space duration (microseconds).
35 LIRC_MODE2_PULSE.
37 Value reflects a pulse duration (microseconds).
38 LIRC_MODE2_FREQUENCY.
40 Value reflects a frequency (Hz); see the LIRC_SET_MEASURE_CAR‐
41 RIER_MODE ioctl.
42 LIRC_MODE2_TIMEOUT.
44 The package reflects a timeout; see the LIRC_SET_REC_TIME‐
45 OUT_REPORTS ioctl.
46 Reading input with the
48 LIRC_MODE_LIRCCODE drivers
49 In the LIRC_MODE_LIRCCODE mode, the data returned by read(2) reflects
51 decoded button presses. The length of each packet can be retrieved
52 using the LIRC_GET_LENGTH ioctl. Reads must be done in blocks matching
53 the bit count returned by the LIRC_GET_LENGTH ioctl, rounded up so it
54 matches full bytes.
55 Sending data
57 When sending data, only the LIRC_MODE_PULSE mode is supported. The
58 data written to the character device using write(2) is a pulse/space
59 sequence of integer values. Pulses and spaces are only marked implic‐
60 itly by their position. The data must start and end with a pulse, thus
61 it must always include an odd number of samples. The write(2) function
62 blocks until the data has been transmitted by the hardware. If more
63 data is provided than the hardware can send, the write(2) call fails
64 with the error EINVAL
65
67 The complete list of ioctl commands is maintained in the kernel docu‐
68 mentation, see SEE ALSO. The ioctl commands presented here is a subset
69 of the kernel documentation.
70 The LIRC device's ioctl definition is bound by the ioctl function defi‐
72 nition of struct file_operations, leaving us with an unsigned int for
73 the ioctl command and an unsigned long for the argument. For the pur‐
74 poses of ioctl portability across 32-bit and 64-bit architectures,
75 these values are capped to their 32-bit sizes.
76 #include <lirc/include/media/lirc.h> /* But see BUGS */
78 int ioctl(int fd, int cmd, ...);
79 The following ioctls can be used to probe or change specific lirc hard‐
81 ware settings. Many require a third argument, usually an int.
82 referred to below as val.
83 In general, each driver should have a default set of settings. The
85 driver implementation is expected to re-apply the default settings when
86 the device is closed by user space, so that every application opening
87 the device can rely on working with the default settings initially.
88 Always Supported Commands
90 /dev/lirc* devices always support the following commands:
91 LIRC_GET_FEATURES (void)
93 Returns a bit mask of combined features bits; see FEATURES. Some
94 drivers have dynamic features which are not updated until after an
95 init() command. If a driver does not announce support of certain
96 features, calling of the corresponding ioctls is undefined.
97 LIRC_GET_REC_MODE
99 Return the receive mode, which will be one of:
100 LIRC_MODE_MODE2 (void)
102 The driver returns a sequence of pulse/space durations.
103 LIRC_MODE_LIRCCODE
105 The driver returns integer values, each of which represents
106 a decoded button press.
107 If a device returns an error code for LIRC_GET_REC_MODE, it is safe to
109 assume it is not a lirc device.
110 Optional Commands
112 Some lirc devices support commands listed below. Unless otherwise
113 stated, these fail with the error ENOIOCTLCMD or with the error ENOSYS
114 if the operation isn't supported, or with the error EINVAL if the oper‐
115 ation failed.
116 LIRC_SET_REC_MODE (int)
118 Set the receive mode. val is either LIRC_MODE_LIRCCODE or
119 LIRC_MODE_MODE2.
120 LIRC_GET_LENGTH (void)
122 Return the length of the returned codes for LIRC_MODE_LIRCCODE-
123 type drivers, otherwise fail with the error ENOIOCTLCMD.
124 LIRC_GET_SEND_MODE (void)
126 Return the send mode. Currently, only LIRC_MODE_PULSE is sup‐
127 ported.
128 LIRC_SET_SEND_MODE (int)
130 Set the send mode. Currently serves no purpose since only
131 LIRC_MODE_PULSE is supported.
132 LIRC_GET_SEND_CARRIER (void)
134 Get the modulation frequency (Hz).
135 LIRC_SET_SEND_CARRIER (int)
137 Set the modulation frequency. The argument is the frequency
138 (Hz).
139 LIRC_GET_SEND_CARRIER (void)
141 Get the modulation frequency used when decoding (Hz).
142 SET_SEND_DUTY_CYCLE (int)
144 Set the carrier duty cycle. val is a number in the range
145 [0,100] which describes the pulse width as a percentage of the
146 total cycle. Currently, no special meaning is defined for 0 or
147 100, but the values are reserved for future use.
148 LIRC_GET_MIN_TIMEOUT (void), LIRC_GET_MAX_TIMEOUT (void)
150 Some devices have internal timers that can be used to detect
151 when there's no IR activity for a long time. This can help
152 lircd(8) in detecting that an IR signal is finished and can
153 speed up the decoding process. These operations return integer
154 values with the minimum/maximum timeout that can be set
155 (microseconds). Some devices have a fixed timeout. For such
156 drivers, LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT will
157 return the same value.
158 LIRC_SET_REC_TIMEOUT (int)
160 Set the integer value for IR inactivity timeout (microseconds).
161 To be accepted, the value must be within the limits defined by
162 LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT. A value of 0 (if
163 supported by the hardware) disables all hardware timeouts and
164 data should be reported as soon as possible. If the exact value
165 cannot be set, then the next possible value greater than the
166 given value should be set.
167 LIRC_SET_REC_TIMEOUT_REPORTS (int)
169 Enable (val is 1) or disable (val is 0) timeout packages in
170 LIRC_MODE_MODE2. By default, timeout reports should be turned
171 off.
172 LIRC_SET_REC_CARRIER (int)
174 Set the receive carrier frequency (Hz).
175 LIRC_SET_REC_CARRIER_RANGE (int)
177 After opening device, the first use of this operation sets the
178 lower bound of the carrier range, and the second use sets the
179 upper bound (Hz).
180 LIRC_SET_MEASURE_CARRIER_MODE (int)
182 Enable (val is 1) or disable (val is 0) the measure mode. If
183 enabled, from the next key press on, the driver will send
184 LIRC_MODE2_FREQUENCY packets. By default this should be turned
185 off.
186 LIRC_GET_REC_RESOLUTION (void)
188 Return the driver resolution (microseconds).
189 LIRC_GET_MIN_FILTER_PULSE (void), LIRC_GET_MAX_FILTER_PULSE (void)
191 Some devices are able to filter out spikes in the incoming sig‐
192 nal using given filter rules. These ioctls return the hardware
193 capabilities that describe the bounds of the possible filters.
194 Filter settings depend on the IR protocols that are expected.
195 lircd(8) derives the settings from all protocols definitions
196 found in its lircd.conf(5) config file.
197 LIRC_GET_MIN_FILTER_SPACE (void), LIRC_GET_MAX_FILTER_SPACE (void)
199 See LIRC_GET_MIN_FILTER_PULSE.
200 LIRC_SET_REC_FILTER (int)
202 Pulses/spaces shorter than this (microseconds) are filtered out
203 by hardware.
204 LIRC_SET_REC_FILTER_PULSE (int), LIRC_SET_REC_FILTER_SPACE (int)
206 Pulses/spaces shorter than this (microseconds) are filtered out
207 by hardware. If filters cannot be set independently for
208 pulse/space, the corresponding ioctls must return an error and
209 LIRC_SET_REC_FILTER should be used instead.
210 LIRC_SET_TRANSMITTER_MASK
212 Enable the set of transmitters specified in val, which contains
213 a bit mask where each enabled transmitter is a 1. The first
214 transmitter is encoded by the least significant bit, and so on.
215 When an invalid bit mask is given, for example a bit is set even
216 though the device does not have so many transmitters, this oper‐
217 ation returns the number of available transmitters and does
218 nothing otherwise.
219 LIRC_SET_WIDEBAND_RECEIVER (int)
221 Some devices are equipped with a special wide band receiver
222 which is intended to be used to learn the output of an existing
223 remote. This ioctl can be used to enable (val equals 1) or dis‐
224 able (val equals 0) this functionality. This might be useful
225 for devices that otherwise have narrow band receivers that pre‐
226 vent them to be used with certain remotes. Wide band receivers
227 may also be more precise. On the other hand its disadvantage
228 usually is reduced range of reception.
229 Note: wide band receiver may be implicitly enabled if you enable
231 carrier reports. In that case, it will be disabled as soon as
232 you disable carrier reports. Trying to disable a wide band
233 receiver while carrier reports are active will do nothing.
234 LIRC_SETUP_START (void), LIRC_SETUP_END (void)
236 Setting of several driver parameters can be optimized by brack‐
237 eting the actual ioctl calls LIRC_SETUP_START and LIRC_SET‐
238 UP_END. When a driver receives a LIRC_SETUP_START ioctl, it can
239 choose to not commit further setting changes to the hardware
240 until a LIRC_SETUP_END is received. But this is open to the
241 driver implementation and every driver must also handle parame‐
242 ter changes which are not encapsulated by LIRC_SETUP_START and
243 LIRC_SETUP_END. Drivers can also choose to ignore these ioctls.
244 LIRC_NOTIFY_DECODE (void)
246 This ioctl is called by lircd(8) whenever a successful decoding
247 of an incoming IR signal is possible. This can be used by sup‐
248 porting hardware to give visual user feedback, for example by
249 flashing an LED.
250
252 The features returned by The LIRC_GET_FEATURES ioctl returns a bit mask
253 describing features of the driver. The following bits may be returned
254 in the mask:
255 LIRC_CAN_REC_RAW
257 The driver is capable of receiving using LIRC_MODE_RAW.
258 LIRC_CAN_REC_PULSE
260 The driver is capable of receiving using LIRC_MODE_PULSE.
261 LIRC_CAN_REC_MODE2
263 The driver is capable of receiving using LIRC_MODE_MODE2.
264 LIRC_CAN_REC_LIRCCODE
266 The driver is capable of receiving using LIRC_MODE_LIRCCODE.
267 LIRC_CAN_SET_SEND_CARRIER
269 The driver supports changing the modulation frequency using
270 LIRC_SET_SEND_CARRIER.
271 LIRC_CAN_SET_SEND_DUTY_CYCLE
273 The driver supports changing the duty cycle using
274 LIRC_SET_SEND_DUTY_CYCLE.
275 LIRC_CAN_SET_TRANSMITTER_MASK
277 The driver supports changing the active transmitter(s) using
278 LIRC_SET_TRANSMITTER_MASK.
279 LIRC_CAN_SET_REC_CARRIER
281 The driver supports setting the receive carrier frequency using
282 LIRC_SET_REC_CARRIER.
283 LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE
285 The driver supports LIRC_SET_REC_DUTY_CYCLE_RANGE.
286 LIRC_CAN_SET_REC_CARRIER_RANGE
288 The driver supports LIRC_SET_REC_CARRIER_RANGE.
289 LIRC_CAN_GET_REC_RESOLUTION
291 The driver supports LIRC_GET_REC_RESOLUTION.
292 LIRC_CAN_SET_REC_TIMEOUT
294 The driver supports LIRC_SET_REC_TIMEOUT.
295 LIRC_CAN_SET_REC_FILTER
297 The driver supports LIRC_SET_REC_FILTER.
298 LIRC_CAN_MEASURE_CARRIER
300 The driver supports measuring of the modulation frequency using
301 LIRC_SET_MEASURE_CARRIER_MODE.
302 LIRC_CAN_USE_WIDEBAND_RECEIVER
304 The driver supports learning mode using LIRC_SET_WIDE‐
305 BAND_RECEIVER.
306 LIRC_CAN_NOTIFY_DECODE
308 The driver supports LIRC_NOTIFY_DECODE.
309 LIRC_CAN_SEND_RAW
311 The driver supports sending using LIRC_MODE_RAW.
312 LIRC_CAN_SEND_PULSE
314 The driver supports sending using LIRC_MODE_PULSE.
315 LIRC_CAN_SEND_MODE2
317 The driver supports sending using LIRC_MODE_MODE2.
318 LIRC_CAN_SEND_LIRCCODE
320 The driver supports sending. (This is uncommon, since LIRCCODE
321 drivers reflect hardware like TV-cards which usually dos not
322 support sending.)
323
325 Using these devices requires the kernel source header file lirc.h.
326 This file is not available before kernel release 4.6. Users of older
327 kernels could use the file bundled in ⟨http://www.lirc.org⟩.
328
330 lircd(8)
331 https://www.kernel.org/doc/htmldocs/media_api/lirc_dev.html
333
335 This page is part of release 4.15 of the Linux man-pages project. A
336 description of the project, information about reporting bugs, and the
337 latest version of this page, can be found at
338 https://www.kernel.org/doc/man-pages/.
339Linux 2016-07-17 LIRC(4)