XASTIR Manual

Preface

Much of this documentation is in the process of being edited and updated. If you'd like to see the old versions of the README files, please see the Source Forge Docs page.

Please contribute here! This is documentation is now hosted on a wiki and, as such, can be easily updated by the user community.

Introduction

  TBD

What is APRS?

According to the United States Patent and Trademark Office APRS is a trademark of Bob Bruninga, WB4APR. It stands for "Automatic Packet Reporting System" (also known as "Automatic Position Reporting System") and is intended to be a local, real-time tactical communication system. One of its key features is the ability to communicate the positions of stations and other spatially-referenced information between participants.

How does APRS work?

  TBD

About XASTIR

Lists major features of Xastir.

  TBD

For more information

This wiki is intended to be a living version of the Xastir documentation, changing over time as new features are added and old bugs are cleaned up. Try the search feature, browse the pages here and see if you can find what you want. Xastir has an extensive, indexed Help file available under the Help Menu. The Xastir source code also ships with a copious number of README text files, some of which have been the basis of the information here on the wiki. The Xastir source code itself is one of the definitive places for how or why things work or don't work as you might expect.

If you're stuck on a question, one of the fastest ways to get an answer is to check the Xastir mailing lists. Many of the Developers and Contributors are active participants and are generally happy to respond in a timely manner.

Getting started

Getting the code

There are multiple ways to get Xastir. The first question you might ask is whether you can just find a binary on the 'net somewhere and install it instead of compiling Xastir from sources. Yes, this is possible -- See: Downloads. However, Xastir changes so often (bug fixes and of course adding new features) that you're really limiting yourself by using pre-compiled binaries. Binaries are typically not updated all that often, if at all, so you'll forever be behind the curve.

The easiest way to have the most up to date version of Xastir is to download the source code. Another reason to compile from sources is to customize it to use all of the features you have available on your system. As you add more libraries that Xastir can use, you can do a quick configure/compile/install, and Xastir will be able to take advantage of them.

For those that really must have the latest-latest: Download the Xastir sources using Git, then issue the command "git pull" periodically in order to snag the latest changes. If anything comes down the pipe, just configure/make/install and then use the latest version. This avoids large file downloads (after the initial download) as it just grabs _changes_ to the sources off the 'net each time you issue the "git pull" command. This is the power-user's method of keeping Xastir up-to-date. See Notes:Git for details.

Installation summary

This document will take you through the steps necessary to get Xastir up and running in one of the following configurations:

1. Minimal install which will get you up and running quickly. It's recommended that you try this configuration first then add to it.
2. Typical install including maps, weather alerts, geo-coding files, etc. so that full regular operation is achieved.
3. Maximum install with all configure options enabled and most of the useful maps loaded/enabled. All the bells and whistles.

Note that you can start with either of the first two options and add only the options you wish in order to come up with your own custom configuration of Xastir.

These instructions were originially written for Linux users, and were originally distributed with the source code as text files. This Wiki is a community supported effort to update and extend the Xastir documentation. Please take the time to contribute!

Windows users should refer to the HowTo:Windows. MacOSX/Solaris/FreeBSD users should refer to the README document first, then the Install_Guides pages, and finally the below instructions for further notes.

After the three configuration sections there's a section on operating, which simply talks you through the initial configuration settings and how things work. After that you can refer to the Help menu option in Xastir itself, plus the INSTALL and README.* text files for additional information. Please note that the non-English help files lag severely behind the English help file.

First of all, NEVER RUN XASTIR AS THE ROOT USER! You're risking the security of your system by attempting it. Create another regular user on your system and use that user for all of your normal activity. This goes for any other normal activity on the system as well. Only use the "root" account for maintenance activities, not for regular user activities (see Notes:Sudo). You'll thank me later!

Before we begin, consider subscribing to the Xastir mailing list. That's where everyone is kept up-to-date on the latest features, plus lots of questions are asked/answered there on a weekly or sometimes daily basis. It's a great way to learn and to stay connected with the other Xastir users. See the mailing links on the left of the Xastir home page.

So... Let's get started!

Configuring Xastir

<<fold in Configuring Xastir>>

Getting on the air

TNC interface

To connect Xastir to a TNC, you need to define an interface. This is done in the Interface->Interface Control menu. Click Add and chose the type of interface to create. This can be:

• Serial TNC
• Serial TNC with GPS on AUX Port
• Serial TNC with GPS on HSP Cable
• Serial KISS TNC
• Serial Multi-port KISS TNC
• AX.25 kernel network interface on Linux

You might need to tell xastir to use a specific startup or stop script to get your TNC initialized properly. Some specific examples are listed below.

General Comments

Most TNC-2 compatible TNCs work well with Xastir. Most require only minor modifications of an existing startup script. See the collection of tnc-startup.XXX files in /usr/local/share/xastir/config (or /usr/share/xastir/config if you're using a pre-packaged version of Xastir), and find one that either matches your TNC model or is very close to it. If you can't find the exact model in our collection, then copy one that's closest and edit it to suit.

One important issue that crops up from time to time is that some TNC models do not accept the "k" command as a synonym for the "converse" command, which takes the TNC out of CMD mode and into "converse" mode. The Kantronics KPC-2 is one such TNC. The command used by Xastir to instruct a normal-mode TNC to go into converse mode is "k", but this can be changed by the user in the Interface Control dialog. You can do this at any time. If you do so at the time you set up your initial interface, you'll be presented with the interface properties dialog right away as part of the set-up process. If you've already defined your interface and need to get back to the properties, choose "Interface Control" from the "Interface" menu, select your TNC interface, and then choose "Properties." The "Converse CMD" entry may be changed to match the command your TNC uses to go into converse mode.

KAM TNC

The KAM TNC is a special case. We have recently discovered (Late 2012) that the KAM will not go into converse mode after receiving the command to do so unless a delay of as much as a second is inserted between the converse command and subsequent data. A patch was added in Release 2.0.2 to address this. On the Interface Properties page for your KAM TNC, select the "Add Delay" checkbox. A 1-second delay will now take place after Xastir sends the converse mode command and before it sends data to be transmitted.

One second is fairly long, but it has been determined through brief testing to be the smallest delay that works reliably. Shorter delays may be attempted (with possibly reduced effectiveness) by editing the xastir.cnf file and changing the number associated with the DEVICEn_TNCEXTRADELAY setting. The number is the delay in microseconds, and is 0 if "Add Delay" is deselected and 1000000 if "Add Delay" is selected. There is no mechanism for changing the default delay length from within xastir, only to turn it on or off.

Kenwood TM-D700 with GPS

Interfacing Xastir with a D700 couldn't be easier. Once you have Xastir running and you are ready to setup the interface to your D700 go to Interface -> Interface Control -> Add. A list of interface types will be displayed. Select "Serial TNC w/GPS on AUX port" and click "Add". This will bring up a configure screen that allows you to enter in all the pertinent information about how to connect to your D700. The TNC port entry should contain your serial port address (COM1 is /dev/ttyS0, COM2 is /dev/ttyS1, etc). The connection speed between your computer and the D700 should be selected in the Port Settings area (typical setting is 9600 bps). Port style should also be set (typical is 8,N,1). If you are running the D700 as an IGate station the you can select how you want this behavior to function on this interface under the "IGate Options". The path for your station can be set at the "Unproto Paths" area. Not to make everything work... Under your TNC Configuration Files you will have to change the files to "tnc-startup.d700" for the setup filename and "tnc-stop.d700" for the shutdown filename. These files tell Xastir how to setup your D700 to function properly.

IF YOU ARE RUNNING A VERSION OF XASTIR AFTER 22 August 2012: A change to the code made on 22 August 2012 requires one additional step for the Kenwood radios. If you have used the "Serial TNC w/GPS on AUX port" interface type, you will see a check box labeled "Send Control-E to get GPS data?" You must un-check this box for the Kenwood radios. The default is not correct for the Kenwood radios.

If you have interfaced a GPS with your D700 (via the GPS port on the radio), then Xastir will receive this data as well and use it to track you. You can see the status of your GPS data by going to VIEW -> GPS Status.

If you have no GPS attached to your D700, you should select "Serial TNC" instead of "Serial TNC w/GPS on AUX port" --- in that case you'll need to set your station location through the File->Configure->Station menu or with the "Move My Station Here" item on the right-click menu in the map window. If you have no GPS attached and use the "w/GPS" option to set up the interface, Xastir will wait for valid GPS data instead of transmitting the manually entered position, and since you have no GPS it'll just not transmit your position.

Kenwood TH-D7A with GPS

Interfacing Xastir with a Kenwood D7 handheld is almost the same as connecting it to a D700. For the TNC start-up script, use "tnc-startup.thd7" instead, and for the stop script use "tnc-stop.thd7". Other than that it's the same as for a D700.

Kantronics KPC3+ TNC

If you have a Kantronics KPC3+ with no GPS attached, set up your interface to be of type "Serial TNC." If you have a GPS attached, choose "Serial TNC with GPS on AUX port." In either case you should use the start-up script "tnc-start.kpc3". There is no associated KPC3-specific tnc-stop script, so you can just leave the default there.

IF YOU ARE RUNNING A VERSION OF XASTIR AFTER 22 August 2012: A change to the code made on 22 August 2012 requires one additional step for the Kantronics KPC-3+ with attached GPS. If you have used the "Serial TNC w/GPS on AUX port" interface type, you will see a check box labeled "Send Control-E to get GPS data?" Double-check that this box is checked. The default is for it to be checked.

Serial KISS TNC

Many TNCs can be put into KISS (Keep It SImple Stupid) mode, and several lower-priced TNCs work ONLY in KISS mode. KISS mode is often preferred by APRS users, and Xastir is able to use a TNC in KISS mode by selecting the Serial KISS TNC option when defining a new interface. With a KISS TNC, Xastir is able to work as an optional "WIDE1-1" fill-in digipeater if your local network needs one.

It is important to note that some models of TNC have KISS options but should not be used in this mode due to bugs. The most well known of these is the Kantronics KPC-3+, which has a bug in its KISS mode that causes it to experience extreme delays between receiving a packet and passing that packet on to the computer. This has serious impact on the APRS network, especially when used in a computer-controlled digipeater or IGate application.

There are many parameters available on the Serial KISS TNC properties dialog, but mostly you need to set serial port and baud rate. The other defaults should be OK for most applications. Be careful about changing any of the parameters in the "KISS Parameters" box, as they can degrade performance if you set them wrong.

If you have a TNC that can be taken in and out of KISS mode and you want to use it for other, non-KISS packet radio when you're not using Xastir, Xastir provides a script called 'kiss-off.pl' that will send the right characters to a TNC to take it out of KISS mode. This script is installed by recent versions of Xastir into /usr/local/share/xastir/scripts, and you should redirect its output to the serial port to which your TNC is connected.

 /usr/local/share/xastir/scripts/kiss-off.pl > /dev/ttyS0

would take the KISS TNC connected to /dev/ttyS0 out of KISS mode and return it to normal command mode.

AX.25 Kernel Network Interface on Linux

AX.25 kernel networking on Linux allows multiple programs on your system to share the TNC, and enables you to run daemons that share the TNC across your LAN. The AX.25 kernel port acts essentially like a network interface similar to an ethernet or wifi card. Using AX.25 networking should be considered a somewhat advanced technique.

Setting up an AX.25 kernel network interface in Xastir on Linux first requires that you have an AX.25 port defined on your system. The details of setting this up are beyond the scope of Xastir's manual, but in broad strokes it involves these steps:

• Attach a KISS TNC to your system.
• Define a port in /etc/ax25/axports that defines the baud rate of the TNC's serial port.
• Assure that the KISS kernel modules are loaded.
• Run "kissattach" to associate the kernel's AX.25 port with a serial port to which the TNC is attached.
• Run "kissparms" to set the appropriate values for transmit delay, persistence, duplex, etc.
• Install Xastir with AX.25 support compiled in, and make sure that the xastir binary has suid-root permission (e.g. sudo chmod u+s /usr/local/bin/xastir).
• Define an AX.25 interface in Xastir, using the ax.25 port name you defined in the axports file.

For more details, see HowTo:AX.25.

Internet interface

If you wish to connect Xastir to one of the internet servers you do so by selecting Interface->Interface Control, clicking "Add", and choosing the "Internet Server" option. You will need to enter

• The name of the server you wish to connect to
• The pass-code associated with your call-sign (get it from the "callpass" program that is installed at the same time you install Xastir)
• Any filter parameters you wish to use
• The port number to connect to on the Internet Server

Recommendations

Servers: if you don't know the name of the closest APRS-IS server to you, try using "rotate.aprs2.net." Look for specific servers to use at http://www.aprs2.net/.

The default port that xastir uses is an unfiltered port on the server, and using it will probably be like drinking from a firehose unless you have a very fast internet connection and want to see world-wide traffic. You are probably better off using port 14580 and specifying a filter string. See examples of what filter strings you can use at http://www.aprs-is.net/javAPRSFilter.aspx. Note that this last link will tell you to use the word "filter" at the beginning of the filter string, but that is not correct for xastir. Just leave off that first word and use only the stuff that follows their recommendations. Xastir will put in the filter keyword when it passes your string on to the server.

IGATE capabilities

  TBD

Mapping capabilities

  TBD

Where to find maps

To be filled out. See HowTo:MAPS in the meantime.

Canada

Geobase.ca - Road Vector and Landsat 7 scenes of Canada
BC Geological Vector maps - Use Geographic Projection?

Installing and using maps

See HowTo:MAPS

Managing maps

  TBD

Making your own maps

 TBD

Advanced usage

  TBD

Experimental: Persistence support with a geospatial database.

Glossary

APRS

Automatic Position Reporting System

APRS is a two-way real-time communication system that allows users to share information about events in the local area. Though often used for vehicle tracking, APRS also provides announcements and information on events or weather. It is sometimes called a "situational awareness service."

APRS-IS

Automatic Position Reporting System - Internet Service

A network of Internet gateways providing worldwide connectivity between APRS radio networks.

ASL

Above Sea Level

Height or distance above sea level.

AX.25

Data link layer protocol used for packet radio.

callsign, callname, call letters

A callsign is a unique designation for a transmitting station. A government agency may assign a callsign along with an amateur radio license.

CW

Continuous Wave

A wave with constant amplitude and frequency that may be keyed on and off, such as with Morse code.

digipeater

digital repeater

A repeater that stores and forwards (retransmits) data on a single-frequency, allowing a signal to cover long distances.

DRG

Digital Raster Graphic

Raster image (scan or bitmap) of a United States Geological Survey (USGS) topographic map, georeferenced to the earth’s surface and fit to the Universal Transverse Mercator (UTM) projection.

ESRI Shapefile

A shapefile is a vector-based geospatial map format; based on lines, curves, and points. ESRI is a company name.

HAAT

Height Above Average Terrain

Height or distance above the nearby area. This is calculated from the altitude of the antenna location, minus the average altitude of specified points in the vicinity. This can be a negative value.

Also EHAAT, Effective Height Above Average Terrain.

IGate

Internet gateway

An IGate is a gateway APRS station that passes message packets between RF and APRS-IS. An IGate may be bi-directional or may only pass packets in one direction.