]>
Commit | Line | Data |
---|---|---|
f625b728 | 1 | .\" Copyright (c) 2015-2016, Alec Leamas |
a0d4d605 | 2 | .\" Copyright (c) 2018, Sean Young <sean@mess.org> |
422852de AL |
3 | .\" |
4 | .\" %%%LICENSE_START(GPLv2+_DOC_FULL) | |
5 | .\" This is free documentation; you can redistribute it and/or | |
6 | .\" modify it under the terms of the GNU General Public License as | |
7 | .\" published by the Free Software Foundation; either version 2 of | |
8 | .\" the License, or (at your option) any later version. | |
9 | .\" | |
10 | .\" The GNU General Public License's references to "object code" | |
11 | .\" and "executables" are to be interpreted as the output of any | |
12 | .\" document formatting or typesetting system, including | |
13 | .\" intermediate and printed output. | |
14 | .\" | |
15 | .\" This manual is distributed in the hope that it will be useful, | |
16 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
18 | .\" GNU General Public License for more details. | |
19 | .\" | |
20 | .\" You should have received a copy of the GNU General Public | |
21 | .\" License along with this manual; if not, see | |
22 | .\" <http://www.gnu.org/licenses/>. | |
23 | .\" %%%LICENSE_END | |
3df541c0 | 24 | .TH LIRC 4 2016-07-17 "Linux" "Linux Programmer's Manual" |
422852de AL |
25 | .SH NAME |
26 | lirc \- lirc devices | |
27 | .SH DESCRIPTION | |
11ac5b51 | 28 | .PP |
8c01f86f | 29 | The |
8e7e9720 | 30 | .I /dev/lirc* |
8c01f86f | 31 | character devices provide a low-level |
8e7e9720 MK |
32 | bidirectional interface to infra-red (IR) remotes. |
33 | Most of these devices can receive, and some can send. | |
e3f37bb8 SY |
34 | When receiving or sending data, the driver works in two different modes |
35 | depending on the underlying hardware. | |
11ac5b51 | 36 | .PP |
422852de | 37 | Some hardware (typically TV-cards) decodes the IR signal internally |
8e7e9720 MK |
38 | and provide decoded button presses as scancode values. |
39 | Drivers for this kind of hardware work in | |
a0d4d605 | 40 | .BR LIRC_MODE_SCANCODE |
8c01f86f | 41 | mode. |
422852de | 42 | Such hardware usually does not support sending IR signals. |
a0d4d605 SY |
43 | Furthermore, they can only decode a limited set of IR protocols, usually |
44 | only the protocol of the specific remote which is | |
422852de | 45 | bundled with, for example, a TV-card. |
11ac5b51 | 46 | .PP |
422852de AL |
47 | Other hardware provides a stream of pulse/space durations. |
48 | Such drivers work in | |
8c01f86f MK |
49 | .BR LIRC_MODE_MODE2 |
50 | mode. | |
422852de AL |
51 | Sometimes, this kind of hardware also supports |
52 | sending IR data. | |
8e7e9720 MK |
53 | Such hardware can be used with (almost) any kind of remote. |
54 | This type of hardware can also be used in | |
a0d4d605 | 55 | .BR LIRC_MODE_SCANCODE |
8e7e9720 MK |
56 | mode, in which case the kernel IR decoders will decode the IR. |
57 | These decoders can be written in | |
58 | .BR bpf (2) | |
59 | and attached to the | |
60 | .B lirc | |
61 | device. | |
11ac5b51 | 62 | .PP |
85e952c6 SY |
63 | The \fBLIRC_GET_FEATURES\fR ioctl (see below) allows probing for whether |
64 | receiving and sending is supported, and in which modes, amongst other | |
65 | features. | |
787dd4ad | 66 | .\" |
a0d4d605 | 67 | .SS Reading input with the LIRC_MODE_MODE2 mode |
11ac5b51 | 68 | .PP |
422852de AL |
69 | In the \fBLIRC_MODE_MODE2 mode\fR, the data returned by |
70 | .BR read (2) | |
a0d4d605 | 71 | provides 32-bit values representing a space or a pulse duration. |
8c01f86f | 72 | The time of the duration (microseconds) is encoded in the lower 24 bits. |
422852de AL |
73 | The upper 8 bit reflects the type of package: |
74 | .TP 4 | |
75 | .BR LIRC_MODE2_SPACE . | |
76 | Value reflects a space duration (microseconds). | |
77 | .TP 4 | |
78 | .BR LIRC_MODE2_PULSE . | |
79 | Value reflects a pulse duration (microseconds). | |
80 | .TP 4 | |
81 | .BR LIRC_MODE2_FREQUENCY . | |
8c01f86f | 82 | Value reflects a frequency (Hz); see the |
af4f61fa | 83 | .B LIRC_SET_MEASURE_CARRIER_MODE |
422852de AL |
84 | ioctl. |
85 | .TP 4 | |
86 | .BR LIRC_MODE2_TIMEOUT . | |
a0d4d605 | 87 | Value reflects a space duration (microseconds). |
8c01f86f | 88 | The package reflects a timeout; see the |
422852de AL |
89 | .B LIRC_SET_REC_TIMEOUT_REPORTS |
90 | ioctl. | |
787dd4ad | 91 | .\" |
a0d4d605 | 92 | .SS Reading input with the LIRC_MODE_SCANCODE mode |
11ac5b51 | 93 | .PP |
a0d4d605 | 94 | In the \fBLIRC_MODE_SCANCODE\fR |
422852de | 95 | mode, the data returned by |
8c01f86f | 96 | .BR read (2) |
8e7e9720 MK |
97 | reflects decoded button presses, in the struct \fIlirc_scancode\fR. |
98 | The scancode is stored in the \fIscancode\fR field, and the IR protocol | |
99 | in \fIrc_proto\fR. | |
100 | This field has on the values of the \fIenum rc_proto\fR. | |
787dd4ad | 101 | .\" |
a0d4d605 | 102 | .SS Writing output with the LIRC_MODE_PULSE mode |
11ac5b51 | 103 | .PP |
422852de | 104 | The data written to the character device using |
8c01f86f | 105 | .BR write (2) |
422852de AL |
106 | is a pulse/space sequence of integer values. |
107 | Pulses and spaces are only marked implicitly by their position. | |
108 | The data must start and end with a pulse, thus it must always include | |
109 | an odd number of samples. | |
110 | The | |
8c01f86f | 111 | .BR write (2) |
422852de AL |
112 | function blocks until the data has been transmitted by the |
113 | hardware. | |
114 | If more data is provided than the hardware can send, the | |
8c01f86f | 115 | .BR write (2) |
422852de AL |
116 | call fails with the error |
117 | .BR EINVAL | |
787dd4ad | 118 | .\" |
a0d4d605 SY |
119 | .SS Writing output with the LIRC_MODE_SCANCODE mode |
120 | .PP | |
121 | The data written to the character devices must be a single struct | |
8e7e9720 MK |
122 | \fIlirc_scancode\fR. |
123 | The \fIscancode\fR and \fIrc_proto\fR fields must | |
124 | filled in, all other fields must be 0. | |
125 | The kernel IR encoders will | |
a0d4d605 SY |
126 | convert the scancode to pulses and spaces. |
127 | .BR write (2) | |
128 | call fails with the error | |
129 | .BR EINVAL | |
8e7e9720 MK |
130 | The protocol or scancode is invalid, or the |
131 | .B lirc | |
132 | device cannot transmit. | |
f625b728 | 133 | .SH IOCTL COMMANDS |
11ac5b51 | 134 | .PP |
f625b728 AL |
135 | The complete list of ioctl commands is maintained in the kernel |
136 | documentation, see SEE ALSO. | |
2dcd3026 MK |
137 | The ioctl commands presented here is a subset of the kernel |
138 | documentation. | |
11ac5b51 | 139 | .PP |
f625b728 AL |
140 | The LIRC device's ioctl definition is bound by the ioctl function |
141 | definition of struct file_operations, leaving us with an unsigned | |
2dcd3026 MK |
142 | int for the ioctl command and an unsigned long for the argument. |
143 | For the purposes of ioctl portability across 32-bit and 64-bit architectures, | |
f625b728 | 144 | these values are capped to their 32-bit sizes. |
11ac5b51 | 145 | .PP |
422852de | 146 | .nf |
565301fc | 147 | #include <linux/lirc.h> /* But see BUGS */ |
422852de AL |
148 | int ioctl(int fd, int cmd, ...); |
149 | .fi | |
11ac5b51 | 150 | .PP |
8e7e9720 MK |
151 | The following ioctls can be used to probe or change specific |
152 | .B lirc | |
422852de AL |
153 | hardware settings. |
154 | Many require a third argument, usually an | |
155 | .IR int . | |
156 | referred to below as | |
8c01f86f | 157 | .IR val . |
11ac5b51 | 158 | .PP |
422852de AL |
159 | In general, each driver should have a default set of settings. |
160 | The driver implementation is expected to re-apply the default settings | |
6f858d5c | 161 | when the device is closed by user space, so that every application |
422852de AL |
162 | opening the device can rely on working with the default settings |
163 | initially. | |
787dd4ad | 164 | .\" |
422852de | 165 | .SS Always Supported Commands |
11ac5b51 | 166 | .PP |
422852de AL |
167 | \fI/dev/lirc*\fR devices always support the following commands: |
168 | .TP 4 | |
169 | .BR LIRC_GET_FEATURES " (\fIvoid\fP)" | |
8c01f86f | 170 | Returns a bit mask of combined features bits; see FEATURES. |
85e952c6 SY |
171 | .PP |
172 | If a device returns an error code for | |
173 | .BR LIRC_GET_FEATURES , | |
8e7e9720 MK |
174 | it is safe to assume it is not a |
175 | .B lirc | |
176 | device. | |
85e952c6 SY |
177 | .\" |
178 | .SS Optional Commands | |
179 | .PP | |
8e7e9720 MK |
180 | Some |
181 | .B lirc | |
182 | devices support commands listed below. | |
85e952c6 SY |
183 | Unless otherwise stated, these fail with the error \fBENOTTY\fR if the |
184 | operation isn't supported, or with the error \fBEINVAL\fR if the operation | |
185 | failed, or invalid arguments were provided. | |
f625b728 | 186 | If a driver does not announce support of certain features, calling of |
85e952c6 | 187 | the corresponding ioctls will return ENOTTY. |
422852de | 188 | .TP |
85e952c6 | 189 | .BR LIRC_GET_REC_MODE " (\fIvoid\fP)" |
89405cc0 | 190 | Return the receive mode, which will be one of: |
422852de AL |
191 | .RS 4 |
192 | .TP | |
85e952c6 | 193 | .BR LIRC_MODE_MODE2 |
89405cc0 | 194 | The driver returns a sequence of pulse/space durations. |
422852de | 195 | .TP |
a0d4d605 | 196 | .BR LIRC_MODE_SCANCODE |
8e7e9720 MK |
197 | The driver returns struct |
198 | .I lirc_scancode | |
199 | values, each of which represents | |
a0d4d605 | 200 | a decoded button press. |
422852de | 201 | .RE |
422852de AL |
202 | .TP |
203 | .BR LIRC_SET_REC_MODE " (\fIint\fP)" | |
204 | Set the receive mode. | |
205 | .IR val | |
206 | is either | |
a0d4d605 | 207 | .BR LIRC_MODE_SCANCODE |
422852de AL |
208 | or |
209 | .BR LIRC_MODE_MODE2 . | |
422852de | 210 | .TP |
422852de | 211 | .BR LIRC_GET_SEND_MODE " (\fIvoid\fP)" |
8c01f86f | 212 | Return the send mode. |
422852de | 213 | .BR LIRC_MODE_PULSE |
a0d4d605 SY |
214 | or |
215 | .BR LIRC_MODE_SCANCODE | |
422852de AL |
216 | is supported. |
217 | .TP | |
218 | .BR LIRC_SET_SEND_MODE " (\fIint\fP)" | |
219 | Set the send mode. | |
a0d4d605 SY |
220 | .IR val |
221 | is either | |
222 | .BR LIRC_MODE_SCANCODE | |
223 | or | |
224 | .BR LIRC_MODE_PULSE. | |
422852de AL |
225 | .TP |
226 | .BR LIRC_SET_SEND_CARRIER " (\fIint\fP)" | |
8c01f86f MK |
227 | Set the modulation frequency. |
228 | The argument is the frequency (Hz). | |
422852de | 229 | .TP |
7734ee11 | 230 | .BR LIRC_SET_SEND_DUTY_CYCLE " (\fIint\fP)" |
422852de | 231 | Set the carrier duty cycle. |
8c01f86f MK |
232 | .I val |
233 | is a number in the range [0,100] which | |
234 | describes the pulse width as a percentage of the total cycle. | |
422852de AL |
235 | Currently, no special meaning is defined for 0 or 100, but the values |
236 | are reserved for future use. | |
2dad4c59 | 237 | .IP |
422852de AL |
238 | .TP |
239 | .BR LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)", " "\ | |
240 | LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)" | |
241 | Some devices have internal timers that can be used to detect when | |
242 | there's no IR activity for a long time. | |
243 | This can help | |
8c01f86f | 244 | .BR lircd (8) |
422852de AL |
245 | in detecting that an IR signal is finished and can speed up the |
246 | decoding process. | |
8c01f86f MK |
247 | These operations |
248 | return integer values with the minimum/maximum timeout that can be | |
422852de | 249 | set (microseconds). |
8c01f86f MK |
250 | Some devices have a fixed timeout. |
251 | For such drivers, | |
422852de AL |
252 | .BR LIRC_GET_MIN_TIMEOUT |
253 | and | |
254 | .BR LIRC_GET_MAX_TIMEOUT | |
255 | will return the same value. | |
256 | .TP | |
257 | .BR LIRC_SET_REC_TIMEOUT " (\fIint\fP)" | |
89405cc0 | 258 | Set the integer value for IR inactivity timeout (microseconds). |
422852de AL |
259 | To be accepted, the value must be within the limits defined by |
260 | .BR LIRC_GET_MIN_TIMEOUT | |
261 | and | |
262 | .BR LIRC_GET_MAX_TIMEOUT . | |
263 | A value of 0 (if supported by the hardware) disables all hardware | |
264 | timeouts and data should be reported as soon as possible. | |
265 | If the exact value cannot be set, then the next possible value | |
266 | .I greater | |
267 | than the given value should be set. | |
268 | .TP | |
269 | .BR LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)" | |
89405cc0 | 270 | Enable |
422852de | 271 | .RI ( val |
89405cc0 | 272 | is 1) or disable |
8c01f86f | 273 | .RI ( val |
422852de AL |
274 | is 0) timeout packages in |
275 | .BR LIRC_MODE_MODE2 . | |
17f08f5e MK |
276 | The behavior of this operation has varied across kernel versions: |
277 | .RS | |
278 | .IP * 3 | |
279 | Since Linux 4.16: | |
280 | each time the | |
ae04ed07 SY |
281 | .BR lirc |
282 | device is opened, timeout reports are enabled for that | |
17f08f5e MK |
283 | file descriptor. |
284 | .IP * | |
285 | In Linux 4.15 and earlier: timeout reports were disabled by default, | |
286 | and enabling them had effect for | |
287 | .I all | |
ae04ed07 | 288 | .BR lirc |
17f08f5e MK |
289 | file descriptors until timeouts were disabled again. |
290 | .RE | |
422852de AL |
291 | .TP |
292 | .BR LIRC_SET_REC_CARRIER " (\fIint\fP)" | |
922819b8 MK |
293 | Set the upper bound of the receive carrier frequency (Hz). |
294 | See | |
29a18474 | 295 | .BR LIRC_SET_REC_CARRIER_RANGE . |
422852de | 296 | .TP |
422852de | 297 | .BR LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)" |
29a18474 | 298 | Sets the lower bound of the receive carrier frequency (Hz). |
922819b8 | 299 | For this to take affect, first set the lower bound using the |
29a18474 SY |
300 | .BR LIRC_SET_REC_CARRIER_RANGE |
301 | ioctl, and then the upper bound using the | |
302 | .BR LIRC_SET_REC_CARRIER | |
303 | ioctl. | |
422852de | 304 | .TP |
af4f61fa | 305 | .BR LIRC_SET_MEASURE_CARRIER_MODE " (\fIint\fP)" |
89405cc0 | 306 | Enable |
422852de | 307 | .RI ( val |
89405cc0 | 308 | is 1) or disable |
8c01f86f MK |
309 | .RI ( val |
310 | is 0) the measure mode. | |
422852de AL |
311 | If enabled, from the next key press on, the driver will send |
312 | .BR LIRC_MODE2_FREQUENCY | |
8c01f86f MK |
313 | packets. |
314 | By default this should be turned off. | |
422852de AL |
315 | .TP |
316 | .BR LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)" | |
89405cc0 | 317 | Return the driver resolution (microseconds). |
422852de | 318 | .TP |
422852de | 319 | .BR LIRC_SET_TRANSMITTER_MASK |
89405cc0 MK |
320 | Enable the set of transmitters specified in |
321 | .IR val , | |
322 | which contains a bit mask where each enabled transmitter is a 1. | |
8c01f86f | 323 | The first transmitter is encoded by the least significant bit, and so on. |
422852de | 324 | When an invalid bit mask is given, for example a bit is set even |
8c01f86f MK |
325 | though the device does not have so many transmitters, |
326 | this operation returns the | |
422852de AL |
327 | number of available transmitters and does nothing otherwise. |
328 | .TP | |
329 | .BR LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)" | |
8c01f86f | 330 | Some devices are equipped with a special wide band receiver which is |
422852de AL |
331 | intended to be used to learn the output of an existing remote. |
332 | This ioctl can be used to enable | |
333 | .RI ( val | |
334 | equals 1) or disable | |
335 | .RI ( val | |
336 | equals 0) this functionality. | |
337 | This might be useful for devices that otherwise have narrow band | |
338 | receivers that prevent them to be used with certain remotes. | |
339 | Wide band receivers may also be more precise. | |
340 | On the other hand its disadvantage usually is reduced range of | |
341 | reception. | |
342 | .IP | |
343 | Note: wide band receiver may be implicitly enabled if you enable | |
344 | carrier reports. | |
8c01f86f | 345 | In that case, it will be disabled as soon as you disable carrier reports. |
422852de AL |
346 | Trying to disable a wide band receiver while carrier reports are active |
347 | will do nothing. | |
787dd4ad | 348 | .\" |
422852de | 349 | .SH FEATURES |
11ac5b51 | 350 | .PP |
422852de | 351 | The features returned by |
8c01f86f | 352 | The |
422852de | 353 | .BR LIRC_GET_FEATURES |
8c01f86f MK |
354 | ioctl returns a bit mask describing features of the driver. |
355 | The following bits may be returned in the mask: | |
356 | .TP | |
422852de AL |
357 | .BR LIRC_CAN_REC_MODE2 |
358 | The driver is capable of receiving using | |
359 | .BR LIRC_MODE_MODE2 . | |
8c01f86f | 360 | .TP |
a0d4d605 | 361 | .BR LIRC_CAN_REC_SCANCODE |
422852de | 362 | The driver is capable of receiving using |
a0d4d605 | 363 | .BR LIRC_MODE_SCANCODE . |
8c01f86f | 364 | .TP |
422852de | 365 | .BR LIRC_CAN_SET_SEND_CARRIER |
8c01f86f | 366 | The driver supports changing the modulation frequency using |
422852de | 367 | .BR LIRC_SET_SEND_CARRIER . |
8c01f86f | 368 | .TP |
422852de | 369 | .BR LIRC_CAN_SET_SEND_DUTY_CYCLE |
8c01f86f | 370 | The driver supports changing the duty cycle using |
422852de | 371 | .BR LIRC_SET_SEND_DUTY_CYCLE . |
8c01f86f | 372 | .TP |
422852de | 373 | .BR LIRC_CAN_SET_TRANSMITTER_MASK |
8c01f86f | 374 | The driver supports changing the active transmitter(s) using |
422852de | 375 | .BR LIRC_SET_TRANSMITTER_MASK . |
8c01f86f | 376 | .TP |
422852de | 377 | .BR LIRC_CAN_SET_REC_CARRIER |
8c01f86f | 378 | The driver supports setting the receive carrier frequency using |
422852de | 379 | .BR LIRC_SET_REC_CARRIER . |
29a18474 SY |
380 | Any |
381 | .B lirc | |
382 | device since the drivers were merged in kernel release 2.6.36 | |
383 | must have | |
384 | .BR LIRC_CAN_SET_REC_CARRIER_RANGE | |
385 | set if | |
386 | .BR LIRC_CAN_SET_REC_CARRIER | |
387 | feature is set. | |
8c01f86f | 388 | .TP |
422852de | 389 | .BR LIRC_CAN_SET_REC_CARRIER_RANGE |
8c01f86f | 390 | The driver supports |
422852de | 391 | .BR LIRC_SET_REC_CARRIER_RANGE . |
29a18474 SY |
392 | The lower bound of the carrier must first be set using the |
393 | .BR LIRC_SET_REC_CARRIER_RANGE | |
922819b8 | 394 | ioctl, before using the |
29a18474 SY |
395 | .BR LIRC_SET_REC_CARRIER |
396 | ioctl to set the upper bound. | |
8c01f86f | 397 | .TP |
422852de | 398 | .BR LIRC_CAN_GET_REC_RESOLUTION |
8c01f86f | 399 | The driver supports |
422852de | 400 | .BR LIRC_GET_REC_RESOLUTION . |
8c01f86f | 401 | .TP |
422852de | 402 | .BR LIRC_CAN_SET_REC_TIMEOUT |
8c01f86f | 403 | The driver supports |
422852de | 404 | .BR LIRC_SET_REC_TIMEOUT . |
8c01f86f | 405 | .TP |
422852de | 406 | .BR LIRC_CAN_MEASURE_CARRIER |
8c01f86f | 407 | The driver supports measuring of the modulation frequency using |
af4f61fa | 408 | .BR LIRC_SET_MEASURE_CARRIER_MODE . |
8c01f86f | 409 | .TP |
422852de | 410 | .BR LIRC_CAN_USE_WIDEBAND_RECEIVER |
8c01f86f | 411 | The driver supports learning mode using |
422852de | 412 | .BR LIRC_SET_WIDEBAND_RECEIVER . |
8c01f86f | 413 | .TP |
422852de | 414 | .BR LIRC_CAN_SEND_PULSE |
8c01f86f | 415 | The driver supports sending using |
a0d4d605 SY |
416 | .BR LIRC_MODE_PULSE |
417 | or | |
418 | .BR LIRC_MODE_SCANCODE | |
787dd4ad | 419 | .\" |
422852de | 420 | .SH BUGS |
8c01f86f MK |
421 | Using these devices requires the kernel source header file |
422 | .IR lirc.h . | |
2dcd3026 MK |
423 | This file is not available before kernel release 4.6. |
424 | Users of older kernels could use the file bundled in | |
8c01f86f MK |
425 | .UR http://www.lirc.org |
426 | .UE . | |
787dd4ad | 427 | .\" |
422852de | 428 | .SH SEE ALSO |
e5f0504c | 429 | \fBir\-ctl\fP(1), \fBlircd\fP(8),\ \fBbpf\fP(2) |
11ac5b51 | 430 | .PP |
50a8a7f4 | 431 | https://www.kernel.org/doc/html/latest/media/uapi/rc/lirc-dev.html |