Reading input with the LIRC_MODE_MODE2 drivers¶

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

LIRC_MODE2_SPACE.

Value reflects a space duration (microseconds).

LIRC_MODE2_PULSE.

Value reflects a pulse duration (microseconds).

LIRC_MODE2_FREQUENCY.

Value reflects a frequency (Hz); see the LIRC_SET_MEASURE_CARRIER_MODE ioctl.

LIRC_MODE2_TIMEOUT.

The package reflects a timeout; see the LIRC_SET_REC_TIMEOUT_REPORTS ioctl.

Reading input with the¶

LIRC_MODE_LIRCCODE drivers

In the LIRC_MODE_LIRCCODE mode, the data returned by read(2) reflects decoded button presses. The length of each packet can be retrieved using the LIRC_GET_LENGTH ioctl. Reads must be done in blocks matching the bit count returned by the LIRC_GET_LENGTH ioctl, 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 character device using 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 write(2) function blocks until the data has been transmitted by the hardware. If more data is provided than the hardware can send, the write(2) call fails with the error EINVAL

Always Supported Commands¶

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

LIRC_GET_FEATURES (void)

Returns a bit mask of combined features bits; see FEATURES. Some drivers have dynamic features which are not updated until after an init() command. If a driver does not announce support of certain features, calling of the corresponding ioctls is undefined.

LIRC_GET_REC_MODE

Return the receive mode, which will be one of:

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

Optional Commands¶

Some lirc devices support commands listed below. Unless otherwise stated, these fail with the error ENOIOCTLCMD or with the error ENOSYS if the operation isn't supported, or with the error EINVAL if the operation failed.

LIRC_SET_REC_MODE (int)

Set the receive mode. val is either LIRC_MODE_LIRCCODE or LIRC_MODE_MODE2.

LIRC_GET_LENGTH (void)

Return the length of the returned codes for LIRC_MODE_LIRCCODE-type drivers, otherwise fail with the error ENOIOCTLCMD.

LIRC_GET_SEND_MODE (void)

Return the send mode. Currently, only LIRC_MODE_PULSE is supported.

LIRC_SET_SEND_MODE (int)

Set the send mode. Currently serves no purpose since only LIRC_MODE_PULSE is supported.

LIRC_GET_SEND_CARRIER (void)

Get the modulation frequency (Hz).

LIRC_SET_SEND_CARRIER (int)

Set the modulation frequency. The argument is the frequency (Hz).

LIRC_GET_SEND_CARRIER (void)

Get the modulation frequency used when decoding (Hz).

SET_SEND_DUTY_CYCLE (int)

Set the carrier duty cycle. 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.

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(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, LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT will return the same value.

LIRC_SET_REC_TIMEOUT (int)

Set the integer value for IR inactivity timeout (microseconds). 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)

Enable (val is 1) or disable (val is 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)

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).

LIRC_SET_MEASURE_CARRIER_MODE (int)

Enable (val is 1) or disable (val is 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)

Return the driver resolution (microseconds).

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(8) derives the settings from all protocols definitions found in its lircd.conf(5) 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 (microseconds) are filtered out by hardware.

LIRC_SET_REC_FILTER_PULSE (int), LIRC_SET_REC_FILTER_SPACE (int)

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 LIRC_SET_REC_FILTER should be used instead.

LIRC_SET_TRANSMITTER_MASK

Enable the set of transmitters specified in 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.

LIRC_SET_WIDEBAND_RECEIVER (int)

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 (val equals 1) or disable (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.

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.

LIRC_SETUP_START (void), LIRC_SETUP_END (void)

Setting of several driver parameters can be optimized by bracketing the actual ioctl calls LIRC_SETUP_START and 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(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.