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.
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.
Lists major features of Xastir.
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.
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 CVS, then issue the command "cvs update" 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 "cvs update" command. This is the power-user's method of keeping Xastir up-to-date. See Notes:CVS for details.
This document will take you through the steps necessary to get Xastir up and running in one of the following configurations:
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!
<<fold in Configuring Xastir>>
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:
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.
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.
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.
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.
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.
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.
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 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:
For more details, see HowTo:AX.25.
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
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.
To be filled out. See HowTo:MAPS in the meantime.
Experimental: Persistence support with a geospatial database.
callsign, callname, call letters