man4/lirc.4

   1 .\" Copyright (c) 2015-2016, Alec Leamas
   2 .\" Copyright (c) 2018, Sean Young <sean@mess.org>
   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
  24 .TH LIRC 4 2016-07-17 "Linux" "Linux Programmer's Manual"
  25 .SH NAME
  26 lirc \- lirc devices
  27 .SH DESCRIPTION
  28 .PP
  29 The
  30 .I /dev/lirc*
  31 character devices provide a low-level
  32 bidirectional interface to infra-red (IR) remotes.
  33 Most of these devices can receive, and some can send.
  34 When receiving or sending data, the driver works in two different modes
  35 depending on the underlying hardware.
  36 .PP
  37 Some hardware (typically TV-cards) decodes the IR signal internally
  38 and provides decoded button presses as scancode values.
  39 Drivers for this kind of hardware work in
  40 .BR LIRC_MODE_SCANCODE
  41 mode.
  42 Such hardware usually does not support sending IR signals.
  43 Furthermore, such hardware can only decode a limited set of IR protocols,
  44 usually only the protocol of the specific remote which is
  45 bundled with, for example, a TV-card.
  46 .PP
  47 Other hardware provides a stream of pulse/space durations.
  48 Such drivers work in
  49 .BR LIRC_MODE_MODE2
  50 mode.
  51 Sometimes, this kind of hardware also supports
  52 sending IR data.
  53 Such hardware can be used with (almost) any kind of remote.
  54 This type of hardware can also be used in
  55 .BR LIRC_MODE_SCANCODE
  56 mode, in which case the kernel IR decoders will decode the IR.
  57 These decoders can be written in extended BPF (see
  58 .BR bpf (2))
  59 and attached to the
  60 .B lirc
  61 device.
  62 .PP
  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.
  66 .\"
  67 .SS Reading input with the LIRC_MODE_MODE2 mode
  68 .PP
  69 In the \fBLIRC_MODE_MODE2 mode\fR, the data returned by
  70 .BR read (2)
  71 provides 32-bit values representing a space or a pulse duration.
  72 The time of the duration (microseconds) is encoded in the lower 24 bits.
  73 The upper 8 bits indicate 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
  82 Value reflects a frequency (Hz); see the
  83 .B LIRC_SET_MEASURE_CARRIER_MODE
  84 ioctl.
  85 .TP 4
  86 .BR LIRC_MODE2_TIMEOUT
  87 Value reflects a space duration (microseconds).
  88 The package reflects a timeout; see the
  89 .B LIRC_SET_REC_TIMEOUT_REPORTS
  90 ioctl.
  91 .\"
  92 .SS Reading input with the LIRC_MODE_SCANCODE mode
  93 .PP
  94 In the \fBLIRC_MODE_SCANCODE\fR
  95 mode, the data returned by
  96 .BR read (2)
  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 is stored in \fIrc_proto\fR.
 100 This field has one the values of the \fIenum rc_proto\fR.
 101 .\"
 102 .SS Writing output with the LIRC_MODE_PULSE mode
 103 .PP
 104 The data written to the character device using
 105 .BR write (2)
 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
 111 .BR write (2)
 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
 115 .BR write (2)
 116 call fails with the error
 117 .BR EINVAL .
 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
 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
 125 convert the scancode to pulses and spaces.
 126 The protocol or scancode is invalid, or the
 127 .B lirc
 128 device cannot transmit.
 129 .SH IOCTL COMMANDS
 130 .PP
 131 The LIRC device's ioctl definition is bound by the ioctl function
 132 definition of
 133 .IR "struct file_operations" ,
 134 leaving us with an
 135 .IR "unsigned int"
 136 for the ioctl command and an
 137 .IR "unsigned long"
 138 for the argument.
 139 For the purposes of ioctl portability across 32-bit and 64-bit architectures,
 140 these values are capped to their 32-bit sizes.
 141 .PP
 142 .nf
 143 #include <linux/lirc.h>    /* But see BUGS */
 144 int ioctl(int fd, int cmd, ...);
 145 .fi
 146 .PP
 147 The following ioctls can be used to probe or change specific
 148 .B lirc
 149 hardware settings.
 150 Many require a third argument, usually an
 151 .IR int .
 152 referred to below as
 153 .IR val .
 154 .\"
 155 .SS Always Supported Commands
 156 .PP
 157 \fI/dev/lirc*\fR devices always support the following commands:
 158 .TP 4
 159 .BR LIRC_GET_FEATURES " (\fIvoid\fP)"
 160 Returns a bit mask of combined features bits; see FEATURES.
 161 .PP
 162 If a device returns an error code for
 163 .BR LIRC_GET_FEATURES ,
 164 it is safe to assume it is not a
 165 .B lirc
 166 device.
 167 .\"
 168 .SS Optional Commands
 169 .PP
 170 Some
 171 .B lirc
 172 devices support the commands listed below.
 173 Unless otherwise stated, these fail with the error \fBENOTTY\fR if the
 174 operation isn't supported, or with the error \fBEINVAL\fR if the operation
 175 failed, or invalid arguments were provided.
 176 If a driver does not announce support of certain features, invoking
 177 the corresponding ioctls will fail with the error
 178 .BR ENOTTY .
 179 .TP
 180 .BR LIRC_GET_REC_MODE " (\fIvoid\fP)"
 181 If the
 182 .B lirc
 183 device has no receiver, this operation fails with the error
 184 .BR ENOTTY .
 185 Otherwise, it returns the receive mode, which will be one of:
 186 .RS
 187 .TP
 188 .BR LIRC_MODE_MODE2
 189 The driver returns a sequence of pulse/space durations.
 190 .TP
 191 .BR LIRC_MODE_SCANCODE
 192 The driver returns struct
 193 .I lirc_scancode
 194 values, each of which represents
 195 a decoded button press.
 196 .RE
 197 .TP
 198 .BR LIRC_SET_REC_MODE " (\fIint\fP)"
 199 Set the receive mode.
 200 .IR val
 201 is either
 202 .BR LIRC_MODE_SCANCODE
 203 or
 204 .BR LIRC_MODE_MODE2 .
 205 If the
 206 .B lirc
 207 device has no receiver, this operation fails with the error
 208 .B ENOTTY.
 209 .TP
 210 .BR LIRC_GET_SEND_MODE " (\fIvoid\fP)"
 211 Return the send mode.
 212 .BR LIRC_MODE_PULSE
 213 or
 214 .BR LIRC_MODE_SCANCODE
 215 is supported.
 216 If the
 217 .B lirc
 218 device cannot send, this operation fails with the error
 219 .B ENOTTY.
 220 .TP
 221 .BR LIRC_SET_SEND_MODE " (\fIint\fP)"
 222 Set the send mode.
 223 .IR val
 224 is either
 225 .BR LIRC_MODE_SCANCODE
 226 or
 227 .BR LIRC_MODE_PULSE .
 228 If the
 229 .B lirc
 230 device cannot send, this operation fails with the error
 231 .BR ENOTTY .
 232 .TP
 233 .BR LIRC_SET_SEND_CARRIER " (\fIint\fP)"
 234 Set the modulation frequency.
 235 The argument is the frequency (Hz).
 236 .TP
 237 .BR LIRC_SET_SEND_DUTY_CYCLE " (\fIint\fP)"
 238 Set the carrier duty cycle.
 239 .I val
 240 is a number in the range [0,100] which
 241 describes the pulse width as a percentage of the total cycle.
 242 Currently, no special meaning is defined for 0 or 100, but the values
 243 are reserved for future use.
 244 .IP
 245 .TP
 246 .BR LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)", " "\
 247 LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)"
 248 Some devices have internal timers that can be used to detect when
 249 there has been no IR activity for a long time.
 250 This can help
 251 .BR lircd (8)
 252 in detecting that an IR signal is finished and can speed up the
 253 decoding process.
 254 These operations
 255 return integer values with the minimum/maximum timeout that can be
 256 set (microseconds).
 257 Some devices have a fixed timeout.
 258 For such drivers,
 259 .BR LIRC_GET_MIN_TIMEOUT
 260 and
 261 .BR LIRC_GET_MAX_TIMEOUT
 262 will fail with the error
 263 .BR ENOTTY .
 264 .TP
 265 .BR LIRC_SET_REC_TIMEOUT " (\fIint\fP)"
 266 Set the integer value for IR inactivity timeout (microseconds).
 267 To be accepted, the value must be within the limits defined by
 268 .BR LIRC_GET_MIN_TIMEOUT
 269 and
 270 .BR LIRC_GET_MAX_TIMEOUT .
 271 A value of 0 (if supported by the hardware) disables all hardware
 272 timeouts and data should be reported as soon as possible.
 273 If the exact value cannot be set, then the next possible value
 274 .I greater
 275 than the given value should be set.
 276 .TP
 277 .BR LIRC_GET_REC_TIMEOUT " (\fivoid\fP)"
 278 Return the current inactivity timeout (microseconds).
 279 Available since Linux 4.18.
 280 .TP
 281 .BR LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)"
 282 Enable
 283 .RI ( val
 284 is 1) or disable
 285 .RI ( val
 286 is 0) timeout packages in
 287 .BR LIRC_MODE_MODE2 .
 288 The behavior of this operation has varied across kernel versions:
 289 .RS
 290 .IP * 3
 291 Since Linux 4.16: each time the
 292 .B lirc device is opened,
 293 timeout reports are by default enabled for the resulting file descriptor.
 294 The
 295 .B LIRC_SET_REC_TIMEOUT
 296 operation can be used to disable (and, if desired, to later re-enable)
 297 the timeout on the file descriptor.
 298 .IP *
 299 In Linux 4.15 and earlier:
 300 timeout reports are disabled by default, and enabling them (via
 301 .BR LIRC_SET_REC_TIMEOUT )
 302 on any file descriptor associated with the
 303 .B lirc
 304 device has the effect of enabling timeouts for all file descriptors
 305 referring to that device (until timeouts are disabled again).
 306 .RE
 307 .TP
 308 .BR LIRC_SET_REC_CARRIER " (\fIint\fP)"
 309 Set the upper bound of the receive carrier frequency (Hz).
 310 See
 311 .BR LIRC_SET_REC_CARRIER_RANGE .
 312 .TP
 313 .BR LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)"
 314 Sets the lower bound of the receive carrier frequency (Hz).
 315 For this to take affect, first set the lower bound using the
 316 .BR LIRC_SET_REC_CARRIER_RANGE
 317 ioctl, and then the upper bound using the
 318 .BR LIRC_SET_REC_CARRIER
 319 ioctl.
 320 .TP
 321 .BR LIRC_SET_MEASURE_CARRIER_MODE " (\fIint\fP)"
 322 Enable
 323 .RI ( val
 324 is 1) or disable
 325 .RI ( val
 326 is 0) the measure mode.
 327 If enabled, from the next key press on, the driver will send
 328 .BR LIRC_MODE2_FREQUENCY
 329 packets.
 330 By default, this should be turned off.
 331 .TP
 332 .BR LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)"
 333 Return the driver resolution (microseconds).
 334 .TP
 335 .BR LIRC_SET_TRANSMITTER_MASK " (\fIint\fP)"
 336 Enable the set of transmitters specified in
 337 .IR val ,
 338 which contains a bit mask where each enabled transmitter is a 1.
 339 The first transmitter is encoded by the least significant bit, and so on.
 340 When an invalid bit mask is given, for example a bit is set even
 341 though the device does not have so many transmitters,
 342 this operation returns the
 343 number of available transmitters and does nothing otherwise.
 344 .TP
 345 .BR LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)"
 346 Some devices are equipped with a special wide band receiver which is
 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.
 356 On the other hand, their disadvantage usually is reduced range of
 357 reception.
 358 .IP
 359 Note: wide band receiver may be implicitly enabled if you enable
 360 carrier reports.
 361 In that case, it will be disabled as soon as you disable carrier reports.
 362 Trying to disable a wide band receiver while carrier reports are active
 363 will do nothing.
 364 .\"
 365 .SH FEATURES
 366 .PP
 367 the
 368 .BR LIRC_GET_FEATURES
 369 ioctl returns a bit mask describing features of the driver.
 370 The following bits may be returned in the mask:
 371 .TP
 372 .BR LIRC_CAN_REC_MODE2
 373 The driver is capable of receiving using
 374 .BR LIRC_MODE_MODE2 .
 375 .TP
 376 .BR LIRC_CAN_REC_SCANCODE
 377 The driver is capable of receiving using
 378 .BR LIRC_MODE_SCANCODE .
 379 .TP
 380 .BR LIRC_CAN_SET_SEND_CARRIER
 381 The driver supports changing the modulation frequency using
 382 .BR LIRC_SET_SEND_CARRIER .
 383 .TP
 384 .BR LIRC_CAN_SET_SEND_DUTY_CYCLE
 385 The driver supports changing the duty cycle using
 386 .BR LIRC_SET_SEND_DUTY_CYCLE .
 387 .TP
 388 .BR LIRC_CAN_SET_TRANSMITTER_MASK
 389 The driver supports changing the active transmitter(s) using
 390 .BR LIRC_SET_TRANSMITTER_MASK .
 391 .TP
 392 .BR LIRC_CAN_SET_REC_CARRIER
 393 The driver supports setting the receive carrier frequency using
 394 .BR LIRC_SET_REC_CARRIER .
 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.
 403 .TP
 404 .BR LIRC_CAN_SET_REC_CARRIER_RANGE
 405 The driver supports
 406 .BR LIRC_SET_REC_CARRIER_RANGE .
 407 The lower bound of the carrier must first be set using the
 408 .BR LIRC_SET_REC_CARRIER_RANGE
 409 ioctl, before using the
 410 .BR LIRC_SET_REC_CARRIER
 411 ioctl to set the upper bound.
 412 .TP
 413 .BR LIRC_CAN_GET_REC_RESOLUTION
 414 The driver supports
 415 .BR LIRC_GET_REC_RESOLUTION .
 416 .TP
 417 .BR LIRC_CAN_SET_REC_TIMEOUT
 418 The driver supports
 419 .BR LIRC_SET_REC_TIMEOUT .
 420 .TP
 421 .BR LIRC_CAN_MEASURE_CARRIER
 422 The driver supports measuring of the modulation frequency using
 423 .BR LIRC_SET_MEASURE_CARRIER_MODE .
 424 .TP
 425 .BR LIRC_CAN_USE_WIDEBAND_RECEIVER
 426 The driver supports learning mode using
 427 .BR LIRC_SET_WIDEBAND_RECEIVER .
 428 .TP
 429 .BR LIRC_CAN_SEND_PULSE
 430 The driver supports sending using
 431 .BR LIRC_MODE_PULSE
 432 or
 433 .BR LIRC_MODE_SCANCODE
 434 .\"
 435 .SH BUGS
 436 Using these devices requires the kernel source header file
 437 .IR lirc.h .
 438 This file is not available before kernel release 4.6.
 439 Users of older kernels could use the file bundled in
 440 .UR http://www.lirc.org
 441 .UE .
 442 .\"
 443 .SH SEE ALSO
 444 \fBir\-ctl\fP(1), \fBlircd\fP(8),\ \fBbpf\fP(2)
 445 .PP
 446 https://www.kernel.org/doc/html/latest/media/uapi/rc/lirc-dev.html