man4/lirc.4

   1 .\" Copyright (c) 2015-2016, Alec Leamas
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" The GNU General Public License's references to "object code"
  10 .\" and "executables" are to be interpreted as the output of any
  11 .\" document formatting or typesetting system, including
  12 .\" intermediate and printed output.
  13 .\"
  14 .\" This manual is distributed in the hope that it will be useful,
  15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17 .\" GNU General Public License for more details.
  18 .\"
  19 .\" You should have received a copy of the GNU General Public
  20 .\" License along with this manual; if not, see
  21 .\" <http://www.gnu.org/licenses/>.
  22 .\" %%%LICENSE_END
  23 .TH LIRC 4 2016-07-17 "Linux" "Linux Programmer's Manual"
  24 .SH NAME
  25 lirc \- lirc devices
  26 .SH DESCRIPTION
  27 .P
  28 The
  29 .B /dev/lirc*
  30 character devices provide a low-level
  31 bi-directional interface to infra-red (IR) remotes.
  32 When receiving data, the driver works in two different modes depending
  33 on the underlying hardware.
  34 .P
  35 Some hardware (typically TV-cards) decodes the IR signal internally
  36 and just provides decoded button presses as integer values.
  37 Drivers for this kind of hardware work in
  38 .BR LIRC_MODE_LIRCCODE
  39 mode.
  40 Such hardware usually does not support sending IR signals.
  41 Furthermore, it usually only works with a specific remote which is
  42 bundled with, for example, a TV-card.
  43 .P
  44 Other hardware provides a stream of pulse/space durations.
  45 Such drivers work in
  46 .BR LIRC_MODE_MODE2
  47 mode.
  48 Sometimes, this kind of hardware also supports
  49 sending IR data.
  50 Such hardware can be used with (almost) any kind of remote.
  51 .P
  52 The \fBLIRC_GET_REC_MODE\fR ioctl (see below) allows probing for the
  53 mode.
  54 .\"
  55 .SS Reading input with the LIRC_MODE_MODE2 drivers
  56 .P
  57 In the \fBLIRC_MODE_MODE2 mode\fR, the data returned by
  58 .BR read (2)
  59 provides 32-bit values representing a space or a pulse duration, by
  60 convention typed as
  61 .IR lirc_t .
  62 The time of the duration (microseconds) is encoded in the lower 24 bits.
  63 The upper 8 bit reflects the type of package:
  64 .TP 4
  65 .BR LIRC_MODE2_SPACE .
  66 Value reflects a space duration (microseconds).
  67 .TP 4
  68 .BR LIRC_MODE2_PULSE .
  69 Value reflects a pulse duration (microseconds).
  70 .TP 4
  71 .BR LIRC_MODE2_FREQUENCY .
  72 Value reflects a frequency (Hz); see the
  73 .B LIRC_SET_MEASURE_CARRIER_MODE
  74 ioctl.
  75 .TP 4
  76 .BR LIRC_MODE2_TIMEOUT .
  77 The package reflects a timeout; see the
  78 .B LIRC_SET_REC_TIMEOUT_REPORTS
  79 ioctl.
  80 .\"
  81 .SS Reading input with the
  82 .B LIRC_MODE_LIRCCODE
  83 drivers
  84 .P
  85 In the \fBLIRC_MODE_LIRCCODE\fR
  86 mode, the data returned by
  87 .BR read (2)
  88 reflects decoded button presses.
  89 The length of each packet can be retrieved using
  90 the \fBLIRC_GET_LENGTH\fR ioctl.
  91 Reads must be done in blocks matching
  92 the bit count returned by the \fBLIRC_GET_LENGTH\fR ioctl, rounded
  93 up so it matches full bytes.
  94 .\"
  95 .SS Sending data
  96 .P
  97 When sending data, only the \fBLIRC_MODE_PULSE\fR
  98 mode is supported.
  99 The data written to the character device using
 100 .BR write (2)
 101 is a pulse/space sequence of integer values.
 102 Pulses and spaces are only marked implicitly by their position.
 103 The data must start and end with a pulse, thus it must always include
 104 an odd number of samples.
 105 The
 106 .BR write (2)
 107 function blocks until the data has been transmitted by the
 108 hardware.
 109 If more data is provided than the hardware can send, the
 110 .BR write (2)
 111 call fails with the error
 112 .BR EINVAL
 113 .\"
 114 .SH IOCTL COMMANDS
 115 .P
 116 The complete list of ioctl commands is maintained in the kernel
 117 documentation, see SEE ALSO.
 118 The ioctl commands presented here is a subset of the kernel
 119 documentation.
 120 .P
 121 The LIRC device's ioctl definition is bound by the ioctl function
 122 definition of struct file_operations, leaving us with an unsigned
 123 int for the ioctl command and an unsigned long for the argument.
 124 For the purposes of ioctl portability across 32-bit and 64-bit architectures,
 125 these values are capped to their 32-bit sizes.
 126 .P
 127 .nf
 128 #include <lirc/include/media/lirc.h>    /* But see BUGS */
 129 int ioctl(int fd, int cmd, ...);
 130 .fi
 131 .P
 132 The following ioctls can be used to probe or change specific lirc
 133 hardware settings.
 134 Many require a third argument, usually an
 135 .IR int .
 136 referred to below as
 137 .IR val .
 138 .P
 139 In general, each driver should have a default set of settings.
 140 The driver implementation is expected to re-apply the default settings
 141 when the device is closed by user space, so that every application
 142 opening the device can rely on working with the default settings
 143 initially.
 144 .\"
 145 .SS Always Supported Commands
 146 .P
 147 \fI/dev/lirc*\fR devices always support the following commands:
 148 .TP 4
 149 .BR LIRC_GET_FEATURES " (\fIvoid\fP)"
 150 Returns a bit mask of combined features bits; see FEATURES.
 151 Some drivers have dynamic features which are not updated until after an
 152 .I init()
 153 command.
 154 If a driver does not announce support of certain features, calling of
 155 the corresponding ioctls is undefined.
 156 .TP
 157 .BR LIRC_GET_REC_MODE
 158 Return the receive mode, which will be one of:
 159 .RS 4
 160 .TP
 161 .BR LIRC_MODE_MODE2 " (\fIvoid\fP)"
 162 The driver returns a sequence of pulse/space durations.
 163 .TP
 164 .BR LIRC_MODE_LIRCCODE
 165 The driver returns integer values, each of which represents a decoded
 166 button press.
 167 .RE
 168 .P
 169 If a device returns an error code for
 170 .BR LIRC_GET_REC_MODE ,
 171 it is safe to assume it is not a lirc device.
 172 .\"
 173 .SS Optional Commands
 174 .P
 175 Some lirc devices support commands listed below.
 176 Unless otherwise stated, these fail with the error \fBENOIOCTLCMD\fR
 177 or with the error \fBENOSYS\fR if the operation
 178 isn't supported, or with the error \fBEINVAL\fR if the operation
 179 failed.
 180 .TP
 181 .BR LIRC_SET_REC_MODE " (\fIint\fP)"
 182 Set the receive mode.
 183 .IR val
 184 is either
 185 .BR LIRC_MODE_LIRCCODE
 186 or
 187 .BR LIRC_MODE_MODE2 .
 188 .TP
 189 .BR LIRC_GET_LENGTH " (\fIvoid\fP)"
 190 Return the length of the returned codes for
 191 .BR LIRC_MODE_LIRCCODE -type
 192 drivers, otherwise fail with the error
 193 .BR ENOIOCTLCMD .
 194 .TP
 195 .BR LIRC_GET_SEND_MODE " (\fIvoid\fP)"
 196 Return the send mode.
 197 Currently, only
 198 .BR LIRC_MODE_PULSE
 199 is supported.
 200 .TP
 201 .BR LIRC_SET_SEND_MODE " (\fIint\fP)"
 202 Set the send mode.
 203 Currently serves no purpose since only
 204 .BR LIRC_MODE_PULSE
 205 is supported.
 206 .TP
 207 .BR LIRC_GET_SEND_CARRIER " (\fIvoid\fP)"
 208 Get the modulation frequency (Hz).
 209 .TP
 210 .BR LIRC_SET_SEND_CARRIER " (\fIint\fP)"
 211 Set the modulation frequency.
 212 The argument is the frequency (Hz).
 213 .TP
 214 .BR LIRC_GET_SEND_CARRIER " (\fIvoid\fP)"
 215 Get the modulation frequency used when decoding (Hz).
 216 .TP
 217 .BR SET_SEND_DUTY_CYCLE " (\fIint\fP)"
 218 Set the carrier duty cycle.
 219 .I val
 220 is a number in the range [0,100] which
 221 describes the pulse width as a percentage of the total cycle.
 222 Currently, no special meaning is defined for 0 or 100, but the values
 223 are reserved for future use.
 224
 225 .TP
 226 .BR LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)", " "\
 227 LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)"
 228 Some devices have internal timers that can be used to detect when
 229 there's no IR activity for a long time.
 230 This can help
 231 .BR lircd (8)
 232 in detecting that an IR signal is finished and can speed up the
 233 decoding process.
 234 These operations
 235 return integer values with the minimum/maximum timeout that can be
 236 set (microseconds).
 237 Some devices have a fixed timeout.
 238 For such drivers,
 239 .BR LIRC_GET_MIN_TIMEOUT
 240 and
 241 .BR LIRC_GET_MAX_TIMEOUT
 242 will return the same value.
 243 .TP
 244 .BR LIRC_SET_REC_TIMEOUT " (\fIint\fP)"
 245 Set the integer value for IR inactivity timeout (microseconds).
 246 To be accepted, the value must be within the limits defined by
 247 .BR LIRC_GET_MIN_TIMEOUT
 248 and
 249 .BR LIRC_GET_MAX_TIMEOUT .
 250 A value of 0 (if supported by the hardware) disables all hardware
 251 timeouts and data should be reported as soon as possible.
 252 If the exact value cannot be set, then the next possible value
 253 .I greater
 254 than the given value should be set.
 255 .TP
 256 .BR LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)"
 257 Enable
 258 .RI ( val
 259 is 1) or disable
 260 .RI ( val
 261 is 0) timeout packages in
 262 .BR LIRC_MODE_MODE2 .
 263 By default, timeout reports should be turned off.
 264 .TP
 265 .BR LIRC_SET_REC_CARRIER " (\fIint\fP)"
 266 Set the receive carrier frequency (Hz).
 267 .TP
 268 .BR LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)"
 269 After opening device, the first use of this operation
 270 sets the lower bound of the carrier range,
 271 and the second use sets the upper bound (Hz).
 272 .TP
 273 .BR LIRC_SET_MEASURE_CARRIER_MODE " (\fIint\fP)"
 274 Enable
 275 .RI ( val
 276 is 1) or disable
 277 .RI ( val
 278 is 0) the measure mode.
 279 If enabled, from the next key press on, the driver will send
 280 .BR LIRC_MODE2_FREQUENCY
 281 packets.
 282 By default this should be turned off.
 283 .TP
 284 .BR LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)"
 285 Return the driver resolution (microseconds).
 286 .TP
 287 .BR LIRC_GET_MIN_FILTER_PULSE " (\fIvoid\fP)", " " \
 288 LIRC_GET_MAX_FILTER_PULSE " (\fIvoid\fP)"
 289 Some devices are able to filter out spikes in the incoming signal
 290 using given filter rules.
 291 These ioctls return the hardware capabilities that describe the bounds
 292 of the possible filters.
 293 Filter settings depend on the IR protocols that are expected.
 294 .BR lircd (8)
 295 derives the settings from all protocols definitions found in its
 296 .BR lircd.conf (5)
 297 config file.
 298 .TP
 299 .BR LIRC_GET_MIN_FILTER_SPACE " (\fIvoid\fP)", " " \
 300 LIRC_GET_MAX_FILTER_SPACE " (\fIvoid\fP)"
 301 See
 302 .BR LIRC_GET_MIN_FILTER_PULSE .
 303 .TP
 304 .BR LIRC_SET_REC_FILTER " (\fIint\fP)"
 305 Pulses/spaces shorter than this (microseconds) are filtered out by
 306 hardware.
 307 .TP
 308 .BR LIRC_SET_REC_FILTER_PULSE " (\fIint\fP)", " " \
 309 LIRC_SET_REC_FILTER_SPACE " (\fIint\fP)"
 310 Pulses/spaces shorter than this (microseconds) are filtered out by
 311 hardware.
 312 If filters cannot be set independently for pulse/space, the
 313 corresponding ioctls must return an error and
 314 .BR LIRC_SET_REC_FILTER
 315 should be used instead.
 316 .TP
 317 .BR LIRC_SET_TRANSMITTER_MASK
 318 Enable the set of transmitters specified in
 319 .IR val ,
 320 which contains a bit mask where each enabled transmitter is a 1.
 321 The first transmitter is encoded by the least significant bit, and so on.
 322 When an invalid bit mask is given, for example a bit is set even
 323 though the device does not have so many transmitters,
 324 this operation returns the
 325 number of available transmitters and does nothing otherwise.
 326 .TP
 327 .BR LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)"
 328 Some devices are equipped with a special wide band receiver which is
 329 intended to be used to learn the output of an existing remote.
 330 This ioctl can be used to enable
 331 .RI ( val
 332 equals 1) or disable
 333 .RI ( val
 334 equals 0) this functionality.
 335 This might be useful for devices that otherwise have narrow band
 336 receivers that prevent them to be used with certain remotes.
 337 Wide band receivers may also be more precise.
 338 On the other hand its disadvantage usually is reduced range of
 339 reception.
 340 .IP
 341 Note: wide band receiver may be implicitly enabled if you enable
 342 carrier reports.
 343 In that case, it will be disabled as soon as you disable carrier reports.
 344 Trying to disable a wide band receiver while carrier reports are active
 345 will do nothing.
 346 .TP
 347 .BR LIRC_SETUP_START " (\fIvoid\fP), " LIRC_SETUP_END " (\fIvoid\fP)"
 348 Setting of several driver parameters can be optimized by bracketing
 349 the actual ioctl calls
 350 .BR LIRC_SETUP_START
 351 and
 352 .BR LIRC_SETUP_END .
 353 When a driver receives a
 354 .BR LIRC_SETUP_START
 355 ioctl, it can choose to not commit further setting changes to the
 356 hardware until a
 357 .BR LIRC_SETUP_END
 358 is received.
 359 But this is open to the driver implementation and every driver
 360 must also handle parameter changes which are not encapsulated by
 361 .BR LIRC_SETUP_START
 362 and
 363 .BR LIRC_SETUP_END .
 364 Drivers can also choose to ignore these ioctls.
 365 .TP
 366 .BR LIRC_NOTIFY_DECODE " (\fIvoid\fP)"
 367 This ioctl is called by
 368 .BR lircd (8)
 369 whenever a successful decoding of an incoming IR signal is possible.
 370 This can be used by supporting hardware to give visual user
 371 feedback, for example by flashing an LED.
 372 .\"
 373 .SH FEATURES
 374 .P
 375 The features returned by
 376 The
 377 .BR LIRC_GET_FEATURES
 378 ioctl returns a bit mask describing features of the driver.
 379 The following bits may be returned in the mask:
 380 .TP
 381 .BR LIRC_CAN_REC_RAW
 382 The driver is capable of receiving using
 383 .BR LIRC_MODE_RAW .
 384 .TP
 385 .BR LIRC_CAN_REC_PULSE
 386 The driver is capable of receiving using
 387 .BR LIRC_MODE_PULSE .
 388 .TP
 389 .BR LIRC_CAN_REC_MODE2
 390 The driver is capable of receiving using
 391 .BR LIRC_MODE_MODE2 .
 392 .TP
 393 .BR LIRC_CAN_REC_LIRCCODE
 394 The driver is capable of receiving using
 395 .BR LIRC_MODE_LIRCCODE .
 396 .TP
 397 .BR LIRC_CAN_SET_SEND_CARRIER
 398 The driver supports changing the modulation frequency using
 399 .BR LIRC_SET_SEND_CARRIER .
 400 .TP
 401 .BR LIRC_CAN_SET_SEND_DUTY_CYCLE
 402 The driver supports changing the duty cycle using
 403 .BR LIRC_SET_SEND_DUTY_CYCLE .
 404 .TP
 405 .BR LIRC_CAN_SET_TRANSMITTER_MASK
 406 The driver supports changing the active transmitter(s) using
 407 .BR LIRC_SET_TRANSMITTER_MASK .
 408 .TP
 409 .BR LIRC_CAN_SET_REC_CARRIER
 410 The driver supports setting the receive carrier frequency using
 411 .BR LIRC_SET_REC_CARRIER .
 412 .TP
 413 .BR LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE
 414 The driver supports
 415 .BR LIRC_SET_REC_DUTY_CYCLE_RANGE .
 416 .TP
 417 .BR LIRC_CAN_SET_REC_CARRIER_RANGE
 418 The driver supports
 419 .BR LIRC_SET_REC_CARRIER_RANGE .
 420 .TP
 421 .BR LIRC_CAN_GET_REC_RESOLUTION
 422 The driver supports
 423 .BR LIRC_GET_REC_RESOLUTION .
 424 .TP
 425 .BR LIRC_CAN_SET_REC_TIMEOUT
 426 The driver supports
 427 .BR LIRC_SET_REC_TIMEOUT .
 428 .TP
 429 .BR LIRC_CAN_SET_REC_FILTER
 430 The driver supports
 431 .BR LIRC_SET_REC_FILTER .
 432 .TP
 433 .BR LIRC_CAN_MEASURE_CARRIER
 434 The driver supports measuring of the modulation frequency using
 435 .BR LIRC_SET_MEASURE_CARRIER_MODE .
 436 .TP
 437 .BR LIRC_CAN_USE_WIDEBAND_RECEIVER
 438 The driver supports learning mode using
 439 .BR LIRC_SET_WIDEBAND_RECEIVER .
 440 .TP
 441 .BR LIRC_CAN_NOTIFY_DECODE
 442 The driver supports
 443 .BR LIRC_NOTIFY_DECODE .
 444 .TP
 445 .BR LIRC_CAN_SEND_RAW
 446 The driver supports sending using
 447 .BR LIRC_MODE_RAW .
 448 .TP
 449 .BR LIRC_CAN_SEND_PULSE
 450 The driver supports sending using
 451 .BR LIRC_MODE_PULSE .
 452 .TP
 453 .BR LIRC_CAN_SEND_MODE2
 454 The driver supports sending using
 455 .BR LIRC_MODE_MODE2 .
 456 .TP
 457 .BR LIRC_CAN_SEND_LIRCCODE
 458 The driver supports sending.
 459 (This is uncommon, since
 460 .BR LIRCCODE
 461 drivers reflect hardware like TV-cards which usually dos not support
 462 sending.)
 463 .\"
 464 .SH BUGS
 465 Using these devices requires the kernel source header file
 466 .IR lirc.h .
 467 This file is not available before kernel release 4.6.
 468 Users of older kernels could use the file bundled in
 469 .UR http://www.lirc.org
 470 .UE .
 471 .\"
 472 .SH SEE ALSO
 473 .BR lircd (8)
 474 .P
 475 https://www.kernel.org/doc/htmldocs/media_api/lirc_dev.html