WHAT IS CALLERIDPOP?

To put it simply, it's a Perl script intended for use by users of Linksys/Sipura VoIP adapters and/or phones, that will cause a popup notification to appear on the user's computer whenever there is an incoming call, showing the caller's name and number plus the day, date and time of the call. For proper operation, the VoIP adapter's home web page must be accessible from the computer running the script - if there are any firewalls in the way, it won't work.  If you can access the adapter's page from a web browser running on the same computer (and the web browser is not going through a proxy or VPN) then it should work.  (Note: Where I use the word adapter, you can substitute the word phone, but it must be a Linksys or Sipura phone with a web-based user interface, and I can't guarantee that it will work with all models).

There are separate versions of the script for Mac OS X, Win32, and Linux. I do NOT have any knowledge of whether the Win32 version will run under Vista, but you are free to experiment. The script is being offered under the GNU General Public License, see the individual Instructions.txt file for each version for details.

WHAT YOU NEED TO RUN THE CALLERIDPOP PERL SCRIPT

Each version of CALLERIDPOP has its own Instructions.txt file, however I've been told it's about as clear as mud in a couple of spots.  So I'm including this to clarify a few things that apply to all versions.  You'll still need to read the Instructions.txt for your platform, but at least you may have a bit better idea of what you are reading.

The instructions.txt initially assumes that everything on your system is ready for installation of the script.  But, that will not be the case for many, and perhaps a majority of users.  In that case, you will then need to read the "If it does not work" section in the file.  Note that I don't give Linux users as much hand-holding as I do Mac and Windows users, for two reasons:  One is that right at the moment I don't have a desktop Linux box anyplace I can easily get to it, and the other is that Linux users tend to pride themselves on knowing how to do this sort of thing.  If you are a Linux user and not an uber-geek, you may find some installation hints by reading through the Mac OS X Instructions.txt, since both platforms are based on Unix (if you go back far enough).

Before you can run the CallerIDpop Perl script on your computer, you must have certain prerequisites.  The Instructions.txt file for your version will have more specific instructions, but please be aware that if you have never run a Perl script on your computer before, there are certain things you need to check on first.

1. IS PERL INSTALLED?  The answer is probably yes if you have Mac OS X or some popular distributions of Linux.  You probably don't have it if you have a minimalist Linux distribution, or any version of Windows (unless you have already installed it). From a command or terminal prompt, try typing:
perl --help
If you get a Perl help screen, then it's installed. If you need Perl, Linux users can probably find it in your software repository for your Linux distro, while Windows users can download and install ActivePerl as described in the Win32 version's Instructions.txt file (there are versions of ActivePerl for other platforms as well).

2) DO YOU HAVE THE REQUISITE PERL MODULES INSTALLED?  At a bare minimum you need all of the following modules installed:

Config::Simple
Getopt::Long
LWP::Simple
Mac::Growl (Mac OS X only)
Win32::Snarl (Win32 only)

If you're not sure if you have any of these, just try installing them in the normal manner (if you're not sure how, see the "If it does not work" section of the Instructions.txt file for your platform, or use Google. You'll probably want to look for instructions on installing modules using CPAN unless you are a a Windows user, in which case you'll probably be using ppm [Perl Package Manager] to install modules).

3) DO YOU HAVE THE APPROPRIATE POPUP NOTIFICATION ADD-ON FOR YOUR COMPUTER INSTALLED? On a Mac you need Growl, for Win32 you want Snarl, and on a Linux system we use libnotify (via a system call to a command line utility that comes with libnotify).

4) DID YOU COPY THE APPROPRIATE ICON FILE INTO THE SAME DIRECTORY AS THE CALLERIDPOP SCRIPT?  The icon files are not interchangeable between platforms, for the most part.  If you want to use your own icon, make sure it's the same size and format as the default one supplied (which, by the way, is an old Automatic Electric wall phone, NOT an upside down desk phone).

5) IF YOU ARE UPGRADING, DO YOU NEED TO INSTALL ANY NEW MODULES?  It appears that if a module is used anywhere in a Perl script, it has to be present on the target system, even if you are not using the particular feature it enables.  Therefore, if I start using a new module and you get an updated version, you'll need to install the new module if you don't already have it. As an example, the Config::Simple module was not used in early versions of this script, but was added to give the ability to use a configuration file.  However, it's required even if you only use command line options (unfortunately).

6) DID YOU RUN THE SCRIPT WITH THE --help OPTION, AND/OR READ THE SAMPLE CONFIGURATION FILE? These will show you how to run the script to best advantage.  Note that when you use an option with spaces in it, you must enclose the option value inside quotation marks.  If it seems like some options are being ignored, look for unpaired quotation marks in the command line! And, again, note that there is NO ERROR CHECKING - if you misspell an option it will probably simply be ignored.

7) FINALLY, MAKE SURE TO ENTER OPTIONS CORRECTLY.  Whether you enter options primarily via command line, or via configuration file, you should be aware that the script has very little in the way of error checking.  So, for example, if you tell it that the base address of your local network is 1922.1168.1. and that you want it to search through addresses 0 through 2555, it will happily try to do so (it may fail, but not because I planned it that way).  This is supposed to be a set-and-forget script - once you get the options right, you probably aren't going to touch it again unless your adapter breaks and has to be replaced. So, the burden is on YOU, not the script, to make sure you are entering something sane.  If this really bothers you, please feel free to modify the code to add more error-trapping - if you do that and send it to me, I'll include it in the next release.

I STRONGLY recommend that the first few times you run the script, you do so from inside a terminal window or at a command prompt, so you can see any output from the script.  Please realize that the first time you run the script, it may take several minutes to find the adapter (if you have given the script a MAC address), so don't panic if it doesn't work right away.  On subsequent runs, it should find the VoIP adapter right away, unless it has been assigned a new IP address in the interim.  Once you are sure the script is operating properly, you can make it a background task at system startup if you like.

NOTE ABOUT THE LOG FUNCTIONS (Starting with Version 0.7):  Please note that any logging functions included in this script are only able to record calls that actually cause the phone to ring, and a popup notification to appear on the screen.  This means they will NOT log calls that do not reach the adapter or phone, including calls that arrive when the device is busy or when Internet connectivity is disrupted. They also will not log calls if the option is not properly enabled, using a FULL path and filename.  I mention this only because if you need accurate logging of all incoming calls, you should be using a VoIP provider that gives you that data via a Web portal, using data logged by their switch.  On the other hand, some providers will only show you completed (answered) calls, whereas this script will attempt to log any incoming call, whether answered or not (and it does not distinguish between an answered and unanswered call!).  I included this only so users could look back and see what calls they might have missed when they weren't home, etc.

NOTE ABOUT NUMBER-NAME FILE USED WITH THE namepath OPTION: This must be a PLAIN TEXT file. The first item on each line is the Caller ID phone number (only) as sent by the provider, then one or more spaces, then the name you want to appear on the display.  Use quotation marks around the name if it contains commas, or any special characters that cause it not to be displayed.

NOTE ABOUT NUMBER-IMAGE PATH FILE USED WITH THE picpath OPTION: This must be a PLAIN TEXT file. The first item on each line is the Caller ID phone number (only) as sent by the provider, then one or more spaces, then the complete PATH and FILENAME of the image you wish to use as an icon when a call from the specified number is received.  It is the user's responsibility to make sure that the specified image file is compatible with the notification system in use.  Use quotation marks around the path and filename if any part of that string contains spaces, or any other special characters that might cause problems if the path and filename are not enclosed in quotes.