HELP-INDEX>READ ME FIRST - License

                          READ ME FIRST - License

For the most current information please read the README.md 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-2026 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:

 https://github.com/Xastir/Xastir
 https://github.com/Xastir/Xastir/wiki
 https://www.xastir.org

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

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


HELP-INDEX>Welcome! and Notes from the Authors

                      Welcome! and Notes from the Authors

XASTIR, or X 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) was created by Bob Bruninga and originally trademarked by
him.  It is currently a trademark of the Tucson Amateur Radio Packet
Corporation.  When Bob Bruninga became a silent key, maintenance and
documentation of APRS for the community was taken over by the APRS
Foundation, whose web site is https://how.aprs.works/ .  This is the
best modern source for up-to-date information about APRS.

A historical copy of Bob Bruninga's original APRS web site is
maintained at https://aprs.org/ .


HELP-INDEX>What's new in Xastir

The "What's New" section of this help file has been long neglected,
and has not been updated in every release.  As of release 2.2.4 we have
removed all the old entries and will not update it further.

The best way to see what's new in any release of Xastir is to view the
release notes we provide with each release on Github.  These may be viewed at
https://github.com/Xastir/Xastir/releases.


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 -l Dutch
    xastir -l English
    xastir -l French
    xastir -l German
    xastir -l Italian
    xastir -l Portuguese
    xastir -l Spanish
    xastir -l ElmerFudd
    xastir -l MuppetsSwedishChef
    xastir -l OldeEnglish
    xastir -l PigLatin
    xastir -l PirateEnglish

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.  We transmit course/speed in this format but not altitude.
In order to send course/speed AND altitude requires adding nine characters to
the packet which negates part of the reason to use compressed posits.

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 overlay-ed 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 overlay-ed, 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.  All values must be
specified if you wish to transmit PHG information.

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 also
works for gating specific callsigns to RF.

"Transmit Compressed objects/items?", 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?" and 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.

"My Trails in one color" shows all trails with your callsign but different
ssids in the same color.  With My trails in one color selected, mycall-1
and mycall-2 are shown in the same color.  With My trails in one color
unchecked, mycall-1 and mycall-2 are shown in different colors.

"Load predefined objects from file" and the pick list which follows it allows
you to replace the list of Predefined objects that are accessible from the
right click pop-up menu with your own list of objects.  A set of standard
Search and Rescue objects and a set of typical public event objects are
supplied in the predefined_SAR.sys and predefined_EVENT.sys files.  You may
also use these files as a template to create a predefined_USER.sys file.
See the instructions in the predefined_SAR.sys and predefined_EVENT.sys file
for details on how to define objects for a custom predefined objects menu.
If both "Load predefined objects from file" is selected and a file that
exists in the xastir/config/ directory is selected, then the objects defined
in that file will be shown on the Predefined objects menu.  The unaltered
predefined_SAR.sys file defines the same objects as the default menu.


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.  Caution: setting the new track time to 0 will turn
off the display of all tracks.

RINO -> Objects Interval adjusts how often waypoints are downloaded from an
attached Garmin RINO radio/GPS unit.  APRS(tm) 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.   Caution: setting new track interval to 0
degrees will turn off the display of all tracks.

Snapshot Interval (minutes) specifies how often snapshot files will be
written if either File->PNG Snapshots or File->KML Snapshots are selected.

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 check-box 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.md 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:
https://www.cstr.ed.ac.uk/projects/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 on screen, and how many
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 Page-Up/Page-Down 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 Pos/Zoom" 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 tactical 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 configuration.

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.

The Predefined Objects option in the right click menu allows you to rapidly
place standard Search and Rescue objects without having to go through the
Object/Item creation dialog.  These objects include standard Incident
Command System symbols for ICP, Staging, Base, and Helibase, as well as
SAR objects for PLS, IPP (with 4 area circles), and LKP If an object of the
same name as an object you select off the list allready exists, a new
object will be created with a number appended to the end.  For example,
the first time you select Staging from the Predefined objects menu, an
object named Staging will be created.  If you then create an additional
Staging object from the Predefined objects menu, it will be named Staging2.
Heli- (and user defined objects ending in a "-") will be created as Heli-1,
Heli-2, Heli-3, etc.  If you have received one of these standard objects that
was transmitted by another station, your first object will be named with an
appended number.  You may wish to assign a tactical call to your object in
this situation (for example, replacing ICP2 with a tactical call).

The Predefined Objects menu is customizable by modifying the files
predefined_SAR.sys, predefined_EVENT.sys, and predefined_USER.sys, and then
selecting one these files through the File/Configuration/Defaults dialog.
See the predefined_SAR.sys file for details.

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:
    https://www.aprs.org/dfing.html
for Bob Bruninga's discussion of how to use these techniques.
(FIXME: Separate section on DF'ing techniques?)

= Probability Circles =
This allows you to define the radius (in miles) of two circles centered on
the object or item.  Min is the radius (in miles) of the smaller, inner
circle, and Max is the radius (in miles) of the larger, outer circle.
These circles are drawn in red.  They can be used to assist in planning
Search and Rescue operations.  To create more than two circles, add additional
probability circle objects to the same location.  Probability circles may not
be displayed by other client software.

= 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 1/1500 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 1/1500 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 peoples' screens for an extended period.


Description of weather watch boxes:

Watch boxes and "areas of maximum concern" (AOMC) generated by the WXSVR
(https://www.aprs-is.net/WX/Default.aspx) 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>CAD Objects

                     CAD Objects

CAD object support is preliminary at this time.  Features and the user
interface are subject to change.

CAD objects are arbitrary shapes that you can draw on maps in xastir, but
can't transmit by APRS.

Currently supported CAD objects are:
Polygons: Closed areas of at least three points.

To create a CAD object, first press the Draw radio button on the toolbar.
This will change the cursor to a pencil.  Begin drawing a polygon by
clicking with the middle mouse button (or both buttons on a two button mouse,
for which you will need to have three button mouse emulation enabled).  This
places a point on the map.  Now move the cursor somewhere else (the normal
left click/right click navigation and zoom functions still work normally) and
click the middle mouse button again.  This draws a line between the two points
you have selected.  Middle click again to draw another line segment and keep
repeating until you have drawn all except for the closing line segment of your
polygon.  To close the polygon, select Map/Draw
CAD Objects/Close Polygon.  This will close your polygon and bring up a dialog
that will allow you to enter a name, comment, and probability for the polygon.

When you have finished drawing CAD objects, exit the CAD drawing mode by
deselecting the Draw radio button on the toolbar.

CAD objects can be edited from the View/CAD Polygons menu and from the
Map/Draw CAD Objects/CAD Polygons menu.  CAD objects can be  deleted from the
Map/Draw CAD Objects/Erase CAD Polygons menu.

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 WXSVR. 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 acquired.

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). A setting of
  "auto" allows a dbfawk file to control this parameter directly (usable only
  if dbfawk is compiled in and the map in question is a Shapefile). You can
  also select whether a map is considered by the "Auto maps" feature here.
  Finally, you can specify the minimum and maximum 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.

Search Location
This feature generally requires an internet connection.

This option brings up a search dialog where you can enter an address
or name of a business or location.  It will generate an internet
request to a "Nominatim" server that queries OpenStreetMap data to
find the location.  If any are found, the dialog will be filled in
with a list of matching locations.  Choose one by clicking on it and
then click either "Go To" or "Mark."  Either option will center the map
on the location chosen, the "Mark" button will also place a large blue "X"
over the location.

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
  GraphicsMagick 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.

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

NOTE:  "Auto maps" is a deprecated feature that is best left turned off!

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 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 on the map.   If the coordinate
system is UTM a UTM grid will be displayed.  If the coordinate system is
latitude/longitude then a latitude and longitude grid will be displayed.  As you
zoom in the grid switches to a finer resolution.  The spacing of the latitude
and longitude grid may be manually adjusted with the "+" and "-" keys.

Enable Map Border
When both Enable Map Grid and Enable Map Border are enabled, a narrow white
border is drawn around the map and the grid lines are labeled using the
selected coordinate system (File/Configure/Coordinate System), and the selected
border font (Map/Configure/Map Labels font/Border Font).   If the UTM or MGRS
coordinate systems are selected, the grid lines will be labeled with easting
and northing values only at zoom levels smaller than about 2048.

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 at
https://github.com/Xastir/Xastir/wiki/Xastir-Mapping-Overview and its
various links. 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 historical 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 with no additional external libraries needed.
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 GraphicsMagick support,
enabling support for many graphic formats as maps.  Xastir supports weather
alert maps in ESRI Shapefile format, available from NOAA.  See the Github
wiki page https://github.com/Xastir/Xastir/wiki/Installing-Xastir for details.

Details of locations to obtain many of the above types of maps are found in
the file https://github.com/Xastir/Xastir/wiki/Xastir-Mapping-Overview and
links below it.

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 the Xastir Github
wiki at https://github.com/Xastir/Xastir/wiki/Xastir-Mapping-Overview.
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 GraphicsMagick), 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/GraphicsMagick 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 (GraphicsMagick). 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 <https://website>
This specifies the URL of a map image to be loaded from a web or ftp site.
GraphicsMagick only.

TIEPOINT <x-pixel> <y-pixel> <longitude> <latitude>
Two tie-points 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 GraphicsMagick 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.

GraphicsMagick 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 URLs such as weather radar, where you
wish Xastir to auto-redraw the map at a specified interval.  By
adding this tag to weather radar .geos, 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.  Color-mapped images use the map value, so white is
usually 0xffffffff (32-bits of 1s).  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:

WMSSERVER
Allows use of Web Map Services (WMS). Several example of this type of
online map source are automatically installed in the maps directory such
as "USTigermap.geo" and the weather radar maps in the "NWS" directory.

OSMSTATICMAP
OSM_TILED_MAP
Allows use of OpenStreetMap servers that provide either a single
static image or small map tiles.  Several examples whose names begin with
"OSM_" are installed in the maps directory.


GeoTIFF maps are a variant of the TIFF image format with extra
georeferencing tags embedded.  Those in the US usually have come with
two files: a .tif and a .fgd file.  The .tif file is the actual map
data.  The .fgd file is a metadata file that conforms to a federal standard,
but for Xastir's purposes 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 its 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  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 CD-ROM 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.
Furthermore, unless your shapefile set matches those that Xastir already
has rendering rules for, you will have to construct a "dbfawk" file to get
Xastir to make it pretty.


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
https://github.com/Xastir/Xastir/wiki/Xastir-Mapping-Overview.  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.  For an example, if you wished to see
the track that happened two days ago, all day long, you might set the first
slider to 48 hours (start time of two days ago) and the second slider to 24
hours to snag exactly one day's worth of data, from the start until 24 hours
later.


Export all
This sub-menu allows saving data for all stations to files [or databases]

    Export to KML file
      Saves all stations and their trails to a Keyhole Markup Language
      file in ~/.xastir/tracklogs.  The filename will be the current
      date and time with a .kml extension, e.g. 20080125-033045.kml
      KML files can also be written on a regular basis using KML
      Snapshots on the file menu.

    Store to open databases [Not yet implemented]
      [Store to database interfaces is currently only implemented through
      individual SQL database interface dialogs]

    To save a png snapshot of the current map, use File->PNG Snapshots

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.  Currently, Xastir recognizes any station that begins with
      the letters C through G, whose second letter is "W", and which has
      four digits following as CWOP stations.

  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(tm) users.

Clear All Tactical Calls Clears all assigned tactical calls. This will
take effect the next redraw. Note that this will NOT clear tactical
calls on other peoples' screens if you've published them via a message
to "TACTICAL" (see the help text for "Send Message").

Clear Tactical Call History This removes the tactical call history
file, meaning that tactical calls assigned will not remain permanent
between Xastir restarts.  Note that this will NOT clear tactical calls
on other peoples' screens if you've published them via a message to
"TACTICAL" (see the help text for "Send Message".

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 stations' 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 canceling the pending messages or receiving
and acknowledgment 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 control 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.

To publish TACTICAL calls to other Xastir and APRS+SA stations as
well as assign those tactical calls locally: Send a message to
"TACTICAL" with the body of the message containing lines something
like:

  callsign-1=TAC1;callsign-2=TAC2;callsign-3=TAC3

To remove these tactical calls later from local AND remote screens,
assure that the original message(s) assigning them has timed-out or
been cancelled, then send a message like this and let it retry until
it times out (assigns blank tactical calls to the original
callsigns, thereby removing the assignment):

    callsign-1=;callsign-2=;callsign-3=

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.

Interface Control
This option displays a window where you can turn on and off your configured
interfaces, as well as add, delete, or configure interfaces. 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 as well.

Enable Server Port
This enables/disables TCP and UDP listening sockets at port 2023.  You may
connect other APRS(tm) clients to the TCP port in order to send/receive
APRS(tm) 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.  Note that ANY user with the proper credentials can
come in on the TCP or UDP ports if they are enabled.  The only one of these two
ports currently that can send to RF is the UDP Server port.  The TCP
port cannot.

    "user WE7U-13 pass XXXX vers XASTIR 1.3.3"

Connect another APRS(tm) 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.

You should also have a binary called "xastir_udp_client" which can send packets
into the UDP listening port.  Invoke it like this:

 xastir_udp_client localhost 2023 <callsign> <passcode> "APRS Packet Goes Here"

Currently that will inject the packet into Xastir's decoding routines and send
it to any TCP-connected clients. It will also igate it to the INET if you have
igating enabled.  It will send the packet out the RF ports as third-party
packets only if you add the "-to_rf" flag after the passcode like this:

 xastir_udp_client localhost 2023 <callsign> <passcode> -to_rf "APRS Packet"

The UDP client is useful for generating and injecting APRS packets from
external scripts.  It can also be used to fetch the callsign of the remote
xastir server by using the -identify flag:

 xastir_udp_client localhost 2023 <callsign> <passcode> -identify

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(tm) 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 (local only) tactical 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. Assigning a blank tactical call clears this feature, and
it can also be cleared for all stations in the Stations menu.  This
feature assigns tactical calls to the local Xastir station only, but
see below to publish them to others.

To publish tactical calls across the air to other Xastir and APRS+SA
stations (as well as assign them locally), see the "Send Message" help
section.

"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 track-log 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 the track of the station to a file on disk. The
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 track-logs in a similar manner.
These track-log files will be placed in the directory ~/.xastir/tracklogs
with a name equal to the stations call with ".trk" as extension.  "Store
Track" will simultaneously save the station's track as a Keyhole Markup
Language (.kml) file with a filename equal to the station's call, the
current date and time and .kml as extension.  If shapefile support has
been included, the station's track will also be saved as a set of four
files (.dbf,.prj,.shp,.shx).  Subsequent presses of Store Track for the
same station will write additional lines into the .trk file, and create
new .kml (and shapefile) files (each containing all positions in the
station's track.

"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 "Helper Scripts" page on the wiki,
https://github.com/Xastir/Xastir/wiki/Helper-Scripts

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:  GraphicsMagick 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.  The default time period is set at once per five
minutes.  Assuming that you have "convert" from the GraphicsMagick 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" toggle-button.
The rate is once every five minutes (configurable from the Configure
Timing dialog from "File->Configure->Timing"), 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.  A .kml file is also written to allow you to use the snapshot as
a graphic overlay on terrain in applications capable of reading kml.  See
kml_snapshot_to_web.sh and kml_snapshot_feed.kml in the scripts directory
for more information on using the snapshot.png and snapshot.kml file to
produce a kml feed using the snapshots.

                    Creating Automatic KML Snapshots

Xastir is capable of writing all current stations and tracks to a kml file
on a recurring basis.  Enable this feature via the "File->KML Snapshots"
toggle button.  The rate at which these snapshots are generated is the same
as that of PNG snapshots, configured from "File->Configure->Timing" by
setting the snapshot time interval.  Each snapshot is written to a .kml
file in ~/.xastir/tracklogs, with a filename based on the date and time
of the snapshot, e.g. 20080206-000720.kml  This behavior may change to
make KML snapshots write to a single file like PNG snapshots.


HELP-INDEX>Included Scripts

                        Included Scripts

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

get-fcc-rac.pl
This shell script automates retrieving and installing the FCC and the RAC
callsign databases. Note that these databases are very large!

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.

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-separated 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.

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

track-get.pl
This script downloads the track-log of a specified object from a Garmin GPS.
It requires the GPS::Garmin module. It prompts for an object name, and writes
the track-log 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.

db_gis_mysql.sql  db_gis_postgis.sql
These will create tables for storing station data in a mysql or postgresql/
postgis database.  SQL Server database support is experimental.  See the
"OPTIONAL: Experimental.  Add GIS database support" section in INSTALL.md

HELP-INDEX>Configuring Interfaces

                           Configuring Interfaces

Click on Interfaces, then Interface Control.

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.

Supported interface types 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
SQL Databases  (Experimental)

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.

SQL Databases will only appear as an option if you have MySQL or Postgis
support compiled.

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.

Selecting "Add Delay" will tell xastir to insert a one second delay
between issuing the command to enter "Converse" mode and the actual
data to be sent.  This options exists solely to deal with the
Kantronics KAM TNC, which will often fail to enter converse mode if it
receives data immediately after the converse command is given.  If you
have a KAM, check this box, if not, leave it unchecked.

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 WIDE2-2 may be a
good choice. If you are using low power and/or are distant from a digi then
WIDE1-1, WIDE2-2 may work better. Or if you know the call of your closest digi you
may use XXXCALL, WIDE2-2. 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.  If no paths are
entered it will default to WIDE2-2.

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, WIDE2-2 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
Gpsd for further information on the configuration of these devices.

"Send Control-E to get GPS Data?"

This checkbox controls whether Xastir sends a Control-E to the TNC every time
it needs GPS data.

Some TNCs that support a GPS on an auxiliary port require that Xastir
send a Control-E to the TNC in order to get the GPS data each time it
is needed.  Devices in this class include the Kantronics KPC-3+.

Some devices, like Kenwood APRS radios (D700, etc.) do NOT require
this, and in fact the Control-E interferes with correct operation of
these devices.

Because Control-E was required by the most common TNCs that had an aux
port for GPS at the time that this interface type was written, this is
the default behavior of Xastir.  If you have a Kenwood radio that you are
using in this mode, you must DESELECT the "Send Control-E to get GPS data?"
checkbox in the configuration dialog for this interface type.

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 "Digipeat?" will tell Xastir to digipeat traffic.  It will do
this if the first unused digipeater call in the path matches your callsign or a
callsign listed in your Xastir config file ("RELAY_DIGIPEAT_CALLS" line,
default is "WIDE1-1"). This option is only recommended for base stations in
regions where there are few other fill-in digipeaters in the area. Consult with
a local group about the best setting for your region. You may hand-edit the
Xastir config file when Xastir is not running in order to change this string to
match your local recommendations. In the U.S., "WIDE1-1" is the recommended
setting.

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 WIDE2-2 may be a
good choice. If you are using low power and/or are distant from a digi then
WIDE1-1,WIDE2-2 may work better. Or if you know the call of your closest digi
you may use XXXCALL,WIDE2-2. 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.  If no paths
are entered it will default to WIDE2-2.

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, WIDE2-2 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. It will do
this if the first unused digipeater call in the path matches your callsign or a
callsign listed in your Xastir config file ("RELAY_DIGIPEAT_CALLS" line,
default is "WIDE1-1"). This option is only recommended for base stations in
regions where there are few other fill-in digipeater 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. You may hand-edit the Xastir config
file when Xastir is not running in order to change this string to match your
local recommendations. In the U.S., "WIDE1-1" is the recommended setting.

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 WIDE2-2 may be a
good choice. If you are using low power and/or are distant from a digi then
WIDE1-1,WIDE2-2 may work better. Or if you know the call of your closest digi
you may use XXXCALL,WIDE2-2. 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.  If no paths
are entered it will default to WIDE2-2.

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, WIDE2-2 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>Configure a SQL Database Connection

                Configure a SQL Database Connection
                         [Experimental]

Xastir can experimentally store and retrieve station data from either
a MySQL database or a Postgresql + Postgis database.  See the
"OPTIONAL: Experimental.  Add GIS database support." section in the
INSTALL file for more information.  Station and object data are stored
as spatial data, and can be retrieved from other GIS applications, for example
Xastir can write station locations into a Postgis database from which they
can also be viewed using QGIS.  SQL database connections also allow for the
persistence of data between Xastir sessions.  All aspects of spatial database
support, including database structures, are currently experimental and may
change at any time.  You may configure multiple SQL database connections,
but you should only have one active at a time.

Before creating a database connection in Xastir, you will need to create a
database to connect to, create an appropriate set of tables
(see the db_gis_xxxxx.sql scripts in the scripts directory), and add a user
with a password and rights to access the database.  For postgis databases
you may also need to appropriately configure the user in pg_hba.conf

Configuration options on the SQL database dialog include:
Database: MySQL (lat/long) for very old MySQL databases,
          Postgis for postgresql + postgis, and
          MySQL (Spatial) for current MySQL databases.
With tables for: Currently only the Xastir simple schema - a very basic
          flat table holding minimal information about stations.
Host: IP address or hostname for the database server, default is localhost.
Port: Default is 3306 for MySQL and 5432 for Postgresql.  The database can
          be on a remote server, but the appropriate port will need to be
          open in any firewalls.
Username: Can be unique to your database, e.g. xastir_user
Password: Unique to your database.
Schema name: Your database name. e.g. xastir
MySQL Socket: check my.cnf, or mysql --help | grep socket
          Leave blank for postgis databases.
Reconnect on Net Failure: [Not yet implemented]
MySQL defaults and Postgis defaults provided by the buttons may
or may not be correct for your database.

Three options control the behavior of the SQL Database interface:
Activate on Startup:  Try to connect to this database and begin storing heard
station data as soon as Xastir starts (if store incoming data is also selected).

Store incoming data: Stores each station (including objects and items) report
as a record in the database.  All stations heard on all interfaces will be
stored to the database - if you are connected to internet feeds and leave
xastir running this can easily be a million records per day.

Load data on startup: Retrieve all station data from the database
when restaring Xastir.  Currently the only way to retrieve persistent
data from a database.  Will attempt to connect to database and retrieve data
independent of the settings of either activate on startup or store incoming
data.  Due to rounding and conversion errors, non-mobile stations may move
slightly.

The "Most Recent Error" box may or may not contain an error message to help
identify connection problems.  When Xastir fails to connect to a database,
the interface will show ERROR on the interface list, and the most recent error
may be shown here.   Running xastir from the console and observing error
messages there, or running xastir from the console with xastir -v1 may help
identify the cause of connection problems, as may examination of the
database's error logs.

You will only be able to configure a SQL Database interface if you have
compiled Xastir with support for that DBMS (--with-mysql or --with-postgis).

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 at https://github.com/hessu/aprs-symbols.


                             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