NAME

Lirc::Client - A client library for the Linux Infrared Remote Control

SYNOPSIS

  use Lirc::Client;
  ...
  my $lirc = Lirc::Client->new( 'progname' );
  my $code;
  do {                            # Loop while getting ir codes
    $code = $lirc->next_code;     # wait for a new ir code
    print "Lirc> $code\n";
    process( $code );             # do whatever you want with the code
  } while( defined $code );       # undef will be returned when lirc dev exists

DESCRIPTION

This module provides a simple interface to the Linux Infrared Remote Control (Lirc). The module encasuplates parsing the Lirc config file (.lircrc), openning a connection to the Lirc device, and retrieving events from the device.

Use Details

new( program, [rcfile], [dev], [debug], [fake] )

new( program, \%options )

  my $lirc = Lirc::Client->new( {    
               prog    => 'progname',           # required
               rcfile  => "$ENV{HOME}/.lircrc", # optional
               dev     => "/dev/lircd",         # optional
               debug   => 0,                    # optional
               fake    => 1,                    # optional
        } );

  # Depreciated positional syntax; don't use
  my $lirc = Lirc::Client->new( 'progname',    # required
               "$ENV{HOME}/.lircrc",           # optional
               '/dev/lircd', 0, 0 );           # optional

The constructor accepts two calling forms: an ordered list (for backwards compatibility), and a hash ref of configuration options. The two forms can be combined as long as the hash ref is last.

When called the constructor defines the program token used in the Lirc config file, opens and parses the Lirc config file (rcfile defaults to ~/.lircrc if none specified), connects to the Lirc device (dev defaults to /dev/lircd if none specified), and returns the Lirc::Client object. Pass a true value for debug to have various debug information printed (defaults to false). A true value for the fake flag will cause Lirc::Client to read STDIN rather than the lircd device (defaults to false), which is primarily useful for debuging.

recognized_commands()

  my @list = $lirc->recongnized_commands;

Returns a list of all the recongnized commands for this application (as defined in prog parameter to the call to new).

next_code()

nextcode()

  my $code = $lirc->next_code;

Retrieves the next IR command associated with the progname as defined in new(), blocking if none is available. next_code uses the stdio read commands which are buffered. Use next_codes if you are also using select.

next_codes()

nextcodes()

  my @codes = $lirc->next_codes;

Retrieves any IR commands associated with the progname as defined in the new() constructor, blocking if none are available. next_codes uses sysread so it is compatible with select driven event loops. This is the most efficient method to accomplish a non-blocking read.

Due to the mechanics of sysread and select, this version may return multiple ir codes so the return value is an array.

Here is an example using IO::Select:

    use IO::Select;
    ....
    my $select = IO::Select->new();
    $select->add( $lirc->sock );
    while(1){
        # do your own stuff, if you want
        if( my @ready = $select->can_read(0) ){ 
            # an ir event has been received (if you are tracking other
                        # filehandles, you need to make sure it is lirc)
            my @codes = $lirc->next_codes;    # should not block
            for my $code (@codes){
                process( $code );
            }
        }
    }

This is much more efficient than looping over next_code in non-blocking mode. See the select.t test for the complete example. Also, checkout the Event module on cpan for a nice way to handle your event loops.

sock()

  my $sock = $lirc->sock;

Returns (or sets if an arguement is passed) the socket from which to read lirc commands. This can be used to work Lirc::Client into you own event loop.

parse_line()

  my $code = $lirc->parse_line( $line );

Takes a full line as read from the lirc device and returns code on the config line of the lircrc file for that button. This can be used in combination with sock to take more of the event loop control out of Lirc::Cli

clean_up()

  $lirc->clean_up;

Closes the Lirc device pipe, etc. clean_up will be called when the lirc object goes out of scope, so this is not necessary.

debug()

  $lirc->debug;

Return the debug status for the lirc object.

TODO

Features that are outlined in the .lircrc specification which have not yet been implmeneted include:

The mode should be independent of the prog token
Implement the once flag
Implement the quit flag and executing multiple entries
Support for multiple config entries
Implement the delay token
Supprot non-printable charaters in the config command
Support key sequenses (multiple remote, button entries per block)
Support VERSION and LIST commands
Watch for signals from lircd to re-read rc file (SIGHUP)
Add SEND_* support

Features that have been recently implemented include:

Support for modes
Recognizing the startup_mode flag and automatically starting in a mode that is identical to the program name
The include directive
Support wild card * entries for remote or button, and blocks that lack a remote

If anyone has need of one or more of these features, please let me know (via http://rt.cpan.org if possible).

AUTHOR

Mark Grimes <mgrimes@cpan.org>

BUGS

There are a few features that a .lircrc file is supposed to support (according to http://www.lirc.org/html/configure.html#lircrc_format) that have not yet been implemented. See TODO for a list.

See http://rt.cpan.org to view and report bugs

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.2 or, at your option, any later version of Perl 5 you may have available.

CPAN RT