Aprs.fi user guide
This page should eventually evolve into a comprehensive user guide for the aprs.fi web service. It's still in it's early stages. This is a Wiki page, so you're welcome to expand the document!
Introduction
The aprs.fi web service collects information from the Automatic Packet (or Position) Reporting System Internet network (APRS-IS). APRS is used by amateur (ham) radio operators to transmit real-time position information, weather data, telemetry and messages over the radio. A vehicle equipped with a GPS receiver, a VHF transmitter or HF transceiver and a small computer device called a tracker transmits it's location, speed and course in a small data packet, which is then received by a nearby iGate receiving site which forwards the packet on the Internet. Systems connected to the Internet can send information on the APRS-IS without a radio transmitter, or collect and display information transmitted anywhere in the world.
In addition to that, aprs.fi also displays AIS data transmitted by most large ships. AIS transmissions are received by volunteers at numerous sites, but most areas are largely uncovered.
This guide aims to become an user guide for the aprs.fi web site, and as such does not attempt to describe the APRS or AIS systems in detail. To get started with APRS, please consult the following pages:
- Wikipedia: Automatic Packet Reporting System
- G4ILO: APRS - Putting ham radio on the map
- K9DCI: APRS Beginner Guide (PDF)
AIS is described well on the Wikipedia page for Automatic Identification System.
Languages and localisation
The aprs.fi service has been translated by volunteer users to numerous different languages. The language shown to you will be selected based on your browser's language preference settings. If you wish to preview the site in different languages, please prepend the two-letter language code to the site URL:
- http://fi.aprs.fi/ - aprs.fi in Finnish
- http://ja.aprs.fi/ - aprs.fi in Japanese
- http://en.aprs.fi/ - aprs.fi in English
The site also supports different measurement units (metric, imperial and nautical), which can be selected in the preferences.
TODO: describe how the links work, which have callsigns embedded and when
Real-time map
The real-time map which opens up first when you arrive on the site displays, in nearly real time, APRS and AIS data on top of maps or satellite images provided by Google Maps. By default, it opens up showing the real-time situation in an area which should be relatively near your current location. The location guess is based on your IP address and it is a bit rough, but usually it opens up at least in the correct country. It is possible to select and save an initial view, but more on that later!
On the left side of the map you'll find the familiar Google Maps map controls which can be used to zoom and pan around the map. You can also use the mouse to drag the map, and the wheel of a mouse (if you have one) to zoom.
On the top of the map there is a box showing the coordinates and locator currently under the mouse pointer, a controls to switch between different map layers (street map, terrain map, satellite images and hybrid satellite+street map), and a control to enable additional layers on top of the map (traffic info, bicycle routes, and so forth).
On the right side of the map is a menu area containing the search boxes, links to switch views, links to information pages, and possibly some advertisements or links to news about the aprs.fi site. Near the bottom, right above the advertisement is a small status box which indicates the rather frequent updates of the real-time map data. The updates normally happen once every few seconds.
Clicking on any of the ship or vehicle symbols will open up an info balloon showing current information on that tracking target.
Controlling the amount of data displayed
Near the top right corner there is a drop-down selection for the amount of history shown. When looking at the real-time view of an area (and not tracking a station), the maximum setting is 24 hours. Beware – if you're looking at a busy area, or have zoomed out to see a lot of APRS stations, selecting 24 hours will likely make your browser slow down to a halt, just because it needs to display so many symbol graphics and path lines.
If you're tracking a single target, the maximum selection is 7 days.
If you're having trouble with the map being too slow, or the browser freezing, please take a look at the troubleshooting section.
Searching for an APRS callsign or AIS vessel
The first input field in the top right corner of the page, labelled Track callsign is used for looking up a specific station by it's amateur radio callsign. Ships can be looked up by either their names (which are not always unique) or by their unique MMSI numbers (think of it as a phone number for the ship). Enter the callsign of the station in the box and click on Search. The most recent known position of that transmitter will be shown. For example:
(Please right-click the link and select Open in new window or new tab to avoid navigating away from this page.)
After looking up the station, no other stations in the area will be shown. You can bring other stations into view by clicking on Show all, while still tracking the selected station. If the tracked station moves, the map will center on the new position.
To stop tracking stations, click on Clear. This will reset the page to a real-time view at the same location and zoom level.
Looking up multiple targets at the same time
It's possible to search for multiple targets at once by separating the callsigns or names with commas:
SSIDs - identifying multiple stations owned by the same operator
More often than not, a single amateur radio operator has multiple stations: one at home, one in the car, and maybe a hand-held walkie-talkie too. These are identified by their SSID (Secondary System Identifier) numbers, which range from 1 to 15. OH7LZB could be the home station, OH7LZB-9 is probably the car, and OH7LZB-14 could be a motorcycle. After you have successfully looked up one of these, links to the other available SSIDs for that station are shown below the search boxes. The ones which have recently transmitted their position are shown with a larger font.
Searching for an address
The second input field on the right searches for an address, a city, or a QTH locator. Given a specific address it will center the map at that address. Example searches:
- Kuopio - searches for the city of Kuopio in Finland.
- Paris - searches for the city of Paris. It is quite likely to jump to Paris, the capital city of France, but if you are located in the USA, it might as well come up with the city of Paris in Illinois, USA. Many city and town names are not unique!
- Paris, IL, USA - searches for Paris in the state of Illinois, USA.
- Paris, France - searches for Paris in France.
- Paris, FI - searches for a Paris in Finland, and manages to find Pariisinkatu (Paris Street) in Helsinki.
Enter the components of the address from the most specific to the least specific, separating them by comma characters. For example:
In other countries and languages, use whatever addressing system is typically used. Google understands many languages. As an example, here is the Japanese address for the Kyoto tower. Zoom in and switch to the satellite view:
You can also enter coordinates in the address search box in several different formats:
The address lookup service is provided by Google Maps, and functions similarly to maps.google.com. In other words, if it doesn't find something, it's Google's fault.
QRA locator search
Given a Maidenhead / QRA / QTH locator aprs.fi will center on the locator's middle point and draw a rectangle around the locator's borders. For example:
You can also check the coordinates and locator of a position on the map by simply pointing at the position with your mouse and reading the coordinates from the box in top left corner of the map.
Looking up historical data
To view past positions of a station, first look up the current position. A date browsing menu will appear on the right, consisting of the years for which data is available on aprs.fi. First, click on the year, then select the month, and finally, select the day you wish to view. The menus might open up a bit slowly at first, since aprs.fi needs to consult it's huge historical database to check the availability of data for the station in question.
aprs.fi normally stores position history data for about a year. If you wish to retain your tracks for a longer time, please use the Data export tool to download a KMZ file for offline viewing using Google Earth.
Tool buttons
In the top right corner of the real-time map you'll see a set of buttons. These are used for controlling different tools on the real-time map.
The hide button hides and displays the menu bar on the right, effectively switching to a full-screen mode of a sort.
The home button jumps back to your initial view, which might be a very rough guess of your location, or a specific view configured by yourself.
The PHG button toggles between no PHG circles shown, half-size PHG circles and full-size circles. The PHG circles display estimated service areas of APRS digipeaters and igates. They are very rough estimates or guesses made by the operator of each digipeater and usually they are not based on any exact statistical measurements.
The ruler button enables the ruler tool, which can be used to measure distances and bearings on the map. After clicking on the tool button, click somewhere on the map, and a marker will appear. Use the mouse to drag the marker to another position on the map. Another marker will appear from below the first one, a line connecting the two will be shown, together with the distance and bearing from point A to point B. You can also click the markers to see the exact coordinates of the marker. Multiple rulers may be placed on the map at the same time, just click on the button again to start from the beginning!
Selecting an initial default view
You can save the current map view, including the map type, zoom level and tracking settings, so that they will be recalled when you next open up aprs.fi. It's a good idea to do this especially if the initial guessed location is far off from your area of interest.
- Click on Preferences to open up the settings window. It's under the Other views title.
- The first item in view is Save current map view as default view. Check the checkbox.
- Click on Save at the bottom of the page.
The preferences are stored in your browser's cookies, so they will not apply when you open up aprs.fi on another computer or using another browser. You do not need to have an user account aprs.fi to save the preferences. The rest of the settings in the Preferences dialog are described in the Preferences section of the document.
Street View
Please note: The Street View feature is currently available on beta.aprs.fi only.
Google's Street View has been integrated in aprs.fi, allowing you to view street-view panoramic photos on the site.
You can open Street View by dragging the yellow pegman (from above the zoom control) to the map. When dragging the pegman, a yellow overlay will indicate the roads with panorama photos. Drop the pegman on a road and the panorama will open. You can drag the panorama to look around, and click on the arrows to advance along the streets.
If you click on Track in Street View in the info balloon of a station, the panorama which is closest to the current location of the station will be opened. You can also click on any red track point along the path of a station to jump there (or any other station, for that matter). When a currently tracked station moves, the Street View jumps to the new position automatically.
If the clicked station is transmitting a course (which generally requires that the station is moving), the Street View will open up pointing to that direction. If the station is not transmitting a course, the camera will point from the panorama picture's center coordinates (where Google's camera was when the panorama was taken) to the exact coordinates transmitted by the stations. This implies that clicking on a house symbol of someone's home station will often open up a photo of that house (with antennas on top).
If no panorama photos are available for the required position, the Street View will close automatically.
For more information on Street View, please consult Google's Street View documentation.
Packet path lines
When you bring the mouse cursor on top of an APRS station or a red track point, a line indicating the packet's known path over the APRS network is drawn. The line should traverse via the digipeaters and end up at the igate listed in the packet's path.
The path taken by that position packet is shown in the info balloon. In this case, the packet's destination callsign was APZMDR, it went through the digipeater OH7RDA, was transmitted with an original path of TRACE2-2 (requesting two digipeater hops) and received by the igate OH7AA.
There are a lot of digipeaters in the network which still do not add their callsign to the path when retransmitting the packet. Because of this the path display is often incorrect and shows some incredibly long hops.
Clicking the right mouse button on the real-time map opens up a context menu, which can be used to trigger actions specific to that location.
Add marker
Creates a new temporary marker, which can be moved (drag-and-drop). The markers can be used to temporary mark locations and initiate further actions on those locations, such as creating labelled links. The markers will be forgotten as soon as you navigate away from the real-time map. Multiple temporary markers may be created at a time.
Clicking on the marker opens up an info balloon, displaying the coordinates for the marker, and the action links.
Clicking on Link to this position generates a link with the coordinates, which can then be sent over an email or IM conversation. Clicking on the link will open up the map at those coordinates, showing a marker on the specified position. You can also add a descriptive label in the link by typing it in the provided input field. The label will be shown in an info balloon when the link is clicked. For example:
Center map here
Centers the view on the specified location.
Keyboard shortcuts
- Arrow keys – pan the map
- Page up, Page down, Home, End – pan the map quicker, one page at a time
- +, - – zoom in/out
Common search features
Searching using a wildcard
If you don't know the exact callsign or name of the target, you can try to search for it using wildcard characters. The * character will match any number of any characters, and the ? character will match any single character. For example:
These searches will bring up a wildcard search result page. Because the original search was made from the real-time map which supports displaying information for multiple targets at the same time, you can either click on a single callsign to view that stations' position, or check the checkboxes on the left side of the callsigns and click on Show selected to start tracking multiple stations at the same time. Many views on aprs.fi, like the Weather page, do not support multiple targets at the same time, in which case the checkboxes do not appear on the wildcard search result page.
Date range selection
Some pages, including the weather and telemetry pages, support selecting an arbitrary date/time range. The start and end dates must be entered in numeric year-month-day format. 2010-11-12 stands for the 12th of November, 2010. Leading zeroes can be omitted, so 2010-5-3 will bring up the 3rd of May.
You can also click on the calendar icon to bring up a calendar tool which helps with the date input.
Info page
TODO: describe the /info/ pages.
Info graphs
TODO: describe the /info/graphs/ page.
Static maps
Since the real-time map is quite heavy on computing resources, and appears slow (or does not work at all) on many old devices and mobile phone browsers, there is a Static map feature. It even supports looking up multiple stations at the same time, but cannot show real APRS symbol graphics in that mode.
It is designed to be very simple and lightweight, and it should work fine on small devices or with slow Internet connections.
KML: Viewing APRS positions in Google Earth
TODO: describe the KML features
Weather display
TODO: describe the /weather/ graphs and the weather features of the real-time map.
Telemetry
APRS stations can transmit measured analogue and digital telemetry such as voltages, temperatures, and switch / alarm statuses. aprs.fi collects the data and presents it on the info and telemetry pages. The telemetry page allows looking up historic data over the past year.
- VK2RBY-1, like many other Australian digipeaters, reports temperature, battery voltage and transmitter PTT keydowns using APRS telemetry.
- OH2RCH, an igate running the aprx software, reports channel busy status and received packets.
Preferences
TODO: describe the Preferences view.
Status packets
TODO: describe status packets view.
Beacon packets
TODO: describe beacon packets view.
Bulletin board
TODO: describe bulletins view.
Raw packets
The raw packets page allows you to browse and inspect APRS packets received from the APRS-IS. When you load the page initially (or click Clear) it will show the most recent APRS packets received. The previous and next buttons can be used to browse older ones. If you click on Raw packets in the real-time map while tracking a station, you will automatically get the packets sent by that station.
Invalid packets (and ones which are valid but which are not supported by aprs.fi) are shown in red, together with an English error message. Unreadable non-ASCII characters are displayed in hex with a purple colour. <0x1c> stands for a byte which has a hex value of 1C (28 decimal).
To see a hex dump of the complete packet contents (revealing difference in whitespace: tabs, amount of space characters in the end of the lime), move the mode selector from Normal to Hex.
To view the decoded contents of the packets, switch to the Decoded mode. This will display what information the Ham::APRS::FAP APRS packet parser is able to find from the packets, and is very useful for understanding the contents of mic-e and compressed format packets. aprs.fi internally uses the open-source Ham::APRS::FAP parser for decoding.
Prefix browsing
Exporting and downloading position data
Tools for network operators
The aprs.fi service has several features designed for APRS digipeater and igate owners.
Heard statistics
Receiver range calculation
Heard map
Gated map
Troubleshooting
My position is not showing up on aprs.fi
If your APRS position is not showing up on the site, the most common problem is incorrect symbol setting in the tracker. Please check the raw packets to see the error messages (enter your callsign and click on Search).
You should also check if your positions show up on other sites such as DB0ANF and findu.com. If the positions are not showing up on the other sites, the problem is most likely in your tracker's configuration or the local APRS network (or lack of it). Please get in touch with either another local APRS user, or your tracker's user group. Many of them are listed on the google group's front page.
If the positions are showing up on other sites but not aprs.fi, please check the raw packets again. aprs.fi is sometimes a little bit stricter than others about the packet syntax correctness, especially when it comes to symbol settings, and might reject a broken packet which others digest happily. Sorry about that.
My vehicle's position is jumping back and forth to old positions
This can happen due to many reasons, including:
- Your tracker transmitting packets very often, increasing the chance that they arrive at aprs.fi in the wrong order
- Your tracker transmitting packets with a very long digipeater path, increasing the chance that they arrive out-of-order
- A dysfunctional digipeater buffering packets for a long time before retransmitting them
- An igate with a bad Internet connection buffering packets before getting them on the APRS-IS
- A broken digipeater or igate mangling the contents of packets, so that the duplicate packet looks a little bit different than the original and won't be detected by the duplicate detection algorithms
The first two are easy to fix. The second two are harder to track down, but their effects can sometimes be mitigated by reducing the transmitting rate and using a shorter path, so that the packets do not go to a faraway broken digipeater.
aprs.fi tries hard to filter old positions, but sometimes they still get through. Because APRS packets do not contain sequence numbers and usually do not contain timestamps, it's hard or impossible to properly catch the duplicates.
There is a long blog post describing issues with duplicate and delayed APRS packets on the aprs.fi blog.
The real-time map does not show
This application makes heavy use of Javascript and Cookies. Make sure your browser allows aprs.fi to use both. If it asked for permission to use these when you first arrived on the site, and you didn't allow it at that time, the selection was probably stored in your browser's configuration, and you'll need to go to the security preferences menu to change that.
The page layout looks funny or strange
You're probably running Internet Explorer 6 or Internet Explorer 7. I strongly feel that IE6 must die, and everyone should upgrade to Internet Explorer 8 or whatever else. It's very much broken, and it takes an awful lot of time for me to make the site work with IE6. Others just work. Some layout and placement problems are still there and I can't make them go away, since IE6 is buggy. IE7 has some bugs left, too, IE8 is OK for me.
If you're running a modern browser and still see layout problems (or any other problems), please let me know through the google group.
The real-time map is slow
The map is quite heavy for the browser, especially when a lot of symbol graphics and track lines are visible at the same time. This application is simply quite complicated and heavy for being "just a web page". It is very hard to make this run smoothly on a slow computer.
If possible, try out another browser. Google Chrome and Apple Safari have much faster Javascript engines than Internet Explorer and Firefox. New Internet Explorer versions (IE8 and later) are faster than the older ones (IE6, IE7).
The map is faster when there are fewer markers visible – just try zooming in a bit. In Preferences => Filtering you can hide some target types you're not interested in. Selecting Show with track instead of Track + waypoints will hide the small red dots indicating transmitted positions along the track, which will reduce the amount of markers and might give a considerable speed-up.
Discussion group, blog and other points of communication
If you have any questions, answers, ideas, tips or tricks, please share them on the official aprs.fi Google Group. It's available as a web-based forum and as a regular mailing list. Before posting, please read the instructions on the forum's front page, especially the requirement for as many relevant details as possible (including exact callsigns and page links in question). The forum exists strictly for discussing the aprs.fi web service – please use the other relevant forums for discussion about generic APRS issues or tracker configuration problems.
News about the aprs.fi service are posted on the aprs.fi blog, which can also be subscribed over email, or using an RSS reader such as reader.google.com. Headlines from the blog are shown regularly in the lower right corner of the real-time map.