254 lines
10 KiB
XML
254 lines
10 KiB
XML
<section id="lirc_dev">
|
|
<title>LIRC Device Interface</title>
|
|
|
|
|
|
<section id="lirc_dev_intro">
|
|
<title>Introduction</title>
|
|
|
|
<para>The LIRC device interface is a bi-directional interface for
|
|
transporting raw IR data between userspace and kernelspace. Fundamentally,
|
|
it is just a chardev (/dev/lircX, for X = 0, 1, 2, ...), with a number
|
|
of standard struct file_operations defined on it. With respect to
|
|
transporting raw IR data to and fro, the essential fops are read, write
|
|
and ioctl.</para>
|
|
|
|
<para>Example dmesg output upon a driver registering w/LIRC:</para>
|
|
<blockquote>
|
|
<para>$ dmesg |grep lirc_dev</para>
|
|
<para>lirc_dev: IR Remote Control driver registered, major 248</para>
|
|
<para>rc rc0: lirc_dev: driver ir-lirc-codec (mceusb) registered at minor = 0</para>
|
|
</blockquote>
|
|
|
|
<para>What you should see for a chardev:</para>
|
|
<blockquote>
|
|
<para>$ ls -l /dev/lirc*</para>
|
|
<para>crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0</para>
|
|
</blockquote>
|
|
</section>
|
|
|
|
<section id="lirc_read">
|
|
<title>LIRC read fop</title>
|
|
|
|
<para>The lircd userspace daemon reads raw IR data from the LIRC chardev. The
|
|
exact format of the data depends on what modes a driver supports, and what
|
|
mode has been selected. lircd obtains supported modes and sets the active mode
|
|
via the ioctl interface, detailed at <xref linkend="lirc_ioctl"/>. The generally
|
|
preferred mode is LIRC_MODE_MODE2, in which packets containing an int value
|
|
describing an IR signal are read from the chardev.</para>
|
|
|
|
<para>See also <ulink url="http://www.lirc.org/html/technical.html">http://www.lirc.org/html/technical.html</ulink> for more info.</para>
|
|
</section>
|
|
|
|
<section id="lirc_write">
|
|
<title>LIRC write fop</title>
|
|
|
|
<para>The data written to the chardev 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, therefore, the data must always include
|
|
an uneven number of samples. The write function must block until the data has
|
|
been transmitted by the hardware.</para>
|
|
</section>
|
|
|
|
<section id="lirc_ioctl">
|
|
<title>LIRC ioctl fop</title>
|
|
|
|
<para>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 arg. For the purposes
|
|
of ioctl portability across 32-bit and 64-bit, these values are capped
|
|
to their 32-bit sizes.</para>
|
|
|
|
<para>The following ioctls can be used to change specific hardware settings.
|
|
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.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>LIRC_GET_FEATURES</term>
|
|
<listitem>
|
|
<para>Obviously, get the underlying hardware device's features. If a driver
|
|
does not announce support of certain features, calling of the corresponding
|
|
ioctls is undefined.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LIRC_GET_SEND_MODE</term>
|
|
<listitem>
|
|
<para>Get supported transmit mode. Only LIRC_MODE_PULSE is supported by lircd.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LIRC_GET_REC_MODE</term>
|
|
<listitem>
|
|
<para>Get supported receive modes. Only LIRC_MODE_MODE2 and LIRC_MODE_LIRCCODE
|
|
are supported by lircd.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LIRC_GET_SEND_CARRIER</term>
|
|
<listitem>
|
|
<para>Get carrier frequency (in Hz) currently used for transmit.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LIRC_GET_REC_CARRIER</term>
|
|
<listitem>
|
|
<para>Get carrier frequency (in Hz) currently used for IR reception.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LIRC_{G,S}ET_{SEND,REC}_DUTY_CYCLE</term>
|
|
<listitem>
|
|
<para>Get/set the duty cycle (from 0 to 100) of the carrier signal. Currently,
|
|
no special meaning is defined for 0 or 100, but this could be used to switch
|
|
off carrier generation in the future, so these values should be reserved.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LIRC_GET_REC_RESOLUTION</term>
|
|
<listitem>
|
|
<para>Some receiver have maximum resolution which is defined by internal
|
|
sample rate or data format limitations. E.g. it's common that signals can
|
|
only be reported in 50 microsecond steps. This integer value is used by
|
|
lircd to automatically adjust the aeps tolerance value in the lircd
|
|
config file.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LIRC_GET_M{IN,AX}_TIMEOUT</term>
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LIRC_GET_M{IN,AX}_FILTER_{PULSE,SPACE}</term>
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LIRC_GET_LENGTH</term>
|
|
<listitem>
|
|
<para>Retrieves the code length in bits (only for LIRC_MODE_LIRCCODE).
|
|
Reads on the device must be done in blocks matching the bit count.
|
|
The bit could should be rounded up so that it matches full bytes.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LIRC_SET_{SEND,REC}_MODE</term>
|
|
<listitem>
|
|
<para>Set send/receive mode. Largely obsolete for send, as only
|
|
LIRC_MODE_PULSE is supported.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LIRC_SET_{SEND,REC}_CARRIER</term>
|
|
<listitem>
|
|
<para>Set send/receive carrier (in Hz).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LIRC_SET_TRANSMITTER_MASK</term>
|
|
<listitem>
|
|
<para>This enables the given set of transmitters. The first transmitter
|
|
is encoded by the least significant bit, etc. When an invalid bit mask
|
|
is given, i.e. a bit is set, even though the device does not have so many
|
|
transitters, then this ioctl returns the number of available transitters
|
|
and does nothing otherwise.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LIRC_SET_REC_TIMEOUT</term>
|
|
<listitem>
|
|
<para>Sets the integer value for IR inactivity timeout (cf.
|
|
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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LIRC_SET_REC_TIMEOUT_REPORTS</term>
|
|
<listitem>
|
|
<para>Enable (1) or disable (0) timeout reports in LIRC_MODE_MODE2. By
|
|
default, timeout reports should be turned off.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LIRC_SET_REC_FILTER_{,PULSE,SPACE}</term>
|
|
<listitem>
|
|
<para>Pulses/spaces shorter than this 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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LIRC_SET_MEASURE_CARRIER_MODE</term>
|
|
<listitem>
|
|
<para>Enable (1)/disable (0) 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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LIRC_SET_REC_{DUTY_CYCLE,CARRIER}_RANGE</term>
|
|
<listitem>
|
|
<para>To set a range use LIRC_SET_REC_DUTY_CYCLE_RANGE/LIRC_SET_REC_CARRIER_RANGE
|
|
with the lower bound first and later LIRC_SET_REC_DUTY_CYCLE/LIRC_SET_REC_CARRIER
|
|
with the upper bound.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LIRC_NOTIFY_DECODE</term>
|
|
<listitem>
|
|
<para>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 feedback to the user e.g. by flashing a LED.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LIRC_SETUP_{START,END}</term>
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LIRC_SET_WIDEBAND_RECEIVER</term>
|
|
<listitem>
|
|
<para>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 it usually 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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<section id="lirc_dev_errors">
|
|
&return-value;
|
|
</section>
|
|
</section>
|
|
</section>
|