uird v1.1, Universal Infrared Receiver Daemon
Copyright 2000, 2001, 2002, Carl Bingel, bingel@dacom.se

*********************************************************************
** This software is released under the GNU General Public License. **
*********************************************************************

What is uird?
    This is a program to make stuff happend on a Linux system when you
  push a button on your remote control.
    To make this work, you must of course have an IR-receiver
  connected to your PC. A really good alternative if you're into
  building stuff your self is the UIR,
  (http://www.geocities.com/SiliconValley/Sector/3863/uir/index.html);
  which is the only device supported at the moment.
    The UIR works by sending the RC5 (encoding scheme for IR transmissions
  used by almost any remote control) codes as a 6 bytes string to the 
  serial port on the PC.

History
  2002-06-25	v1.1 released, added network support
  2000-11-18	v1.0 released to the public

Bugs
  The routine for reading from the TTY should incorporate a select
  call instead of the current thingy.
  More error checking could of course be implemented.
  The Learn-mode is kinda stupid. It does not, for example, check if the
  button is already defined in the config file.


-------------
HOW TO USE IT
-------------


Uird can work in four separate modes:
  Normal mode	This is the default mode of operation. The program
		starts with reading the config-file (uird.conf) where
		you specify what should happend when you push a
		specific button on your remote. The format of this
		file is explained later on. Then it enters an perpetual
		loop and reads ir-data and executes your commands.
  Learn mode	This mode is for the initial configuration phase and
		lets you interactively push a button on your remote
		and then enter the command that should be executed
		whenever that button is pressed. This information is
		then appended in the right format in the configation file.
  Perl mode	This mode lets a perl-script handle all intelligence.
		Everytime a button is pressed on the remote, uird calls
		a perl subroutine. Uird calls the perl routine with the
		6 byte string of ir-data. It is then all up to the
		perl routine to make all the magic stuff happen.
  Code testing	This is a mode to use for debugging and testing. All
		uird does is to write the received ir-data in a
		human readable form.
  Network mode	Send all ir-data encapsulated in UDP-packets to 
                arbitrary host/port (default localhost/5253).
		Perl-module to use as receiver is included
                as Uird.pm, example.pl is a little example how to
                use the module.


Swithes that uird understands:
  -N		Normal mode (default if no other mode-switch is specified)
  -L		Learn mode
  -P		Perl mode
  -C		Code testing mode

  -K		Kill running uird in daemon mode 
		(PID found in /var/run/uird.pid)

  -d		Daemon mode. Uird starts and goes to background operation. 
		To be combined with one of the above modes. Default is
		foreground mode (no fork). The default is foreground mode,
		which could be changed in defaults.h

  -f <file>	Specifies which config-file to use, default uird.conf
  -t <tty>	Specifies which tty the UIR is connected to, 
		default '/dev/ttyS0'
  -p <file>	Specifies which perl-script to be loaded, default 'uird.pl'
		If a file name of 'NONE' is specified, no Perl-script is
		loaded when running in Normal mode. The default value
		could be changed to NONE in defaults.h if the Perl-feature
		is not wanted.
  -s <handler>	Specifies which perl subroutine to be called everytime 
		a button is pressed when in Perl mode, default
		'uird_handler'
  -U		Network mode, sends UDP-packets with the ir-data to arbitrary
		UDP-port
  -Uaddr <addr>	Specifies which IP-address to send the data-packets to (default 
		127.0.0.1)
  -Uport <port> Specifies which port to send data-packets to (default 5253)
  -Upw <passwd>	Specifies which password to use (if any), WARNING: sent in 
		clear-text over the network


Format of uird.conf:
    Every line specifies what should happen when you push a particular button.
  Every button has it's own uniqe fingerprint, which consists of 6 bytes
  of data. This fingerprint is represented in the config file as 6 decimal
  coded numbers separated with dashes. Every lines should begin with this
  fingerprint, the followed by a colon and then action to perform when
  the button is pressed.
    The action can either be a plain shell-command (which in turn can be
  to execute another program or whatever) or a perl subroutine call.
  To call a perl subroutine, enter 'PERL_HANDLER <handler-name>' as the
  action. All other things will be interpreted by incorporating a shell.
    You can also define a default action. That action is then executed
  every time an unknown button is pressed, i.e. the fingerprint for the button
  is not specified in the config-file.
    A second special case is the always action, which is an action that gets
  executed every time a button is pressed after the ordinary button action
  has been performed.
    Blank lines or line starting with hash ('#') are ignored and may be
  used for comments.

    All this should be clear when looking at the example below:

--- uird.conf ---
23-238-129-0-0-0: echo You pushed the PLAY button!
22-30-158-0-0-0: PERL_HANDLER make_stuff_happen
21-30-174-0-0-0: /usr/bin/shutdown -h now
21-30-173-0-0-0: PERL_HANDLER make_some_other_stuff_happen
24-30-172-0-0-0: /usr/local/bin/mpg123 "/tmp/Britney Spears - Make my boobies one more size.mp3"
# Make a LED flash everytime i push a button
always: /usr/local/bin/flash_led
# Make a beep if you push an unknown button
default: echo -n -e '\a'
-----------------


  There is also an example perl script (uird.pl.ex) to show how easy it is to
write your own advanced handlers in perl.


Good luck, and feel free to give me feedback (only positive that is :).

  --Kalle, bingel@dacom.se

