0.9.2.1pre - Documentation

Installation

Just install the provided qpegps package.

Warning: The format of the entries in maps.txt has changed since version 0.2.3. The installlation of the 0.9 version will overwrite an existing maps.txt ! For those who want to update their old maps.txt manually: Just add width and height of the images behind the scale entry. If You get problems at downloading maps, You may need to install the zlib package, too (this depends on Your installed Qtopia or Opie version).

For users of the german Sharp ROM (or any other non english version from Sharp): Due to a bug in the Sharp ROM, the english help is not found if Your Zaurus has another default language than english. To enable the included help ("?") You need to add a link to the qpegps.html file (type in a terminal, one line):
ln -s /opt/QtPalmtop/help/html/qpegps.html
/opt/QtPalmtop/help/de/html/qpegps.html
(For other languages replace "/de" with the corresponding path of Your language)

General notes:

qpeGPS now includes two different modes...

1.) GPS-navigation mode - This is standard GPS navigation with some additional features such as saving plae coordinates and saving destination points. You will see the standard navigation crosshair in the center of the screen.

2.) map-navigation mode - This mode enables you to browse maps even without a GPS receiver. Instead of the crosshair this mode uses an arrow in the center of the screen, which points in the direction of the selected position.

config | status | map | info | track | route

1. CONFIG

The path to directory where the images of the maps are stored can be selected (the internal configuration files maps.txt and sources.txt are in the same directory). This can be used for selecting different storage devices or for the selection of different kind of maps (street, aviation, nautic...).

qpeGPS uses wget for fetching maps from the net. If Your PDA is connected via a proxy server to the internet, You may need to set the address of the "Proxy" (e.g. http://foo.bar.com:80). If You don't use a proxy server, just let it empty. (For the specialists: this sets the environment variable http_proxy. If it is still set in Your environment, let it empty).

You can select the units for altitude, speed and distance. The format of the position can be selected, too. There are also checkboxes where You can select which information will be displayed on the map.

The colors and the size of the text inside the map display can be selected, too.

back

2. GPS Status

The setup and the health of the GPS connection is displayed on the GPS status page.

In order to use all the features of qpegps, a proper connection to a GPS device is needed. qpegps does not directly connect to the device, it uses a separate program called "gpsd". gpsd is a daemon program which runs in the background connects and reads data from a GPS and provides its data via Tcp/Ip to clients via the telnet protocol.gpsd needs to be run where the GPS is physically connected to. gpsd is not part of qpegps but its included in the installation. gpsd is freely available from the web (click here Thanks to Russ Nelson).

The GPS status page consists of four sections:

2.1 gpsd Settings

Here you can change the arguments to gpsd when run locally (default). Or specify the hostname/port of the remote machine gpsd is running on. Note: in order to run gpsd on the local machine the hostname must be "localhost". Any modifications to the setup here will automatically reset the current connection and start/restart gpsd if necessary.

CompactFlash GPS users: try changing gpsd arguments to -p /dev/ttyS3 -s 4800 if you have no GPS signal.

back

2.2 Data Status

This group provides a quick overview of the current health of the GPS connection. The data is updated every 1/4 second and reflects the actual data read from the GPS (via gpsd).

gpsd: Shows the status of the vital gpsd connection. The status is either green (OK) which means a proper telnet connection to the gpsd program has been established and data can be exchanged. Or the status is red (???) which means no connection has been established.

Please check gpsd settings.

GPS: Shows the actual status of the GPS device connected to gpsd. A valid gpsd connection is required to show any useful information. The status is either green which means a GPS device has been found and is sending data correctly. In this case the status also shows the three letter GPS device code (e.g. GRM form Garmin). Or the status is red (???) which means no GPS device was found or the GPS stopped sending.

Please check the cable or gpsd settings.(e.g. baud rate)

Note: It is possible that the status shows multiple device tags alternating. This is not a problem, it just shows that there is more than one GPS device connected. (e.g. a GPS and a DGPS device).

GMT: This field either shows the current GMT (Greenwich Mean Time) received by the GPS (green) or "No GMT Signal rcvd" (in red) when no valid GPS connection has been found yet. Or it shows the last received time in red meaning the GPS has stopped sending data.

Lat/Lon: These fields show the last fixed position (Latitude/Longitude) of the GPS in either green which means the shown location is valid for the GMT time shown above, or in red, which means the shown position is outdated/not valid since the GPS can not achieve a proper location fix due to various problems.

Note: A proper connection to the GPS is required at all times to display a valid fix. If the connection to the GPS is interrupted somehow the status will turn red to reflect this accordingly. However, for your convinience the position of the last valid fix and it's time stamp are still shown.

back

2.3 Misc Graphics

This group shows various information. Three timegraphs at the top show the changes to the Altitude (A), the Speed (S) and the Satellites (#) over the past 160 seconds. The altitude and speed timeline shows relative values. All values shown are scaled so the maximum and minimum values known so far line up with the upper and lower margins of the graph.

The Satellite timeline shows valuable information about the number of Satellites visible (blue) and number of Satelites used for the position pix (green) at that time. Since only twelve Satellites can be used at any time the graph shows absolute values (12 pixels). In addition, if there is a communication problem with the GPS, a red vertical bar is shown.

Below the timelines is a compass showing the current heading and bearing with arrows in the color chosen in the qpegps main setup. On the right hand side of the compass it shows the current speed, altitude, heading and bearing in absolute values and in the format chosen in the qpegps main setup.

Note: The display of Heading and Bearing can be switched on/off independantly (see main setup).

back

2.4 Satellite Signal Quality

This graph shows the SNR (Signal Noise Ratio) from 0db to 50db for each satellite in view, which basically expresses the quality of the signal for each satellite and the location fix in total. In addition the name of each Satellite is shown below the graph. If there is a current valid location fix the signal bars are drawn in green, otherwise they are drawn in red.

back

3. INFO about and handling of Maps

3.1 Check Maps

Just select one map and click on a position with a known latitude and longitude and compare it with the displayed postion on the bottom of the map.

3.2 Display Tracks

You can display tracks on the map.

3.3 Download Map

The map download feature allows you to download maps for use with qpegps from the internet. There are several sites which provide free maps for download.

In the Map Source groupbox, select the source from the dropdown for the site you wish to download from. In the Download groupbox, specify a name for the map. The name should not contain spaces and is not a filename. Specify latitude and longitude as decimal values being sure to set the hemisphere dropdowns to the appropriate settings. (Note that a longitude of -71.0 East is equivalent to the longitude of 71.0 West.) Finally, specify the scale of the map you wish to download. Some common scale values are provided in the dropdown, but the field is also editable so you may enter the exact scale that you want. Clicking OK from this dialog will begin the download. Depending on the speed of your internet connection and the size of the map image being downloaded, this could take a few minutes. Once the download is complete the map is available to qpegps.

Map Source Configuration

Qpegps uses a text configuration file to store map download source specifications. In your qpegps maps directory there is a sources.txt file. You can edit this file to add additional map sources. Qpegps comes preconfigured with one download source setup (MapBlast). Look at sources.txt to see the format.

back

3.4 Import Map

In the first dialog you are selecting the map/image which shall be imported. During the import the image is copied to the maps directory and converted to the PNG format. With the radio buttons You can select, whether the original image shall be removed or not. Pressing OK opens the second dialog which shows the selected map and some necessary parameter. Which parameters are used depends on the projection.All inputs of latitudes or longitudes can be entered as a floating value in degree or in the format Degree Minutes Seconds (e.g.: 15.51 = 15°30'36" = 15 30 36).

Available projections and there parameters:

• Linear (=cylindrical equal distance)
  • scale: only used for the selection of maps, if there is more than one which covers the current position.
  • 2 known points: x and y are the position of the pixels of the map and long and latitude represents the position on earth. x1,y1 (x2,y2) can be obtained by selecting there edit fields and then clicking on the map. After this enter the corresponding long1,lat1 (long2,lat2).
• CEA (Cylindrical Equal Area)
  • scale: only used for the selection of maps, if there is more than one which covers the current position.
  • 2 known points: x and y are the position of the pixels of the map and long and latitude represents the position on earth. x1,y1 (x2,y2) can be obtained by selecting there edit fields and then clicking on the map. After this enter the corresponding long1,lat1 (long2,lat2).
• UTM (Universal Transverse Mercator)
  • scale: only used for the selection of maps, if there is more than one which covers the current position.
  • 2 known points: x and y are the position of the pixels of the map and east and north represents the position on earth. x1,y1 (x2,y2) can be obtained by selecting there edit fields and then clicking on the map. After this enter the corresponding easting and northing: east1,north1 (east2,north2).
  • Zone: Zone of the map
• TM (Transverse Mercator)
  • scale: only used for the selection of maps, if there is more than one which covers the current position.
  • 2 known points: x and y are the position of the pixels of the map and long and latitude represents the position on earth. x1,y1 (x2,y2) can be obtained by selecting there edit fields and then clicking on the map. After this enter the corresponding long1,lat1 (long2,lat2).
  • stdLongitude: the standard longitude for which the projection was calculated, usually noted on the map. If not, try the longitude of the center of Your map.
• MERCATOR
  • scale: only used for the selection of maps, if there is more than one which covers the current position.
  • 2 known points: x and y are the position of the pixels of the map and long and latitude represents the position on earth. x1,y1 (x2,y2) can be obtained by selecting there edit fields and then clicking on the map. After this enter the corresponding long1,lat1 (long2,lat2).
• LAMBERT (Lamberts conical projection with 2 standard parallels)
  • scale: only used for the selection of maps, if there is more than one which covers the current position.
  • 2 known points: x and y are the position of the pixels of the map and long and latitude represents the position on earth. x1,y1 (x2,y2) can be obtained by selecting there edit fields and then clicking on the map. After this enter the corresponding long1,lat1 (long2,lat2).
  • std1, std2: 2 standard latitudes, usually noted on the map
  • refLong: reference longitude, if not noted on the map, usually the center of the map (the whole map, not just a scanned part of it).
• FRITZ (projection usefull for maps from mapblast and expedia derived from FRITZ Ganthers gpsdrive :-)
  • scale: is used for caculating distances (=relation between distance on earth and pixels from the image).
  • center_latitude, center_longitude: the postion in degrees of the center of the map.
  • See also the download section.

back

3.5 Map Properties

Here You can change the properties (parameters) of maps

3.6 Remove Map

Removes the selected map. There is a check box, where You can select whether the map shall only be removed from the internal maps list or if the image of the map shall be deleted, too.

back

4. Moving MAP

Now available two qpeGPS modes:

1. GPS navigation mode ("GPS mode") - This is standard GPS navigation with some addition (saving place coordinates, and setting destination features). In this mode you will see standard navigation crosses at the center of the screen.

2. Map navigation mode ("map mode") - This is mode to browsing maps. It work with or without GPS receiver. You can browse maps in this mode. In this mode we will see an arrow in the center of the screen (it will point to selected current position).

3. Use <BS> keyboard button (key) or Double Click - to switch between GPS and Map navigation modes.

If Your maps are overlapping by 240 pixel vertically and 320 pixel horizontally (screen size), You will never see the end of a map, because qpeGPS then will always select the map which fills the screen.

back

4.1 Map mode features

In "map mode" you can simply move current position (browse map) by pressing <Arrow key> (for example Up to move up...). Also you can move map by moving stylus (mouse). For this you can press on the touchscreen (or mouse button), move stylus (cursor) and then release stylus (mouse button) it will change current map position (move map).

Also in "map mode" you can change map scale (choose more or less detailed map) by pressing <Shift+Arrow key> (for example Shift+Up to chose more detailed map...). Also you can do it by pressing Ok or Return key and selecting appropriate item in popup menu.

You can click to any point on the map and you will see dialog with point's position (coordinates) in this dialog you can save this position in places.txt file (by pressing "Save" button or "OK" key ) or measure distance from this point to any another point (which will be selected by next click) by pressing "Measure" button. Also you can measure summary distance between few places (wayponts) by clicking on the map few times and using "Measure� button each time then you will see distance between last two points and summary distance.

You can set any coordinates (current position) or restore position. All places saved in file /places.txt in configurable "Track dir:" directory (default path: /home/QtPalmtop/qpegps/tracks/places.txt). You can do it by pressing Enter or Ok key and choosing "Go to Place/Waypoint" item in popup menu.

You can save / restore places (waypoints) current position or potentially any position in "map mode� (by pressing <Shift+Enter> key or by pressing Enter or Ok key and choosing "Save Place/Waypoint� item in popup menu, or buy clicking on the appropriate point and pressing "Save� button).

back

4.2 GPS mode features

A cross marks your position on the map (always in center). The color of the cross (and the text) indicates the gps status: black=ok, yellow=not fixed. The green line indicates your current heading. The red line indicates the direction to the next waypoint (bearing). If the waypoint reaches a position on the map, it is marked by a small rectangle. Altitude, heading, speed, bearing, distance to the waypoint and the time to the next waypoint are given as text info on the map.

Selecting maps:

'most Detail mode' (default): If You have several maps (with a different scale) which cover Your current location, then always the map with the most details is selected.
'Specific scale': This mode is enabled by pressing the 'Down' key. It selects always the map with a similiar scale to the current one. In the upper left corner it shows "-/+".
"+" : there is a more detailed map available. You can select it by pressing the "Up" key.
"-" : there is a less detailed map available. You can select it by pressing the "Down" key.
"D" : the next pressing of "Up" will select the "most Detail mode'.

Pressing the 'Space' key toggles the view between fullscreen and window mode.

You can save / restore places (waypoints) current position in "GPS mode" (by pressing <Enter> key) or potentially any position in "map mode" (by pressing <Shift+Enter> key or by pressing Enter or Ok key and choosing "Save Place/Waypoint" item in popup menu.

You can Set/Clear Destination point/place (only for qpeGPS not for GPS receiver). Press Enter or Ok key and choose "Set/Clear Destination" item in popup menu after it you will see "Set/Clear Destination" dialog where you can choose place/waypoint or enter coordinates, you will set destination if you will press Ok button/key or you will clear/cancel previously destination if you will will press "Cancel" key or "..." window button.

After setting Destination you will see distance from current point to this destination point in the bottom of the screen.

In any mode you can delete saved places (waypoints) in "Track" tab (simply choose place in combo box and press "Delete" button). Or you can manually edit /places.txt file by any text editor. This file stored in configurable "Track dir:" directory (default path: /home/QtPalmtop/qpegps/tracks/places.txt).

GPS mode	Map navigation mode (works with or without GPS receiver)
<BS> keyboard button (key) or Double Click - switch between GPS and Map navigation modes	<BS> keyboard button or Double Click - switch between modes GPS and Map navigation modes
<Stylus/Mouse click> switch to full screen mode
	<Stylus click> or <Mouse click> - we will see message with point coordinates and with three buttons and associated possibilities: 1. Press: "Cancel" button - to Quit (do nothing) 2. Press: "Save" or "OK" button to - save place coordinates 3. Press: "Measure" button - to measure distance between two points. This point will be first. Make next click
<Return> or <OK> keyboard button by using popup menu you can: 1. Save current position coordinates as place coordinates in places.txt file 2. or Set/Clear Destination	<Return> or <OK> keyboard button to chose popup menu. Then you can select: "Go to Place/Waypoint" - to move current position to manually entered place coordinates or to coordinates from saved places (from places.txt file) "Save Place/Waypoint" to save current position "More detailed map (Shift+Up)" to chose more detailed map "Less detailed map (Shift+Down)" to chose less detailed map
<Shift + Return> or <Shift + OK> keys - Save current position coordinates as place coordinates in places.txt file	<Shift + Return> or <Shift + OK> keys Save current position coordinates as place coordinates in places.txt file
<space> key switch between full screen and normal modes (no changes same as in original version)	<space> key switch between full screen and normal modes
<Left>, <Right>, <Up>, <Down> keys choose less and more detailed maps (no changes same as in original version)	<Left> <Right> <Up> <Down> keys move current position (and map of course) to appropriate direction. Use it for navigation/browsing maps Also you can press on the touchscreen (or mouse button), move stylus (cursor) and then release stylus (mouse button) for changing current position (moving map). <Shift + ArrowUP>, <Shift + ArrowDown>, <Shift + ArrowLeft>, <Shift + ArrowRight>, <Left>, <Right>, <Up>, <Down> keys choose less and more detailed maps (no changes same as in original version)

back

5. TRACKlogs

Make sure that an existing track directory is selected for storing tracks. To start logging your track write its name to the write field and check the checkbox. The tracklog will be actually written when unchecking the checkbox or quitting qpegps. If you select a existing filename, new trackpoints are appended to the existing track. You can set a minimal time difference between trackpoints to control the size of the file.

To display a track select it or write its name to read field and check the checkbox. It's displayed in bearing color (set in config) with specified line width (1-5) in the map page (if it fits in). To see it on the info map you have to reload the map.

You can also copy the file to your desktop and display it with GpsDrive.

5.1 Deleting places

You can delete saved places in "Track" tab (simply choose place in combo box and press "Delete" button). Or you can manually edit /places.txt file with any text editor. This file stored in configurable "Track dir:" directory (default path: /home/QtPalmtop/qpegps/tracks/places.txt)

back

6. Route

Waypoints and routing are still on our schedule. But qpeGPS uses the routing information from the GPS (bearing and distance to next waypoint).

back