HELP-INDEX>READ ME FIRST - License

                          READ ME FIRST - License

For the most current information please read the README file in the Xastir
directory.  Also see the LICENSE and COPYING files for additional information.

Remember this program is intended to be used by the HAM community, in the USA
the FCC restricts you from transmitting over RF if you are not a licensed HAM.
Users in countries outside the USA should seek their local government 
restrictions. 

LICENSE:

XASTIR, Amateur Station Tracking and Information Reporting
Copyright (C) 1999,2000 Frank Giannandrea
Copyright (C) 2000-2004 The Xastir Group

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.

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; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

More information on the program can be found at:

 http://www.xastir.org
 http://sourceforge.net/projects/xastir/
 http://xastir.sourceforge.net

There are some mailing lists available that are Xastir-specific.
Please subscribe to one or both of them for the latest Xastir
information.  See http://www.xastir.org to subscribe.

For more information on the GNU License look at:
http://www.gnu.org


HELP-INDEX>Welcome! and Notes from the Authors

                      Welcome! and Notes from the Authors

XASTIR, or X-windows Amateur Station Tracking and Information Reporting.

Xastir is an APRS(tm) program that is Open Source and free to use and 
pass out to others. Currently this program is in development and should 
not be seen as a finished product! Your help will be needed to make this
a better program.  If you have programming skills and/or can write 
documentation, your help may be needed! We have a lot of ideas but very 
little time, so if you think you can add something to the effort let us
know!



APRS(tm) is a Trademark of Bob Bruninga, his home page is at
"http://web.usna.navy.mil/~bruninga/aprs.html". A great deal of information
on APRS(tm) can be found in the APRSdos documentation written by
Bob Bruninga. An additional source of information is the APRS(tm)
specification, available from http://www.tapr.org .

HELP-INDEX>What's new in Xastir 1.4
Comment fields for interfaces
split_gnis and ozi2geo scripts, need to add to section on scripts
serial mkiss interface
move objects without confirm
new timing params wrt trails, need to add to config|timing part
geocoder (already in docs)
exponential/random backoff for everything
dbfawk default, memory leaks fixed
click+drag zoom boxes
tactical callsign support
numerious small memory leaks, unintialized data uses, and similar bugs fixed. 
GPS quality info
RINO waypoints downloading
label trackpoints
comment/status timestamps
listener socket/ability to act like a limited internet server


HELP-INDEX>What's new in Xastir 1.3

                    What's new in Xastir 1.3

This latest Xastir release greatly improves on the efficiency and usability of
Xastir, and adds many helpful and often-requested new features.

.geo files can now have REFRESH tags, to specify how often the file is
reloaded. This is useful for weather radars and other dynamic images. .geo
files can also have a TRANSPARENT tag to make a certain color transparent, and
a CROP tag to specify a specific region to display.

Some Opentrac packets are now decoded and displayed. See
http://opentrac.org/ for more details.

The default main Xastir directory is now /usr/local/share/xastir; please see
the upgrade notes in README for migration information. This more closely
mirrors the behavior of other applications.  If you're installing
from a binary package (rpm/deb/etc), the default install location
may be /usr/share/xastir.

Xastir efficiency has been greatly improved. Changes in data structures and
timing values have made this Xastir release the most efficient yet.
Additionally, map redraw sequences are interruptible, so map panning speed
has been improved.

dbfawk support - Experimental support for configurable shapefile metadata, in
an awk-like language. See README.MAPS for more details; this must be turned
on with a specific switch to the configure command.

GDAL/OGR support - Experimental support for GDAL and loading of native TIGER
data (.RT1 files). This is automatically enabled if the GDAL library is
found.

Support for UTM w/special zones and MGRS coordinate systems.

Cad drawing mode allows one to draw regions on your screen using the center
mouse button. This feature is not yet complete, but is functional.

User interface changes:
* Several of the menus have been reorganized to have a hierarchical design.
* Additionally, a few colors have been modified for better visibility.
* The map label font and style are more configurable
* The cursor changes to let one know if they're in move object or measure mode.
* If the coordinate system is set to UTM, and "Map Grid" is selected, an UTM
  grid is displayed. 

Snapshot mode now generates a .geo file, allowing the image to later be used
as a map.

Tiger maps have been moved back back the chooser, as was the pre-1.2 behavior.
This is more consistent.


HELP-INDEX>Starting Xastir for the first time

                    Starting Xastir for the first time

When first running Xastir, you should start it from a terminal window so
that any warning or error messages can be seen. On most systems a path is
set up to run programs in /usr/local/bin and all you need to do is type
"xastir &" at the prompt. On systems that do not have this path installed
type "/usr/local/bin/xastir &" to start the program.  The '&' character
will cause Xastir to start in the background, leaving the terminal window
available for other uses.

You may also set the language choice at this time. To set the language or
change the current language choice, call Xastir with the option '-l':

    xastir -lEnglish

Language options are:
    xastir -lDutch
    xastir -lEnglish
    xastir -lFrench
    xastir -lGerman
    xastir -lItalian
    xastir -lPortuguese
    xastir -lSpanish

The chosen language will be stored in your config file, so it is preserved
for the next time you call Xastir.  For new installs Xastir will default to
English until you change the language with this command line option.

The menus on the top may be accessed with the mouse or with keyboard
shortcuts. The keyboard shortcuts may not work correctly with num-lock on.

You will need to configure interfaces in order to actually use Xastir.
Interface configuration is detailed under the "Configuring Interfaces" help
topic and its subtopics.

If you are operating in a situation where a coordinate system other than the
default DD MM.MMMM system would be helpful, you may select your preferred
system by going to File|Configure|Coordinate system.  Any of the supported
coordinate systems my be used as input by using the Coordinate Calculator.

HELP-INDEX>Configure the Station Information

                         Configure the Station Information

Click on File, then Configure, then Station.

Fill in your Amateur Station call sign.

Fill in your station position if you are not using Xastir with a GPS 
unit. You can locate your general position on the map with Xastir and
use the position given by the cursor placement over the map. This
position will be viewable in the box at the bottom of the Xastir screen
2nd from the left, whenever the mouse is over the drawing area. You can also
choose "Move My Station Here" from the right-click menu while your mouse is
over your location. If you have a GPS you can skip this and set up the GPS
later.

"Send Compressed posits", if selected, will transmit in the newer compressed
format. This format will reduce the amount of data on the air, thereby
increasing the capacity of the APRS(tm) network. The maximum precision of the
transmitted position is also higher. Some older programs, including recent
versions of WinAPRS, do not decode this format yet. Findu.com might also have
trouble with it.

To select a symbol to be used for your station you need to specify
a group and a symbol character. You can manually fill in these fields,
or press select to graphically choose a symbol. There are two groups
of symbols available. A text description of each symbol can be found
in the "symbol table" help topic.

For some symbols of the secondary group you can specify an overlay.
With that a symbol will be displayed together with an additional
overlay character, e.g. a car symbol with the number 1 overlayed on
top of the symbol.

For using overlays you need to select a symbol from the secondary symbol
table and enter the overlay character to be shown in the group/overlay
field. Only numbers and uppercase characters are allowed as overlay
characters. According to the APRS(tm) specification not every symbol can
be overlayed, Xastir doesn't enforce this, but some other programs may.
Note that not all of the symbols have been implemented in the graphics
chooser yet, and some of them are not per the APRS(tm) spec yet.

Next, enter the data for the power/height/gain of your station. This
is useful information but is not required; simply select "Disable PHG"
to disable it. These choices present a granular representation of your
stations range. Select the combination of values closest to the
description of your station.  Please use height above average
terrain (HAAT) for the height value.  Do NOT use average height
above sea level or height above ground.

Another option would be to specify the RNG in the comment field in miles
instead of using PHG. See the APRS(tm) spec for details.
    
For Gain use the gain of your antenna in dBi. 
(FIXME: dBd? spec is unclear, I think it's implying dBi because it says "in
absence of any data, stations are assumed to be running 10w to a 3dB omni at
20ft. A typical omni is only 3dBi.....) 

Note: The gain setting is really intended for vertical antennas; the gain
setting for a beam should be quite a bit below the forward gain of the beam.
This is because with directivity set, the PHG circle is only offset by 1/3rd
of its size toward the specified direction. Setting gain higher will enlarge
the whole circle unrealistically, rather than increasing the directivity.
There was talk several years ago about amending the specifications to better
deal with beam antennas, but nothing was changed.

Enter a comment, not required but it will add insight on your station.
A common thing to enter here is your preferred e-mail address.  It will
be transmitted along with your posits.

Position ambiguity will allow you control how accurately you transmit your
position. A setting of none will allow your station to transmit the exact
position you have entered or received from a GPS. The other choices will
place you somewhere in the range of the choice you selected.  Note that
this may throw some non-spec compliant stations for a loop.  Findu.com
doesn't understand position ambiguity.

Clicking OK will save your changes, Clicking on Cancel will keep the
previous settings.

HELP-INDEX>Configure Default Operation

                        Configure Default Operation

Click on File, then Configure, then Defaults.

This page sets up some standard defaults for the program operation. 

Transmit Station Option sets the type of packet your station will transmit 
its data as.

IGate Options will set your station up as an Internet-RF gateway. This option
should be used with caution; As a ham you are responsible for the data that
comes in via the Internet and is transmitted via RF. You also will need to
choose an IGate option on each interface in order for the IGate to function.
If you want to have your IGate forward NWS weather alerts to RF, you must
create a ~/.xastir/data/nws-stations.txt file listing each call or NWS station
(like "PHISVR") that you would like to transmit via RF.  This feature is
currently implemented only for NWS messages.
                     
"Compress object/item data while transmitting?", if selected, will transmit
objects and items in the newer compressed format. The maximum precision of the
transmitted position is higher, and the transmission is shorter, but some older
programs do not decode this format yet.  Currently this only compresses
"standard" objects/items with an optional speed/course.  It won't compress
area, signpost, or DF objects/items, and won't currently represent
altitude in "standard" objects/items.

"Pop up new Bulletins", if selected, will cause Xastir to bring up the bulletin
dialog when bulletins within the configured range are received. "View 
zero-distance bulletins" will cause bulletins with no known location not to
be displayed or cause pop-ups.

"Warn if Modifier keys" will cause Xastir to print a warning if you attempt to
use Xastir while num-lock, scroll-lock, or caps-lock is engaged. Some users
report the screen blanking on them and similar problems when they attempt to
use Xastir with one of these modifier keys on.

You can also select "Activate alternate net?" choose an altnet call from this
dialog. Altnet allows you to have a private APRS(tm) network among the
stations that also have altnet configured, and have the same altnet call
entered.

"Disable Posit Dupe-Checks" disables the check for duplicate copies of a
position. This should only be used when a station might return to exactly the
same position (within 60' or so for non-compressed positions) and you wish to
see the duplicate positions and/or tracks displayed on the map.  This option
is almost never needed in practice, but can be useful for special events like
search and rescue operations.

HELP-INDEX>Configure Timing

                            Configure Timing

Click on File, then Configure, then Timing.

Posit TX Interval specifies how often your station's position will be
transmitted.  For fixed stations a good recommendation is every 30 minutes,
and definitely no less than 10 minutes.  Mobile stations may wish to use a
faster rate.  Note that if you're using SmartBeaconing, this slider is
ignored.

Object/Item Max TX Interval is the maximum interval used for sending out
objects and items. Try to keep these intervals reasonable, as transmitting
to a long path every 5 minutes will really take up a lot of the air time.
A decaying interval algorithm is triggered any time an object is created,
modified, or killed.  The transmit interval will increase until it hits the
max interval indicated by the slider.

GPS Check Interval will set the interval of time to look at the GPS for new
data. This is available for stations using an HSP or shared cable with their
TNC.

Dead-Reckoning Timeout adjusts how long a position is assumed valid for the
purpose of estimating its current position.

New Track Time adjusts how many minutes must elapse before a new
separate track is started.

RINO -> Objects Interval adjusts how often waypoints are downloaded from an
attached Garmin RINO radio/GPS unit.  APRS Objects are created out of any
waypoints beginning with "APRS".  The "APRS" prefix is removed when creating
the Object names.

Station Ghosting Time specifies the ghosting interval. Stations that have not
been heard in the given period will appear ghosted on screen.

Station Clear Time specifies when a station will be removed from the screen.

Station Delete Time specifies the number of full days before data from a
station will be entirely removed from the Xastir database.

Serial Inter-Char Delay specifies a wait time in milliseconds between each
character sent to an attached TNC.

New Track Interval (degrees) specifies distance in lat/long degrees at which
a new track segment is started.

HELP-INDEX>Configure Audio Alarms

                           Configure Audio Alarms

Click on File, then Configure, then Audio Alarms.

To use this option you must have a sound card and a program that will play
wav files. The Audio Play Command should contain the program you want to
execute to play the audio file (and any command line options). That of
course doesn't work if the only sound card in the system is used for a
soundmodem...

Each type of alert has a checkbox to enable it. The fields will contain the
name of the file to play. Fields under the option will set parameters for the
option.

The current choices are:
Play message on hearing a new station.
Play message on receiving a new message.
Play message on receiving data from a station within the min/max distance of
     your proximity settings. 
Play message on receiving data from a station (via TNC) within the min/max
     distance of your band opening settings.
Play message on receiving and displaying a new weather alert.

There is a standard set of sounds available most places where Xastir can be
obtained, please see the file INSTALL for more information.

HELP-INDEX>Configure Speech

                       Configure Speech Synthesis

To use this option you must have a sound card and the 'festival' speech
synthesis software installed.  Install Festival and start it in 'server' 
mode prior to starting up XASTIR.  The normal command for this is 
"festival_server &".  If you use the "festival --server" option instead (old
method), you may run into problems with connections getting rejected by the
server.

Once you have festival installed, Xastir will have the ability to speak using
the following choices:

New Station       - Announce the call of a new station.
New Message Alert - Announce the arrival of a new message.
New Message Body  - Speak the contents of a message.
Proximity Alert   - Announce when receiving data from a station within the
    min.max distance of your proximity settings.  This option uses the 
    proximity settings found in the Audio Alarms menu.
Tracked station Proximity Alert - Announce when receiving data from a
    station within the min.max distance of the tracked station. This option
    uses the proximity settings found in the Audio Alarms menu.
Band Opening      - Announce when receiving data from a station (via TNC) 
    within the min/max distance of your band opening settings.  This option 
    uses the distance settings found in the Audio Alarms menu.
New Weather Alert - Not implemented yet.

Info on Festival may be obtained from: http://www.speech.cs.cmu.edu/festival/

HELP-INDEX>Configure Smart Beaconing

Click File, then Configure, then Smart Beaconing.

The main "Enable SmartBeaconing(tm)" Will cause Xastir to transmit positions at
various rates and locations based on the movement of the station. It creates
more realistic trails and makes dead-reckoning much more accurate. This option
is only useful in a mobile station with a GPS attached.

There are several options available to customize the operation of
SmartBeaconing:

High rate
The interval (in seconds) at which beacons are sent when the speed is above the
High speed setting.  This parameter is also used to compute a beacon rate based
on speed when traveling between the high and low speeds.

High speed
The speed threshold that will cause beacons at the rate specified above.

Low rate
The interval (in minutes) at which beacons are sent when the speed is below the
Low speed setting.  Basically consider this to be the stopped beacon rate.
This parameter is not used at all when traveling at a rate of speed higher than
"Low speed".

Low speed
The speed threshold that will cause beacons at the rate specified above.

Minimum Turn
The minimum degrees that corner pegging can occur at "High speed" or above.
Lower speeds will require more degrees of turn to trigger a posit, based on
the value of "Turn Slope" below.

Turn Slope
Fudge factor for making turns less sensitive at lower speeds.  The parameter
doesn't have any units. It ends up being non-linear over the speed range the
way the original SmartBeaconing(tm) algorithm works.

Wait Time
The time in seconds between corner-pegging beacons, prevents multiple
beacons in short succession.

HELP-INDEX>Configure Units of Measure

                        Configure Units of Measure

The default selection is for the Metric System: mm, cm, km/h, etc. To select
English units, inches, feet, MPH, etc. Click on File, then Configure, then
toggle the "Enable English Units" check-box.

HELP-INDEX>Save Config Now!

                        Save Config Now!

This button will save all of the current configuration to the config file.
Note that when Xastir is closed, it also saves configuration to the config
file.

HELP-INDEX>Bottom Status Bar

                         Bottom Status Bar

At the bottom of the window various status messages are available:

In the first box on the left general status messages are displayed for a
short time.

The second box displays the current lat/long or UTM, and Maidenhead grid
square position of the mouse over the map. If file|configure|Dist/Bearing
Status is selected, this box will also contain the course and bearing of
this position relative to your station.

A third box is used to display how many stations are in the database.

The fourth box will display the current zoom level and will display "Tr" if
the station tracking is on.  At some zoom levels the Tr is not
displayed properly due to the size of the box. 

The fifth box indicates whether logging is enabled.

The last area will display the device status for each interface. Each will
display in order first to last or 0 to 9. The interface status is separated
into three areas, top device type, center data flow, and bottom interface
operational status.

The device type will show what interfaces are configured. The color will
show what type of device the interface is configured for. Blues are for
the various TNC devices; Greens will show the GPS devices; Yellow for
Internet Servers; Orange for WX interfaces.

The center will show data flow in (arrow pointing left) or data flow out
(arrow pointing right) for that interface.

A green box at the bottom will show if that interface is active. A red
box will show if the interface is active but in an error condition.
Otherwise nothing will show if the interface is not active.

HELP-INDEX>Moving the Map and the Options Menu

                    Moving the Map and the Options Menu

Map movement is very simple, ease and quickness of movement is dependent on
your processor speed and the amount of detail you load. Hint: You can
disable all maps in the maps menu in order to move around quickly, then
enable maps again.

Zooming:
Zooming can be accomplished by right clicking on the map (and holding the 
button down). This will bring up an options menu, with choices to zoom in or
out a single level, or to change to one of the preset zoom levels.

All zooming functions from the options menu will zoom in or out at the point
on the map where you clicked the right mouse button. Zoom levels have a cascade
menu. Levels 1-64 are for very local areas and levels 256 and above are for
large areas. The lower number the level, the more local the area.

A quicker zoom in function is to push and hold the left mouse button, drag it
across the area of interest and let go.  The map will zoom to approximately
the size of the square you just described with the mouse drag operation. The
"move" and "measure" toolbar check-boxes must be disabled for this feature to
work. Clicking the middle button zooms out with a factor of 2, centering
where you clicked as well.

The map can also be zoomed with the keyboard PageUp/PageDown keys, or the "In"
and "Out" buttons in the toolbar. The zooming in this case keeps the same map
center (no centering).

Panning/Centering:
The map can be centered at a specific location by choosing center in the
right-click options menu.

Panning is also accomplished by using the options menu, or by using the arrow
buttons on the toolbar. The map position will shift a portion of a screen.
Enough data from the previous screen should be available to re-orient yourself.

The map can also be panned with the keyboard arrow keys.

More About Options Menu:

Map Display Bookmarks
See the help topic "Creating and using Map Display Bookmarks"

The "Station Info" selection on the options menu will look for the station
closest to where you right-clicked the mouse. If more than one station is
close to that position a "Station chooser" list will appear, then you can
choose what station's data you want to look at. If only one station is close
to the mouse pointer then that station's data will display immediately. For
mobile stations with a lot of track data this could need some time on slow
computers. Note that expired stations still have their data stored in the
Xastir database, and if one knows a station's former location, one can still
view its info in this manner. Use the "Display Expired Data" option
to display some data that disappears for ghosted stations, like
speed/altitude, etc.

With "Last Map View" you can restore the previous map view by restoring the
previous values of the map zoom and centering values.

For Object and Item information, please see the help topic "Objects and Items"

Draw CAD objects lets you create polygons on screen, for tactial or
presentation use. This feature is still under construction.

"Move my Station here" Allows you to move your station to a specified map
location without editing the station configration.

HELP-INDEX>Objects and Items

A station could place several different objects on the map, with their
position transmitted to other stations. The object names are less restrictive
than the normal station names.

Objects and items are nearly the same things, but their use could differ a bit.
Objects are generally used for moving or variable things such as thunderstorms,
while items are generally used for more inanimate things, such as water
stations. Because items may not be decoded by some flavors of APRS(tm)
programs, objects are often used for inanimate things, too.

Besides normal objects with a symbol at its position there are some special
objects available. Area objects are useful for a variety of operations in
which you want to draw or highlight an area of interest on the map. They can
also be used to draw trails/roads/boundaries, watch boxes for severe weather,
runways, perimeter of a search area or of a public service event, areas of
damage, areas to stay out of, buildings that aren't on the map, checker/chess
boards for gaming on APRS(tm). :-)  Note that area objects are not
implemented on all versions of APRS(tm) programs, and some of the details of
how they are displayed may also be different on other programs.
For the other three, probability circles, signposts and DF objects, see below.

Objects/Items are retransmitted at a decaying rate up to the max interval
specified in File|Configure|Timings.  "killed" objects/items are also
retransmitted in this manner until they expire from the queue (currently 20
transmits).  Objects/Items are persistent across Xastir sessions, and are
stored in ~/.xastir/config/object.log. This file may be cleared by selecting
"Clear Object/Item history" from the Stations menu.

The Object/Item creation option in the right click menu will bring up a dialog
with the position of your object filled in based on where you clicked the
mouse. You may fill in the details, and add an object/item from this menu.

The Object/Item modification option brings you the object modification dialog.
It is similar to the object creation dialog, except the object's current
information is already filled out, and the object's name and a few of the
other options can't be changed. You could also delete the object with this
option.

Objects and items can be moved with the mouse if the "Move" check-box on the
toolbar is enabled.  


Description of the entries in the object dialogue:

= Signpost =
This makes the object a signpost object. These signs can contain one
to three characters, and currently appear in Xastir as a blank sign.
Station Info shows the value contained on the sign.

= Area Object =
This makes the object an area object, and enables the area object controls
described below.

= DF Object =
This is a direction-finding report. Enabling it allows you to choose Omni or
Beam report, and allows you to put in the specifics for each.  See:
    http://web.usna.navy.mil/~bruninga/dfing.html
and the APRSdos documentation for details on these useful techniques.
(FIXME: Separate section on DFing techniques?)

= Probability Circles =
FIXME: Write this part

= Name =
This is the name of the object or item. It may be up to 9 characters long,
with spaces allowed inside the name. When modifying an object, this may not
be changed. To rename an object you must delete the original and then create
a new object. Note that if you select Signpost/Area Object/DF Object that
this field and perhaps others are cleared. Enter the name AFTER you've
selected the type of object it will become.

= Station Symbol =
You may select a symbol for the object. Press select to choose graphically,
or see the symbol table help section for descriptions of each symbol.  Note
also that area objects, signpost objects, and DF objects have special fixed
symbols and therefore can't be selected here.  Those particular symbols get
automatically assigned when you change to that type of object.

= Location =
The location of the object is specified here. If you selected "Create 
Object/Item" from the right-click menu, the location you clicked will be filled
in. If you moved an object with the mouse, the new location will be in these
fields.  You can also type in a location, for instance you may be placing an
object from an over-the-air voice report.

= Generic Options =
You may specify the speed, direction, and altitude of objects here. Some object
types cannot have a speed or direction, in which case the fields are grayed
out.

= Signpost Text =
If the object is a signpost object, you may specify the 1 to 3 digit
number that appears on the sign here.  Note that Xastir doesn't display
signpost objects properly yet.

= Area Object =
Area Objects are used to highlight specific parts of maps, or to draw extra
detail onto maps. This will be done with the following entries:
  = Bright Color =
    Use the brighter version of the colors allowed.
  = Color-Fill =
    The area should be filled, not just outlined. This may be useful to
    exclude an area from a search or other event.
  = Object Type =
    Choose from the geometric shapes allowed.
  = Object Color =
    Choose the color in which the object will display. This is also affected
    by the "Bright Color" option above.
  = Object Offset Up =
    In hundredth of a degree latitude.  An unfortunate detail of the spec,
    and hard to calculate easily.  Suffice it to say that you can change
    the size of the object once you place it.
  = Object Offset Left except / =
    In hundredth of a degree longitude.  See above.
  = Object corridor =
    This is the width of a line area object. Useful for runways, weather
    watch boxes, describing an area of interest or an area of exclusion, etc.

Always delete your objects and items when you are done with them!
Don't just allow them to expire from your cache, as they may hang
around on other people's screens for an extended period.


Description of weather watch boxes:

Watch boxes and "areas of maximum concern" (AOMC) generated by the Wxsvr
(http://wxsvr.net/) are colored as follows:

  Yellow dashed = Severe Thunderstorm Watch  (looks like crime scene tape)
   Yellow solid = AOMC for Severe Thunderstorm Warning
     Red dashed = Tornado Watch
      Red solid = AOMC for Tornado Warning.
   Green dashed = Mesoscale (larger) discussion area
    Blue dashed = Test Watch
     Blue solid = Test Warning

HELP-INDEX>View Menu

                     View Menu Options

The View menu presents various ways to look at data in Xastir.

Bulletins
This is the APRS(tm) bulletin board, where important announcements are posted.
If you are connected with the internet interface, it is a good idea to set the
range field to a few hundred miles, to ignore posts from other portions of the
world. "0" in the range field means the entire world. Click the "Change range"
button to make changes to this field effective. Xastir currently does not
support sending bulletins. Incoming bulletins will open this dialog
automatically if you select "pop up new bulletins" in the Configure|Defaults
dialog.  The "View zero-distance bulletins" button enables viewing bulletins
for which you don't have a range yet (they haven't sent a posit yet, but you
received a bulletin from them).  If this is unchecked, you must get a position
from a station, and the station must be within the range selected (or range
must be set to zero), in order for the bulletin to be viewed.
 
Incoming packet data
This displays the incoming data on your TNC or internet interface. The radio
buttons below select if you want to see only TNC data, only internet data, or
both.

Mobile Stations
This is a list of stations that are moving. Stations qualify for this list if
they have moved (more than one position received for them), the symbol of the
station is not considered. Information shown includes course, speed, altitude,
position, number of packets received, number of visible GPS satellites, course
from your station, and distance from your station. 

All Stations
This option displays a table of all stations sorted alphabetically. It includes
the number of packets heard, the time the station was last heard, the path that
the most recent packet took, the PHG, and the comment of the station.

Local stations
This option displays only stations that are heard via your TNC. It includes
the number of packets heard, the time the station was last heard, the path that
the most recent packet took, the PHG, and the comment of the station.

Last Stations
This option displays a table of all stations sorted from most recently heard
to least recently heard. It includes the number of packets heard, the time
the station was last heard, the path that the most recent packet took, the PHG,
and the comment of the station.

Objects & Items
This option displays only objects and items. It includes the number of packets
heard, the time the objects/item was last heard, the path that the most recent
packet took, the PHG, and the comment of the object/item.

Own Objects & Items
This option displays only objects and items that you control (i.e.: Have sent
the most recent update for). It includes the number of packets heard, the time
the objects/item was last heard, the path that the most recent packet took, the
PHG, and the comment of the object/item. A ghosted icon indicates that the
object has been deleted.

Weather Stations
This option displays a table of all the APRS(tm) weather stations and their
data. Data includes wind course, wind speed, wind gust speed, temperature,
humidity, barometric pressure, rain in the past hour, rain since midnight,
and rain in the last 24 hours.

Own weather data
Displays your weather data if you have a weather station and have configured
Xastir to access it.

Weather Alerts
Displays weather alerts received, including the alert flags, alert source/type,
alert destination, expiration, message, and effected location. This data
is used for the alert highlighting. Double-clicking on an alert will request
further information about it via finger from the online WXserver. This only
works if you have internet access; future versions may access this data over
radio as well.

Message Traffic
Shows all message traffic while the window is open. It includes the source,
destination, interface, and message. The range option can limit this display
to nearby stations, much like the range control on bulletins. A range of 0
causes all messages to be displayed.

GPS Status
Shows the status of your GPS unit, including the type of fix and number of
satellites aquired.

Uptime
Shows the amount of time elapsed since Xastir was started.

HELP-INDEX>Map Menu and the Map Chooser

                       Map Menu and the Map Chooser

Map Menu:

Map Chooser
This will present you with a list of map directories and/or files in your
map directory. Checking the "Expand Dirs" option toggles the expansion of
directories into individual map files. The properties dialog allows more
advanced controls, and is described below. Click on map names to highlight
them, this will cause them to be displayed when you click the OK button. You
may select any number of maps. Clicking "Clear" will select no maps,
clicking "Vector" will select only vector maps. The three "topo" options will
automatically select all GeoTIFF images of the listed size. Clicking the OK
button will display the selected maps. Cancel will abandon any changes.

  Map Chooser Properties
  Clicking the Properties button will bring up a dialog where you can specify
  the layer in which maps appear, and in which zoom levels they appear. Higher
  layer numbers are displayed on top of lower numbers. The range may be
  specified from -99999 to 99999; it is suggested that you space your layering
  numbers widely to allow later insertion of additional map layers. From this
  dialog you may specify whether a vector map is drawn with color fills. This
  is a per-map setting; the global disable option on the Maps menu can override
  this. The Filled setting is ignored for raster maps (images). You can also
  select whether a map is considered by the "Auto maps" feature here. Finally,
  you can specify the minimum and maximul zoom levels at which a map is
  displayed. This is useful to prevent very detailed local maps from loading at
  very wide zoom positions, and visa-versa. A minimum zoom of 10 means a map
  will be displayed at all zooms including and above 10. Likewise, a maximum
  zoom of 256 means a map will be displayed at all zooms below and including
  256.

Map Display Bookmarks
See the help topic "Creating and using Map Display Bookmarks"

Locate Map Feature
This option brings up a search dialog where you can search through the labels
in a GNIS file to find a specific location.  It will center the map on the
new location if it is found. The "GNIS File:" entry is saved between calls
and between invocations of Xastir.  You must put GNIS files into the
xastir/GNIS directory in order to use this feature.

Find Address 
This option brings up a search dialog where you can enter an address. It will 
center on the map if the address is found. The path to the goecoder file is 
saved between calls. 

Coordinate Calc
This option opens a simple calculator that can convert between coordinate
systems. This is useful for converting positions to the various formats used
by different groups of people. This same calculator can be called up by the
Calc button on some of the other dialogs. It's useful for entering coordinates
in other formats.

Configure menu:
  Background color
  This option controls the color of the background behind the maps you have
  displayed. The background color is often entirely hidden by filled maps
  (see below).

  Map Intensity
  This controls the brightness of any graphics used as maps. This option only
  appears if you have compiled with GeoTIFF support.

  Adjust Gamma Correction
  This allows you to apply gamma connection to all loaded map graphics. Maps
  can be adjusted individually in their .geo files, see the section on .geos in
  "Map files and WX Counties". This option only appears if you've compiled with
  ImageMagick support, and does not apply to geoTIFF maps; see the above
  option.

  Map labels font
  This allows you to set the font style and size used for map labels.

  Station Text Style
  Controls which font and style to use for station text and others.

  Icon Outline Style
  This allows you to specify an outline that surrounds station icons. This
  helps improve visibility on various backgrounds.

  Configure Tigermap
  Turning this option on causes Xastir to download the map from the US census
  bureau's online tiger mapping server. The dialog that comes up allows one to
  select which layers are displayed, as well as the brightness of the resulting
  map. This is only available if you have compiled with ImageMagick support.
  Tigermaps are always loaded as the bottom layer; they do not have layering
  settings in the Map Chooser.

Disable All Maps
This option disables the loading of any maps. It is most useful when doing
rapid zooming or panning, because it saves the need to load the maps on each
redraw.  Note that this option is not saved between sessions.

Enable Auto Maps
When enabled, any map found in the map directory (or any directory under it)
will be displayed if it falls within the current display region. You can add
any number of directory levels under the main map directory for your maps. Auto
maps will go through any that have Auto Maps enabled (in the Map Chooser
Properties dialog) check them all and find what map (or part) should be
displayed.  All Maps will be merged into the viewing area. If you have a large
quantity of maps, very detailed maps or a slower computer this can be quite
slow. When this option is off, maps selected with the Map Chooser and/or Tiger
Maps dialog will be displayed.

Auto Maps - disable Raster maps
This option prevents Auto Maps from loading maps which are graphics (images).
Only vector maps will be displayed in this case.

Enable Map Grid
When enabled, this option will display a grid line every 10 degrees.  As you
zoom in it switches to a 1 degree spacing. The spacing may be manually adjusted
with the "+" and "-" keys.

Enable Map Levels
When enabled, this option will try to filter out data when the zoom level
shows large areas. This does not work will all maps but will work with the
maps generated from Tiger Line maps at the aprs.rutgers.edu site, and with
ESRI Shapefile maps. This does not decrease the loading times of the maps very
much, rather it simply reduces screen clutter.

Enable Map Labels
This option toggles the display of map labels embedded in DosAPRS, WinAPRS,
GNIS, and ESRI Shapefile format maps.

Enable Area Color Fills
This option controls the filling of vector maps. In certain cases, you
may want to eliminate the fill to see maps below the top maps. This is a global
control, maps may individually have color fill toggled in the properties dialog
of the Map Chooser.

Enable Weather Alert Counties
This toggles the display of county warning area maps for severe weather.
These maps can be obtained and installed according to the directions in the
README.MAPS file. They are displayed on screen when special weather alert
messages are received, and expire after a time or can be remotely canceled.
The weather alert text can be seen under View|Weather Alerts. The
xastir/Counties directory must be populated with the correct files from NOAA
and Shapelib support must be compiled into Xastir in order to enable this
functionality.

Index New Maps on Startup
This option controls if the map index file is built on startup. Most users
should leave this enabled. If the timestamp of the map file is newer than
the map index file, the map will be indexed.

Index: Add New Maps
This option adds any new maps to the max index.  Same rules as the above
Index New Maps feature, but a manual method of invoking it.

Index: Reindex ALL Maps
This option starts over from scratch, indexing every map it recognizes in the
maps directory. This is useful if the Add New Maps function is skipping some
maps, perhaps because of old timestamps on the map files.  This function may
take quite a while to complete if you have a lot of maps.

Mouse pointer menu
This option brings up the options menu normally available by right clicking.

One note on maps:  Many of the currently available vector maps for the
U.S. were created in NAD 1927 datum, while Xastir and other APRS(tm) programs
use WGS 1984 datum.  If zoomed in to a small area on the map the datum
shift may be very noticeable.  The USGS topographic maps have their datum
corrected by Xastir as they are displayed, so positions will generally
be more accurate with those topographic maps.

HELP-INDEX>Map files and WX Counties

                         Map files and WX Counties

Map Types
Xastir will work with various types of map files. All DosAPRS, Windows/Mac
APRS(TM) map files are supported, as well as PocketAPRS format maps and GNIS
(Geographic Names Information System) label files.  Xastir also can be
compiled to use external libraries to support XPixmap (XPM) images, GeoTIFF
topographic maps, and ESRI Shapefile maps.  The graphics handling capability
of Xastir can be greatly extended by compiling with ImageMagick support,
enabling support for many graphic formats as maps (see
"http://www.imagemagick.org/www/formats.html").  Xastir supports weather
alert maps in ESRI Shapefile format, available from NOAA.

Details of locations to obtain many of the above types of maps are found in
the file README.MAPS

Map Locations
Any map file should be stored in the /usr/local/share/xastir/maps directory
on your computer. This location may be different on some systems, depending on
how Xastir was compiled/installed. You can create any number of directories
under this directory to help organize and separate your data. The maps will be
loaded in alphanumerical order unless layering is specified.

Hints on installing and organizing maps are found in README.MAPS. 
Maps in a pixel graphics format actually need a combination of two files,
a data file with a graphic pixmap (.xpm) (or other format if you compiled
with ImageMagick), and a calibration file (.geo). The .xpm file is the
standard graphic format, available without additional libraries. If you
want to save storage space you can use gzip to compress those files 
("gzip map.xpm" will result in "map.xpm.gz"). Xastir detects this
automatically during map loading. You can use XView/Gimp/ImageMagick and
other programs to convert gif, jpg, and tif images into this format if
you don't have support for many image types compiled in (ImageMagick). If
you have problems with maps in xpm format, try to load and save the
graphics with Gimp first, to convert all unknown color names into the
binary representation.

The .geo file is a text data file that will tie the image to a location
in the world. Here is an example of a .geo file that will cover the entire
world with the map world1.xpm:

FILENAME   world1.xpm
#          x          y        lon         lat
TIEPOINT   0          0        -180        90
TIEPOINT   639        319      180         -90
IMAGESIZE  640        320

.geo files can have many elements:

FILENAME <filename>
This specifies the filename of a map image to be loaded from the local disk.  

URL <http://website>
This specifies the URL of a map image to be loaded from a web or ftp site. 
ImageMagick only.

TIEPOINT <x-pixel> <y-pixel> <longitude> <latitude>
Two tiepoints are required, and more than 2 will be ignored.
these two lines are for connecting an x,y pixel position in the image
to a lat and long position on the earth. The points should be as close as
possible to the upper left corner and the lower right corner of the image for
best accuracy.  The latitude/longitude are specified in decimal degrees.

IMAGESIZE <pixels horizontally> <pixels vertically>
This specifies the size of the image in pixels. If this is not set, the image
will be loaded each map redraw, regardless if it is on screen or not.
IMAGESIZE is a REQUIRED OPTION if a URL is specified.  For local files, it's
an optional parameter (we use ImageMagick to query the image size for local
files).

DATUM <datum>
This feature is not implemented.

PROJECTION <projection>
This feature is only partially implemented, default is "LatLon", other
possibility is "TM" to specify that the map is in  Transverse Mercator
projection.

# <anything>
Any line with the first character of a '#' will be ignored.

ImageMagick specific image enhancements:

GAMMA
eg: GAMMA 1.2    or    GAMMA 1.2,2.0,1.2
The first will change overall gamma for this image, the second will
lighten green more than red or blue.

CONTRAST
eg: CONTRAST 0    or    CONTRAST 1
Doesn't seem to do that much, other values make no difference.

NEGATE
eg: NEGATE 0    or    NEGATE 1
0 will negate all colors, 1 just grayscale colors.

EQUALIZE
No argument.

NORMALIZE
No argument.

LEVEL <black_point, mid_point, white_point>
eg: LEVEL 0,1,65535
These values seem to be the defaults.

MODULATE <brightness, saturation, hue>
eg: MODULATE 90,150,100
These are percents, 100,100,100 is the default.

REFRESH <seconds>
eg: REFRESH 900
This tag is used for dynamic URL's such as weather radar, where you
wish Xastir to auto-redraw the map at a specified interval.  By
adding this tag to weather radar .geo's, you can watch the weather
move across your screen.  Xastir contains only one interval counter,
so the smallest REFRESH interval loaded takes effect for all selected
maps.

TRANSPARENT 
Color to remove from the background (make it transparent).  Use a
number, 0=black.  Colormapped images use the map value, so white is
usually 0xffffffff (32-bits of 1's).  Values must be in hexadecimal,
and are preceeded by "0x".  The value can be obtained by using debug
level 16.  The first of the four numbers after "Color allocated is"
is the colormap index.

CROP <left top right bottom>
Removes borders (makes them transparent).  Values are in pixels with
(0,0) at the upper left.  A good value for the 620x620 NWS radar
images is "CROP 35 20 616 600"

Special/nonstandard .geo files:

TIGERMAP
A file with just the word "TIGERMAP" will cause Xastir to retrieve an
online Tiger map of the area on screen. These are not available for every
place in the world. A tigermap.geo is automatically installed in the maps
directory.

TERRASERVER
A file with just the word "TERRASERVER" will cause Xastir to retrieve a
Terraserver satellite photo of the area on screen. Those services are not
available for every place in the world. Note that using the Terraserver
maps at any zoom above 256 will probably take a long time to load, won't
show much detail, and probably won't display correctly. This is a limit
of Microsoft's Terraserver, not Xastir.

TOPOSERVER
A file with just the word "TOPOSERVER" will cause Xastir to retrieve a
topographic map of the area on screen. Those services are not available for
every place in the world. Note that using the maps at any zoom above 256
will probably take a long time to load, won't show much detail, and
probably won't display correctly. This is a limit of Microsoft's
Terraserver, not Xastir.



geoTIFF maps are a combination of two files as well: a .tif and a .fgd file.
The .tif file is the actual map data.  The .fgd file need only contain four
lines like this (but may contain many other lines):

1.5.1.1   WEST BOUNDING COORDINATE:  -122.000000
1.5.1.2   EAST BOUNDING COORDINATE:  -120.000000
1.5.1.3   NORTH BOUNDING COORDINATE:  48.000000
1.5.1.4   SOUTH BOUNDING COORDINATE:  47.000000

Xastir uses only those four lines in it's calculations to determine the corner
points of a map, to see whether the map fits in the current viewport (so it
can decide whether to skip it).  If your map data are USGS topographic maps,
the .fgd file should be readily available to you. If it is not, the mapfgd.pl
script can create it for you. If you don't have a .fgd file, the map will load
fine, but the white borders won't be cropped and the size and rotation may be
off a tad bit. An added feature in Xastir is the ability to do datum
translations from NAD 1927 to WGS 84 datum, which makes the USGS topographic
maps much more positionally accurate on the Xastir screen.

Xastir can use USGS geoTIFF topographic maps directly from the CD drive.
Manually mount the disk or use auto-mounter to do it for you, and make sure
you have a sym-link created in your maps directory that points to where you
mounted your CDROM drive.  That's it!


ESRI Shapefile maps are also a combination of several files, a .shp file, a
.dbf file, and a .shx file. You only need to select the .shp file to load the
map, but the other(s) must be present for the map to load correctly.


GNIS (Geographic Names Information System) data is a collection of names of
locations, or geographic features. These labels behave like map labels in
Dos/WinAPRS maps.  As you zoom in, more labels will appear, assuming you've
selected the GNIS file as a map and have enabled Map Labels in the Maps menu.
If you have some of them in the xastir/GNIS directory, you can also search
for map labels within Xastir.


WX County Maps
All WX County maps should be stored in the /usr/local/share/xastir/Counties
and Xastir only supports the ESRI Shapefile standard for these. Installation
is explained in README.MAPS.  You must have Shapelib compiled in.

As NWS messages are received, different areas will get tinted to designate
areas of concern.  They are color-coded to specify different types of
alerts. The colors are: Cyan for advisory, yellow for watch, red for warning,
orange for canceled alert, royal blue for tests, and green for undetermined
alert levels. The coloring is done with a pixmap stipple that displays the
type of alert, if it is able to be determined. These changes were made so that
the underlying maps may still be seen underneath the weather alert areas, and
so the alert type may be more easily determined, as sometimes matching the
alerts on screen and in the weather alerts dialog is difficult. The display
of weather alerts may be turned on/off via the Map menu.

HELP-INDEX>Stations Menu

                             Stations Menu

These options will allow you to control the data displayed around the stations
on the map. It will also let you track and find stations, and clear stations
and trails in the database and from the map.

Find Station
See the help topic "Locating a Station".

Track Station
See the help topic "Tracking a Station"

Fetch Findu Trail
Downloads historic trail data from findu.com. Slider bars control the starting
point and duration of data downloaded.

Filter Data
This sub-menu allows filtering of the displayed symbols:

  Select None
    Determines if symbols should be drawn on the map. The other options depend
    on this being enabled.

  Select Mine
    Determines if your own station is shown on the map.

  Select via TNC
   Global toggle for displaying data received via a TNC, but may be narrowed:

   Select Direct
     This option only displays stations heard directly (not digipeated).

   Select via Digi
     This option displays stations heard indirectly via a digipeater.

  Select Net
    This option displays stations with data received via the Internet.

  Include Expired Data
    Causes Xastir to continue to display the station data that normally goes
    away when the symbol is ghosted.  The expiration time can be adjusted in
    the File|Configure|Defaults menu.


  Select Stations
    Global toggle for displaying stations, but may be narrowed:

    Select Fixed Stations
      This option displays stationary stations.

    Select Moving Stations
      This option displays stations with multiple positions or non-zero speed

    Select WX Stations
      This option displays Weather Stations.

     Select CWOP WX Stations
      This option includes the display of citizen weather (non-ham) weather
      data.

  Select Objects/Items
    Global toggle for displaying objects/items, but may be narrowed:

    Select WX Objects/Items
     This option displays weather Objects and Items. This includes tropical
     storms and remote weather stations.

    Select Water Gauge Objects/Items
     This option toggles the display of water gauge (/w) objects.

    Select Other Objects/Items
     This option enables or disables the display of objects other than those
     listed above.


Filter Display
This sub-menu allows filtering of the displayed data:

  Display Callsign
  Determines if the callsign is displayed.

    Label Trailpoints
    This option includes callsigns along trails, to help identify which
    points belong to which stations.

  Display Symbol
  Determines if the symbol is shown to the left of the callsign.

    Rotate Symbol
    Some symbols will change their orientation to show the direction in which
    they are traveling.

  Display Trail
  When enabled, any moving station will trail a colored line.  We now display
  as many locations as we have in our database (old limit was 100).  Long
  trail segments (over 2 degrees latitude or 2 degrees long), or segments with
  more than 45 minutes receive delay between the points will not be displayed.
  Duplicate points are also eliminated from the track (SAR team returning to
  base:  Last segment may not be displayed due to the starting point appearing
  twice in the trail list).

  Display Course
  When enabled, green text will appear below the call sign. This will display
  the last known course (in degrees) the station was traveling.

  Display Speed
  When on, red text will appear below the call sign (or course). This will
  display the last known speed of the station. 

    Display Short Speed
    This option removes display of the measurement units for speed.

  Display Altitude
  When enabled, blue text will appear above the call sign. This will display
  the last known altitude of the station.


  Display Weather Info
  Global toggle for displaying weather information, but may be narrowed:

    Display Weather Text
    When enabled, the latest weather data (temp,wind speed/course/gust,
    humidity) is displayed. This may be adjusted with the following option:

      Display Temperature Only
      Displays only the temperature data for the station.

    Display Wind Barb
    When enabled, a wind barb showing the direction and speed of the wind is
    drawn for all displayed stations reporting this information. 


  Display Position Ambiguity
  When enabled, the area in which station using position ambiguity may be
  located within is shaded, with the relevant station in the center.

  Display Power/Gain
  When on, Power/Gain Circles will be displayed. Overlapping circles indicate
  that the stations are theoretically within simplex range of one another.
  This is only roughly accurate, especially in areas of variable terrain. 

    Use Default Power/Gain
    Enables a default power/gain setting as specified in the APRS(tm)
    specification.

    Display Mobile Power/Gain
    Enables power/gain circles for mobile stations.


  Display DF Attributes
  When enabled, any DF circles/lines will be displayed on the screen.

  Enable Dead-Reckoning
  When enabled, the positions of stations are estimated based on past course
  and speed. The recalculation rate should be reasonable, but can be adjusted
  in the configuration file.

    Display Arc
    Displays an expanding arc of expected maximum travel distance, location and
    course given the past course and speed. The arc slowly becomes a circle as
    the position report gets older.

    Display Course
    Displays an expected course and distance traveled by the station, assuming
    the course hasn't changed.
 
    Display Symbols
    Displays a ghosted version of the stations symbol at the expected position,
    assuming the station has continued at its current course and speed.


  Display Dist/Bearing
  When enabled, two lines of text will be displayed on the left side of the
  stations' icon. The top line will contain the distance from your station to
  this station. The bottom line will contain the course from your station to
  this station.

  Display Last Report Age
  Display the time since the station was last heard.

Reload Object/Item History
This will reload the ~/.xastir/config/objects.log file used for Object and Item
persistence. This is needed if you edit the file while Xastir is running.

Clear Object/Item History
This will clear the ~/.xastir/config/objects.log file used for Object and Item
persistence. It is recommended that you manually select and delete all Objects
and Items that you own before doing this, otherwise they may remain on the
screens of other APRS users.

Clear All Tactical Calls
Clears all assigned tactical calls. This will take effect the next redraw.

Clear Tactical Call History
This removes the tactical call history file, meaning that tactical calls
assigned will not remain permanant between Xastir restarts.

Clear All Trails
This will wipe all the line tracking data from the station database and
refresh the screen.  This option is perhaps useful if you're low on memory
or just want an uncluttered screen.  You may also clear individual station's
trails from the Station Info dialog.

Clear All Stations
This will wipe all the data from the station database except yours.  This
option is perhaps useful if you're low on memory or just want to unclutter
your screen.

HELP-INDEX>Messages and the Messages menu

                  Messages and the Messages menu

Send Message to and Open group messages

These are very similar. "Send message to" will send your messages to one
station and will only receive data from that station. Group messages are more
general: you can receive any message for the group and you will send out your
messages to that group name. Group messages code is not fully implemented yet
and various problems still need to be worked out.  The "groups" file is looked
for in ~/.xastir/config.  This is where the groups you are a member of are
stored.  As was said before the "groups" functionality may not be complete yet.

At some point in the near future sending of bulletins should be added to this
menu as well.  It's not coded yet.

Each of these two screens contains a message box, a call line, a message line,
and various buttons. You must first enter the call of the group or station you
want to contact. Once that is done any new message that has come in from that
station to you will be displayed. If the station is sending you information
and no message window is up it will automatically pop up a new window (up to
10) with that station's call sign filled in for you. You can now enter a
message on the message line. The message can be longer that the message line,
and will max out at about 250+ characters. Once your message is entered,
clicking on the "Send Now!" button will send your message. The "Send Now!"
button will gray out until your message is completely ack'ed. Any message you
receive will be sorted by the line # and be placed in the message window. If
you are in a group mode each line will display the call sign from where the
message was sent followed by the message itself. Currently group messages are
sorted by call and then line #. When you are done sending messages clicking on
the exit button will close the window. Other buttons are also available:  The
"New Call" button will allow you to look at old data a station has sent.  Type
in the call and click on this button, any old information will be displayed.
You can also use this button to change the call of the station you're talking
with. Enter the new call and click the button. The "Clear Msg History" button
will clear any message displayed in the message window.  "Cancel Pending Msgs"
will cancel any messages in the transmit queue that haven't been acknowledged
by the remote station yet.  After cancelling the pending messages or receiving
and acknowlegment packet from the remote station, you may send new messages to
the remote station.  Xastir will allow you to type ahead, so you can just keep
typing if you don't want to wait for the acknowledgments.

Messages in reply to previous ones will attempt to use the path of the
received message to avoid flooding the system with broadcast messages. You
may adjust the path in the send message dialog, or the default path(s) set
in the interface properties will be used if you leave this blank.  The path
can be set for each message sent, but once a message is sent the path
remains fixed for that particular message.

Each outgoing message remains highlighted until it is ack'ed by the remote
station.  If it times out or if you cancel the pending messages, those
messages will remain highlighted unless you clear the message history.

Clear all outgoing messages
This will clear all un-ack'ed messages you have sent.

General Stations Query
This sends an ?APRS? packet, which should cause all local stations to report
their position and/or status. Most software ignores this query, because
responding to it would cause massive floods of data.

IGate Stations Query
This sends an ?IGATE? packet, which should cause all local IGates to respond
with their capabilities.

WX Stations Query
This sends an ?WX? packet, which should cause all local weather stations to
report their position and weather.

Modify Auto reply message
This will set the message that is sent as an Auto Reply.

Enable Auto Reply Msg
This will turn on an automatic reply when an incoming message is received.

Satellite Ack Mode
This mode disables the sending of ack messages in response to received
messages. Messages are still acknowledged using the reply-ack system. When
operating over a satellite it is clear that your message made it, because you
will hear it repeated. The receiving station sending an independent ack only
adds QRM.
 
HELP-INDEX>Interfaces Menu

                         Interfaces menu

This menu contains interface related options.

Start/Stop
This option displays a window where you can turn on and off your configured
interfaces.

Properties
This choice brings up a list of installed interfaces, and allows you to adjust
their settings. See the "Configure Interfaces" help topic.

Disable Transmit options
These options disable the transmission of everything, one's position, or one's
objects. These are global options and affect all interfaces. Most interfaces
have an option to disable transmission on that specific interface in their
configuration menus also.

Enable Server Port
This enables/disables a listening socket at port 2023.  You may connect other
APRS clients to that port in order to send/receive APRS data.  Once they
authenticate, they'll be able to send data to Xastir.  Without authentication,
they'll be able to receive every bit of TNC and INET data that Xastir receives.

    "user WE7U-13 pass XXXX vers XASTIR 1.3.3"

Connect another APRS client to that port and it should authenticate
and be able to send to any server that Xastir is connected to, as
well as receive packets from all ports/servers Xastir is hooked to.

Transmit now
Causes all interfaces that have transmit enabled (see configure|interfaces) to
transmit a position packet.  It will be grayed out if Disable Transmit: ALL
is selected.

If you have GPSMan installed, you have these additional menu options
displayed:

Fetch GPS Track
Download a set of trackpoints from an attached GPS.

Fetch GPS Routes
Download a set of routes from an attached GPS.

Fetch GPS Waypoints
Download a set of waypoints from an attached GPS.

Fetch Garmin RINO Waypoints
Snag waypoints from an attached Garmin RINO, create APRS Objects out of any
waypoints which begin with "APRS".

HELP-INDEX>Station info box - FCC and RAC lookup

                  Station info box - FCC and RAC lookup

Station Info will display any data decoded by Xastir.

You can assign tactial calls to stations from here, by clicking the "Assign
Tactical Call" button. This will cause the station on screen to display as
the tactical call instead of its callsign. Assiggning blank clears this
feature, and it can also be cleared for all stations in the Stations menu.

"Enable Automatic Updates" will cause the window to refresh frequently with the
latest information.

The information available may include: Number of packets heard, the time
last heard, the device the packet came from, station comments, 
power/height/gain of the station, course/distance from your station,
weather information, and current and previous positions.

For moving stations a tracklog follows with the most recent entries on top.
A '+' in front indicates that a new track starts at that point (if there was
a large gap in time or position). A star at the end of a line indicates that
this station could be heard direct (without a digi) at that specific position.
Positions are followed by the 6 digit Maidenhead grid square the station was
located in at that point.

For your own station, there is an "Echoed from" field, listing the
last six digipeaters that heard you directly. This is useful for setting
non-generic paths.

Currently two rows of four buttons appear in the Station Info window.  Some
of the labels on the buttons change based on the type of station that you're
dealing with.

For objects/items:

Store     Modify    Blank      Close
Track     Object/
          Item

Station   Trace     Un-Acked   Direct
Version   Query     Messages   Stations
Query               Query      Query

For other stations:

Store     Send      Search     Close
Track     Message   FCC (RAC)
                    Database

Station   Trace     Un-Acked   Direct
Version   Query     Messages   Stations
Query               Query      Query

"Station Version Query" changes to "Clear Track" for mobile stations.
The Clear Track button will clear any line tracking for this station that is
currently stored or on the map display.

Store Track will save that station's track to a file on disk. The used
format is similar to that used by GPS receivers but its specification
might be changed (enhanced) in future versions. There is currently no
way to read that track data back in, but it is planned for the future.
The goal is to also read and display GPS tracklogs in a similar manner.
These tracklog files will be placed in the directory ~/.xastir/tracklogs
with a name equal to the stations call with ".trk" as extension.

Modify Object/Item will bring up the Object Modify window.

Send message will open up the message window and allow you to send a message
to this station. It will fill in the call sign for you.

If the FCC (U.S. Federal Communications Commission) or RAC (Radio Amateurs of
Canada) database is installed and the callsign appears to be a Canadian or
U.S. callsign, the Search FCC/RAC Database button will become active,
otherwise this button will be inactive.  The FCC and RAC files should be
placed in the /usr/local/share/xastir/fcc directory, and case is important!
Pressing this button adds the station's name and address into the Station
Info box.  Instructions for installing these databases are in the README.MAPS
file.

Xastir will create index files for each database file upon startup. If a newer
callsign file is placed there while Xastir is running, it will create or
rebuild the index on the next lookup.  Special prefixes are NOT handled.

HELP-INDEX>Creating a log
                              Creating a log

Xastir can log data from the internet or TNC for later playback, or for
debugging purposes.  WARNING: Logging can fill up your hard drive, so be
careful using it, or make preparations for rolling over the log files
automatically via cron. An indication will be shown on the status bar when
logging is enabled.

All these choices are accessible via the File menu:

Enable TNC Logging
Logs all TNC data received and transmitted. These logs can be played back using
the "Open Log File" feature.

Enable Net logging
Logs all internet data received and transmitted. These logs can be played back
using the "Open Log File" feature.  If you have no interfaces started but still
want to log your posits and objects locally, this is the option to enable for
that as well.

Enable IGate logging
Logs all data forwarded in both directions, and rejected forwards with reasons
for rejection. Includes NWS messages forwarded to RF.

Enable WX logging
Logs all weather data received from your weather station.


HELP-INDEX>Replaying a log

                              Replaying a log

Click on "File", then "Open Log File" and a file selector window will display.
You can use it to browse your hard drive and select any file containing raw
TNC data like those created by the TNC and Net logging options. Your station
will still function the same way, receiving and transmitting. If you were
logging data, the typical place to look for those files would be 
~/.xastir/logs/

NOTE: This function doesn't read the saved station tracklogs.

HELP-INDEX>Locating a Station

                             Locating a Station

Click on "Stations", then "Find Station". A window will pop up. You can now
enter a call or part of a call. By default it will search for an exact match
(full call, not partial) and is not case sensitive. If you are looking for a
partial match, "Match Exact" should not be selected.

For objects which could contain lower case letters you have to check
"Match Case"! Opposite to the name, without "Match Case" the search
text will only be converted to upper case...

Clicking on the "Locate Now!" button will center the first station
found in the center of your screen at the current zoom level.

Clicking "FCC/RAC Lookup" will look up the user's information if the FCC or RAC
database, of those databases are installed.

Clicking on "Cancel" will close the window.

This dialog will pop up if a station sends a Mic-e "Emergency!" packet, to
encourage users to locate and perhaps help the listed station.

HELP-INDEX>Creating and using Map Display Bookmarks

                  Creating and using Map Display Bookmarks

Click on "Maps", then "Map Display Bookmarks" and a window will pop up.
If this is the first time you have used this then the box will have no
entries in it. To add a bookmark to the list: Position the main map to
the area and zoom level you want to use. Enter a unique name in the
"New Name" area, then click on add. Your entry will be added to the
list (in alphabetical order).  You can add as many map display bookmarks
as you want. To use one of the bookmarks mark its name and click
"Activate!". The main map will then show the stored area and zoom level.
You can similarly delete a bookmark by clicking on the bookmark name and
then the "Delete" button.

"Maps->Locate Map Feature" is another method to jump to a location, if
the name of the location is known and you have GNIS files installed.

HELP-INDEX>Tracking a Station

                        Tracking a Station

Click on "Stations", then "Track Station". Enter the callsign to track (all or
part) then click on the "Track Now!" button. As the station moves it will
remain viewable in the main map window. As the stations starts to get close
to the edge of the map window the window will re-center so that the object is
always visible. To stop tracking this station click on the "Clear Tracking"
button. While tracking is active, a "Tr" is shown in the status bar next to
the zoom level.  If the station is not on the map yet, tracking will begin
as soon as it shows up.

HELP-INDEX>Printing

                       Printing the Map Screen

Note: Printing has not been set up on Windows/Cygwin.  These instructions
are for Unix and Unix-like operating systems.

Xastir can print the drawing area in either black & white or color.  It does
this by first dumping the image to an XPixmap file on disk, then using external
tools to convert it to postscript, scale it, rotate it, preview it, then print
it.  You must have your system printing set up to handle postscript (usually
this requires Ghostscript and a print filter installed, as well as lp or lpr
print spoolers).  You must also have the following tools installed for this
capability:  ImageMagick tools (specifically "convert"), "Ghostscript",
Ghostscript fonts, and "gv".  Once all of these packages are installed and
functional, you should get a "gv" window popping up shortly after you tell
Xastir to create a print file.  From there  you can view the printed image, and
if acceptable, tell "gv" to print it.  Note that sometimes changing to a white
default background for the maps is recommended, depending on what maps you have
viewable.  This can save greatly on ink.

HELP-INDEX>Creating Snapshots

                     Creating Automatic Snapshots

Xastir has the capability to create automatic snapshots of the map screen
on a recurring basis.  This time period is currently set at once per five
minutes.  Assuming that you have "convert" from the ImageMagick tools
installed, Xastir will create an XPM format file in ~/.xastir/tmp/, then
convert it to the PNG file ~/.xastir/tmp/snapshot.png. This file is useful for
embedding in web pages to show a "live" image of what is on your Xastir
screen.  Enable this feature via the "File->PNG Snapshots" togglebutton. 
The rate is once every five minutes, or every time the button is toggled from
off to on. A .geo is created to allow you to use the snapshot as a map.

HELP-INDEX>Included Scripts

                        Included Scripts

Xastir includes several Perl scripts and a shell script that may be useful:

fcc-get
This shell script automates retrieving and installing the FCC and the RAC
callsign databases. Note that these databases are large; the two downloads are
60Mb total!

icontable.pl
This script generates an xpm bitmap of all Xastir's primary and secondary
symbols from the symbols.dat file. The overlays and specials are ignored.
Output is to STDOUT, so a typical call would be "icontable.pl > symbols.xpm".

inf2geo.pl
This script creates .geo files from UI-View .inf files. To create a map.geo
from a map.inf, typical usage would be "inf2geo.pl map".

kiss-off.pl
This script sends the commands needed to turn off a TNC's KISS mode.

mapblast2geo.pl
This script creates .geo files for Mapblast pixel maps. It includes usage
information.

mapfgd.pl
This script creates minimal .fgd files for GeoTIFF images lacking them, based
on information found in the GeoTIFF file. The created files allow Xastir to
crop the white borders and rotate/scale the map properly. Typical usage would
be "mapfgd.pl mapdir" where mapdir is the directory containing the GeoTIFF
images.

overlay.pl
This script creates .log format files from comma-seperated overlay files. See
the script comments for full usage information. 

ozi2geo.pl
This script creates .geo files from OziExplorer .map files.

permutations.pl
This script converts between different lat/lon formats. See the script comments
for further details.

split_gnis.bash
This will take a GNIS datapoint file (typically for a whole state, 8+Mb), break
it down into smaller chunks (typically for a county, 30-200k) it will also
throw away the trailing spaces and <CR>'s at EOL.

split_gnis.pl
This is a perl version of the above script.

test_coord.pl
Tests for the Coordinate.pm perl module.

track-get.pl
This script downloads the tracklog of a specified object from a Garmin GPS.
It requires the GPS::Garmin module. It prompts for an object name, and writes
the tracklog to the ~/.xastir/logs directory.

update_langfile.pl
This script is targeted toward developers. It rebuilds a specified language
file to contain all the strings of another. It is usually used to regenerate
the non-English language files when significant changes have been made to the
English file. When the second language file lacks a string in the main file,
the untranslated string is inserted. Typical usage would be 
"update_langfile.pl language-German.sys" . The main language file is
hard-coded but easily editable.

waypoint-get.pl
This similar script downloads the waypoints from a Garmin GPS, and creates a
log in the ~/.xastir/logs directory containing the waypoints as objects. It
also requires the GPS::Garmin module.

HELP-INDEX>Configuring Interfaces

                           Configuring Interfaces

Click on Interfaces, then Properties.

An "Installed Interfaces" box should appear. This box will allow you to add,
delete, and modify the properties of various devices you may want to use with
Xastir.

Current options are:
Serial TNC
Serial TNC w/GPS on HSP cable
Serial GPS
Serial WX
Internet Server
AX.25 TNC
Networked GPS (via gpsd)
Networked WX
Serial TNC w/GPS on AUX port
Serial KISS TNC
Networked Database (Not Implemented Yet)
Networked AGWPE
Serial Multi-Port KISS TNC

To add a device, click on the add button. A "Choose Interface Type" box will
appear. Click on the type of device you would like to add. Then click the Add
button in the "Choose Interface Type" box. Properties for that device will
appear. Fill out the requested information and click OK.

To delete the device, click on the device you wish to delete and then click
the delete button.

To modify the properties of a device, click on the device you wish to modify,
then click the properties button. The properties for that device will appear.
Change the information you want and click OK.

More specific help is available under the help topics of each interface type.

HELP-INDEX>Configure Serial TNC Devices 

                          Configure Serial TNC Devices 

This section covers adding or modifying Serial TNCs or Serial TNCs with a
GPS on a HSP cable.

If you have a HSP cable, which allows you to share the TNC port with a GPS
unit you may choose a TNC with GPS (HSP Cable). This is a special cable and may
not work on all computers/GPS/TNC combinations. If you use this device the TNC
and the GPS should be set to the same communications parameters. Generally
4800 bps, 8 data bits, no parity, and 1 stop bit.

TNC Port Options:
Selecting "Activate on start up" will tell Xastir to look for this device and
set up communications with it when the program first starts.

Selecting "Allow Transmitting" will tell Xastir that any outgoing RF data can
be sent to this device for broadcast.

The TNC Port is the Unix device that the TNC (or TNC and GPS) is hooked to.
Normally you can use /dev/ttyS0 (com1), /dev/ttyS1 (com2) etc.

Comment will allow you to set a friendly name or comment for the port.

Now set the bps rate under port settings, and the parameters under port
style. Port Style setting 8N1 is used for 8 data bits, No parity and 1 stop
bit. 7E1 is used for 7 data bits, even parity and 1 stop bit. 7O1 is used for
7 data bits, odd parity, and 1 stop bit. These parameters must match your TNC
and GPS.

Choose the correct IGate operation for this device. You may have several TNC
devices, and this option can be different for each device. If you are not
running an IGate leave it at the default option of "Disable".

Enter up to three UNPROTO paths. Xastir will assume the XX VIA part of the
UNPROTO path. There are three paths allowed so that your signal will be heard
if conditions are bad. XASTIR will cycle through each one that is filled in,
one per transmission time.  If you are local to a digi, just a WIDE may be a
good choice. If you are using low power and/or are distant from a digi then
RELAY, WIDE may work better. Or if you know the call of your closest digi you
may use XXXCALL, WIDE. Most of you will only need one path. If you are in a
remote area and your signal is difficult to get out you may need more. Check
with a local group and ask what path may be best for your area.  Some areas
use the more efficient flooding protocols, in which case you might use WIDE3-3
or RELAY,WIDE3-3.  If no paths are entered it will default to RELAY,WIDE.

If you are IGating to RF, you may enter a specific path to use for the packets
you send to RF. If you leave this blank, the UNPROTO paths above will be used.
If the UNPROTO paths are blank, RELAY,WIDE will be used.

TNC Startup and Shutdown files. These fields specify a filename that is
located in the /usr/local/share/xastir/config directory. Each file is a
standard text file containing any commands you would like to send your TNC at
the time the device is activated (startup file) or shut down.

HELP-INDEX>Configure Serial TNC w/GPS on HSP cable or AUX port

                Configure Serial TNC w/GPS on HSP cable or AUX port

These hybrid interface types implement the options of both serial TNCs and
GPSs. Please consult the configuration help for both serial TNCs and serial
GPSs for further information on the configuration of these devices.

HELP-INDEX>Configure Serial KISS TNC

                     Configure Serial KISS TNC

This section covers adding or modifying Serial KISS TNCs. KISS mode can be done
by most standard TNCs too, and it eliminates the necessity to set the options
specially in the startup files, at the expense of slightly higher processor
usage. And of course this enables the use of purely KISS TNCs, such as the one
described in the November 2000 issue of QST, without a separate program or
kernel module.

Options
Selecting "Activate on start up" will tell Xastir to look for this device and
set up communications with it when the program first starts.

Selecting "Allow Transmitting" will tell Xastir that any outgoing RF data can
be sent to this device for broadcast.

Selecting "RELAY Digipeat?" will tell Xastir to digipeat traffic with either
your callsign or "RELAY" in the path. This option is only recommended for
base stations in regions where there are few other RELAY stations in the
area. Consult with a local group about the best setting for your region. 

The TNC Port is the Unix serial device that the TNC is hooked to.
Normally you can use /dev/ttyS0 (com1), /dev/ttyS1 (com2) etc.

Comment will allow you to set a friendly name or comment for the port.

Now set the bps rate under port settings.

Choose the correct IGate operation for this device. You may have several TNC
devices, and this option can be different for each device. If you are not
running an IGate leave it at the default option of "Disable".

Enter up to three UNPROTO paths. Xastir will assume the XX VIA part of the
UNPROTO path. There are three paths allowed so that your signal will be heard
if conditions are bad. Xastir will cycle through each one that is filled in,
one per transmission time.  If you are local to a digi, just a WIDE may be a
good choice. If you are using low power and/or are distant from a digi then
RELAY, WIDE may work better. Or if you know the call of your closest digi you
may use XXXCALL, WIDE. Most of you will only need one path. If you are in a
remote area and your signal is difficult to get out you may need more. Check
with a local group and ask what path may be best for your area.  Some areas
use the more efficient flooding protocols, in which case you might use WIDE3-3
or RELAY,WIDE3-3.  If no paths are entered it will default to RELAY,WIDE.

If you are IGating to RF, you may enter a specific path to use for the packets
you send to RF. If you leave this blank, the UNPROTO paths above will be used.
If the UNPROTO paths are blank, RELAY,WIDE will be used.

Next configure the KISS parameters: TXdelay is the time (in 10ms units) needed
between the keying of the radio and when it is ready to send data. Persistence
and slottime are the channel access parameters: Slottime is how often the
channel access algorithm is executed, and should usually be set to 10.
Persistence is how aggressively your station tries to grab the channel when
free, and should be ideally set to 255 divided by the number of stations on the
channel. Full duplex allows the transmission to begin while there are packets
being received on the channel, this should be disabled in most cases (set to
"0").

HELP-INDEX>Configure AX.25 TNC Devices

                        Configure AX.25 TNC Devices

This section covers adding or modifying AX.25 TNC devices. AX.25 devices can
be any device that uses the Linux AX.25 drivers. This is a kernel level
driver, and device such as a Baycom or a sound modem can be used as a TNC.
These devices must be set up and running before Xastir can use them.

Selecting "Activate on start up" will tell Xastir to look for this device and
set up communications with it when the program first starts.

Selecting "Allow Transmitting" will tell Xastir that any outgoing RF data can
be sent to this device for broadcast.

Selecting "RELAY Digipeat?" will tell Xastir to digipeat traffic with either
your callsign or "RELAY" in the path. This option is only recommended for
base stations in regions where there are few other RELAY stations in the
area.  Consult with a local group about the best setting for your region.
This is only needed if you are not using any other software that performs
this function, such as aprsdigi or DIGI_NED.

Enter the AX.25 Device name you specified in the axports file for this device.

Comment will allow you to set a friendly name or comment for the port.

Choose the correct IGate operation for this device. You may have several TNC
devices and this option can be different for each device. If you are not
running an IGate leave it at the default option of "Disable".

Enter in up to three UNPROTO paths. Xastir will assume the XX VIA part of the
UNPROTO path. There are three paths allowed so that your signal will be heard
if conditions are bad. Xastir will cycle through each one that is filled in,
one per transmission time.  If you are local to a digi, just a WIDE may be a
good choice. If you are using low power and/or are distant from a digi then
RELAY, WIDE may work better. Or if you know the call of your closest digi you
may use XXXCALL, WIDE. Most of you will only need one path. If you are in a
remote area and your signal is difficult to get out you may need more. Check
with a local group and ask what path may be best for your area.  Some areas
use the more efficient flooding protocols, in which case you might use WIDE3-3
or RELAY,WIDE3-3.  If no paths are entered it will default to RELAY,WIDE.

If you are IGating to RF, you may enter a specific path to use for the packets
you send to RF. If you leave this blank, the UNPROTO paths above will be used.
If the UNPROTO paths are blank, RELAY,WIDE will be used.

NOTE: To use AX.25 devices with Xastir you will need to run the program as
"root". If you want to run Xastir as another user you may want to set the
suid bit on the Xastir program file. Please see INSTALL file for more
information; current Xastir drops the extra privileges but has not been audited
for exploits. Use in this fashion in a multi-user environment at your own risk!

HELP-INDEX>Configure Serial GPS Devices

                       Configure Serial GPS Devices

Set the serial port device for your GPS unit. Common values of /dev/ttyS0
(COM1) or /dev/ttyS1 (COM2) can be used.

Comment will allow you to set a friendly name or comment for the port.

Selecting "Activate on start up" will tell Xastir to look for this device and
set up communications with it when the program first starts.

Selecting "Set system clock from GPS data" will tell Xastir to try setting the
system's clock to the highly accurate time signal from the GPS receiver. This
requires root privileges on most systems.

Now set the bps rate under port settings, and the parameters under port
style. Port Style setting 8N1 is used for 8 data bits, No parity and 1 stop
bit. 7E1 is used for 7 data bits, even parity and 1 stop bit. 7O1 is used for
7 data bits, odd parity, and 1 stop bit. These parameters must match your GPS.
Most GPS units will use 4800 bps and 8,n,1.

HELP-INDEX>Configure Networked GPS Devices

                    Configure Networked GPS Devices

If you need to share the GPS data with different programs or machines, this
option is best. Xastir will work with gpsd which will allow several
connections to share your GPS data.

Set the host name (or IP address) and the port number for the gpsd host on
your network.

Comment will allow you to set a friendly name or comment for the port.

Selecting "Activate on start up" will tell Xastir to look for this device and
set up communications with it when the program first starts.

Selecting "Reconnect on failure" will tell Xastir to try to reconnect when the
data stream has failed.

Selecting "Set system clock from GPS data" will tell Xastir to try setting the
system's clock to the highly accurate time signal from the GPS receiver. This
requires root privileges on most systems.

HELP-INDEX>Configure the Internet Server

                         Configure the Internet Server

Internet Servers allow you to send and receive data for all over the world.

Selecting "Activate on start up" will tell Xastir to look for this device and
setup communications with it when the program first starts.

Selecting "Allow Transmitting" will tell Xastir that any outgoing Internet
data can be sent to this device.

Enter the host name (or IP address) and the port number of the Internet
Server you want to contact. 

Enter a valid pass-code to validate your connection, this will allow your
data to be transmitted via an IGate. If you don't have a pass-code, use the 
included "callpass" program to generate one. Note that passcodes are dependent
on callsigns.  From the src directory, "make callpass" should create the
executable if it isn't already compiled.

Enter any filter parameters. This causes a special message to be sent to the
server requesting that the data be filtered in a certain way. The exact format
of this field is fully specified, please consult APRSSIG for more information.

Comment will allow you to set a friendly name or comment for the port.

Selecting "Reconnect on failure" will tell Xastir to try to reconnect when the
data stream has failed.

HELP-INDEX>Configure a Serial WX Station

                     Configure a Serial WX Station

Set the serial port device for your WX unit. Common values of /dev/ttyS0
(COM1) or /dev/ttyS1 (COM2) can be used.

Comment will allow you to set a friendly name or comment for the port.

Selecting "Activate on start up" will tell Xastir to look for this device and
set up communications with it when the program first starts.

Now set the bps rate under port settings, and the parameters under port
style. Port Style setting 8N1 is used for 8 data bits, No parity and 1 stop
bit. 7E1 is used for 7 data bits, even parity and 1 stop bit. 7O1 is used for
7 data bits, odd parity, and 1 stop bit. These parameters must match your WX
unit. The Data Type option will allow you to override what type of serial data
the program will look for. The auto-detect feature will first look for Weather
data in a binary type as the Radio Shack WX-200 uses. If no binary data is
found in the stream, Xastir will look for an ASCII type of WX station (like
Peet Bros.).

Now set the Rain Gauge correction factor. Xastir requires that the rain gauge
report in .01 inch increments. If the unit reports in .1 inch or .1 millimeter
increments, a correction must be specified to obtain accurate measurements.

HELP-INDEX>Configure a Networked WX Station

                   Configure a Networked WX Station

Xastir can use WX data servers such as wx200d. wx200d will allow several
network connections, thus sharing the Weather data with several programs or
computers.

Enter the host name (or IP address) and the port number of the WX data server
you want to contact.

Comment will allow you to set a friendly name or comment for the port.

Selecting "Activate on start up" will tell Xastir to look for this device and
set up communications with it when the program first starts.

Selecting "Reconnect on failure" will tell Xastir to try to reconnect when the
data stream has failed.

As before the Data Type will override the auto detection.

Now set the Rain Gauge correction factor. Xastir requires that the rain gauge
report in .01 inch increments. If the unit reports in .1 inch or .1 millimeter
increments, a correction must be specified to obtain accurate measurements.

HELP-INDEX>Configure an AGWPE Connection

                   Configure an AGWPE Connection

Xastir can use an AGWPE network interface running on a Windows box
as a TNC interface. It can also use the login/password security that
AGWPE has built-in, but you must set up the account in the AGWPE
application with your callsign for the username, in all capital
letters.  For instance: "AB7CD".

The other options are described in the sections for Serial TNC and for
Network interfaces.


HELP-INDEX>Symbol Table

These are the symbols that you can select for your station under the "Station
Information" configuration menu. The current list can be found in the APRS(tm)
Reference which you could get from http://www.tapr.org

                             Symbol Table

Symbol     Group /                       Group \

!          Triangle w/!                  Triangle w/!
"          Rain Cloud                    Rain Cloud
#          Digi                          DIGI
$          Phone Symbol                  $ Symbol
%          DX                            DX
&          GATE-HF                       GATE
'          Small Aircraft                Aircraft Crash
(          Cloud                         Cloud
)          TBD
*          SNOW Flake                    SNOW Flake
+          Red Cross
,          Reverse L
-          House w/omni
.          Small x
/          Red Dot
0          0 in a box                    Circle
1          1 in a box
2          2 in a box
3          3 in a box
4          4 in a box
5          5 in a box
6          6 in a box
7          7 in a box
8          8 in a box
9          9 in a box                    GAS
:          Fire                          ?
;          Tent                          Tent
<          Motorcycle                    Pennant
=          Train Engine
>          Car                           Car
?          POS Antenna                   ? in a box
@          HURRICANE/STORM               HURRICANE/STORM
A          First Aid                     Box
B          BBS                           Blowing Snow
C          Canoe
D          D in a circle
E          E in a circle                 Smoke Stack
F          F in a circle
G          Grid Square Antenna           ?
H          Hotel/Bed
I          TCP/IP                        ?
J          J in a circle                 Lightening
K          School House
L          Light House                   Light House
M          Mac
N          NTS                           ?
O          Balloon
P          Police car                    Rx
Q          Circle with in Circles        Circle with in Circles
R          RV                            Restaurant
S          Shuttle                       Satellite
T          Thunderstorm (cloud/bolt)     Thunderstorm (cloud/bolt)
U          School Bus                    Sun
V          VOR TAC                       VOR TAC Symbol
W          National Weather Service      NWS-Digi
X          Helicopter
Y          Sail Boat
Z          Windows
[          Runner                        WC
\          DF Triangle
]          Packet Mail Box
^          Large Aircraft                Large Aircraft
_          Weather Station               WS-Digi
`          Satellite Dish
a          Ambulance
b          Bike                          blowing cloud
c          DX antenna
d          Fire dept.                    DX Antenna
e          Horse                         Sleet cloud
f          Fire Truck                    FC Cloud
g          glider                        Pennant (2)
h          Hospital                      HAM
i          Island                        Island
j          Jeep                          Jeep
k          Truck                         Truck
l          Small dot                     Small Dot
m          MIC                           Mile Post
n          N                             Small Triangle
o          EOC                           Dot with in Circles
p          Puppy                         Dot with in Circles
q          GS Antenna                    GS Antenna
r          Antenna Tower                 Antenna Tower
s          Boat                          Boat
t          TS                            ?
u          18 Wheel Truck
v          Van                           Dot with in Circles
w          H20                           Flood
x          X Windows                     Red Dot
y          House w/Yagi                  House w/yagi
z                                        X Windows
{          FOG                           FOG
|          Black Line                    Black Line
}          TCP                           TCP
~          Sail Boat                     Sail Boat

HELP-INDEX>What was new in Xastir 1.0

Over the past year, Xastir has been under active development, and this new
release is the culmination of those efforts. Development has been run by
Chuck Byam, who agreed to take over for Frank Giannandrea. Many other
individuals have contributed to this project, and are listed in the AUTHORS
file.

The Xastir package now uses GNU autoconf to build makefiles and select
features based on the libraries and software one has installed. No more
editing makefiles as in previous releases!

Starting Xastir 1.0, one probably won't immediately notice any major
changes. The familiar interface of previous Xastir versions has been retained
for the most part. The great majority of the changes are improvements in
efficiency under the hood:
* Startup time for the program has been improved.
* Memory usage has greatly improved, with dynamic allocation of separate
  station, trail, and weather data on an as-needed basis. No longer will
  memory be wasted on stationary stations for trail data, nor will non-weather
  stations waste memory for weather information. With these modifications,
  Xastir can even be connected to the internet link comfortably on a 16mb
  machine.
* Improvements have been made to avoid having to reload maps from disk at every
  minor change; Weather alerts and changes to the display and tracking options
  no longer cause the maps to reload, rather the trails and symbols are
  redrawn alone.
* Improvements have been made to various dialog boxes that re-drew often, to
  redraw less often, to allow them to be usable on slower systems. This is
  also true of tracking a station, with the map redrawing only if the station
  approaches the edge of the screen.
Thanks to these changes, Xastir is perfectly usable on slower Pentium(tm)
machines.

Native GeoTIFF support is now included, and will be compiled into one's copy
of Xastir if they have the GeoTIFF libraries installed on their system. These
map files are of very high quality, and are especially useful in search and
rescue operations. Maps on this format are available from the USGS, and
commercially on CDROM. Xastir understands how to convert from the NAD-27
datum to the new WGS-84 datum, so maps of both format can be read accurately.
New shortcut buttons have been added to the map selection dialog to enable
one to pick all maps of a specific type.

Support for the Festival Speech Synthesis System is now available to announce
new stations and band openings. The old system of alert sounds has been
retained as well.

Xastir now supports adding and deleting objects. Finally, Xastir users are able
to manage resources with this useful feature. Objects are helpful for
coordinating events, directing travelers, and doing search and rescue work.

The County Warning Area maps that display weather alerts are no longer painted
onto the maps below, but are shaded onto the maps. While this does make the
colors unpredictable, it is now possible to see the road-maps below the 
alert! 

A new and useful feature is the change in the orientation of a symbol based on
the direction in which it is moving. Even without a trail, a quick glance can
tell you a mobile station's bearing. There are several more new options in the
display menu, enabling one to decide more precisely what is displayed and what
isn't.

Panning and control over the map has been enhanced: There are now arrow buttons
visible at the top of the screen to pan the map. The map can also be panned
with the arrow keys, and the zoom can be adjusted with the page up and page
down keys. There are new option in the click menu, to center the map where you
clicked or to place an object where you clicked. The panning options in this
menu have been removed in favor of the new controls at the top of the screen.

Support for altnet has been added, enabling one to have a private APRS(tm)
network for special events, search and rescue, storm chasing, or whenever else
the user doesn't want to be bothered by the hundreds of APRS(tm) stations
around.

There are numerous small changes, both visible and invisible to the user. The
interface control dialog now has a "Start all" and "Stop all" option, to save
the user the time of performing these actions for each interface. The station
setup dialog now shows you your symbol, so you don't have to exit the dialog to
see which symbol you chose. Several buffer overflows that caused unpredictable
behavior and/or crashes have been fixed. And many minor improvements have been
made to the source code to ensure that it compiles correctly on various
systems.

Enjoy the new Xastir!


HELP-INDEX>What was new in Xastir 1.1

                    What was new in Xastir 1.1

This new release, Xastir 1.1, adds significant new features and enhancements
to the user interface. Unlike 1.0, the interface changes will take some getting
used to, but the flexibility and versatility of the enhanced interface will
more than make up for the troubles.
Among the improvements to the user interface:
* Keyboard shortcuts for menus and dialogs, menu reorganization, and mouse
  behavior changes.
* The ability to move objects or measure distance with the mouse, using the
  appropriate check-boxes in the toolbar.
* A scale has been added to allow one to judge distance on a map.
* Map labels for windows-style APRS(tm) maps are rotated to match the marked
  map features.
* The user interface for dealing with objects has been entirely redesigned.
* Station info boxes can be set to automatically update.
* Tear-off menus.  Allow you to keep a menu on the screen and play with
  different options. Tear off a menu by clicking on the dashed-line portion.

Map support has been greatly enhanced, with PocketAPRS, ESRI Shapefiles, GNIS
labels and many graphics formats with ImageMagick. Additionally, support for
downloading graphical maps from webservers has been added, allowing Xastir to
use online radar, Tiger, and Terraserver maps. 

Xastir 1.1 supports much more of the APRS(tm) protocol than its predecessor:
* It can add, modify, move and view area objects, signpost objects, and items.
  These features are invaluable for event coordination and search and rescue
  use. Objects and items are also periodically retransmitted.
* Support for displaying position ambiguity squares, pre-calculated radio
  ranges, Maidenhead grid squares, and weather objects. These features aren't
  extremely common, but do come up occasionally.
* Support for the APRS(tm) radio direction finding features. These features
  are useful for anything from tracking jammers to locating lost hikers. Xastir
  supports both Omni and Beam reports.
  
Other notable improvements:
* Xastir can now search for a specified location or landmark using GNIS data.
* Track logs can now be exported to file.
* Maps can be printed if certain tools and libraries are present.
* Support for retrieving historical track data from findu.com.
* Xastir now compiles and runs on Mac OS X, Solaris and FreeBSD with only
  minimal changes; see README for details. 
* Several major bugs found in 1.0 have been corrected, including the problems
  loading DOS maps and the problems with the weather reporting. Other minor
  bugs and memory leaks have been fixed. And several more errors have been
  corrected in the parsing routines, so Xastir should remain stable no matter
  what is thrown at it! 


HELP-INDEX>What was new in Xastir 1.2

                    What was new in Xastir 1.2

The latest Xastir release adds numerous new capabilities, keeping Xastir a
benchmark for APRS programs on any operating system.

Xastir's hardware support has been enhanced, with
* Support for Serial KISS TNCs
* Support for Serial TNCs with GPS on the AUX port
* Support for using AGWPE as a TNC
* Support for Dallas One-Wire weather station
  (see http://melhuish.info/simon/projects/oww/)
* Support for more weather stations via the wx200d daemon (WX-200/WM-918/
  WMR-918/WMR-968)
* Support for the different sized rain gauges of the Peet Brothers weather
  stations.

Additionally, several bugs in the weather reporting code were corrected, and
support for setting the system clock based on the GPS was added.

There have been many additions and improvements to the Xastir user interface:
The most notable is the addition of dead-reckoning. This means that stations
that are moving will continue to move on your screen in the direction and at
the speed speed that they last reported. The estimated location can be shown
with any combination of a ghosted icon, a dashed line from the last position,
or an arc of expected possible distance and angle.

Also very notable are the improvements to the Map Chooser. Maps can now be
selected a directory at a time, or individually. And the new map properties
dialog allows individual control of map layering, map color filling, and
consideration for auto-maps. Additionally, with extent caching under the hood,
auto-maps regains much of its formal usefulness even with many maps installed!

Bulletins pop up on screen, and emergency beacons cause an alert with the 
locate station dialog on hand. These changes are helpful in emergencies and
event coordination.

Xastir can now be set to use one of several coordinate systems, including UTM,
dd.ddddd, dd mm.mmm, and dd mm ss.s. This is helpful for coordinating with
other groups using a different system.

The online Tiger maps can now be enabled from the map menu, and options can
be adjusted to request maps with just the data you want displayed.

The stations menu has been reorganized, allowing more intuitive filtering of
stations shown and of accompanying data.

Other smaller interface changes include:
* The density of the grid-lines can be adjusted with the +, =, and - keys.
* Objects and item lists have been added to the view menu.
* Station maidenhead grid squares are now shown in station info and the
  coordinate calculator.
* There is a check-box "Track me" to enable easily tracking your own station
* The length of trails downloaded from findu.com can now be specified.
* Xastir can now ID via voice ID's or Screen ID's, by editing the configuration
  file. This is intended for configurations when the Xastir screen is seen
  remotely via fast-scan TV. 
* Timestamps are written to log files every 30 seconds of operation, to keep a
  record of when data was heard.
* The status bar can display the course/distance to your station when
  enabled in the file|configure menu.
* Range scales are now shown opposite the map scale. This is an attempt to
  standardize various APRS client approaches to zoom levels.

New additions under-the-hood:
* Tracked proximity alarms.
* Export waypoints within proximity boundaries.  Your GPS can show
  you the locations of APRS stations as waypoints on the GPS map
  screen.
* Export trail as ESRI Shapefile.  New feature if you have Shapelib
  compiled in.  Station Info->Store Track button also creates a
  Shapefile map of the station's track now.

The weather reporting features have been improved, with the addition of
optional wind barbs to weather stations and decoding of storm wind radius data.
Weather alert shading is now done with pixmap stipples showing the type of
alert. Further information on an alert is available over the internet from
the WXserver by simply double-clicking the alert in the weather alerts list.
Weather alerts now use the newer ESRI Shapefile-format maps.

Xastir's map support has been improved with enhancements to the ESRI Shapefile
code to handle point-type ESRI Shapefiles. Additionally, speed improvements
have been made in the ImageMagick graphical map loading, and many
color-correction features have been added. As mentioned above, the Map Chooser
has been greatly improved, and weather alerts use ESRI Shapefile-format maps.

Under the hood, Xastir has had several major improvements:

The messaging system has been largely rewritten, and the annoying timed updates
to dialogs no longer occur. The new messaging system allows multiple messages
to be queued, and implements reply-ack's for speed. Xastir also attempts to
specify a reasonable path for the message based on received messages. This
improves speed and congestion control. The messaging GUI has been largly
untouched, and remains high on the list of future improvements.

The build process has been significantly improved; Xastir is now able to be
built on numerous operating systems with few manual interventions.

Xastir now supports GPSMan/gpsmanshp, allowing the importing of waypoints,
tracks, and routes from several types of GPS receivers.  This allows you to
create ESRI Shapefile-format maps out of GPS data.

Xastir now implements SmartBeaconing(tm), which greatly improves trail quality
and reduces unneeded channel usage. See the "Configure SmartBeaconing" help
topic.

IGating support has also improved, with the ability to configure a specific RF
path for IGated packets, and the addition of a 29 second anti-dupe queue to
reduce unnecessary redundancy on the RF channel.

Map extents and filenames are now cached, so maps will not be loaded from disk
unless they are on screen. This is a major improvement for map types that did
not specify this information. Additionally, auto-maps uses this information,
making it usable even with many maps installed.

Objects controlled by Xastir are now stored in a file, so a restart of Xastir
will not cause them to be lost. Additionally, Xastir now supports the
compressed format for objects and items, which can help reduce RF channel
congestion. It also gives you better location accuracy of the placed objects.
See the help topic "Configure Default Operation".

Xastir now drops root privileges when not needed if run setuid root. Please
read the information about this in INSTALL; this change provides only
limited protection.

Xastir now supports using a private colormap with the command-line argument
"-i". This is recommended for systems running in 8-bit color mode. 

Additionally, several more buffer overruns and other errors were corrected in
Xastir's data parser, and numerous other bugs have been fixed.

Enjoy the new Xastir!
