1LIRC(4)                    Linux Programmer's Manual                   LIRC(4)
2
3
4

NAME

6       lirc - lirc devices
7

DESCRIPTION

9       The  /dev/lirc*  character  devices  provide a low-level bi-directional
10       interface to infra-red (IR) remotes.  When receiving data,  the  driver
11       works in two different modes depending on the underlying hardware.
12
13       Some hardware (typically TV-cards) decodes the IR signal internally and
14       just provides decoded button presses as integer  values.   Drivers  for
15       this  kind  of hardware work in LIRC_MODE_LIRCCODE mode.  Such hardware
16       usually does not support sending IR signals.  Furthermore,  it  usually
17       only works with a specific remote which is bundled with, for example, a
18       TV-card.
19
20       Other hardware provides a stream of pulse/space durations.  Such  driv‐
21       ers  work  in  LIRC_MODE_MODE2  mode.  Sometimes, this kind of hardware
22       also supports sending IR data.  Such hardware can be used with (almost)
23       any kind of remote.
24
25       The LIRC_GET_REC_MODE ioctl (see below) allows probing for the mode.
26
27   Reading input with the LIRC_MODE_MODE2 drivers
28       In  the  LIRC_MODE_MODE2  mode,  the  data returned by read(2) provides
29       32-bit values representing a space or a pulse duration,  by  convention
30       typed as lirc_t.  The time of the duration (microseconds) is encoded in
31       the lower 24 bits.  The upper 8 bit reflects the type of package:
32
33       LIRC_MODE2_SPACE.
34           Value reflects a space duration (microseconds).
35
36       LIRC_MODE2_PULSE.
37           Value reflects a pulse duration (microseconds).
38
39       LIRC_MODE2_FREQUENCY.
40           Value reflects a  frequency  (Hz);  see  the  LIRC_SET_MEASURE_CAR‐
41           RIER_MODE ioctl.
42
43       LIRC_MODE2_TIMEOUT.
44           The   package   reflects  a  timeout;  see  the  LIRC_SET_REC_TIME‐
45           OUT_REPORTS ioctl.
46
47   Reading input with the
48       LIRC_MODE_LIRCCODE drivers
49
50       In the LIRC_MODE_LIRCCODE mode, the data returned by  read(2)  reflects
51       decoded  button  presses.   The  length of each packet can be retrieved
52       using the LIRC_GET_LENGTH ioctl.  Reads must be done in blocks matching
53       the  bit  count returned by the LIRC_GET_LENGTH ioctl, rounded up so it
54       matches full bytes.
55
56   Sending data
57       When sending data, only the LIRC_MODE_PULSE  mode  is  supported.   The
58       data  written  to  the character device using write(2) is a pulse/space
59       sequence of integer values.  Pulses and spaces are only marked  implic‐
60       itly by their position.  The data must start and end with a pulse, thus
61       it must always include an odd number of samples.  The write(2) function
62       blocks  until  the  data has been transmitted by the hardware.  If more
63       data is provided than the hardware can send, the  write(2)  call  fails
64       with the error EINVAL
65

IOCTL COMMANDS

67       The  complete  list of ioctl commands is maintained in the kernel docu‐
68       mentation, see SEE ALSO.  The ioctl commands presented here is a subset
69       of the kernel documentation.
70
71       The LIRC device's ioctl definition is bound by the ioctl function defi‐
72       nition of struct file_operations, leaving us with an unsigned  int  for
73       the  ioctl command and an unsigned long for the argument.  For the pur‐
74       poses of ioctl portability  across  32-bit  and  64-bit  architectures,
75       these values are capped to their 32-bit sizes.
76
77       #include <lirc/include/media/lirc.h>    /* But see BUGS */
78       int ioctl(int fd, int cmd, ...);
79
80       The following ioctls can be used to probe or change specific lirc hard‐
81       ware  settings.   Many  require  a  third  argument,  usually  an  int.
82       referred to below as val.
83
84       In  general,  each  driver  should have a default set of settings.  The
85       driver implementation is expected to re-apply the default settings when
86       the  device  is closed by user space, so that every application opening
87       the device can rely on working with the default settings initially.
88
89   Always Supported Commands
90       /dev/lirc* devices always support the following commands:
91
92       LIRC_GET_FEATURES (void)
93           Returns a bit mask of combined features bits; see  FEATURES.   Some
94           drivers  have dynamic features which are not updated until after an
95           init() command.  If a driver does not announce support  of  certain
96           features, calling of the corresponding ioctls is undefined.
97
98       LIRC_GET_REC_MODE
99           Return the receive mode, which will be one of:
100
101           LIRC_MODE_MODE2 (void)
102                  The driver returns a sequence of pulse/space durations.
103
104           LIRC_MODE_LIRCCODE
105                  The  driver returns integer values, each of which represents
106                  a decoded button press.
107
108       If a device returns an error code for LIRC_GET_REC_MODE, it is safe  to
109       assume it is not a lirc device.
110
111   Optional Commands
112       Some  lirc  devices  support  commands  listed below.  Unless otherwise
113       stated, these fail with the error ENOIOCTLCMD or with the error  ENOSYS
114       if the operation isn't supported, or with the error EINVAL if the oper‐
115       ation failed.
116
117       LIRC_SET_REC_MODE (int)
118              Set the receive  mode.   val  is  either  LIRC_MODE_LIRCCODE  or
119              LIRC_MODE_MODE2.
120
121       LIRC_GET_LENGTH (void)
122              Return  the length of the returned codes for LIRC_MODE_LIRCCODE-
123              type drivers, otherwise fail with the error ENOIOCTLCMD.
124
125       LIRC_GET_SEND_MODE (void)
126              Return the send mode.  Currently, only LIRC_MODE_PULSE  is  sup‐
127              ported.
128
129       LIRC_SET_SEND_MODE (int)
130              Set  the  send  mode.   Currently  serves  no purpose since only
131              LIRC_MODE_PULSE is supported.
132
133       LIRC_GET_SEND_CARRIER (void)
134              Get the modulation frequency (Hz).
135
136       LIRC_SET_SEND_CARRIER (int)
137              Set the modulation frequency.  The  argument  is  the  frequency
138              (Hz).
139
140       LIRC_GET_SEND_CARRIER (void)
141              Get the modulation frequency used when decoding (Hz).
142
143       SET_SEND_DUTY_CYCLE (int)
144              Set  the  carrier  duty  cycle.   val  is  a number in the range
145              [0,100] which describes the pulse width as a percentage  of  the
146              total  cycle.  Currently, no special meaning is defined for 0 or
147              100, but the values are reserved for future use.
148
149       LIRC_GET_MIN_TIMEOUT (void), LIRC_GET_MAX_TIMEOUT (void)
150              Some devices have internal timers that can  be  used  to  detect
151              when  there's  no  IR  activity  for a long time.  This can help
152              lircd(8) in detecting that an IR  signal  is  finished  and  can
153              speed  up the decoding process.  These operations return integer
154              values  with  the  minimum/maximum  timeout  that  can  be   set
155              (microseconds).   Some  devices  have a fixed timeout.  For such
156              drivers,  LIRC_GET_MIN_TIMEOUT  and  LIRC_GET_MAX_TIMEOUT   will
157              return the same value.
158
159       LIRC_SET_REC_TIMEOUT (int)
160              Set  the integer value for IR inactivity timeout (microseconds).
161              To be accepted, the value must be within the limits  defined  by
162              LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT.  A value of 0 (if
163              supported by the hardware) disables all  hardware  timeouts  and
164              data should be reported as soon as possible.  If the exact value
165              cannot be set, then the next possible  value  greater  than  the
166              given value should be set.
167
168       LIRC_SET_REC_TIMEOUT_REPORTS (int)
169              Enable  (val  is  1)  or  disable (val is 0) timeout packages in
170              LIRC_MODE_MODE2.  By default, timeout reports should  be  turned
171              off.
172
173       LIRC_SET_REC_CARRIER (int)
174              Set the receive carrier frequency (Hz).
175
176       LIRC_SET_REC_CARRIER_RANGE (int)
177              After  opening  device, the first use of this operation sets the
178              lower bound of the carrier range, and the second  use  sets  the
179              upper bound (Hz).
180
181       LIRC_SET_MEASURE_CARRIER_MODE (int)
182              Enable  (val  is  1) or disable (val is 0) the measure mode.  If
183              enabled, from the next  key  press  on,  the  driver  will  send
184              LIRC_MODE2_FREQUENCY  packets.  By default this should be turned
185              off.
186
187       LIRC_GET_REC_RESOLUTION (void)
188              Return the driver resolution (microseconds).
189
190       LIRC_GET_MIN_FILTER_PULSE (void), LIRC_GET_MAX_FILTER_PULSE (void)
191              Some devices are able to filter out spikes in the incoming  sig‐
192              nal  using given filter rules.  These ioctls return the hardware
193              capabilities that describe the bounds of the  possible  filters.
194              Filter  settings  depend  on the IR protocols that are expected.
195              lircd(8) derives the settings  from  all  protocols  definitions
196              found in its lircd.conf(5) config file.
197
198       LIRC_GET_MIN_FILTER_SPACE (void), LIRC_GET_MAX_FILTER_SPACE (void)
199              See LIRC_GET_MIN_FILTER_PULSE.
200
201       LIRC_SET_REC_FILTER (int)
202              Pulses/spaces  shorter than this (microseconds) are filtered out
203              by hardware.
204
205       LIRC_SET_REC_FILTER_PULSE (int), LIRC_SET_REC_FILTER_SPACE (int)
206              Pulses/spaces shorter than this (microseconds) are filtered  out
207              by  hardware.   If  filters  cannot  be  set  independently  for
208              pulse/space, the corresponding ioctls must return an  error  and
209              LIRC_SET_REC_FILTER should be used instead.
210
211       LIRC_SET_TRANSMITTER_MASK
212              Enable  the set of transmitters specified in val, which contains
213              a bit mask where each enabled transmitter is  a  1.   The  first
214              transmitter  is encoded by the least significant bit, and so on.
215              When an invalid bit mask is given, for example a bit is set even
216              though the device does not have so many transmitters, this oper‐
217              ation returns the number  of  available  transmitters  and  does
218              nothing otherwise.
219
220       LIRC_SET_WIDEBAND_RECEIVER (int)
221              Some  devices  are  equipped  with  a special wide band receiver
222              which is intended to be used to learn the output of an  existing
223              remote.  This ioctl can be used to enable (val equals 1) or dis‐
224              able (val equals 0) this functionality.  This  might  be  useful
225              for  devices that otherwise have narrow band receivers that pre‐
226              vent them to be used with certain remotes.  Wide band  receivers
227              may  also  be  more precise.  On the other hand its disadvantage
228              usually is reduced range of reception.
229
230              Note: wide band receiver may be implicitly enabled if you enable
231              carrier  reports.   In that case, it will be disabled as soon as
232              you disable carrier reports.  Trying  to  disable  a  wide  band
233              receiver while carrier reports are active will do nothing.
234
235       LIRC_SETUP_START (void), LIRC_SETUP_END (void)
236              Setting  of several driver parameters can be optimized by brack‐
237              eting the actual  ioctl  calls  LIRC_SETUP_START  and  LIRC_SET‐
238              UP_END.  When a driver receives a LIRC_SETUP_START ioctl, it can
239              choose to not commit further setting  changes  to  the  hardware
240              until  a  LIRC_SETUP_END  is  received.  But this is open to the
241              driver implementation and every driver must also handle  parame‐
242              ter  changes  which are not encapsulated by LIRC_SETUP_START and
243              LIRC_SETUP_END.  Drivers can also choose to ignore these ioctls.
244
245       LIRC_NOTIFY_DECODE (void)
246              This ioctl is called by lircd(8) whenever a successful  decoding
247              of  an incoming IR signal is possible.  This can be used by sup‐
248              porting hardware to give visual user feedback,  for  example  by
249              flashing an LED.
250

FEATURES

252       The features returned by The LIRC_GET_FEATURES ioctl returns a bit mask
253       describing features of the driver.  The following bits may be  returned
254       in the mask:
255
256       LIRC_CAN_REC_RAW
257              The driver is capable of receiving using LIRC_MODE_RAW.
258
259       LIRC_CAN_REC_PULSE
260              The driver is capable of receiving using LIRC_MODE_PULSE.
261
262       LIRC_CAN_REC_MODE2
263              The driver is capable of receiving using LIRC_MODE_MODE2.
264
265       LIRC_CAN_REC_LIRCCODE
266              The driver is capable of receiving using LIRC_MODE_LIRCCODE.
267
268       LIRC_CAN_SET_SEND_CARRIER
269              The  driver  supports  changing  the  modulation frequency using
270              LIRC_SET_SEND_CARRIER.
271
272       LIRC_CAN_SET_SEND_DUTY_CYCLE
273              The   driver   supports   changing   the   duty   cycle    using
274              LIRC_SET_SEND_DUTY_CYCLE.
275
276       LIRC_CAN_SET_TRANSMITTER_MASK
277              The  driver  supports  changing  the active transmitter(s) using
278              LIRC_SET_TRANSMITTER_MASK.
279
280       LIRC_CAN_SET_REC_CARRIER
281              The driver supports setting the receive carrier frequency  using
282              LIRC_SET_REC_CARRIER.
283
284       LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE
285              The driver supports LIRC_SET_REC_DUTY_CYCLE_RANGE.
286
287       LIRC_CAN_SET_REC_CARRIER_RANGE
288              The driver supports LIRC_SET_REC_CARRIER_RANGE.
289
290       LIRC_CAN_GET_REC_RESOLUTION
291              The driver supports LIRC_GET_REC_RESOLUTION.
292
293       LIRC_CAN_SET_REC_TIMEOUT
294              The driver supports LIRC_SET_REC_TIMEOUT.
295
296       LIRC_CAN_SET_REC_FILTER
297              The driver supports LIRC_SET_REC_FILTER.
298
299       LIRC_CAN_MEASURE_CARRIER
300              The  driver supports measuring of the modulation frequency using
301              LIRC_SET_MEASURE_CARRIER_MODE.
302
303       LIRC_CAN_USE_WIDEBAND_RECEIVER
304              The  driver  supports   learning   mode   using   LIRC_SET_WIDE‐
305              BAND_RECEIVER.
306
307       LIRC_CAN_NOTIFY_DECODE
308              The driver supports LIRC_NOTIFY_DECODE.
309
310       LIRC_CAN_SEND_RAW
311              The driver supports sending using LIRC_MODE_RAW.
312
313       LIRC_CAN_SEND_PULSE
314              The driver supports sending using LIRC_MODE_PULSE.
315
316       LIRC_CAN_SEND_MODE2
317              The driver supports sending using LIRC_MODE_MODE2.
318
319       LIRC_CAN_SEND_LIRCCODE
320              The  driver supports sending.  (This is uncommon, since LIRCCODE
321              drivers reflect hardware like TV-cards  which  usually  dos  not
322              support sending.)
323

BUGS

325       Using  these  devices  requires  the  kernel source header file lirc.h.
326       This file is not available before kernel release 4.6.  Users  of  older
327       kernels could use the file bundled in ⟨http://www.lirc.org⟩.
328

SEE ALSO

330       lircd(8)
331
332       https://www.kernel.org/doc/htmldocs/media_api/lirc_dev.html
333

COLOPHON

335       This  page  is  part of release 4.16 of the Linux man-pages project.  A
336       description of the project, information about reporting bugs,  and  the
337       latest     version     of     this    page,    can    be    found    at
338       https://www.kernel.org/doc/man-pages/.
339
340
341
342Linux                             2016-07-17                           LIRC(4)
Impressum