man4/lirc.4

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