LIRC libraries
LinuxInfraredRemoteControl
|
Driver API manual excerpt. More...
Driver API manual excerpt.
This document describes the API used by the LIRC userspace drivers in version 2.
It is targeted at active C programmers, and not written with the intention to be understandable by non-programmers.
The guide aims at being fully compatible with the upcoming release LIRC 0.9.2. (CLARIFY)
There are three kinds of drivers in LIRC:
Kernel drivers will not be covered in the present article. User space drivers are nothing else but normal compiled C functions, running as the invoking user (which may or may not be root). Therefore, the decomposition between "program" and driver is a priori not always necessary, but instead serves modularization and structuring.
In the beginning, due to its focus on very simple hardware, LIRC was very centered around kernal modules like directly connected LEDs or IR sensors. Modern hardware, due to embedded micro processors etc., have less requirements on precise timing, and user space drivers are normally the preferred solution. One such driver consists of a C file, containing a number of function, which are linked into the executing program (e. g., Lircd). Traditionally (at least for LIRC) linking takes place during the build process (statically linking). The API for these drivers we will call "Driver API version 1".
Dynamically loaded drivers was introduced LIRC just recently, replacing the statically linked drivers. It turned out to be necessary to slighty augment the driver API version 1. The new version will be referred to as "Driver API version 2".
In this guide, the word plugin refers to the so-file on disk. Each such file contains one or more driver(s) visible in the user interface.
An IR signal consists of a sequence of on-times (pulses) and off-times (gaps). (We disregard modulation for the time being.) A full-fledged IR driver, on reading, can deliver the timing of these period ("durations"). On sending, it can be fed with a list of durations, and it sends these on- and off-periods as (modulated) IR signals. Such a piece of hardware is suitable for receiving and/or transmitting "arbitrary" IR sequences.
Much IR hardware was not designed as general-purpose IR hardware, but to allow e.g. a laptop computer or a TV card to be be controlled by the supplied remote. This hardware in general decodes the IR signal in its own hardware, and delivers, for recognized signals, an integer code denoting the code received (like "play"). For signals not following the protocol, no output is generated. This property is indicated in the drivers as the feature LIRC_CAN_REC_LIRCCODE
.
As usable and flexible IR hardware for LIRC, these devices are second choice. The "learns" (configuration files) from such a device is of very limited value, and not portable to other IR devices, since timing information is missing. In the configuration file, this can be determined by the lines one 0 0
and one 0 0
, which is clearly not usable without the context, namely the hardware used for capturing.
This guide is intended for programmers writing and maintain "real" drivers.
At the time of writing, there are about 44 plugins and 54 drivers. Of the drivers, 13 are "general receivers"; the others are LIRCCODE drivers. (The actual numbers vary depending on configuration i. e. libraries installed on the build system.) Since hardware related to LIRCCODE drivers (typically a TV-card) normally doesn't support sending there is no LIRCCODE driver which can send data.
The tool lirc-lsplugins can be used to generate overviews of the drivers and their capabilities.
A (user space) driver is a C file where all the functions are declared static
, i.e. not (directly) visible from outside of the file. The only thing visible from outside is a particular data structure, containing some data elements, and some pointers to functions, that in these way effectively are made public API. In this way a certain encapsulation is achieved. The data structure will be described next.
struct driver
The struct driver
is the data structure representing the driver for LIRC. It is defined in driver.h
(in directory lib
).
struct driver { char device; int fd; __u32 features; __u32 send_mode; __u32 rec_mode; __u32 code_length; int (*init_func) (void); int (*deinit_func) (void); int (*send_func) (struct ir_remote remote, struct ir_ncode* code); char* (rec_func) (struct ir_remote remotes); int (decode_func) (struct ir_remote remote, struct decode_ctx_t* ctx); int (drvctl_func) (unsigned int cmd, void arg); lirc_t(*readdata) (lirc_t timeout); char *name; unsigned int resolution;
/* The following fields are API version 2 extensions