Like all Java programs, javAPRS comes as a set of .class files, generally packed in a zip file. These files are the program code and data structures that make javAPRS run. These files must be placed in a folder called "javAPRS", located in the same folder as the HTML files you will be writing. Note that for most WWW servers, capitalization is significant, and must be left as is. There is also a single image file, allicons.gif, which contains the icons used by javAPRS, and is placed within the javAPRS folder.
yourPage.html
javAPRS/
yourData.tnc
japrs.zip
javAPRS.class
....class
maps/
usa.html
yourmap.mp
maplist.txt
Security is a major topic of conversation within the Java Community. Obviously the automatic downloading of untrusted programs has the potential for abuse. Java was designed to prevent a downloaded applet from doing any damage to your computer. The principle limitations are that an applet cannot access the file system in any way, and it can only contact the server from which it was run. Unfortunately, this limits the cool stuff you can do with Java. For example, there are several sites on the net that provide dynamic maps, it would be great to use these as a map source with javAPRS, but the security manager prevents this. It also means you can't connect to two different live servers and display the data in a browser. The JDK allows this security to be turned off, however so far the browsers do not. As you are writing your page, keep this in mind. All the data must reside in a single network server if you want it to be viewable by Netscape. You can run the applet locally with the Open File... command, but again, all data must then be on the local file system, and you must use local references to the data files.
This limitation means the javAPRS program must access live data from the same server that the apple loads from. If you want to use the APRServe data stream from the www.aprs.net server, you must load the applet from that location. Fortunately, Java provides a way to do this, as described in the next section. Back to Topic List
Within the HTML file, a special tag is used to invoke applets like
javAPRS. The simplest possible call is:
<APPLET COSEBASE = "javAPRS/" CODE="javAPRS.class" WIDTH=400 HEIGHT=300 ARCHIVE="japrs.zip">
<PARAM name = "dosMap" value = "usa.mp">
Hey dude, get a real browser!
</APPLET>
The CODEBASE parameter specifies where the class files are located. If you wish to use a data stream from another location, you must load the applet from there. This is accomplished with the CODEBASE parameter. To load the applet from the Miami APRServe machine, change the CODEBASE parameter to CODEBASE = "http://www.aprs.net/javAPRS/"
CODE tells the browser which class file to start executing. As other class files are called by the program, they will be automatically loaded. WIDTH and HEIGHT specify the amount of space which should be reserved for the applet. javAPRS automatically uses as much space as is allocated, however it is possible to make the space too large for the graphic buffers to be created, causing the program not to run. Unfortunately, there isn't any way to predict this, but sizes up to 500 by 300 seem to work fine. The ARCHIVE tag specifies a zip file containing the applet program. Java normally puts each class in a separate file, so to run the program a browser must open a connection for each (presently 17)! Netscape reads the classes from the archive in a single connection. Microsoft and other browsers do not understand the tag, so it is important to have both the individual files and the archive available. Any other information which must be passed to the applet is done with the PARAM tag, specifying the name and value of each parameter. Each parameter has a default value, and need not be entered if the default value is desired. All the parameters which javAPRS understands are detailed in the following sections. Any text or other HTML commands which appears between the <APPLE> and </APPLET> tags will only be displayed if the page is being viewed on a browser which doesn't understand Java. Instead of the highly informative error message shown here, you could display a GIF file of what the applet would look like.
Back to Topic List
The only parameter required by javAPRS is one of the three map file
parameters (without a map, there isn't much point to javAPRS!).
All map files must be placed in a folder called "maps"
within the "javAPRS" directory containing the class files.
javAPRS can display two types of maps. The first is the
familiar (to APRS users) dos map format.
<PARAM name = "dosMap" value = "usa.mp">
Dos maps should have the suffix of ".mp". (".map" is not used, as some HTML
servers use this extension for image map files, and these servers will not
send files with the suffix ".map" correctly.
There are several parameters that affect the way dos maps are displayed.
<PARAM name = "showLabels" value = "false"> (default true)
This determines if the labels included in the map file are to be displayed
or not. The labels include data that specify at what scales they should be
displayed. This information can be overridden with:
<PARAM name = "showAllLabels" value = "true"> (default false)
The map can either be automatically scaled to be as large as possible but
still fit within the boundaries of the applet, or the zoom and scale can
be manually specified.
<PARAM name = "autoScale" value = "false"> (default true)
<PARAM name = "offsetX" value = "150"> (default 0)
<PARAM name = "offsetY" value = "200"> (default 0)
<PARAM name = "scale" value = "0.24"> (default 1.0)
autoScale is set to false automatically if a scale parameter is specified.
The values of these parameters must be determined largely by trial and
error to get the display you want. In order to make the process easier,
the program will print out the value of these parameters to the java
console every time a scroll and zoom is done. To use this feature, zoom
and scroll the map as desired, then look in the console for the values.
Note that these values only specify the
initial display; once javAPRS is running the user is able to change the
zoom and scroll to suit themselves.
<PARAM name = "backgroundColor" value = "black"> (default gray)
Normally, javAPRS displays dos maps with a light gray background, and callsigns are
shown in black. javAPRS can also display maps on a black or white background. There
are two separate icon files which are optimized for light and dark backgrounds.
The second type of map files are gif maps. javAPRS has the ability to
display any gif or jpeg file, and use it as a map. To do this, first
specify the file, which must be in the maps directory as noted above.
<PARAM name = "gifMap" value = "atlanta.gif">
The map must then be calibrated so that javAPRS can plot items correctly
onto the map, by specifying the edges of the map in degrees.
<PARAM name = "gifMapLeft" value = "80.3245">
<PARAM name = "gifMapTop" value = "24.2454">
<PARAM name = "gifMapRight" value = "79.4623">
<PARAM name = "gifMapBottom" value = "23.8916">
(Positive degrees in the north and west hemispheres, and negative in the
south and east.)
The third type of map files are TIGER maps. TIGER is a dynamic map
generating system sponsored by the US Census Bureau. These provide street
level maps of the entire US.
The map is specified using the lat/lon of the upper left corner and the
height of the map, all in degrees.
<PARAM name = "tigerMapLeft" value = "80.3245">
<PARAM name = "tigerMapTop" value = "24.2454">
<PARAM name = "tigerMapHigh" value = "1.3">
There are a couple of problems with the TIGER maps. First, the security
manager of Java will not allow javAPRS to obtain the map from a server other
than that from which it was loaded. TIGER maps may be used by running the
applet from within the stand-alone applet viewer or a browser that allows
the security manager to be disabled (Internet Explorer is rumored to have
this capability. Obviously this is not an optimal solution. Another method
is to have the server relay the request between javAPRS and the TIGER computer.
So far the only server that has this capability is the
LIDS Windows TNC server
written by Steve Boyle, KD6WXD. The syntax to use this feature is:
<PARAM name = "tigerMapRelay" value = "sboyle.slip.netcom.com:14500">
This gives javAPRS the name and port number of the relay server.
<PARAM name = "mapList" value = "usa$usaseast$flsouth">
javAPRS now allows the user to choose the map which will be displayed. The
above command creates a pop-up menu at the bottom of the applet area, with
the choices specified.
Rather than use the often cryptic file name in the menu, it is
possible to specify text which is used in the menu. The format for this
data is "filename^Text Name here". The example above becomes:
<PARAM name = "mapList" value = "usa^USA$usaseast^Southeast USA$flsouth^South Florida">
The maps in the menu may be dos, gif, or TIGER maps. If it is a gif map, the syntax
is
fileName.gif^menuName,top,left,bottom,right
where the top, left, bottom, and right are lat/lon values of the edges of the map.
the suffix .gif or .jpg must be specified.
TIGER maps are described by the syntax:
tiger^menuName,top,left,high
the word tiger must be in lower case letters, top and left are the upper left
corner of the map, and high is the height of the map in degrees.
Rather than specify
the list in the parameter file, it can be in a file, one map to a line, using
the same syntax as above. One map is listed per line,
and the file list is specified by:
<PARAM name = "mapListFile" value = "listname.txt">
<PARAM name = "pickBackground" value = "false"> (default true)
When a map list is specified, javAPRS also displays the option for the user to
change the background of the applet. The background menu can only appear if a map
menu is specified, but this parameter can supress the background menu.
Now that we have displayed a map, it's time to display some data. There are
three different types of data which javAPRS can display: NMEA, TNC, and HST.
javAPRS differentiates them based on the suffix, .nmea, .tnc, or .hst.
An unlimited (except by memory) number of files may be opened. Each data
file is loaded by a separate thread, and proceeds independently. Data files
must be numbered sequentially starting with 1.
<PARAM name = "dataFile1" value = "trip.tnc"> (default 0)
<PARAM name = "dataFile2" value = "keys.nmea"> (default 0)
.....
<PARAM name = "dataFile99999" value = "marathon.hst"> (default 0)
NMEA files consist of the stream of data coming from a GPS. javAPRS understands
the $GPRMC, $GPGLL, and $GPGGA sentences, others are ignored. Each position is
plotted on the map as a dot, and the playback of a sequence of this data results
in a moving line.
Example
TNC files are the raw data sent from a TNC.
Consult the APRS documentation for explanations of the
various data formats. This format is the log file saved by MacAPRS and WinAPRS.
If you do use files in this format, keep in mind there is a tremendous amount
of duplication and non-positional report information that comes of a typical
VHF APRS LAN. The display of such a file is greatly enhanced if the file is
manually edited to remove this redundant and extraneous material. In
this example, the
original log file was nearly 700k, but after editing it is only 100k.
HST files are the history files produced by the dos version of APRS. These files
are typically very small, as extraneous and redundant material is removed by
APRSdos.
Example
Data files can be placed within the javAPRS folder containing the class files.
If they are there, only the file name need be specified, as in the examples above.
If the files are anywhere else, the the full URL must be given:
<PARAM name = "dataFile1" value = "http://web.usna.navy.mil/~bruninga/javAPRS/dxspots.tnc">
<PARAM name = "fileReload1" value = "600">
This allows you to periodically reload the data file. This is useful where
the data file is uploaded to the server automatically at defined intervals.
The time between reloads is specified in seconds.
Using javAPRS with static data files adds a bit of animation, but still isn't
anything that couldn't be done with other internet systems.
Where theings really get exciting
is using javAPRS to connect to live data streams. At this time, there is only
one such server operational. Written by WA4DSY for OS/2,
this server
takes live
data coming in from a TNC, and makes it available to any application that requests
it over the internet. Net connections are specified with the dataFile parameter.
<PARAM name = "dataFile1" value = "netc:14579:wa4dsy-3.wa4dsy.radio.org">
The "netc" informs javAPRS that this is a network data stream rather than a file.
The number between the colons is the TCP/IP port number, and will generally be
14579. If you want to put live data on the internet, please contact me directly
for more information.
There is another version of the command that assumes the port number of 14579:
<PARAM name = "dataFile1" value = "net:wa4dsy-3.wa4dsy.radio.org">
Many different paramters control the display of data within javAPRS. Each of
these parameters are documented in the following section. The defaults should
be adequate in most situations, but use of these allows for special display
needs.
<PARAM name = "copyrightTop" value = "false"> (default true)
Vanity requires my name (not to mention the copyright notice) appear somewhere.
By default it will appear near the top of the map, but if needed it may be
made to appear at the bottom with this parameter.
<PARAM name = "echoDataConsole" value = "true"> (default false)
This parameter causes all data to be echoed to the Java Console as it is received.
There is something about Netscape that doesn't work quite right, and not all the
data is displayed, however it works great under the JDK and other Java environments.
<PARAM name = "echoDataStatus" value = "true"> (default false)
This parameter displays all data in the status bar at the bottom of the applet
as it is received. The use of this is discouraged, however, as it seems to interfere
with the plotting of data on the map.
<PARAM name = "stationList" value = "false"> (default true)
javAPRS maintains an internal heard list. This command specifies whether javAPRS
will use the data from this list to redraw the map, for example when the applet
window is brought back to the front. If false, then the file is reloaded from
the beginning.
<PARAM name = "drawVectors" value = "false"> (default true)
Normally javAPRS draws a line indicating course and speed for each report containing
this information, but this can be turned off if desired.
<PARAM name = "trackStations" value = "false"> (default true)
javAPRS keeps a track of prior positions for each station, and when the map is
redrawn it normally plots these track. This option may be used to supress the display
of these tracks.
<PARAM name = "showHurricaneRadius" value = "false"> (default true)
Hurricanes and tropical storm reports carry information about the radius of
storm force and hurricane force winds. javAPRS will display these radii by
default, but this display can be turned off with this parameter.
<PARAM name = "showNewStations" value = "false"> (default true)
The first time javAPRS hears a new station, it will display the message
"New Station: W1XYZ" at the bottom of the screen. This display can be turned off
if it is not desired.
<PARAM name = "homeID" value = "K4HG">
This parameter allows you to specify the "home" station for the applet. When this
parameter is set, javAPRS keeps track of the location of the specified station,
and uses this information in two ways. First when a new station is heard,
javAPRS adds the bearing and distance to the new station message described above.
Second, when a mouse click occurs on the map, javAPRS will not only display the
latitude and longitude, but also the course and bearing from
the home station to the mouse location.
<PARAM name = "sleep" value = "10"> (default 0)
In order to slow the replay of data, it is possible to specify a delay value
between each position plotting. The value is in milliseconds.
<PARAM name = "showStationNames" value = "false"> (default true)
Normally javAPRS draws the callsign of each station when it is plotted. This
can be turned off to reduce the clutter if the station info is not needed.
<PARAM name = "foregroundColor" value = "1"> (default varies)
This controls the color that callsigns are drawn on the map. The default is black,
unless the map is a dos map drawn on a black background, in which case the default
is white. The colors are close to the 16 dos APRS map colors, shown below.
| 0 - Black (normal background) | 8 - dark gray (Railroads) | 1 - dim blue (ferrys, etc) | 9 - Bright Blue |
| 2 - dim grn (Admin areas, Parks) | 10 - Bright Green (Interstates) |
| 3 - dim cyan (Rivers) | 11 - Bright Cyan (Big rivers, Coasts) |
| 4 - deep red (state roads) | 12 - Bright Red (major roads) |
| 5 - dim violet (custom features) | 13 - Bright Violet(special events) |
| 6 - dim orange (state/cnty lines) | 14 - Bright Yellow (Cities,airports) |
| 7 - gray (back roads) | 15 - Bright White (Labels and CALLS) |
<PARAM name = "displayLocalTime" value = "false"> (default true)
Normally javAPRS will display time in local time, using a UTC offset provided
by the operating system. If set to false, time will be displayed in UTC.
<
<PARAM name = "useAPRStime" value = "false"> (default true)
Normally javAPRS will read the time sent in the position reports, but if this
parameter is set to false javAPRS will use the time the packet was recieved by
javAPRS. There is a potential problem in the way time is handled by javAPRS.
The dos version of APRS can send VHF packets using local time. If the time
zone of the VHF transmitter may not match the time zone of the javAPRS computer,
the recieved time will not be correct. Mac and WinAPRS always send time as UTC,
and hopefully APRSdos will follow suit. Until then displayed times may not be
correct.
<
<PARAM name = "startDate" value = "09/01/95">
To save air time, APRS only sends the day of the month along with the time. In
live applications this is fine, however since javAPRS often is used to replay
old events things can get confused. It is possible with this command to set
the month and year of the received packets, so that they will match those of the
actual event. The day in this parameter is ignored. All numbers must be two digits
long (i.e. 9/3/96 would not parse correctly.
I know you must be thinking "Gosh Steve, javAPRS is so cool, it must cost
a fortune!" Nope, as long as you aren't making money with it, neither am I.
All I ask is a link on your page to my javAPRS page (
http://www.aprs.net/javAPRS.html)
and an email message to k4hg@tapr.org,
so I can see what cool things you are doing, and add a link for your site to my page.
If you want to use javAPRS on a commercial site, you need to contact me. If you
just want to use it to demo your product, I'm not likely to want any money,
but I want to make that decision on a case by case basis. However, if you want to use
javAPRS to distribute information on an ongoing basis, it is going to cost you,
but not more than you can afford :-)