]>
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 |
f3c3a5c4 | 38 | and provides decoded button presses as scancode values. |
8e7e9720 | 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. |
f3c3a5c4 MK |
43 | Furthermore, such hardware can only decode a limited set of IR protocols, |
44 | usually 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 | 56 | mode, in which case the kernel IR decoders will decode the IR. |
99a9a45f MK |
57 | These decoders can be written in extended BPF (see |
58 | .BR bpf (2)) | |
8e7e9720 MK |
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. |
f3c3a5c4 | 73 | The upper 8 bits indicate the type of package: |
422852de | 74 | .TP 4 |
f3c3a5c4 | 75 | .BR LIRC_MODE2_SPACE |
422852de AL |
76 | Value reflects a space duration (microseconds). |
77 | .TP 4 | |
f3c3a5c4 | 78 | .BR LIRC_MODE2_PULSE |
422852de AL |
79 | Value reflects a pulse duration (microseconds). |
80 | .TP 4 | |
f3c3a5c4 | 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 | |
f3c3a5c4 | 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 | |
f3c3a5c4 | 99 | is stored in \fIrc_proto\fR. |
aef83b60 | 100 | This field has one 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 | 116 | call fails with the error |
aef83b60 | 117 | .BR EINVAL . |
a0d4d605 SY |
118 | .SS Writing output with the LIRC_MODE_SCANCODE mode |
119 | .PP | |
120 | The data written to the character devices must be a single struct | |
8e7e9720 MK |
121 | \fIlirc_scancode\fR. |
122 | The \fIscancode\fR and \fIrc_proto\fR fields must | |
123 | filled in, all other fields must be 0. | |
124 | The kernel IR encoders will | |
a0d4d605 SY |
125 | convert the scancode to pulses and spaces. |
126 | .BR write (2) | |
127 | call fails with the error | |
128 | .BR EINVAL | |
8e7e9720 MK |
129 | The protocol or scancode is invalid, or the |
130 | .B lirc | |
131 | device cannot transmit. | |
f625b728 | 132 | .SH IOCTL COMMANDS |
11ac5b51 | 133 | .PP |
f625b728 | 134 | The LIRC device's ioctl definition is bound by the ioctl function |
f3c3a5c4 MK |
135 | definition of |
136 | .IR "struct file_operations" , | |
137 | leaving us with an | |
138 | .IR "unsigned int" | |
139 | for the ioctl command and an | |
140 | .IR "unsigned long" | |
141 | for the argument. | |
2dcd3026 | 142 | For the purposes of ioctl portability across 32-bit and 64-bit architectures, |
f625b728 | 143 | these values are capped to their 32-bit sizes. |
11ac5b51 | 144 | .PP |
422852de | 145 | .nf |
565301fc | 146 | #include <linux/lirc.h> /* But see BUGS */ |
422852de AL |
147 | int ioctl(int fd, int cmd, ...); |
148 | .fi | |
11ac5b51 | 149 | .PP |
8e7e9720 MK |
150 | The following ioctls can be used to probe or change specific |
151 | .B lirc | |
422852de AL |
152 | hardware settings. |
153 | Many require a third argument, usually an | |
154 | .IR int . | |
155 | referred to below as | |
8c01f86f | 156 | .IR val . |
787dd4ad | 157 | .\" |
422852de | 158 | .SS Always Supported Commands |
11ac5b51 | 159 | .PP |
422852de AL |
160 | \fI/dev/lirc*\fR devices always support the following commands: |
161 | .TP 4 | |
162 | .BR LIRC_GET_FEATURES " (\fIvoid\fP)" | |
8c01f86f | 163 | Returns a bit mask of combined features bits; see FEATURES. |
85e952c6 SY |
164 | .PP |
165 | If a device returns an error code for | |
166 | .BR LIRC_GET_FEATURES , | |
8e7e9720 MK |
167 | it is safe to assume it is not a |
168 | .B lirc | |
169 | device. | |
85e952c6 SY |
170 | .\" |
171 | .SS Optional Commands | |
172 | .PP | |
8e7e9720 MK |
173 | Some |
174 | .B lirc | |
264a16db | 175 | devices support the commands listed below. |
85e952c6 SY |
176 | Unless otherwise stated, these fail with the error \fBENOTTY\fR if the |
177 | operation isn't supported, or with the error \fBEINVAL\fR if the operation | |
178 | failed, or invalid arguments were provided. | |
f3c3a5c4 MK |
179 | If a driver does not announce support of certain features, invoking |
180 | the corresponding ioctls will fail with the error | |
181 | .BR ENOTTY . | |
422852de | 182 | .TP |
85e952c6 | 183 | .BR LIRC_GET_REC_MODE " (\fIvoid\fP)" |
51169955 SY |
184 | If the |
185 | .B lirc | |
186 | device has no receiver return | |
187 | .B ENOTTY, | |
188 | else return the receive mode, which will be one of: | |
f3c3a5c4 | 189 | .RS |
422852de | 190 | .TP |
85e952c6 | 191 | .BR LIRC_MODE_MODE2 |
89405cc0 | 192 | The driver returns a sequence of pulse/space durations. |
422852de | 193 | .TP |
a0d4d605 | 194 | .BR LIRC_MODE_SCANCODE |
8e7e9720 MK |
195 | The driver returns struct |
196 | .I lirc_scancode | |
197 | values, each of which represents | |
a0d4d605 | 198 | a decoded button press. |
422852de | 199 | .RE |
422852de AL |
200 | .TP |
201 | .BR LIRC_SET_REC_MODE " (\fIint\fP)" | |
202 | Set the receive mode. | |
203 | .IR val | |
204 | is either | |
a0d4d605 | 205 | .BR LIRC_MODE_SCANCODE |
422852de AL |
206 | or |
207 | .BR LIRC_MODE_MODE2 . | |
51169955 SY |
208 | If the |
209 | .B lirc | |
210 | device has no receiver, return | |
211 | .B ENOTTY. | |
422852de | 212 | .TP |
422852de | 213 | .BR LIRC_GET_SEND_MODE " (\fIvoid\fP)" |
8c01f86f | 214 | Return the send mode. |
422852de | 215 | .BR LIRC_MODE_PULSE |
a0d4d605 SY |
216 | or |
217 | .BR LIRC_MODE_SCANCODE | |
422852de | 218 | is supported. |
51169955 SY |
219 | If the |
220 | .B lirc | |
221 | device cannot send, return | |
222 | .B ENOTTY. | |
422852de AL |
223 | .TP |
224 | .BR LIRC_SET_SEND_MODE " (\fIint\fP)" | |
225 | Set the send mode. | |
a0d4d605 SY |
226 | .IR val |
227 | is either | |
228 | .BR LIRC_MODE_SCANCODE | |
229 | or | |
51169955 SY |
230 | .BR LIRC_MODE_PULSE . |
231 | If the | |
232 | .B lirc | |
233 | device cannot send, return | |
234 | .B ENOTTY | |
235 | . | |
422852de AL |
236 | .TP |
237 | .BR LIRC_SET_SEND_CARRIER " (\fIint\fP)" | |
8c01f86f MK |
238 | Set the modulation frequency. |
239 | The argument is the frequency (Hz). | |
422852de | 240 | .TP |
7734ee11 | 241 | .BR LIRC_SET_SEND_DUTY_CYCLE " (\fIint\fP)" |
422852de | 242 | Set the carrier duty cycle. |
8c01f86f MK |
243 | .I val |
244 | is a number in the range [0,100] which | |
245 | describes the pulse width as a percentage of the total cycle. | |
422852de AL |
246 | Currently, no special meaning is defined for 0 or 100, but the values |
247 | are reserved for future use. | |
2dad4c59 | 248 | .IP |
422852de AL |
249 | .TP |
250 | .BR LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)", " "\ | |
251 | LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)" | |
252 | Some devices have internal timers that can be used to detect when | |
f3c3a5c4 | 253 | there has been no IR activity for a long time. |
422852de | 254 | This can help |
8c01f86f | 255 | .BR lircd (8) |
422852de AL |
256 | in detecting that an IR signal is finished and can speed up the |
257 | decoding process. | |
8c01f86f MK |
258 | These operations |
259 | return integer values with the minimum/maximum timeout that can be | |
422852de | 260 | set (microseconds). |
8c01f86f MK |
261 | Some devices have a fixed timeout. |
262 | For such drivers, | |
422852de AL |
263 | .BR LIRC_GET_MIN_TIMEOUT |
264 | and | |
265 | .BR LIRC_GET_MAX_TIMEOUT | |
51169955 SY |
266 | will return |
267 | .BR ENOTTY . | |
422852de AL |
268 | .TP |
269 | .BR LIRC_SET_REC_TIMEOUT " (\fIint\fP)" | |
89405cc0 | 270 | Set the integer value for IR inactivity timeout (microseconds). |
422852de AL |
271 | To be accepted, the value must be within the limits defined by |
272 | .BR LIRC_GET_MIN_TIMEOUT | |
273 | and | |
274 | .BR LIRC_GET_MAX_TIMEOUT . | |
275 | A value of 0 (if supported by the hardware) disables all hardware | |
276 | timeouts and data should be reported as soon as possible. | |
277 | If the exact value cannot be set, then the next possible value | |
278 | .I greater | |
279 | than the given value should be set. | |
280 | .TP | |
a1e1ac25 SY |
281 | .BR LIRC_GET_REC_TIMEOUT " (\fivoid\fP)" |
282 | Return the current inactivity timeout (microseconds). | |
f3c3a5c4 | 283 | Available since Linux 4.18. |
a1e1ac25 | 284 | .TP |
422852de | 285 | .BR LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)" |
89405cc0 | 286 | Enable |
422852de | 287 | .RI ( val |
89405cc0 | 288 | is 1) or disable |
8c01f86f | 289 | .RI ( val |
422852de AL |
290 | is 0) timeout packages in |
291 | .BR LIRC_MODE_MODE2 . | |
17f08f5e MK |
292 | The behavior of this operation has varied across kernel versions: |
293 | .RS | |
294 | .IP * 3 | |
295 | Since Linux 4.16: | |
296 | each time the | |
ae04ed07 SY |
297 | .BR lirc |
298 | device is opened, timeout reports are enabled for that | |
17f08f5e MK |
299 | file descriptor. |
300 | .IP * | |
301 | In Linux 4.15 and earlier: timeout reports were disabled by default, | |
302 | and enabling them had effect for | |
303 | .I all | |
ae04ed07 | 304 | .BR lirc |
17f08f5e MK |
305 | file descriptors until timeouts were disabled again. |
306 | .RE | |
422852de AL |
307 | .TP |
308 | .BR LIRC_SET_REC_CARRIER " (\fIint\fP)" | |
922819b8 MK |
309 | Set the upper bound of the receive carrier frequency (Hz). |
310 | See | |
29a18474 | 311 | .BR LIRC_SET_REC_CARRIER_RANGE . |
422852de | 312 | .TP |
422852de | 313 | .BR LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)" |
29a18474 | 314 | Sets the lower bound of the receive carrier frequency (Hz). |
922819b8 | 315 | For this to take affect, first set the lower bound using the |
29a18474 SY |
316 | .BR LIRC_SET_REC_CARRIER_RANGE |
317 | ioctl, and then the upper bound using the | |
318 | .BR LIRC_SET_REC_CARRIER | |
319 | ioctl. | |
422852de | 320 | .TP |
af4f61fa | 321 | .BR LIRC_SET_MEASURE_CARRIER_MODE " (\fIint\fP)" |
89405cc0 | 322 | Enable |
422852de | 323 | .RI ( val |
89405cc0 | 324 | is 1) or disable |
8c01f86f MK |
325 | .RI ( val |
326 | is 0) the measure mode. | |
422852de AL |
327 | If enabled, from the next key press on, the driver will send |
328 | .BR LIRC_MODE2_FREQUENCY | |
8c01f86f | 329 | packets. |
f3c3a5c4 | 330 | By default, this should be turned off. |
422852de AL |
331 | .TP |
332 | .BR LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)" | |
89405cc0 | 333 | Return the driver resolution (microseconds). |
422852de | 334 | .TP |
a1e1ac25 | 335 | .BR LIRC_SET_TRANSMITTER_MASK " (\fIint\fP)" |
89405cc0 MK |
336 | Enable the set of transmitters specified in |
337 | .IR val , | |
338 | which contains a bit mask where each enabled transmitter is a 1. | |
8c01f86f | 339 | The first transmitter is encoded by the least significant bit, and so on. |
422852de | 340 | When an invalid bit mask is given, for example a bit is set even |
8c01f86f MK |
341 | though the device does not have so many transmitters, |
342 | this operation returns the | |
422852de AL |
343 | number of available transmitters and does nothing otherwise. |
344 | .TP | |
345 | .BR LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)" | |
8c01f86f | 346 | Some devices are equipped with a special wide band receiver which is |
422852de AL |
347 | intended to be used to learn the output of an existing remote. |
348 | This ioctl can be used to enable | |
349 | .RI ( val | |
350 | equals 1) or disable | |
351 | .RI ( val | |
352 | equals 0) this functionality. | |
353 | This might be useful for devices that otherwise have narrow band | |
354 | receivers that prevent them to be used with certain remotes. | |
355 | Wide band receivers may also be more precise. | |
f3c3a5c4 | 356 | On the other hand, their disadvantage usually is reduced range of |
422852de AL |
357 | reception. |
358 | .IP | |
359 | Note: wide band receiver may be implicitly enabled if you enable | |
360 | carrier reports. | |
8c01f86f | 361 | In that case, it will be disabled as soon as you disable carrier reports. |
422852de AL |
362 | Trying to disable a wide band receiver while carrier reports are active |
363 | will do nothing. | |
787dd4ad | 364 | .\" |
422852de | 365 | .SH FEATURES |
11ac5b51 | 366 | .PP |
f3c3a5c4 | 367 | the |
422852de | 368 | .BR LIRC_GET_FEATURES |
8c01f86f MK |
369 | ioctl returns a bit mask describing features of the driver. |
370 | The following bits may be returned in the mask: | |
371 | .TP | |
422852de AL |
372 | .BR LIRC_CAN_REC_MODE2 |
373 | The driver is capable of receiving using | |
374 | .BR LIRC_MODE_MODE2 . | |
8c01f86f | 375 | .TP |
a0d4d605 | 376 | .BR LIRC_CAN_REC_SCANCODE |
422852de | 377 | The driver is capable of receiving using |
a0d4d605 | 378 | .BR LIRC_MODE_SCANCODE . |
8c01f86f | 379 | .TP |
422852de | 380 | .BR LIRC_CAN_SET_SEND_CARRIER |
8c01f86f | 381 | The driver supports changing the modulation frequency using |
422852de | 382 | .BR LIRC_SET_SEND_CARRIER . |
8c01f86f | 383 | .TP |
422852de | 384 | .BR LIRC_CAN_SET_SEND_DUTY_CYCLE |
8c01f86f | 385 | The driver supports changing the duty cycle using |
422852de | 386 | .BR LIRC_SET_SEND_DUTY_CYCLE . |
8c01f86f | 387 | .TP |
422852de | 388 | .BR LIRC_CAN_SET_TRANSMITTER_MASK |
8c01f86f | 389 | The driver supports changing the active transmitter(s) using |
422852de | 390 | .BR LIRC_SET_TRANSMITTER_MASK . |
8c01f86f | 391 | .TP |
422852de | 392 | .BR LIRC_CAN_SET_REC_CARRIER |
8c01f86f | 393 | The driver supports setting the receive carrier frequency using |
422852de | 394 | .BR LIRC_SET_REC_CARRIER . |
29a18474 SY |
395 | Any |
396 | .B lirc | |
397 | device since the drivers were merged in kernel release 2.6.36 | |
398 | must have | |
399 | .BR LIRC_CAN_SET_REC_CARRIER_RANGE | |
400 | set if | |
401 | .BR LIRC_CAN_SET_REC_CARRIER | |
402 | feature is set. | |
8c01f86f | 403 | .TP |
422852de | 404 | .BR LIRC_CAN_SET_REC_CARRIER_RANGE |
8c01f86f | 405 | The driver supports |
422852de | 406 | .BR LIRC_SET_REC_CARRIER_RANGE . |
29a18474 SY |
407 | The lower bound of the carrier must first be set using the |
408 | .BR LIRC_SET_REC_CARRIER_RANGE | |
922819b8 | 409 | ioctl, before using the |
29a18474 SY |
410 | .BR LIRC_SET_REC_CARRIER |
411 | ioctl to set the upper bound. | |
8c01f86f | 412 | .TP |
422852de | 413 | .BR LIRC_CAN_GET_REC_RESOLUTION |
8c01f86f | 414 | The driver supports |
422852de | 415 | .BR LIRC_GET_REC_RESOLUTION . |
8c01f86f | 416 | .TP |
422852de | 417 | .BR LIRC_CAN_SET_REC_TIMEOUT |
8c01f86f | 418 | The driver supports |
422852de | 419 | .BR LIRC_SET_REC_TIMEOUT . |
8c01f86f | 420 | .TP |
422852de | 421 | .BR LIRC_CAN_MEASURE_CARRIER |
8c01f86f | 422 | The driver supports measuring of the modulation frequency using |
af4f61fa | 423 | .BR LIRC_SET_MEASURE_CARRIER_MODE . |
8c01f86f | 424 | .TP |
422852de | 425 | .BR LIRC_CAN_USE_WIDEBAND_RECEIVER |
8c01f86f | 426 | The driver supports learning mode using |
422852de | 427 | .BR LIRC_SET_WIDEBAND_RECEIVER . |
8c01f86f | 428 | .TP |
422852de | 429 | .BR LIRC_CAN_SEND_PULSE |
8c01f86f | 430 | The driver supports sending using |
a0d4d605 SY |
431 | .BR LIRC_MODE_PULSE |
432 | or | |
433 | .BR LIRC_MODE_SCANCODE | |
787dd4ad | 434 | .\" |
422852de | 435 | .SH BUGS |
8c01f86f MK |
436 | Using these devices requires the kernel source header file |
437 | .IR lirc.h . | |
2dcd3026 MK |
438 | This file is not available before kernel release 4.6. |
439 | Users of older kernels could use the file bundled in | |
8c01f86f MK |
440 | .UR http://www.lirc.org |
441 | .UE . | |
787dd4ad | 442 | .\" |
422852de | 443 | .SH SEE ALSO |
e5f0504c | 444 | \fBir\-ctl\fP(1), \fBlircd\fP(8),\ \fBbpf\fP(2) |
11ac5b51 | 445 | .PP |
50a8a7f4 | 446 | https://www.kernel.org/doc/html/latest/media/uapi/rc/lirc-dev.html |