			     Linux xringd
				    by
		      Angelo Haritsis <ah@doc.ic.ac.uk>

GENERAL
-------

How about having your home computer connect to your office or your
provider, turn the air-conditioner on/off or activate _any_ command when
you are not at home? Simple, you would say. Well, imagine now that your
home modem does not have voice/DTMF-capabilities and you can use no
modem to dialup your home. The only thing you ahve is a common telephone.
Furthermore (even if you DO have a modem), you might wish your home
computer to execute a choice of different commands _without_ its modem
going off hook (consequently not paying for any connection).

xringd, the Extended Ring Daemon can do it for you. And a bit more.
It will monitor the serial line for RING signals and activate commands
if specific "ring-delay sequences" are probed.

It will also allow you to execute a command per ring probed. This
allows you to replace your boring phoneset rings with sounds
from your sound card or even with messages displayed on screens
on machine(s) on your network!

How do you actually signal your linux machine to execute different commands?
You just make it receive rings and delays between them that follow
specific patterns (as defined in a configuration file). Different 
patterns activate different commands. For example:
Produce a single ring, wait from 10-25 seonds, produce another single ring.
If no rings appear after this for 30 seconds your linux pc starts up
a connection with your office1!

You can build configuration files that can accept a wealth of ring-delay
patterns and excute different commands upon recognition of each one.

xringd will NOT affect any programs using the serial line. It can even
coexist with your getty. Just make sure that your getty does not pick up
the phone too early so that it gives you some time to "play" with 
your ring "patterns". It uses 2 new ioctls found on official Linux 
kernels of version 1.3.48 and up (ioctl's implemented by the same author).

The most inventive minds will probably make this work without even using
a modem (I have no idea how easy it is to produce a circuit which will
assert the RI line on a UART when the telephone rings - perhaps use the
UART already taken by the mouse - RI is not used on it!).  If you have a
useful idea on this, let me know so that I can include it with this
package. But probably one could use an old 300/1200/2400bps modem and do
the same job on lower cost!

Make sure you read carefully the manual page provided.

Please try this program and send me any comments or bug reports/patches
via email.


TO INSTALL
----------

Change default installation dirs in Makefile if you wish.
Other defaults are mostly ok.
Type: make install

You can run xringd as ANY user. The commands that it can execute are
subject to the permision of the user running xringd. Usually you
run it as root.

For debugging you should uncomment this line from Makefile
#DBG=-DRINGSM_DEBUG
and recompile ringsm.c
Then you should run xringd as: xringd -c config -d
Remember when building the final version to build ringsm.c with no debugging!


HARDWARE
--------

You will need a 16xx0x (most prevalent) uart (the needed kernel ioctls
are currently implemented only for this family) and a fully connected modem
cable if using an external modem (the RI line MUST be connected!).
16xx0x family includes: 8250 82450 16450 16450A 16c450 16550 16550A 16552
and compatible.

KERNEL PATCH
------------

NB: This patch is NOT NEEDED! xinrgd has been tested to work fine on many
setups and all the "stock" kernels after 1.3.48. It is just suggested as
a quick thing to try if you have problems with xringd reporting errors
endlessly.

This kernel patch will make xringd not receive an EIO (or other) error on 
ioctl. The EIO case is taken care of in xringd. However, this patch will
prevent any errors from the ioctl.
drivers/char/tty_io.c, function hung_up_tty_ioctl(). Add before: return -EIO;
	if (cmd == TIOCMIWAIT || cmd == TIOCGICOUNT)
		return tty_ioctl(inode, file, cmd, arg);  

THANKS
------
For beta testing and useful comments, I must not forget to extend my 
thanks to the following people:
Richard Huveneers <huveneer@math.ruu.nl>
Gary Houston <ghouston@actrix.gen.nz>
Mattheos Papavasiliou <mattheos@archinet.demon.co.uk>
Andrea Arcangeli <arcangeli@mbox.queen.it>



-------------------------------------------------------------------
Copyright (c) 1995-1997 Angelo Haritsis. All rights reserved.

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option)
any later version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
more details.

You should have received a copy of the GNU General Public License
along with this program; see the file COPYING.  If not, write to
the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
