LIRC

Section: Linux Programmer's Manual (4)


Updated: Aug 2015


Index Return to Main Contents
 

NAME

lirc - lirc devices

 

DESCRIPTION

/dev/lirc* are character devices providing a low-level bi-directional interface to IR remotes. When receiving data the driver works in two different modes depending on the underlying hardware.

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 works in LIRC_MODE_LIRCCODE. Such hardware usually does not support sending IR signals. Furthermore, it usually only works with a specific remote which is bundled with e. g., a TV-card.

Other hardware provides a stream of pulse/space durations. Such drivers works in LIRC_MODE_MODE2. Sometimes, this kind of hardware also supports sending IR data. It can be used with (almost) any kind of remote.

The LIRC_GET_REC_MODE ioctl allows probing for the mode.

 

Reading using LIRC_MODE_MODE2 drivers

In the LIRC_MODE_MODE2 mode, the driver read() provides 32-bit values representing a space or a pulse duration, by convention typed as lirc_t. The time of the duration (us) is encoded in the lower 24 bits. The upper 8 bit reflects the type of package:

LIRC_MODE2_SPACE
Value reflects a space duration (us).
LIRC_MODE2_PULSE
Value reflects a pulse duration (us).
LIRC_MODE2_FREQUENCY
Value reflects a frequency (hz), see the LIRC_SET_MEASURE_CARRIER ioctl.
LIRC_MODE2_TIMEOUT
The package reflects a timeout, see the LIRC_SET_REC_TIMEOUT_REPORTS ioctl.

 

Reading using LIRC_MODE_LIRCCODE drivers.

In the LIRC_MODE_LIRCCODE mode, the data returned by read() reflects decoded button presses. The length of each packet could be retrieved using the LIRC_GET_LENGTH ioctl. read() on the device must be done in blocks matching the bit count, rounded up so it matches full bytes.

 

Sending data.

When sending data, only the LIRC_MODE_PULSE mode is supported. The data written to the chardev using write() 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 write() function blocks until the data has been transmitted by the hardware. If more data is provided than the hardware can send, the driver returns EINVAL

 

SUPPORTED IOCTL COMMANDS

#include " (uapi/lirc.h)"
int ioctl(int fd, int cmd, ...);

The following ioctls can be used to to probe or change specific lirc hardware settings. Many require a third argument, usually an int.

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 userspace, so that every application opening the device can rely on working with the default settings initially.

 

Always Supported Commands

/dev/lirc* devices always supports the following commands:

LIRC_GET_FEATURES void
Returns a bitmask of combined features bits, see FEATURES. Some drivers have dynamic features which are not updated until after an init() command.
LIRC_GET_REC_MODE void
Returns the receive mode, one of
LIRC_MODE_MODE2
Driver return a sequence of pulse/space durations.
LIRC_MODE_LIRCCODE
Driver returns integer values, each of which representing a decoded button press.

If a device returns a negative error code for LIRC_GET_REC_MODE it is safe to assume it is not a lirc device.

 

Optional Commands

Some lirc devices supports the following commands. Unless otherwise stated these returns -ENOIOCTLCMD or -ENOSYS if the operation isn't supported and -EINVAL if operation failed.

LIRC_SET_REC_MODE (int)
Set the receive mode, either LIRC_MODE_LIRCCODE or LIRC_MODE_MODE2.

LIRC_GET_LENGTH (void)
Return the positive length of the returned codes for LIRC_LIRCCODE type drivers, otherwise -ENOIOCTLCMD.
LIRC_GET_SEND_MODE (void)
Returns the send mode; currently only LIRC_MODE_PULSE is supported.
LIRC_SET_SEND_MODE (int)
Set the send mode. Obsolete since only LIRC_MODE_PULSE is supported.
LIRC_SET_SEND_CARRIER (int)
Set the modulation frequency. The argument is the frequency (Hz).
SET_SEND_DUTY_CYCLE (int)
Set the carrier duty cycle. The argument is an int (0 <= value <= 100) which describes the pulse width in percent of the total cycle. Currently, no special meaning is defined for 0 or 100, but the values are reserved for future use.
LIRC_GET_MIN_TIMEOUT (void), LIRC_GET_MAX_TIMEOUT (void)
Some devices have internal timers that can be used to detect when there's no IR activity for a long time. This can help lircd in detecting that a IR signal is finished and can speed up the decoding process. Returns an integer value with the minimum/maximum timeout that can be set. Some devices have a fixed timeout, in that case both ioctls will return the same value even though the timeout cannot be changed.
LIRC_SET_REC_TIMEOUT (int)
Sets the integer value for IR inactivity timeout. To be accepted, the value must be within the limits defined by LIRC_GET_MIN_TIMEOUT and 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 greater than the given value should be set.
LIRC_SET_REC_TIMEOUT_REPORTS (int)
Enables/disables (1/0) timeout packages in LIRC_MODE_MODE2. By default, timeout reports should be turned off.
LIRC_SET_REC_CARRIER (int)
Set the receive carrier frequency (Hz).
LIRC_SET_REC_CARRIER_RANGE (int)
First time called sets the lower bound of the carrier range, second time the upper bound (Hz).
LIRC_SET_MEASURE_CARRIER (int)
Enable/disable (1/0) the measure mode. If enabled, from the next key press on, the driver will send LIRC_MODE2_FREQUENCY packets. By default this should be turned off.
LIRC_GET_REC_RESOLUTION (void)
Returns the driver resolution (us).
LIRC_GET_MIN_FILTER_PULSE void, LIRC_GET_MAX_FILTER_PULSE void
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. lircd derives the settings from all protocols definitions found in its config file.
LIRC_GET_MIN_FILTER_SPACE (void), LIRC_GET_MAX_FILTER_SPACE (void)
See LIRC_GET_MIN_FILTER_PULSE
LIRC_SET_REC_FILTER (int)
Pulses/spaces shorter than this (us) are filtered out by hardware.
LIRC_SET_REC_FILTER_PULSE (int), LIRC_SET_REC_FILTER_SPACE (int)
Pulses/spaces shorter than this (us) are filtered out by hardware. If filters cannot be set independently for pulse/space, the corresponding ioctls must return an error and LIRC_SET_REC_FILTER shall be used instead.
LIRC_SET_WIDEBAND_RECEIVER (int)
Some receivers are equipped with special wide band receiver which is intended to be used to learn output of existing remote. Calling that ioctl with (1) will enable it, and with (0) disable it. This might be useful of receivers that have otherwise narrow band receiver that prevents them to be used with some remotes. Wide band receiver might also be more precise. On the other hand its disadvantage usually is reduced range of reception. Note: wide band receiver might be implictly enabled if you enable carrier reports. In that case it will be disabled as soon as you disable carrier reports. Trying to disable wide band receiver while carrier reports are active will do nothing

LIRC_SETUP_START (void), LIRC_SETUP_END (void)
Setting of several driver parameters can be optimized by encapsulating the according ioctl calls with LIRC_SETUP_START/LIRC_SETUP_END. When a driver receives a LIRC_SETUP_START ioctl it can choose to not commit further setting changes to the hardware until a 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 LIRC_SETUP_START and LIRC_SETUP_END. Drivers can also choose to ignore these ioctls.

LIRC_NOTIFY_DECODE (void)
This ioctl is called by lircd whenever a successful decoding of an incoming IR signal could be done. This can be used by supporting hardware to give visual user feedback e.g., by flashing a LED.

 

FEATURES

The features returned by LIRC_GET_FEATURES is a bitmask combining the following bits.

LIRC_CAN_REC_RAW
The driver is capable of receiving using LIRC_MODE_RAW
LIRC_CAN_REC_PULSE
The driver is capable of receiving using LIRC_MODE_PULSE
LIRC_CAN_REC_MODE2
The driver is capable of receiving using LIRC_MODE_MODE2
LIRC_CAN_REC_LIRCCODE
The driver is capable of receiving using LIRC_MODE_LIRCCODE
LIRC_CAN_SET_SEND_CARRIER
Driver supports changing the modulation frequency using LIRC_SET_SEND_CARRIER.
LIRC_CAN_SET_SEND_DUTY_CYCLE
Driver supports changing the duty cycle using LIRC_SET_SEND_DUTY_CYCLE.
LIRC_CAN_SET_TRANSMITTER_MASK
Enables the given set of transmitters. The first transmitter is encoded by the least significant bit, etc. When an invalid bit mask is given e. g., a bit is set even though the device does not have so many transmitters, returns the number of available transitters and does nothing otherwise.
LIRC_CAN_SET_REC_CARRIER
Drvier supports setting the receive carrier frequency using LIRC_SET_REC_CARRIER.
LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE
Driver supports LIRC_SET_REC_DUTY_CYCLE_RANGE
LIRC_CAN_SET_REC_CARRIER_RANGE
Driver supports LIRC_SET_REC_CARRIER_RANGE
LIRC_CAN_GET_REC_RESOLUTION
Driver supports LIRC_GET_REC_RESOLUTION
LIRC_CAN_SET_REC_TIMEOUT
Driver supports LIRC_SET_REC_TIMEOUT
LIRC_CAN_SET_REC_FILTER
Driver supports LIRC_SET_REC_FILTER
LIRC_CAN_MEASURE_CARRIER
Driver supports measuring of the modulation frequency using LIRC_MEASURE_CARRIER
LIRC_CAN_USE_WIDEBAND_RECEIVER
Driver supports learning mode using LIRC_SET_WIDEBAND_RECEIVER
LIRC_CAN_NOTIFY_DECODE
Driver supports LIRC_NOTIFY_DECODE.
LIRC_CAN_SEND_RAW
Driver supports sending using LIRC_SEND_RAW
LIRC_CAN_SEND_PULSE
Driver supports sending using LIRC_MODE_PULSE
LIRC_CAN_SEND_MODE2
Driver supports sending using LIRC_SEND_MODE2
LIRC_CAN_SEND_LIRCCODE
Driver supports sending LIRC_SEND_LIRCCODE (this is uncommon, since LIRCCODE drivers reflects hardware like TV-cards which usually does not support sending.)

 

BUGS

Using these devices requires the kernel source header file lirc.h. That this file is not public is a bug, see https://bugzilla.kernel.org/show_bug.cgi?id=75751.

This manual page should really be part of the upstream man-pages project.

 

SEE ALSO

https://www.kernel.org/doc/htmldocs/media_api/lirc_dev.html


 

Index

NAME
DESCRIPTION
Reading using LIRC_MODE_MODE2 drivers
Reading using LIRC_MODE_LIRCCODE drivers.
Sending data.
SUPPORTED IOCTL COMMANDS
Always Supported Commands
Optional Commands
FEATURES
BUGS
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 19:29:43 GMT, August 09, 2016