| .\" Copyright (c) 2015-2016, Alec Leamas |
| .\" |
| .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
| .\" This is free documentation; you can redistribute it and/or |
| .\" modify it under the terms of the GNU General Public License as |
| .\" published by the Free Software Foundation; either version 2 of |
| .\" the License, or (at your option) any later version. |
| .\" |
| .\" The GNU General Public License's references to "object code" |
| .\" and "executables" are to be interpreted as the output of any |
| .\" document formatting or typesetting system, including |
| .\" intermediate and printed output. |
| .\" |
| .\" This manual is distributed in the hope that it will be useful, |
| .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
| .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| .\" GNU General Public License for more details. |
| .\" |
| .\" You should have received a copy of the GNU General Public |
| .\" License along with this manual; if not, see |
| .\" <http://www.gnu.org/licenses/>. |
| .\" %%%LICENSE_END |
| .TH LIRC 4 2016-07-17 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| lirc \- lirc devices |
| .SH DESCRIPTION |
| .P |
| The |
| .B /dev/lirc* |
| character devices provide a low-level |
| bi-directional interface to infra-red (IR) remotes. |
| When receiving data, the driver works in two different modes depending |
| on the underlying hardware. |
| .P |
| Some hardware (typically TV-cards) decodes the IR signal internally |
| and just provides decoded button presses as integer values. |
| Drivers for this kind of hardware work in |
| .BR LIRC_MODE_LIRCCODE |
| mode. |
| Such hardware usually does not support sending IR signals. |
| Furthermore, it usually only works with a specific remote which is |
| bundled with, for example, a TV-card. |
| .P |
| Other hardware provides a stream of pulse/space durations. |
| Such drivers work in |
| .BR LIRC_MODE_MODE2 |
| mode. |
| Sometimes, this kind of hardware also supports |
| sending IR data. |
| Such hardware can be used with (almost) any kind of remote. |
| .P |
| The \fBLIRC_GET_REC_MODE\fR ioctl (see below) allows probing for the |
| mode. |
| .\" |
| .SS Reading input with the LIRC_MODE_MODE2 drivers |
| .P |
| In the \fBLIRC_MODE_MODE2 mode\fR, the data returned by |
| .BR read (2) |
| provides 32-bit values representing a space or a pulse duration, by |
| convention typed as |
| .IR lirc_t . |
| The time of the duration (microseconds) is encoded in the lower 24 bits. |
| The upper 8 bit reflects the type of package: |
| .TP 4 |
| .BR LIRC_MODE2_SPACE . |
| Value reflects a space duration (microseconds). |
| .TP 4 |
| .BR LIRC_MODE2_PULSE . |
| Value reflects a pulse duration (microseconds). |
| .TP 4 |
| .BR LIRC_MODE2_FREQUENCY . |
| Value reflects a frequency (Hz); see the |
| .B LIRC_SET_MEASURE_CARRIER_MODE |
| ioctl. |
| .TP 4 |
| .BR LIRC_MODE2_TIMEOUT . |
| The package reflects a timeout; see the |
| .B LIRC_SET_REC_TIMEOUT_REPORTS |
| ioctl. |
| .\" |
| .SS Reading input with the |
| .B LIRC_MODE_LIRCCODE |
| drivers |
| .P |
| In the \fBLIRC_MODE_LIRCCODE\fR |
| mode, the data returned by |
| .BR read (2) |
| reflects decoded button presses. |
| The length of each packet can be retrieved using |
| the \fBLIRC_GET_LENGTH\fR ioctl. |
| Reads must be done in blocks matching |
| the bit count returned by the \fBLIRC_GET_LENGTH\fR ioctl, rounded |
| up so it matches full bytes. |
| .\" |
| .SS Sending data |
| .P |
| When sending data, only the \fBLIRC_MODE_PULSE\fR |
| mode is supported. |
| The data written to the character device using |
| .BR write (2) |
| is a pulse/space sequence of integer values. |
| Pulses and spaces are only marked implicitly by their position. |
| The data must start and end with a pulse, thus it must always include |
| an odd number of samples. |
| The |
| .BR write (2) |
| function blocks until the data has been transmitted by the |
| hardware. |
| If more data is provided than the hardware can send, the |
| .BR write (2) |
| call fails with the error |
| .BR EINVAL |
| .\" |
| .SH IOCTL COMMANDS |
| .P |
| The complete list of ioctl commands is maintained in the kernel |
| documentation, see SEE ALSO. |
| The ioctl commands presented here is a subset of the kernel |
| documentation. |
| .P |
| The LIRC device's ioctl definition is bound by the ioctl function |
| definition of struct file_operations, leaving us with an unsigned |
| int for the ioctl command and an unsigned long for the argument. |
| For the purposes of ioctl portability across 32-bit and 64-bit architectures, |
| these values are capped to their 32-bit sizes. |
| .P |
| .nf |
| #include <lirc/include/media/lirc.h> /* But see BUGS */ |
| int ioctl(int fd, int cmd, ...); |
| .fi |
| .P |
| The following ioctls can be used to probe or change specific lirc |
| hardware settings. |
| Many require a third argument, usually an |
| .IR int . |
| referred to below as |
| .IR val . |
| .P |
| In general, each driver should have a default set of settings. |
| The driver implementation is expected to re-apply the default settings |
| when the device is closed by user space, so that every application |
| opening the device can rely on working with the default settings |
| initially. |
| .\" |
| .SS Always Supported Commands |
| .P |
| \fI/dev/lirc*\fR devices always support the following commands: |
| .TP 4 |
| .BR LIRC_GET_FEATURES " (\fIvoid\fP)" |
| Returns a bit mask of combined features bits; see FEATURES. |
| Some drivers have dynamic features which are not updated until after an |
| .I init() |
| command. |
| If a driver does not announce support of certain features, calling of |
| the corresponding ioctls is undefined. |
| .TP |
| .BR LIRC_GET_REC_MODE |
| Return the receive mode, which will be one of: |
| .RS 4 |
| .TP |
| .BR LIRC_MODE_MODE2 " (\fIvoid\fP)" |
| The driver returns a sequence of pulse/space durations. |
| .TP |
| .BR LIRC_MODE_LIRCCODE |
| The driver returns integer values, each of which represents a decoded |
| button press. |
| .RE |
| .P |
| If a device returns an error code for |
| .BR LIRC_GET_REC_MODE , |
| it is safe to assume it is not a lirc device. |
| .\" |
| .SS Optional Commands |
| .P |
| Some lirc devices support commands listed below. |
| Unless otherwise stated, these fail with the error \fBENOIOCTLCMD\fR |
| or with the error \fBENOSYS\fR if the operation |
| isn't supported, or with the error \fBEINVAL\fR if the operation |
| failed. |
| .TP |
| .BR LIRC_SET_REC_MODE " (\fIint\fP)" |
| Set the receive mode. |
| .IR val |
| is either |
| .BR LIRC_MODE_LIRCCODE |
| or |
| .BR LIRC_MODE_MODE2 . |
| .TP |
| .BR LIRC_GET_LENGTH " (\fIvoid\fP)" |
| Return the length of the returned codes for |
| .BR LIRC_MODE_LIRCCODE -type |
| drivers, otherwise fail with the error |
| .BR ENOIOCTLCMD . |
| .TP |
| .BR LIRC_GET_SEND_MODE " (\fIvoid\fP)" |
| Return the send mode. |
| Currently, only |
| .BR LIRC_MODE_PULSE |
| is supported. |
| .TP |
| .BR LIRC_SET_SEND_MODE " (\fIint\fP)" |
| Set the send mode. |
| Currently serves no purpose since only |
| .BR LIRC_MODE_PULSE |
| is supported. |
| .TP |
| .BR LIRC_GET_SEND_CARRIER " (\fIvoid\fP)" |
| Get the modulation frequency (Hz). |
| .TP |
| .BR LIRC_SET_SEND_CARRIER " (\fIint\fP)" |
| Set the modulation frequency. |
| The argument is the frequency (Hz). |
| .TP |
| .BR LIRC_GET_SEND_CARRIER " (\fIvoid\fP)" |
| Get the modulation frequency used when decoding (Hz). |
| .TP |
| .BR SET_SEND_DUTY_CYCLE " (\fIint\fP)" |
| Set the carrier duty cycle. |
| .I val |
| is a number in the range [0,100] which |
| describes the pulse width as a percentage of the total cycle. |
| Currently, no special meaning is defined for 0 or 100, but the values |
| are reserved for future use. |
| |
| .TP |
| .BR LIRC_GET_MIN_TIMEOUT " (\fIvoid\fP)", " "\ |
| LIRC_GET_MAX_TIMEOUT " (\fIvoid\fP)" |
| Some devices have internal timers that can be used to detect when |
| there's no IR activity for a long time. |
| This can help |
| .BR lircd (8) |
| in detecting that an IR signal is finished and can speed up the |
| decoding process. |
| These operations |
| return integer values with the minimum/maximum timeout that can be |
| set (microseconds). |
| Some devices have a fixed timeout. |
| For such drivers, |
| .BR LIRC_GET_MIN_TIMEOUT |
| and |
| .BR LIRC_GET_MAX_TIMEOUT |
| will return the same value. |
| .TP |
| .BR LIRC_SET_REC_TIMEOUT " (\fIint\fP)" |
| Set the integer value for IR inactivity timeout (microseconds). |
| To be accepted, the value must be within the limits defined by |
| .BR LIRC_GET_MIN_TIMEOUT |
| and |
| .BR LIRC_GET_MAX_TIMEOUT . |
| A value of 0 (if supported by the hardware) disables all hardware |
| timeouts and data should be reported as soon as possible. |
| If the exact value cannot be set, then the next possible value |
| .I greater |
| than the given value should be set. |
| .TP |
| .BR LIRC_SET_REC_TIMEOUT_REPORTS " (\fIint\fP)" |
| Enable |
| .RI ( val |
| is 1) or disable |
| .RI ( val |
| is 0) timeout packages in |
| .BR LIRC_MODE_MODE2 . |
| By default, timeout reports should be turned off. |
| .TP |
| .BR LIRC_SET_REC_CARRIER " (\fIint\fP)" |
| Set the receive carrier frequency (Hz). |
| .TP |
| .BR LIRC_SET_REC_CARRIER_RANGE " (\fIint\fP)" |
| After opening device, the first use of this operation |
| sets the lower bound of the carrier range, |
| and the second use sets the upper bound (Hz). |
| .TP |
| .BR LIRC_SET_MEASURE_CARRIER_MODE " (\fIint\fP)" |
| Enable |
| .RI ( val |
| is 1) or disable |
| .RI ( val |
| is 0) the measure mode. |
| If enabled, from the next key press on, the driver will send |
| .BR LIRC_MODE2_FREQUENCY |
| packets. |
| By default this should be turned off. |
| .TP |
| .BR LIRC_GET_REC_RESOLUTION " (\fIvoid\fP)" |
| Return the driver resolution (microseconds). |
| .TP |
| .BR LIRC_GET_MIN_FILTER_PULSE " (\fIvoid\fP)", " " \ |
| LIRC_GET_MAX_FILTER_PULSE " (\fIvoid\fP)" |
| Some devices are able to filter out spikes in the incoming signal |
| using given filter rules. |
| These ioctls return the hardware capabilities that describe the bounds |
| of the possible filters. |
| Filter settings depend on the IR protocols that are expected. |
| .BR lircd (8) |
| derives the settings from all protocols definitions found in its |
| .BR lircd.conf (5) |
| config file. |
| .TP |
| .BR LIRC_GET_MIN_FILTER_SPACE " (\fIvoid\fP)", " " \ |
| LIRC_GET_MAX_FILTER_SPACE " (\fIvoid\fP)" |
| See |
| .BR LIRC_GET_MIN_FILTER_PULSE . |
| .TP |
| .BR LIRC_SET_REC_FILTER " (\fIint\fP)" |
| Pulses/spaces shorter than this (microseconds) are filtered out by |
| hardware. |
| .TP |
| .BR LIRC_SET_REC_FILTER_PULSE " (\fIint\fP)", " " \ |
| LIRC_SET_REC_FILTER_SPACE " (\fIint\fP)" |
| Pulses/spaces shorter than this (microseconds) are filtered out by |
| hardware. |
| If filters cannot be set independently for pulse/space, the |
| corresponding ioctls must return an error and |
| .BR LIRC_SET_REC_FILTER |
| should be used instead. |
| .TP |
| .BR LIRC_SET_TRANSMITTER_MASK |
| Enable the set of transmitters specified in |
| .IR val , |
| which contains a bit mask where each enabled transmitter is a 1. |
| The first transmitter is encoded by the least significant bit, and so on. |
| When an invalid bit mask is given, for example a bit is set even |
| though the device does not have so many transmitters, |
| this operation returns the |
| number of available transmitters and does nothing otherwise. |
| .TP |
| .BR LIRC_SET_WIDEBAND_RECEIVER " (\fIint\fP)" |
| Some devices are equipped with a special wide band receiver which is |
| intended to be used to learn the output of an existing remote. |
| This ioctl can be used to enable |
| .RI ( val |
| equals 1) or disable |
| .RI ( val |
| equals 0) this functionality. |
| This might be useful for devices that otherwise have narrow band |
| receivers that prevent them to be used with certain remotes. |
| Wide band receivers may also be more precise. |
| On the other hand its disadvantage usually is reduced range of |
| reception. |
| .IP |
| Note: wide band receiver may be implicitly enabled if you enable |
| carrier reports. |
| In that case, it will be disabled as soon as you disable carrier reports. |
| Trying to disable a wide band receiver while carrier reports are active |
| will do nothing. |
| .TP |
| .BR LIRC_SETUP_START " (\fIvoid\fP), " LIRC_SETUP_END " (\fIvoid\fP)" |
| Setting of several driver parameters can be optimized by bracketing |
| the actual ioctl calls |
| .BR LIRC_SETUP_START |
| and |
| .BR LIRC_SETUP_END . |
| When a driver receives a |
| .BR LIRC_SETUP_START |
| ioctl, it can choose to not commit further setting changes to the |
| hardware until a |
| .BR LIRC_SETUP_END |
| is received. |
| But this is open to the driver implementation and every driver |
| must also handle parameter changes which are not encapsulated by |
| .BR LIRC_SETUP_START |
| and |
| .BR LIRC_SETUP_END . |
| Drivers can also choose to ignore these ioctls. |
| .TP |
| .BR LIRC_NOTIFY_DECODE " (\fIvoid\fP)" |
| This ioctl is called by |
| .BR lircd (8) |
| whenever a successful decoding of an incoming IR signal is possible. |
| This can be used by supporting hardware to give visual user |
| feedback, for example by flashing an LED. |
| .\" |
| .SH FEATURES |
| .P |
| The features returned by |
| The |
| .BR LIRC_GET_FEATURES |
| ioctl returns a bit mask describing features of the driver. |
| The following bits may be returned in the mask: |
| .TP |
| .BR LIRC_CAN_REC_RAW |
| The driver is capable of receiving using |
| .BR LIRC_MODE_RAW . |
| .TP |
| .BR LIRC_CAN_REC_PULSE |
| The driver is capable of receiving using |
| .BR LIRC_MODE_PULSE . |
| .TP |
| .BR LIRC_CAN_REC_MODE2 |
| The driver is capable of receiving using |
| .BR LIRC_MODE_MODE2 . |
| .TP |
| .BR LIRC_CAN_REC_LIRCCODE |
| The driver is capable of receiving using |
| .BR LIRC_MODE_LIRCCODE . |
| .TP |
| .BR LIRC_CAN_SET_SEND_CARRIER |
| The driver supports changing the modulation frequency using |
| .BR LIRC_SET_SEND_CARRIER . |
| .TP |
| .BR LIRC_CAN_SET_SEND_DUTY_CYCLE |
| The driver supports changing the duty cycle using |
| .BR LIRC_SET_SEND_DUTY_CYCLE . |
| .TP |
| .BR LIRC_CAN_SET_TRANSMITTER_MASK |
| The driver supports changing the active transmitter(s) using |
| .BR LIRC_SET_TRANSMITTER_MASK . |
| .TP |
| .BR LIRC_CAN_SET_REC_CARRIER |
| The driver supports setting the receive carrier frequency using |
| .BR LIRC_SET_REC_CARRIER . |
| .TP |
| .BR LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE |
| The driver supports |
| .BR LIRC_SET_REC_DUTY_CYCLE_RANGE . |
| .TP |
| .BR LIRC_CAN_SET_REC_CARRIER_RANGE |
| The driver supports |
| .BR LIRC_SET_REC_CARRIER_RANGE . |
| .TP |
| .BR LIRC_CAN_GET_REC_RESOLUTION |
| The driver supports |
| .BR LIRC_GET_REC_RESOLUTION . |
| .TP |
| .BR LIRC_CAN_SET_REC_TIMEOUT |
| The driver supports |
| .BR LIRC_SET_REC_TIMEOUT . |
| .TP |
| .BR LIRC_CAN_SET_REC_FILTER |
| The driver supports |
| .BR LIRC_SET_REC_FILTER . |
| .TP |
| .BR LIRC_CAN_MEASURE_CARRIER |
| The driver supports measuring of the modulation frequency using |
| .BR LIRC_SET_MEASURE_CARRIER_MODE . |
| .TP |
| .BR LIRC_CAN_USE_WIDEBAND_RECEIVER |
| The driver supports learning mode using |
| .BR LIRC_SET_WIDEBAND_RECEIVER . |
| .TP |
| .BR LIRC_CAN_NOTIFY_DECODE |
| The driver supports |
| .BR LIRC_NOTIFY_DECODE . |
| .TP |
| .BR LIRC_CAN_SEND_RAW |
| The driver supports sending using |
| .BR LIRC_MODE_RAW . |
| .TP |
| .BR LIRC_CAN_SEND_PULSE |
| The driver supports sending using |
| .BR LIRC_MODE_PULSE . |
| .TP |
| .BR LIRC_CAN_SEND_MODE2 |
| The driver supports sending using |
| .BR LIRC_MODE_MODE2 . |
| .TP |
| .BR LIRC_CAN_SEND_LIRCCODE |
| The driver supports sending. |
| (This is uncommon, since |
| .BR LIRCCODE |
| drivers reflect hardware like TV-cards which usually dos not support |
| sending.) |
| .\" |
| .SH BUGS |
| Using these devices requires the kernel source header file |
| .IR lirc.h . |
| This file is not available before kernel release 4.6. |
| Users of older kernels could use the file bundled in |
| .UR http://www.lirc.org |
| .UE . |
| .\" |
| .SH SEE ALSO |
| .BR lircd (8) |
| .P |
| https://www.kernel.org/doc/htmldocs/media_api/lirc_dev.html |