Serial port and GPS

serial Namespace

Set of programs using serial port especially for GPS, containing:
gpsx.exe Command line utility for converting flat files into GPX. See also documentation on the class GpsxTest.
psrf103.exe Command line utility for generating SiRF PSRF103 messages for configuring frequency of certain NMEA sequences generated by the chip. See also documentation of the class Psrf103Test and the documentation on SiRF propertiary messages at http://gpsd.berlios.de/vendor-docs/sirf for more details.
s2ip.exe GUI application for copying the output of a serial port to TCP, UDP or broadcast. May be used in order to connect the PDAs GPS output on a desktop computer. See also documentation on the classes Serial2IPForm, Serial2IPGUI.
scpy.exe GUI application for copying information from one serial port to another (and vice versa). Similar to s2ip.exe the program may be used in order connect PDAs serial port to a desktop computer, this time through a serial port rather than through IP. See also documentation on the classes SerialCpyForm, SerialCpyGUI.
sg.exe GUI application for communicating with the serial port. The application is able to read the serial port, for example in order to trace the NMEA output of a GPS chip, write to the serial port and log the information coming from the serial port into the file. The application is also able to read from IP (TCP, UDP or broadcast) so that it can be connected to the stream generated by s2ip.exe. Because s2ip.exe is presently inable to receive data from IP and copy it to the serial port, the IP based communication can't be used in order to write to the serial port. See documentation on the classes SerialForm, SerialGUI.
sgps.exe The application for showing the current position, both as decimal coordinates, UTM and on a defined map, a map can be defined as a bitmap file with coordinates of the borders. The application is able to read the NMEA sequences from both serial port, for example directly from a serial port on a PDA, and from IP, for example using the stream generated by s2ip.exe. See also documentation on the classes SerialGPSForm and SerialGPSGUI.
utm.exe Command line application for converting geographical coordinates into UTM. Strongly based on an Excel sheet and the theretical description by Prof. Steve Dutch. See also the description of the class UTMTest.cs and the following links: http://www.uwgb.edu/DutchS/UsefulData/UTMFormulas.HTM, http://www.uwgb.edu/DutchS/UsefulData/UTMConversions1.xls
map.exe Help utility for showing a position on a map and for downloading maps from http://www.openstreetmap.org. The program is also able to show a position coming on a specific UDP port, for example from the program cellinfo.exe included in the package cetoys, http://cetoys.sourceforge.net.
osm.exe Command line utility (only for desktop computers) for downloading maps from openstreetmap.org. The maps can be also downloaded using the GUI utilities sgps.exe and map.exe, also directly from the mobile device.

Maps

The applications sgps.exe and map.exe are able to show the current or the given position on a map. The map consists of a set of bitmap files with a textual definition file. The bitmap files are fragments of maps, usually scans of a printed map, screenshots from Google Earth or Mapnik PNG files downloaded from http://www.openstreetmap.org. The textual definition file describes the coordinates of the corners of the map fragments in the bitmap files. Eg. the following description file sgps.map:

11.83489 49.43595 11.85265 49.42637 amberg1.png
11d36m43.96sE 48d08m44.80sN 11d37m48.11sE 48d08m22.06sN muenchen1.jpg
11d35m07.50sE 48d10m03.37sN 11d39m47.59sE 48d07m42.85sN 11d39m48.14se 48d10m03.37sN 11d35m08.47sE 48d07m42.81sN muenchen2.png
defines the three map fragments in the bitmap files amberg1.png, muenchen1.jpg and muenchen2.png with the following coordinates of the corners of the map fragments:
amberg1.png Left-upper corner in 11.83489 degree East, 49.43595 degree North. Right bottom corner in 11.85265 East, 49.42637 North. A rectangular area is assumed, so that the coordinates of the right upper corner are automatically set to 11.85265 East, 49.43595 North and the left bottom corner is located at 11.83489 East, 49.42637 North.
muenchen1.jpg Also a rectangular area, this time for a part of Munich. The coordinates may be expressed either as decimal numbers or using degrees, minutes and seconds. For decimal numbers use always dot as the decimal point rather than a comma, even if comma would be the proper setting for your locales. Negative numbers are for West or South, positive numbers are for East or North. The format for degrees, minutes and seconds is either
<degs>d<mins>m<secs.dec>s[E|W|N|S]
or
<degs><mins>'<secs.dec>''[E|W|N|S]
See also the documentation for the method Utils.coord2dec() for more details on the available formats for coordinates. The left upper corner of the area is located at 11 36' 43.96'' East, 48 8' 44.8'' North, the right bottom corner is located at 11 37' 48.11'' East, 48 8' 22.06'' North.
muenchen2.jpg Another part of Munich. This time coordinates of each 4 corners are defined separately, what allows to define stretched rather than rectangular areas. Usually screenshots from Google Earth are pictures of ellipsoide surfaces rather than rectangular areas. The format of this definition is:
  1. The longitude of the left upper corner.
  2. The latitude of the left upper corner.
  3. The longitude of the right bottom corner.
  4. The latitude of the right bottom corner.
  5. The latitude of the right upper corner.
  6. The longitude of the right upper corner.
  7. The latitude of the left bottom corner.
  8. The longitude of the left bottom corner.
  9. Name of the bitmap file with the map fragment.
See the documentation for the classes BmpMap and BmpMaps for the format of the map description file. Generally the map description file contains one map definition per line, each line consists of tokens separated with a whitespace, comma or semicolon. The first either 4 or 8 tokens are coordinates of either left-upper and righ-bottom corners for a rectangular area or of each 4 corners of a arbitrary quadrangle. The last token is the name of the bitmap file in any of the format supported by the constructor of System.Drawing.Bitmap (bmp, png, jpg, gif etc. are usually supported). It may be either a full path to the bitmap file or a relative name, if it is relative, then the bitmap file is searched relatively to the directory of the map description file.

There are no maps delivered with the programs. The maps can be obtained by scaning regular printed maps, making screenshots from Google Earth & Co. or downloading them from various services available on the internet. For each map you must know the coordinates of the edges of the maps included in the bitmap files, regardless if you scaned them, made a screenshot or downloaded them from somewhere. My favorite source of maps is http://www.openstreetmap.org delivering generated with Mapnik rectangular png files with defined minimum and maximum longitude and latitude. The png file for a required map can be downloaded by sending the following string with the HTTP POST request to the web server http://www.openstreetmap.org/export/finish:

maxlat=c&minlon=c&maxlon=c&minlat=c&format=mapnik&mapnik_format=png&mapnik_scale=s
where the coordinates c are decimal coordinates with dot as decimal point and the scale s is an integer number, usually a few thousands or so. Mapnik export is very sensitive for huge areas in the exported png files, therefore they must be splitted into smaller rectangles. Usually an area with a length or height of 0.03 - 0.06 degree with a scale of 10000-20000 is the maximum you can get in one POST request using the mapnik exporter (format=mapnik in the POST request above). Downloading huge areas, spliting them into smaller chunks and putting all together into a description file suitable to use with sgps.exe and map.exe can achieved using the command line utility

osm.exe

on a desktop computer or the GUI utility

map.exe

both on the mobile device connected to the internet as well as on a desktop PC. See the documentation for the class OsmDldTest for more details on using the command line utility osm.exe. Generally the call to
  osm.exe -basename=munich \
          -minlat=48.06 \
          -maxlat=48.22 \
          -minlon=11.43 \
          -maxlon=11.69 \
          -steplat=0.04 \
          -steplon=0.08 \
          -exporter=osmarender \
          -osmarender_zoom=15 \
          -export_format=png
  
will download a lot of PNG files containing map fragments for Munich, each named munic<num>.png and it will create the map definition file munich.map. Each map fragment will have the width of 0.08 degrees and the height of 0.04 degrees. The download is performed using the osmarender exporter with the osmarender zoom of 15.

Using -exporter=mapnik and the parameter -scale=57600 rather than the osmarender exporter and osmarender zoom you can obtain maps created by mapnik. In my opinion the mapnik exporter delivers better maps, but it often doesn't work at all in the service http://www.openstreetmap.org. Also the exporter osmarender denies any cooperation, if the resulting bitmap files would be higher or weighter than 2000 pixels. It is very important to select a correct values of scale (for mapnik) or the value of osmarender_zoom in order to obtain any results. The best way is to find out these values using tha javascript based web page of www.openstreetmap.org and then to use them for the batch download with either osm.exe or its GUI replacements in map.exe or sgps.exe. If the download has been performed on the desktop computer, please copy the bitmap files (munich*.png in the example above) and the map definition file (munich.map) to one directory on the PDA.

The same can be downloaded using map.exe and sgps.exe. In map.exe select menu Map/Download, enter the coordinates and the scale into the proper text boxes and then select Map/Download again. The same download form can be reached in sgps.exe using menu Port/Config and the button Download. The downloaded map can be used in sgps.exe after defining its location in Port/Config/Map file. In map.exe the location of the map description file is defined in the main window of the application in the text box Map file. For the example above the map definition file will be located in the directory, where osm.exe, sgps.exe or map.exe was called (or in the root directory, if sgps.exe or map.exe was called on the PDA) in the file munich.map. With -basename=/path/munich the maps and the definition file can be downloaded to a specific directory /path. The directory must already exist.

osm.exe, map.exe and sgps.exe allow also to download the maps in XML format (osm) http://www.openstreetmap.org (-exporter=osm), but this format is not supported yet for showing the map in sgps.exe or map.exe. The programs currently support only bitmap formats.

Quick Howto for GPS

Coordinates from UDP

The program map.exe to show also coordinates coming over the UDP port defined in the input box UDP port. Enter a value of the port on which the program has to listen, theoretically any value > 0 is allowed, but some systems may require port numbers > 1024. The entered port number must not be occupied by another listener. Thein switch listening on UDP on by selecting the menu item Map/Listen UDP.
The program expects the following format of the incoming information: This kind of information can be for example sent from program

cellinfo.exe

included in the package cetoys http://cetoys.sourceforge.net, thus

map.exe

can be used for showing locations of the cellular towers found using the Microsoft RIL API used in

cellinfo.exe

.

Compilation

For the compilation the following is needed: After everything has been installed, go to the source directory of this package and compile it using nant, nant doc or nant cab. The effects of the compilation are:

Namespace hierarchy

Classes

ClassDescription
BmpMapForm Form for showing the bitmap map and the current position on it.
BmpMapsCollection of maps.
ClipAccess to clipboard
CmdLineOptsParses command line options.
FormWithInvokeBase class for forms using Invoke methods.
GpsxCreates a Gpx file with a path description
GpsxTestCommand line test program for creating Gpsx files
IPClientClient implementation for the server in Serial2IP
IPClientGPSReads GPS data from the server
MapForm Form for the application map.exe showing an entered position on the map.
MapGUI Main for the program map.exe, starts MapForm.
OsmDldMap download from www.openstreetmap.org.
OsmDldCfgOpenstreetmap download parameters.
OsmDldExcpDownload error got from the openstreetmap server.
OsmDldFormForm controling downloads from openstreetmap.org
OsmDldTest Command line application for downloading OpenStreetMap maps.
Psrf103TestCommand line test program for PSRF103 messages
SerialEncapsulates serial port operations
Serial2IP Copies information from the serial port to IP.
Serial2IPFormThe main form for the serial 2 IP copy application
Serial2IPGUIMain for the the program s2ip.exe, starts Serial2IPForm
SerialCpyCopies data from one port to another
SerialCpyForm Form for the application scpy.exe copying one serial port to another.
SerialCpyGUI Main for the programm scpy.exe, starts SerialCpyForm.
SerialFormThe main form of the application sg.exe
SerialGPSReads coordinates from a GPS serial port
SerialGPSCfgFormForm for the configuration of the program sgps.exe
SerialGPSForm The main form of the program sgps.exe
SerialGPSGUI Main for the program sgsp.exe, starts SerialGPSForm.
SerialGUI Main for the program sg.exe, starts SerialForm.
UdpLstnUDP listener
UtilsCommon purpose utilities
UTMTestCommand line test program for UTM translations

Interfaces

InterfaceDescription
ICmdLineOptInterface for the command line parser

Structures

StructureDescription
BmpMapMap in a bitmap.
OsmDldRecSingle rectangle to download from OSM.
StraightLineStraight line going through two known points

Delegates

DelegateDescription
CoordDelegateCallback for position informations obtained from GGA
OsmDldDelegateCalled from download() after each map or on error
ReadByteDelegateCallback for single byzes read from the serial port
ReadLineDelegate Callback for line strings read from the serial port or IP.
StopCbCallback called while stopping processing
UdpLstnDelegateDelegate for retrieved UDP data

Enumerations

EnumerationDescription
DatumDatum types used for UTM
Psrf103msgMessage types for Utils.psrf103()
ServerTypeThe IP server type