GPS Cycle Computer1. General DescriptionThis is a GPS tracing application for Windows Mobile. You do not need any other GPS software to be installed, i.e. it works directly with Windows GPS driver. You do not need any data network connection to record a log, although there is an option to activate Live Logging (provided by www.crossingways.com), so you position is uploaded to the web site as well. The tool logs GPS data into binary files with .gcc extension (binary files are much smaller than the text files to store the same information). gcc files then can be loaded back for viewing, or saved into .kml or .gpx format, to view in e.g. GoogleEarth. With the latest version of GoogleMaps, you can view kml files on your phone. Just click on a kml file in File Explorer. Note there is a bug in GoogleMaps installation, unless you install it into the main memory - see section "Useful info" below how to fix this. To save battery power, GPS can be switched on/off at pre-defined intervals (5 sec ... 2 hours). . Main display shows: trip distance; trip time (including or excluding "stop time", i.e. when speed is zero); current / average / max speed; altitude (abs or relative to starting point); heading; estimated battery usage. Display units are miles / nautical miles / km for distance, m / feet for altitude, mph / kmh / knots / minpmile / minpkm for speed. Map display shows your track. Also you can use “maps” – any JPEG image with known coordinates of the corners as a background. OpenStreetMap "tiles" are supported - these can be downloaded automatically (if you are connected to the internet), or you can download a set of "tiles" yourself and copy them on your phone. You can also load a "track-to-follow" from gcc, kml or gpx file, which is displayed in different color. 2. InstallationCopy the GpsCycleComputer.CAB file into your Windows Mobile device and click on it from your phone FileExplorer to install. The tool can be intalled into any folder, so probably it is better to install it into "Internal Storage", to save main memory. The path to the tool (on UK Windows) will be then \Internal Storage\Program Files\GpsCycleComputer. You can also find this Readme.htm file in that folder, if you want to read it on your phone. The tool shall work on any screen resolution in portrait mode. It was designed on a VGA screen, so you might have small distortions on other screens due to scaling. For landscape mode, the tool tries to adapt the button layout, but some controls might not be fully visible, i.e. that is to say that the tool is usable in landscape, but better use portrait mode. The tool now supports AppToDate, i.e. if you have AppToDate installed on your phone (get it from here http://www.apptodate.org/get , more info available here http://forum.xda-developers.com/showthread.php?t=327990 ) - then you will be receiving latest GpsCycleComputer version automatically. All CAB versions and the complete source code (in C#) are currently stored at Google Code project page: http://code.google.com/p/gccv2/downloads/list 3. Quick start. Controls on the "Main" screenAs you start the tool, you see the main screen with usual "cycle computer" info: trip time, clock, speed (current, average and max), and the info you would see on a GPS device: altitude, heading, latitude/longitude, plus some info about the GPS status. At the bottom there are 3 buttons: Options (left), Start (center) and Files (right). These 3 buttons changes as you move to different screens or start/stop GPS. In most cases you shall be able just to click Start button, get GPS lock (so it is better to try this outside! ) and record you first track. Find an open place outside (which is not surrounded by trees or buildings), click the Start button and stay still (this helps to get GPS lock). You need to watch: GPS display (bottom right of the main window) :
Info display (bottom left of the main window) :
If you have number of satellites 0, or "no gps data" for some time, then it is likely that your GPS setting are not correct.You need to read further how to set GPS options correctly, see section "Useful info", "GPS setup" below. Assuming that all works (you see "gps on" and green rectangle) with the default settings (or if you have changed the setting, and it works!) , let us proceed with the desciption of the main screen. When running, Start button changes to Pause - to pause GPS and / or add a checkpoint. Press Pause button again to continue logging. The File button changes to Stop - to stop the log and save it into a file. The Options button changes to Maps - which shows you track. When logging is on, you can switch between Main and Maps screens only. On the Maps screen, you can use Zoom in / Zoom out buttons, and move track line with your finger (like in GoogleMaps for Mobile). Also you can plot a "map" as a background for the track - see section "Maps" how to do that. Note the the clock is only updated when logging is active. Also when logging, the tool will prevent your phone going into standby mode (note, the standby time has to be larger than 15 sec), so the screen shall be always on. By default, you can use the hardware "power" button to switch off the screen – GPS will continue logging. Although, this might not work on some phones, so there is a option to display a BkLightOff button, to let you switch off the screen and continue logging (see options). When the logging is off, the clock is not updated (but you can click on any part of the main screen to get it updated), and you phone will be able go into standby and switch off the screen. When logging, if you current speed is not 0, you shall see "heading" (blue arrow at the bottom right of the main screen). This shows direction of your travel, as it looks on a map with "north", as usual on a map, pointing up. Do not be confised - the arrow shows direction of your travel, not the "north" direction (north is up). Now, if you have any data logged, you can stop the logging (press Stop button), and see what you can do with the log file. 4. Working with log filesA log file is automatically created as you click Stop button. The default name "year"+"month"+"day"+”_ “+”hour"+"min"+"sec"+ .gcc. The files are stored in the directory which you can set in Options. By default this is the directory where the executable is installed. It is also possible to enter a custom file name (see Options). Also a file “log.csv”, located in the same folder as gcc files, is updated with the summary of the trace (one line per trace / gcc file) – to give you a quick overview of all your logs in that folder. To go into Files screen, click Files button (right button on the Main screen). You shall see a list of *.gcc files stored in the directory you selected (note, you cannot change the directory in the Files screen, you need go to Options to do that. The buttons on Files screen are: on the right there are buttons to select next/prev file. Also you can selected a file by clicking on it. The center button on the bottom row - loads gcc file (and automatically goes to the Maps screen to view it). The left button on the bottom row - close the Files screen and return to Main. Left and center buttons on the top row save the selected gcc file into KML or GPX - these are two popular formats to exchange GPS data. GCC is the internal format for this tool, so you must save file as KML or GPX before viewing them in other applications. When you save file into KML, a "*" is printed before the file name. If you save into GPX, then a "+" is printed - so you can quickly check which files have been converted into GPX and/or KML. KML files can be viewed with GoogleEarth. Also, with the latest version of GoogleMaps, you can view KML files on your phone. Just click on a kml file in File Explorer (note that bug in GoogleMaps install - see Useful info, Problems with GoogleMaps installation. To view GPX files you can try http://utrack.crempa.net/ web site. Also you can view GPX files in GoogleEarth (go to File | Load menu). GCC file are assosiated with GPS Cycle Computer, so you can also open gcc file by clicking on it from FileExplorer on your phone. But the tool does not load the settings correctly in this case, and also if you have the tool already opened, it does not load another file again (i.e. you need to close it, to get it load a file). If you know how to fix this - please let me know. So at the moment this seems not a very usable option to open gcc files (i.e. better to load them from the tool, as explained above) 5. OptionsOptions must be selected before the logging is activated, otherwise the options button is hidden. If you want to change any options during logging, you can press "pause" button (then the "options" button is available), and resume logging (press "pause" again) after updating options. This way you can change e.g the logging interval, load different maps or track-to-follow. Note that even if you change the input/output file folder, the currently logged file still be written in the folder you set as you started the log, i.e. it will not be changed. There are a few option pages, so press "next" or "previous" (center or right buttons) on options tab to switch between option pages. The first options you see:
Page "GPS options":
Page "Main screen options":
Page "Maps screen options":
Page "KML/GPX options":
Page "Live logging options":
When live logging is activated, you will be asked each time you click "Start" button, if you want to proceed. Also in the "info" box you will see messages "livelog ok" or "livelog error!" - which tells you the status of last log attempt.. and finally:
6. “Maps”A “map” is any JPEG image with known coordinates of the corners. It is plotted as a background on “Maps” page. Maps are automatically selected – the map which has better coverage of the picture (in % of the picture area) and higher resolution (lower km per pixel) is selected. Also there is a option to plot multiple maps at the same time - read below how it is implemented. So first you need a jpeg image, the file must have .jpg or .jpeg extension, e.g. “MyTown.jpg”. Do not create very large images, as it takes long time to load and plot them - a good size is about 1000x1000 max. To specify the map coordinates, you can use 3 methods described below. Also you can use "OpenStreetMap tiles" - these are specially created PNG images, so the image coordinates can be derived from the file names. I.e. you do not need to specify the coordinates for OpenStreetMap tiles - just download them. 6.1 txt + jpeg: first method is to create a text file (with .txt extension and the same name as the image, e.g. “MyTown.txt”) which contains 4 lines: 1st line - latitude of the bottom left corner, 2nd line – longitude of the bottom left corner, 3rd line - latitude of top right corner, 4th line – longitude of the top right corner. The lat/long must be in decimal format, e.g. 55.976598, just the decimal number, no degrees character, etc. You need to place the jpg and txt files into folder with your maps. By default, this is the “maps” subfolder where GpsCycleComputer executable is installed on your phone, e.g. if you install into “Internal Storage”, then the default location (on English Windows) will be: “\Internal Storage\Program Files\GpsCycleComputer\maps”. This folder is created during CAB installation and has a text file “maps_folder.txt” inside, so you shall be able to identify it easily. Note that you can change the maps location in Options. The tool supports up to 512 “maps” per folder. 6.2 kml + jpeg: second method is to use GoogleEarth to create maps, it is quick and accurate. A very good and detailed description how to create such a map is given in the RunGps manual, section 5.2.2 (look at http://www.rungps.net/wiki/DownloadsEN). The only difference is that you need to save location as “.kml” file, not as “.kmz” file used by RunGps. If you already have a .kmz file, then it is easy to convert it to .kml: simple change the .kmz extension into .zip (this is a zip file), and unzip it – the unzipped file will be the .kml. So here are the main steps:
This is it! As with the txt files, you need to place the jpg and kml files into folder with your maps (by default, this is the “maps” subfolder where GpsCycleComputer executable is installed). Here is my interpretation how this works for kml files: The .kml file is just a text file. It contains the coordinate of the map centre (LookAt point) and the height of the “eye” This is a single point, but as I understand, the default angle of view along the horizontal (x-axis) is 60 degrees, so knowing the height of the “eye” and this view angle allows to determine the map size along x-axis. As we know the picture size in pixels, then we can determine the y-size of the map. 6.3 gmi + jpeg: third method is to use GpsTuner' gmi files. Instead of the coordinates of the map' corners, you can supply coordinates of a few reference points (e.g. a bridge or road intersection). gmi file is a text file which contains the following lines: Map Calibration data
file v3.0 First line is the header (must be present, otherwise an error dialog is shown). Second line is the image file name. It is not used by GpsCycleComputer, as the gmi and jpg file must have the same name. Lines 3-4 are the image width/height - these must match the image size, otherwise an error dialog is shown. This is an important check, as if the image size does not match these values, then the lines below will be incorrect, as they give location of the reference point on the image. The format of these lines with reference points is: 4 values separated by ";" - the x and y point location on the image (in pixels), then longitude and latitude of the point. You could have a few reference points/lines, but not less than 2. Note that the "y" coordinate in pixels is calculated from the image top, not from the bottom - e.g. if you load your image into Windows Paint, and move mouse over it watching the mouse position display, you will see that the image origin is the top left corner, not the bottom left. Note that the map must not be rotated, i.e. the north must be up (as with all other maps used by GpsCycleComputer). As with the txt and kml files, you need to place the jpg and gmi files into folder with your maps (by default, this is the “maps” subfolder where GpsCycleComputer executable is installed). A similar idea to set the map coordinates is used in OziExplorer map files and CompeGps imp files. To convert these files into gmi files you can use this web site: http://www.map-imp-gmi-converter.com/index.php 6.4 Using OpenStreeMap tiles - these are PNG images, arranged into a special directory structure based on "zoom level" (0 to 18), and the tile X coordinate within this zoom level. The image Y coordinate is the file name. More info is here: http://wiki.openstreetmap.org/wiki/Slippy_map_tilenames. All images are 256x256 size. As an example, assume that you have a directory "tiles", then first you will see sub-folders with names "0" to "18" (this is the zoom level, not all directories will be there, i.e. you will see the level which you have downloaded). Then inside each sub-folder you will see more sub-folders, each has name as a number - these are the X-coordinates of the tiles. And fnally, you will see the .PNG files itself - the file name is the Y-coordinate. To use tile files in GpsCycleComputer, you need to select the top folder, i.e. the folder "tiles" in the above example, the one which have sub-directories 0 to 18. Note that you should not change the directory structure (then you will get incorrect tile coordinates), or to place any other files there (they will not be loaded, i.e. only the PNG files will be used). There is no limit on the number of tiles (just the size of you phone's storage card!). The large number of tiles will not slow the tool or increase the memory usage - as only the tiles which are required are loaded for plotting. There are a few tool to download tiles, I tried "JTileDownloader" which is available from here: http://wiki.openstreetmap.org/wiki/JTileDownloader.This is a Java tool ("jar" file), so if you click on it and nothing happens (on a PC), then you will need to download and install "Jave runtime" from Sun (just seach for it in Google). As you start JTileDownloader, on the "Main" page you can select zoom level(s) and the area you want to download. As the tiles are downloaded, they are automatically arranged in the directory tree described above - so all you need is to copy it to your mobile, and point GpsCycleComputer to the top folder (e.g. "tiles"). For more info visit www.openstreetmap.org. 6.5 Automatic OpenStreetMap download - if you have an internet connection on your phone, then you can select an option to automatically download OSM tiles which do not exist on your phone, and are required for the current display. To enable this option, select a server name to be used from "Download" combo-box. Note that different server have maps in different "styles", so you need to select different folders for different maps. If you are using this option for a first time, just create a new blank folder with FileExplorer, and use "Set maps files location" button to select this folder. If you already downloaded tiles from a server (using e.g. JTileDownloader), then select that server name and select the folder you already created to download the tiles, so the tiles which are missing and requried for display will be downloaded there. This way your "tile collection" will grow. Note that if a tile file already exist, then it will not be downloaded, so if you want to download a tile again, select a new blank folder, or delete files from existing folder. There is 10 second timeout for a tile download, so if a server does not reply within this time, you will see "Download Error" on the map display. This could happen if a server is busy, so you can try again - just move the map with your finger or press zoom buttons - the map update will trigger download. The predefined list of servers are:
You can specify any OSM server, if requred - just edit a file called "osm_server.txt", which is created in the same folder as GpsCycleComputer.exe, then restart the tool (the file is re-loaded when the tool starts), and select "User-defined" in the "Download" combo-box. The osm_server.txt shall contain a single line, which is the name of the server to use. The server address shall finish with "/", as the required zoom, X coordinates and PNG file name will be appended after the "/", e.g an example address could be http://tah.openstreetmap.org/Tiles/tile/10/12/33.PNG for a server http://tah.openstreetmap.org/Tiles/tile/. Is is a good idea to try to access such a sample address using a web browser, to check that you can see PNG images at that server, i.e.the server is working. 6.6 Map selection. The maps are automatically selected - as you touch and lift you finger from the screen or press zoom-in/zoom-out buttons. The best map name is displayed at the top of the screen. If a folder with OpenStreetMap tiles is detected, then you will see zoom level, x and y coordinates of the best tile. If no maps covers the view area, then no map is used, and the display says “no map”. If there were errors during map download from web or loading from storage card, then the display says “Download Error” or "Read Error". You will also see "Read Error" if there is not enough free memory to display a map (e.g. if an image file it too large, or you try to load too many images at the same time). Note that you can see the map only as a background for your existing track, you cannot just browse any maps you created without having a track recorded for that location (well, if you want to see the map jpeg image - just click on it in File Explorer - this is just a jpeg!) Note that you can select a folder with jpeg file or a top folder with OpenStreetMap tiles - i.e. you cannot store both type of maps in the same folder. 6.7 Multi-maps plotting algorithm - tries to plot multiple jpeg maps (instead of a single, the best, map). The maps a simply plotted on the top of each other, so the trick is to decide in which order to plot the maps. Well, I have an idea to plot the maps in order of "map quality"- starting from the worst, and finishing with the best, so we have the best map on top. There are two factors which determine "map quality" - first is how much area of the screen is covered by the map (the best map will cover 100%). Second factor is what is map zoom level - clearly, there is a zoom level at which the map is best readable on the phone screen - this is selectable in options (you can choose 1x zoom, 2x zoom or 4x zoom). If the zoom level is different (i.e. if you zoom-in or zoom-out) - the map quality will drop (details are too fine and not possible to read, when you zoom-out, or, details dissappear as you zoom in more and more). So the map quality is defined as combination of map coverage and zoom quality factor. Well - this is probably too complicated to explain - but all you need is to experiment with different settings and see which one works best for you. Note that the more maps you use, the more memory requirements. Regarding what set of maps to create - I think the best idea to create maps for the same area at different zoom level (like OpenStreetMap tiles) - e.g. a overview map, then maps which cover some part in more and more details. Then the tool will try to select the best (or the best set of) maps for you. Do not create very large or very small images, the size is about 1000x1000 max. 7. Track-to-followUse "Load track to follow ..." button on the first page of "Options" to load a track data from an existing file. You can load data from "gcc", "kml" or "gpx" files - use "left/right" buttons on the open file dialog to see files with different extension. If you have the 1st (main) track (i.e. if you have logging active, or loaded any .gcc files on the "Main" page), then you shall be able to see both tracks plotted on the Maps page - note that you can set line style (color, width and plot as line/dots) for each track separatelly. To clear "track-to-follow" press "Clear..." button. You shall see message at the bottom of the screen which says "Track to follow cleared". Then you will see only "main" track plotted on the Maps page. If you want to do opposite (i.e. to clear the main track, and view only track-to-follow, then you need to clear the main track as well - press "Clear ... " button twice. You shall see message "All tracks cleared". Now you can load the track-to-follow, and only the 2nd line will be displayed. Note that you can clear the main track only if the logging is not active. 8. Custom button skins and custom back / fore colorYou can set your own background / text color and images for all buttons. All what required is to edit jpeg files which are supplied with the source code (look into GpsCycleComputerSource.zip) and copy the new images into the folder with GpsCycleComputer.exe on your WinMobile, then re-start GpsCycleComputer. The new images will be loaded at the startup. If you want to change just a single button, just copy the files for that button, all files are not required. For example, if you want the change “Maps” button for bottom menu, edit files “map.jpg” and “map_p.jpg” (there are two images, as button has two states, "normal" and "pressed"). Better do not change the image sizes, to avoid image distortions. To change the background color, edit file “bk_color.jpg”. The image shall be filled with a single color. For the font (fore) color, edit fore_color.jpg (and place then with GpsCycleComputer.exe). 9. Source codeA complete source code (in C#) is provided. For GCC file format see file Form1.cs, function "LoadGcc" which loads a gcc file. Basically after a header with general data, the data is written as 5 short int (short int = 16 bits = 2 bytes) which are : x, y, z (in metres, relative to starting point), speed (in kmh*10) and time (sec, relative to start). Also there are a few special records (also as 5 short ints) to save some control info, like battery status. Feel free to change anything you like, but please send me you comments/bug fixes. The project files for MS Visual Studio 2005 are provided. The solution file (*.sln) contains 3 projects: GccGPS (this is the dll to work with GPS - you need to build this for PocketPC 2003 target, release); then GpsCycleComputer project itself (to build the executable - build for Any CPU, release); and the CAB project, the one which creates a CAB (build this last, for Any CPU, release). If you have problems you could create a project files yourself, and just add the existing source files to it. If you have problems building dll - I just use the Wizard to set a MFC DLL project for me (so you could try to do the same), then just add there GccGPS.cpp and .h. If this still does not work, then you actually do not need to build DLL, just copy it from the installation (after you install the application on your phone). 10. Useful Info10.1 GPS setupThere are many ways for a software to connect to GPS. Usually it is assumed that the GPS hardware is connected to a serial port (e.g. COM0..COM14), so all is requried for a software is to "open" the required serial port and listen to the GPS data. The data comes in a form of text strings in so called NMEA format. In addition, Windows provides two drivers to connect to GPS (you can read about this here: http://msdn.microsoft.com/en-us/library/bb201942.aspx) - Windows "raw" GPS driver and Windows "parsed" driver. "Raw" driver is also called "multiplexer", as it does not do any processing of the GPS data, but simply forwards it to all applications, i.e. multiple tools can be connected to GPS at the same time. The COM port for the "raw" driver is different from the GPS hardware port, and it is set in Windows "Settings", "System", "External GPS", "Programs" tab - this is usually COM4 (in WinMobile 6.1). The "parsed" driver does more work for you - it converts GPS data into actual latitude/longitude, etc, so you can just retrieve this data without any knowledge of a COM port or NMEA strings generated by GPS. So how all this can be set in the tool? There is a check box "read GPS data directly", COM port and baud rate selectors on Options page. Option 1 (default and recommended): Check (i.e. select) "read GPS data directly", set COM port to the multiplexer value (check Windows "Settings", "System", "External GPS", "Programs" tab - usually this is COM4), baud rate does not matter (I think) for multiplexer, set to e.g. 4800. This way you use Windows "raw" driver, and let multiple apps to use GPS at the same time. Option 2 (very easy, but often GPS does not work well): Un-check (un-select) "read GPS data directly", the COM/baud rate setting are not used in this case. This way you use Window "parsed" driver and let Windows fully manage and process GPS data for you. Note: with this option you cannot use the phone hardware power off button to switch the phone on/off, and still have the GPS logging - you will need to use BkLightOff button (center button on Main screen, select appropriate option to show it) - to switch the bklight off. Option 3: Check (select) "read GPS data directly", set COM port and baud rate to the GPS hardware port setting (you shall have some instructions from the GPS manufacturer). This way you are connected to the GPS directly. Not sure if this will work correctly with multiple GPS applications running at the same time. You shall be getting at least 1 satellite very quickly (see main screen display, GPS section, parameter "S"), if the settings are correct. If you have 0 satellites or "no gps data" for some time - then something might be wrong in your setup. Tips for a quick GPS lock: 1) use QuickGPS tool (it is supplied with Diamond); 2) do soft-reset for your phone, specially after software updates; 3) find a place outside building with clear sky view (i.e. do not stay next to a large building wall); 4) do not move your phone, keep it still relative to ground (not relative to your car dashboard while you are driving off !). On Diamond, in this conditions, usually you will get a lock in under 30 sec. 10.2 Location of a temporary file created during loggingDuring loging, the tool creates a temporary file "tmp.gcc" in the root folder (i.e. \tmp.gcc), then copies it into the required gcc file as logging is finished. Writing into a file in the main memory seems make the application more stable, than writing into a file located in \Internal Storage. If you phone crashes (and the "final" gcc file was not created), then you still can restore most of your log (the last part might be missing, as the data is not written instantly into the file by Windows). All you need to do is to locate the tmp.gcc file and copy it into the required location with desired name - then you shall be able to open this file with the tool as usual. 10.3 Problems with GoogleMaps installation, if you cannot open KML fileThere is a problem with some versions of GoogleMaps for Mobile - it cannot open a KML file as you click on it in your phone File Explorer. You need to edit registry key to fix this. If you do not know how to edit a registry key, then a simple solution would be to install GoogleMaps into main memory - then it shall work. If you have experience with registry, then go to HKEY_CLASSES_ROOT, "kml" key (without . upfront, as there is a key called ".kml"). Inspect the path to your GoogleMaps.exe, it could be wrong - usually the part "Internal Storage" (on UK Windows) is missing - this is what you need to add. Note that you shall not use any tools to associate kml file with GoogleMaps, as these tools do not know about extra command-line switches (e.g. -KML_FILE) required, i.e. they create incorrect association and you still will not be able to open KML files. 10.4 Running from ACI managed to tell Windows do NOT switch off the screen and GPS when running from battery, but seems these functions does not work when running from AC adaptor. So it is recommended to set the Windows setting "do not switch bklight" and "do not go into standby" when running from AC. Send me a message, if you know how to fix this.... (I guess, set the values in registry is one option?) 11. ContactProgramming: AndyZap Design: expo7. Special thanks to AngelGR. http://forum.xda-developers.com/showthread.php?t=424423 http://code.google.com/p/gccv2/downloads/list Good luck! |
