Using NetPorter

The Internet is everywhere these days. Wouldn't it be great if you could connect your Stamp or PIC project to the network? With NetPorter you can easily connect any RS-232 device to a PC and provide it over the Internet (or an Intranet). NetPorter uses Java so you may be able to run it on other Java platforms as well.

Unlike other Internet gateways, NetPorter rarely requires you to modify your existing RS-232 device. To make that point, this month I'm going to show you how to make an Internet caller ID log using NetPorter and an ordinary modem that has caller ID capability.

NetPorter can:

	Send commands to a device in response to inputs, or on a timed schedule.
	Parse input lines from the device.
	Remember variables read from the input.
	Time stamp incoming data.
	Build files by applying incoming data to a template.
	Act as a Web server, post files to a Web server, and e-mail text or HTML files.
	Allows you to control a device via the Web or Telnet (optional).

About Caller ID

Most modern modems can decode caller ID easily enough. However, you have to issue a special command and that command varies by modem. My modem uses AT+VCID=1 but I also put some other common strings in the example files. You'll have to try until you find the right one or look up the correct command in your modem's technical documentation (rarely shipped with the modem anymore, but often on the manufacturer's Web site).

When an incoming call arrives, the modem will send the message RING. We don't care much about that. However, after the first or second ring, you'll see a message like this:

DATE=0630
TIME=1616
NMBR=8885551212
NAME=Clause Santa

In truth, this format is almost ideal for NetPorter, but as you'll see, it doesn't really matter about the format.

About NetPorter

You configure NetPorter by using a set of files that define a NetPorter application. The main file is usually named netporter.properties (although you can use any name you wish). This file sets up things like what COM port NetPorter should listen to, the address of your Web server, and the names of the other files NetPorter will use.

The second file that NetPorter needs is a rule file. A rule file can have multiple sections. Each section starts with a BEGIN keyword or a MATCH keyword. The BEGIN sections execute when NetPorter starts and never again. The MATCH sections execute when the device sends a line to NetPorter and the MATCH's regular expression matches the input.

There is an optional third file that contains stimulus for the device. You can specify commands to send to the device when NetPorter starts and you can also make NetPorter send a command on a periodic basis.

Code

The NetPorter.properties file is mostly copied from the standard file that ships with NetPorter. Many of the entries in this file are the defaults anyway. Here's the Caller ID properties file with comments in italic. You'll also find comments in the files starting with #.

# This first group are items you will often change
# Remember to use / instead of \ in file names
defaultuser=wd5gnr Your FTP user name for Web publishing
defaultpassword=netporter Your FTP password
defaulthost=wd5gnr.virtualave.net The FTP Host
defaultdirectory=c:/NetPorter/examples/cid Default directory
defaultftpdir=public_html Default FTP directory
defaulttemplatedir=c:/NetPorter/examples/cid Location of templates
smtp=your_outgoing_mail_server Outgoing e-mail server
fromaddress=netporter@your-address.com NetPorter's e-mail address
rules=c:/NetPorter/examples/cid/rules.txt The rule file
stimulus=c:/NetPorter/examples/cid/stim.txt The stim file
port=COM3 Serial port and parameters
baudrate=9600
bits=8
stopbits=1
parity=0
flow=0


# Remove these to disable telnet or www
telnetport=23
wwwport=808
mimetypes=c:/NetPorter/mime.properties

# Not often changed
telnetpw=password
telnetline=false
eolchar=\\r

# Not much need to change below here for most cases
debug=f
defaultport=21
ftppassive=t
nonnumericerror=*ERROR*
tag=var
matchcase=false
missingvalue=*UNKNOWN*

The stimulus file is very simple. We need to initialize the modem and turn on caller ID:

BEGIN ATZ
# You may need to change the below to enable 
# caller ID on your modem
BEGIN AT+VCID=1
# BEGIN AT#CID=1
# BEGIN AT%CCID=1
# BEGIN AT#CC1
# BEGIN AT*ID1

The ATZ command will reset the modem to its default state and you can pick one of the caller ID commands depending on your modem. Both of these stimulus items occur when NetPorter starts since they use the BEGIN command.

The heart of the NetPorter configuration is the rules file. There are three rules in this file. The first one runs when NetPorter starts. It sets a variable, UPTIME, to 1. Since NetPorter marks the time it changes variables, this will allow us to know when NetPorter started. It also clears out the log file (log.htm) by "building" emptylog.template. You'll see in a minute that this template uses the UPTIME variable to get a time stamp. Then the rule saves the built file into log.htm and publishes it to the default Web server. Look at the code before you read about the remaining rules.

# CID Example rules file
BEGIN
SET UPTIME=1
# Clear the log file
BUILD emptylog.template
SAVE log.htm
PUBLISH - log.htm

MATCH (.+)=(.+)
SET $1=$2

# match last record
MATCH NAME=(.+)
BUILD tel.template
APPEND log.htm
PUBLISH - log.htm

The second rule is "MATCH (.+)=(.+). This is a regular expression like those used in Perl, grep, and other programs. I don't want to get into regular expressions in great detail, but you can find more about them at these Web sites:

http://www.perldoc.com/perl5.6/pod/perlre.html

http://language.perl.com/all_about/regexps.html

http://www.robotwisdom.com/net/regexres.html

The idea here is that we will find all the characters before the equal sign and assign them to $1 (the first set of parenthesis). Everything after the equal sign will be in $2. The equal sign isn't in parenthesis so it is discarded. Since the format is so close to what we need for the SET command, the rule's body is simply SET $1=$2. This gives you variables DATE, TIME, NMBR, and NAME. You could change these, though. For example, you might say:

MATCH NMBR=(.*)
SET PhoneNum=$1

You could even write a complex expression to pick apart the phone number.

All the SET $1=$2 rule does is sets the different variables. We don't want to update the log until the last line arrives. NetPorter remembers the variables, and it will process all rules that match, so this job falls on the third rule: MATCH NAME=(.+). Notice that this rule will run after the second rule.

The rule body reads tel.template and substitutes variables for special tags in that file. Then it appends the file to the existing log.htm file. Finally, it publishes the resulting file to the default FTP server.

You could write much more complex rules. For example, calls from a certain person could trigger an e-mail. You could parse apart the time and date from the phone company instead of using NetPorter's time information.

The only piece missing now is the template files. Let's look at them in reverse order. When a phone call arrives, the tel.template file makes a new entry in the log. This is that file:

Call at <VAR DATE TIME><BR>
From <VAR NMBR> (<VAR NAME>)
<HR>

The template uses three <VAR> tag. The first, <VAR DATE TIME> tells NetPorter to substitute the date and time that it received the DATE variable into the text. The other two <VAR> tags simply places the variable's text in the correct place. It is possible to format the date and time differently, and it is also possible to apply numeric formatting to numeric quantities (see the NetPorter manual).

The first template was emptylog.template. It controls the heading displayed at the top of the page:

<HTML><HEAD><TITLE>Telephone Log</TITLE></HEAD><BODY BCGOLOR=gray>
<H1>Telephone log starting at <VAR UPTIME TIME></H1>

In this example, I rely on the fact that most browsers won't care if they don't see </BODY> and </HTML> tags. However, you can code complete Web pages in several ways (the large example on the NetPorter CDROM shows how).

Here's a sample of the output log file:

Granted, this isn't a Stamp it is a modem. However, you can easily make a Stamp or any microcontroller transmit serial data, which means you can interface it to the Web with NetPorter. Since NetPorter uses regular expressions, you can easily adapt it to fit your device. You could easily connect scales, Stamps, PICs, or any RS-232 device to the Internet.

Back Home

This article is copyright 1999, 2000, 2001 by AWC. All Rights Reserved.