Elseed - A simple program to display caller-id information on your TiVo
=======================================================================

NOTE: This software comes with no warranty. I accept no responsibility 
for anything that might happen to your hardware/software/configuration 
as a result of using this software. For all I know, this software 
might make your TiVo explode. USE THIS SOFTWARE AT YOUR OWN RISK. 

WHAT IS ELSEED?
---------------

This is a simple little C program that will open your modem device 
on your TiVo, listen for caller-id information, and then display the 
caller's name and number on your TV screen. This software is 
supposed to (and does as far as I can tell) not interfere with the 
daily call that Tivo makes and the monthly(?) call to DirecTV that 
the DirecTivo makes.

WHAT DO I NEED?
---------------

1. A DirecTivo (DirectTV/Tivo Combo box). This software has been 
   tested mostly on a Phillips DirecTivo DSR6000 running TiVo software 
   version 2.5.1. See WHAT TIVOS DOES ELSEED RUN ON for more info.
   This may work on standalone Tivos or other DirectTivos running other 
   software versions, I have no idea. Let me know if you get it working 
   on different hardware/software.
2. Your phone line attached to your Tivo.
3. Caller-ID service from your telephone company.
4. Some way to get this program onto your Tivo. (Enable bash on the serial 
   port and upload using rz OR take out your drive and copy this software 
   onto the root partition OR TivoNet/TurboNet FTP, etc.)

HELP! I DON'T KNOW HOW TO HACK MY TIVO BUT I REALLY WANT ELSEED!!
-----------------------------------------------------------------

OK, this is a little beyond the scope of this document, but I will give 
you a couple of pointers. There is now a newbie guide to hacking your Tivo 
by Steve Jenkins here:

http://www.stevejenkins.com/tivo/newbie.html

Beware that it contains A LOT of information, not all of it necessary 
for installing elseed.

For just the necessary steps the easiest way to hack your DirecTivo is 
to follow the steps for installing the Turbonet drivers. Once you 
are done, you will have Turbonet drivers installed which you don't 
need, but it doesn't hurt to have them. The install instructions are 
here:

http://www.silicondust.com/turbonet/install_software.html

After the "Install the TurboNet driver" step, you are free to install 
elseed on your machine in a suitable directory by copying it there. See 
the INSTALL file for more details on this.

WHAT TIVOS DOES ELSEED RUN ON?
------------------------------

elseed has been reported to work on:

o Phillips DirecTivo DSR6000
o Sony DirecTivo SAT-T60
o Hughes DirecTivo GXCEB0T

But it appears that same models have different modems so your mileage may
vary.

ELSEED DOESN'T WORK ON MY TIVO!
-------------------------------

I'm sorry to hear that. Here are some tips you can try to get it to 
work. There are no guarantees:

1. Try setting the init-string (using the -i command-line option) to
   'AT-STE=1;+VCID=1'. This reportedly will get elseed to run on 
   a Hughes DirecTivo and some Phillips DirecTivos. Example:

   # elseed -i 'AT-STE=1;+VCID=1' &

2. Try setting the init-string to 'AT+FCLASS=8;+VCID=1'.

3. Try setting the init-string to 'AT-STE=1;#CID=1'.

4. On your Tivo, turn 'Phone available detection on': 
   TiVo Central -> Messages & Setup -> Receiver & Phone Setup -> 
   Phone Connection -> Change Dialing Options -> 
   Set 'Phone Avail.' Detection: On.

   Then try any of the various init-strings listed here.

5. Use an external modem instead (see USING AN EXTERNAL MODEM WITH ELSEED)

USING AN EXTERNAL MODEM WITH ELSEED
-----------------------------------

If you have an extra modem lying about that can do caller-id and 
you desperately want to get this working, you can actually connect 
the modem up to your Tivo via the serial port. This requires 
hardware that is avaliable at http://www.9thtee.com/ and I'm not 
exactly sure what all you need, but if you are crafty, you can 
figure it out. Then you can set the modem device to the serial port 
(set to /dev/ttyS3 using the -d command-line option). You might also 
need to change the init string depending on your modem. And you might 
want to turn on the -M option since you aren't sharing the modem
with tivo anymore.

ELSEED ONLY WORKS SOMETIMES
---------------------------

There have been reports that some of the modems in the DirecTivo's are 
not very consistent in giving caller-id information. I don't know what to 
tell you since I don't have this problem with mine. So either live with 
it, hook up an external modem to your Tivo and use that (see "USING 
AN EXTERNAL MODEM WITH ELSEED"), or work to figure out what the problem is 
and become the hero to many.

Starting with 0.5.0 you can try to use the -e command-line option to 
have elseed exit after it displays caller-id information. There is a 
new shell script called elseed_forever.sh that is now packaged with 
elseed that can be used to launch elseed over after it exists so that 
elseed will run forever. See the INSTALL file for more details.

ELSEED DOESN'T DISPLAY THE CALLER-ID INFO UNTIL THE 3RD OR 4TH RING
-------------------------------------------------------------------

I think there are two factors here. The first is your phone company 
and you likely can't change how soon they send caller-id info down 
your phone line. I think most of them send it between the 1st and 
2nd ring. elseed cannot display caller-id info any faster than your 
other caller-id devices.

The second factor is how soon elseed reads the caller-id data. Before 
elseed version 0.5.0, elseed was waiting 50 tenths of a second, or 5 seconds. 
This was how the elcid code was written that elseed is based on. 
As of 0.5.0, this is set to 20 tenths of a second, or 2 seconds. So elseed 
should display caller-id info 3 seconds faster! In addition, there is a 
new command-line option -v where you can set how long elseed should wait
before reading caller-id info. You can make it faster or slower depending 
on what works for your setup. After I get enough feedback, I might 
turn down the wait time down even further.

NOTE: As of elseed 0.6.0, this delay is set to 5 tenths of a second.

USAGE
-----

Usage: elseed [options]
Options:
    -x N    set x coordinate to N [default 1]
    -y N    set y coordinate to N [default 11]
    -f N    set foreground color to N [default 4]
    -b N    set background color to N [default 1]
    -d S    set modem device to S [default '/dev/cua1']
    -i S    set modem init string to S [default 'AT+VCID=1']
    -l S    set log file to S [default '/var/log/elseed.log']
    -c S    set conf file to S [default '/etc/elseed.conf']
    -t S    set time CID info is on screen [default 10 seconds]
    -v S    set delay for reading from modem in tenths of a second [default 5]
    -z S    set YAC connect timeout in milliseconds [default 100]
    -e      exit after displaying caller-id info [default is off]
    -n      tells elseed not to look for the caller's name [default is off]
    -M      turn off modem sharing [default is on]
    -D      put elseed in debug mode
    -h      show this help

YAC SUPPORT
-----------

As of 0.6.0, elseed can be a YAC server. This means it can be configured 
to send caller-id information to YAC clients on your network like your 
other computers. See CONF FILE FORMAT section on how to configure 
elseed to be a YAC server. Find out about YAC here:

http://www.sunflowerhead.com/software/yac/

I wrote a YAC client for the X-Window System that uses XOSD. Check my tivo 
hacking page at http://bah.org/tivo/ if you are interested in it.

NUMBER/NAME MAPPING
-------------------

If your best friend only shows up as WIRELESS CALLER or even worse OUT OF 
AREA for some reason and you really want to see his/her name instead, you 
can set up a number-to-name mapping in the conf file. See the CONF FILE 
FORMAT section for how to do this.

CONF FILE FORMAT
----------------

As of 0.6.0, there is now an elseed conf file. The default location 
for the conf file is '/etc/elseed.conf', but this can be 
overridden with the '-c' command-line option.

The conf file can be used to configure new features that elseed 
supports. Here are the directives that the conf file supports and 
their details:

o   Map [10-digit Number] [Name]: 
    
        Example: Map 4155551212 INFORMATION SERVICES

        This directive will map a number to a number. So in this 
        example, if someone with the exact phone number of 
        4155551212 will show up as "INFORMATION SERVICES" no 
        matter what the caller-id information said. This is 
        helpful to override the caller-id information when it 
        is incorrect or says something lame like "WIRELESS CALLER"
        
o   YacClient [IP Address]:
    
        Example: YacClient 10.0.0.22
        
        This directive will add 10.0.0.22 as a yac client. Whenever 
        a call comes, elseed will try to send the caller-id information 
        to this client. NOTE: This MUST be an IP address, no 
        hostnames, sorry.
        
NOTE: Only one directive per line, and each argument to the directives 
must be seperated by only ONE space or they won't work. Sorry, 
parsing strings in C is a PITA.

INSPIRATION
-----------

I decided to write this software after seeing TivoCID by JLC which is 
available here: http://pvrhack.sonnik.com/tivo/jlc/. Unfortunately 
it actually runs caller id software on another computer with a 
different modem that has to have caller-id capability and sends 
information to your Tivo over an ethernet card (or PPP over the serial port).
I decided to see if the modem inside the Tivo was capable of doing 
caller-id. Once I found out that it was, it was pretty easy to get this 
software up and running on the Tivo, thus requiring a lot less 
hardware/software/setup.

BORROWING SOFTWARE
------------------

I shamelessly stole the source code from 2 different projects and 
hacked them together to create this software. The two pieces 
of software I "borrowed" were:

elcid - http://elcid.sourceforge.net/
    A simple C-based caller-id program

playitsam - http://minnie.tuhs.org/Programs/Playitsam/
    I only stole the OSD (On-screen display) code from playitsam
    to do the OSD stuff for elseed

    NOTE: Evidently playitsam borrowed  osd.c, osd.h
    from embeem's tivobvi 1.03. Check out:

    http://tivo.samba.org/download/mbm

    For more info on that project and other great tivo hacks. 
    Thanks embeem!

I also looked at the code in mgetty+sendfax to figure out a way to 
attach myself to a modem device while still allowing other programs 
to dial-out (I.E. The Tivo daily call).

For the 0.6.0 release I borrowed code sent to me by Terry Hardie to 
do the yac server stuff. 
    
I also borrowed code from elseedyac, which was a fork of elseed which 
adds in yac client/server support and number/name remapping when I 
was too lazy to do it myself. You can find that code at 
http://pfl2000.dyndns.tv/tivo/elseedyac/.

LICENSE
-------

This software is free software (open source) released under the GNU 
Public License (GPL). See COPYING file in this distribution for more 
details.

THANKS
------

Thanks to the following people:

- nsysblh for massively re-writing the OSD routines, adding new features, 
  and doing a lot of grunt work to help us get elseed to run on many 
  different Tivos
- embeem for the original osd routines and nicepri and the cross-compiler 
  information and for being an all-around helpful person.
- jlc for writing tivocid which gave me my idea
- sporadic@linux.wku.edu for writing elcid, upon which this code is based
- Nathan Lewis (Saturn49) for a new updated font.h
- Terry Hardie for sending me code for adding yac support
- Jensen Harris for writing yac which is very cool
- Nick Hengeveld for doing some beta testing for me
- All the other tivo hackers who came before me and made my life easier

INSTALLING THE SOFTWARE
-----------------------

See INSTALL file in this distribution.

HOMEPAGE
--------

The home page for elseed is http://bah.org/tivo

CONTACT
------

All code Copyright (C) Greg Gardner <greg@bah.org>
