The OpenGTS Project Follow us on
Home | Project | Demo | Documentation | FAQ | More Info

Frequently Asked Questions


Here is a list of commonly asked questions regarding the configuration of OpenGTS. This list is continually growing, so check back periodically for updated questions and answers:

(Additional information can be found on the Documentation page, and in the runtime config file 'private.xml' file that comes with OpenGTS).

Glossary:
  1. General terms, abbreviations, and definitions.

A) Overview:
  1. What type of applications are using OpenGTS?
  2. What is the basic overall architecture of OpenGTS?
  3. How do I get started learning about the OpenGTS configuration options?

B) Installation:
  1. What OS platforms are supported by OpenGTS?
  2. How do I install OpenGTS?
  3. Can I install OpenGTS on a virtual or shared server?
  4. What are the system hardware requirements to run OpenGTS?
  5. How do I upgrade OpenGTS to the latest version?
  6. How do I check my OpenGTS installation to see if it was installed properly?
  7. How do I load the sample data into OpenGTS?
  8. How do I install multiple versions of the 'track.war' file?

C) Configuration:
  1. How do I change the displayed language translation (ie. locale)?
  2. How do I change the look-and-feel of the web-interface?
  3. How do I change the default displayed map location and zoom when no pushpins are displayed?
  4. How do I change the speed settings for the pushpin colors displayed on the Device map?
  5. How do I change the displayed data/time formats?
  6. How do I change the map provider?
  7. How do I change the maximum number of pushpins displayed on the map?
  8. How do I enable reverse-geocoding (ie. turning a latitude/longitude into an address)?
  9. I've enabled reverse-geocoding, but why are my address still blank?
  10. My report addresses are fine, but why are the addresses in my email notifications blank?
  11. How do I change the map and report Calandars to show Monday as the first day of the week?
  12. How do I configure outbound SMTP (EMail) service?
  13. How do I send outbound SMS messages from OpenGTS?
  14. How do I set the first page viewed after logging in (other than the main menu)?
  15. How do I download and serve my own local copy of "OpenLayers.js"?

D) Tomcat:
  1. How do I change the Tomcat listen port?
  2. How do I remove the ":8080" port and "/track/Track" requirements from the Login URL?
  3. How do I change the default session timeout value for Tomcat?
  4. How do I configure SSL (ie. "https") in Tomcat?
  5. I've copied my changed "track.war" file to Tomcat, but I don't see my changes?

E) MySQL:
  1. How do I increase the number of allowed MySQL connections?
  2. How do I reset the MySQL 'root' password?
  3. How do I repair a MySQL reported error indicating an "Incorrect key file"?
  4. How do I copy the MySQL "gts" database to another computer?

F) Device Communication Servers and Events:
  1. How do I use a Boost Mobile Motorola GPS phone with OpenGTS?
  2. How do I use a Sanav GC-101/GX-101 with OpenGTS?
  3. How do I use the "Aspicore GSM Tracker" Nokia phone tracking software with OpenGTS?
  4. Why am I getting a "Read timeout" when using the "sipgear" DCS with a TK102 device?
  5. What is the best GPS tracking/telematic hardware?
  6. How many devices can OpenGTS track?
  7. How is GPS tracking/telematic data sent from the device to the server?
  8. How do I create my own device communication server (DCS)?
  9. Why do the TCP sessions in my DCS module always time-out?
  10. Why does my event table contain events dated in the future, and how do I delete them?
  11. How do I trim/delete old events from the EventData table?
  12. Why does my GPS-based odometer calculation not match my vehicles actual odometer?

G) Troubleshooting:
  1. When attempting to build the project, why do I get a "Permission Denied" error?
  2. How do I fix the compile error "... package javax.mail does not exist"?
  3. How do I fix the login error "Error reading Account"?
  4. How do I fix the web-page error "'private.xml' contains syntax/parsing errors"?
  5. How do I fix the web-page Status 404 error "The requested resource (/track/Track) is not available"?
  6. How do I fix the web-page Status 404 error "The requested resource (/track/track) is not available"?
  7. After logging-in, selecting any menu option logs me out again.
  8. How do I fix the command-line error "Can't locate .../common.pl in @INC ..."?
  9. How do I enter command-line options on Windows?

H) Miscellaneous:
  1. How do I find out more about other commercially available tracking/telematic features?



A.1) What type of applications are using OpenGTS? [_]
The OpenGTS code base is a highly configurable enterprise grade system which has been used for many different types of GPS tracking applications. Much of the code required for many of these applications is already available within the OpenGTS package, and needs only to be configured to activate these alternate features. Most custom changes can be made within the various available runtime configuration files ("config.conf", "private.xml", etc). The following is a partial list of the type of GPS tracking applications utilizing OpenGTS:
  • Personal (cell phone or small personal tracking devices)
  • Athletes
  • Bicycles
  • Personal vehicles
  • Motocycles
  • Tractor/Trailers
  • Taxis
  • School Buses
  • Fuel delivery vehicles
  • Service vehicles
  • Golf carts
  • Delivery vans
  • Police vehicles
  • Emergency response vehicles
  • ATVs
  • Containers (cargo, recycling, etc)
  • Fixed water storage tank levels
  • RFID tagged packages
  • Agriculture
  • Aircraft
  • Ships
  • etc.
top

A.2) What is the basic overall architecture of OpenGTS? [_]
(click to enlarge)
This diagram shows the basic relationships between the various main components of OpenGTS. The various device communication servers run as seperate processes on top of Java. The Track servlet (which provides the web-interface), as well as other servlets (including any http-based device communication servers) run within a Servlet Container, such as the one provided by Apache Tomcat. This architecture allows for running the various components on different physical servers, for assisting with 'high-availability' configurations.
top

A.3) How do I get started learning about the OpenGTS configuration options? [_]
The OpenGTS code base is a highly configurable enterprise grade system. After downloading and installing the OpenGTS system, most of the customizaton changes can be made in one of the following runtime configuration files:
  • private.xml - Web interface configuration. Controls the displayed menus and available pages, the active map provider, the active reverse-geocode provider, the displayed pre-configured reports, and various display properties.
  • config.conf - GTS system wide configuration file. Controls system wide information such as the MySQL configuration, SMTP (EMail) configuration, Outbound SMS gateway, Optional database table column configuration, and various overrides to the "private.xml" file.
  • reports.xml - Report definition/configuration file. Configures the available report definitions that can be made available for user selection.
  • war/track/css/ CSS files - Cascading Style Sheets which can control the fonts and colors of various display options within the web interface.
To learn about the code layout itself, you can view the JavaDocs here. The GTS JavaDocs is a work in progress, and is continually being updated, so check back often.
top



B.1) What OS platforms are supported by OpenGTS? [_]
OpenGTS has been successfully installed on the following platforms:
  • Linux (Fedora, CentOS, Debian, Gentoo, Ubuntu, etc)
  • Mac OS X (Leopard, and Snow Leopard)
  • FreeBSD
  • OpenBSD
  • Windows (XP, Vista, 20XX server, etc)
top

B.2) How do I install OpenGTS? [_]
The document "OpenGTS_Config.pdf", included in the downloaded zip file package, contains step by step information for installing OpenGTS.
top

B.3) Can I install OpenGTS on a virtual or shared server? [_]
This depends on the features and support provided by the virtual or shared hosting service provider. You will need to be able to install the software tools required for OpenGTS (Java, Ant, Tomcat, MySQL, etc). You should also have 'ssh' access to the server to be able to remotely administer the GTS database and tables, restart Tomcat when necessary, and monitor log files. Each virtual/shared hosting service provider is different, so you will need to check with the specific provider to see if they support the features you require. These are some of the questions you should ask:
  • Is Linux available on the server? (what distribution? Fedora, CentOS, etc?)
  • Does the server have at least 4Gb of available RAM? (8Gb+ preferred for larger systems)
  • Does the server have at least 100Gb of available disk space? (300Gb+ preferred for larger systems)
  • Is 'ssh' access allowed/provided to the server?
  • Is 'root' access allowed/provided while on the server?
  • Can other software packages be loaded as required (such as Java, Tomcat, Ant, etc.)?
If the answer to these questions is yes, then this hosting provider will likely be able to run OpenGTS.
top

B.4) What are the system hardware requirements to run OpenGTS? [_]
The following is the general recommended system configuration for running OpenGTS in a production environment:
  • 2.8Ghz Quad-Core CPU
  • 8Gb RAM (16Gb or more recommended when running several DCS modules)
  • 500Gb RAID-1 hard disk array
  • Gigabit Ethernet adapter (fixed IP address)
For a system used for testing purposes, or for tracking a small number of devices, the following minimum configuration may be used:
  • 1.8Ghz CPU
  • 2Gb RAM (1 DCS module only)
  • 75Gb hard disk
  • Ethernet adapter (fixed IP address)
top

B.5) How do I upgrade OpenGTS to the latest version? [_]
Review the "README.txt" and "CHANGELOG.txt" files for any notes that may be important for the new version. The general procedure for updating OpenGTS to the latest version is as follows:
  • Stop all running device communication servers.
  • Unzip and build the latest OpenGTS version along side the previous version (refer to "OpenGTS_Config.pdf" for build and configuration instructions).
  • Change the GTS_HOME environment variable to point to the latest version of the installed OpenGTS.
  • Update the GTS database with the latest tables and columns. The procedure for upgrading the OpenGTS is described in Section 6.2 of the "OpenGTS_Config.pdf" documentation. The Linux command for upgrading the GTS database is as follows:
            %  cd $GTS_HOME
            %  bin/dbAdmin.pl -tables=ca
    This command will add any missing tables, and add any new columns within existing tables.
  • Run "bin/checkInstall.sh" to make sure everything was installed correctly.
  • Rebuild/Redeploy the new "track.war" file.
  • Restart any new device communication servers
The latest OpenGTS version should then be ready for use.
top

B.6) How do I check my OpenGTS installation to see if it was installed properly? [_]
The procedure for checking the OpenGTS installation is described in Section 3.2 of the "OpenGTS_Config.pdf" documentation. The Linux command for checking the OpenGTS installation is as follows:
    %  cd $GTS_HOME
    %  bin/checkInstall.sh
This command will check several different aspects of the OpenGTS installation and display a summary report of its findings. Any errors or warnings should be corrected, or at least understood, before running the system in a production environment.
top

B.7) How do I load the sample data into OpenGTS? [_]
Additional documentation for installing sample 'demo' data into the database can be found in the "README.txt" file in the OpenGTS "sampleData/" directory at "sampleData/README.txt".
top

B.8) How do I install multiple versions of the 'track.war' file? [_]
The typical URL for accessing the login page is as follows:
    http://login.example.com:8080/track/Track
    (where "login.example.com" is your server domain name)
The name "track" listed above derives it's name from the name for the war file, in this case "track.war". This means that you can install multiple/different copies of the "track.war" file, as long as the name of the war file is changed during the copy. For example, if you copy the "track.war" file to Tomcat as follows:
    %  cp $GTS_HOME/build/track.war $CATALINA_HOME/webapps/track1.war
Then you could then access this installed version with the following URL:
    http://login.example.com:8080/track1/Track
top



C.1) How do I change the displayed language translation (ie. locale)? [_]
This can be changed in the 'private.xml' file. On the "Domain" tag, change the "locale" to the desired 2-letter country code. For example, to change the language to German, set the Domain "locale" attribute to 'locale="de"'. You can also add a pull-down language selection menu to the login page by setting the Property "accountLogin.showLocaleSelection" to "true". The language selections are specified in the "SupportedLocales" tag.
(Rebuild/redeploy the 'track.war' file after making any changes to the 'private.xml' file.)
top

C.2) How do I change the look-and-feel of the web-interface? [_]
The colors and fonts can be changed by modifying the various 'CSS' files located in the directory "war/track/css/". The various available 'JSP' files used to display the web-interface are located in the directory "war/track/jsp/", and and have the name format "loginSession*.jsp". Which one of these "loginSession" files is used to display the web-interface is controlled in "private.xml" by the "JSPEntries" tag specification, and the "WebPages" tag attribute "jsp". The "private.xml" file itself has many configurable options that can also be modified to change the look-and-feel. Here is a partial list of look-and-feel features that can be configured within the "private.xml" file:
  • Which login fields are available to the users.
  • The type of main menu that will be presented (ie. icons/buttons, text, etc).
  • Setting the map to grow to the size of the client browser window frame.
  • Where the map controls are placed (ie. right or left).
  • Which map control options are displayed within the map control area.
  • The default displayed map latitude/longitude/zoom when no pushpins are available.
  • Setting various configurable options on the available displayed web pages.
  • Which web-pages are displayed/disabled to the user.
  • etc.
See the "private.xml" file for more information.
(Rebuild/redeploy the 'track.war' file after making any changes to the 'private.xml' file, or any of the CSS files.)
top

C.3) How do I change the default displayed map location and zoom when no pushpins are displayed? [_]
This can be changed in the 'private.xml' file. Currently, the default latitude/longitude and zoom centers over the US. To change this to another location, look for the "default.zoom", "default.lat", and "default.lon" properties in the active "MapProvider", and change them to the desired value:
    ...
    <Property key="default.zoom">4</Property>     
    <Property key="default.lat">39.0000</Property>
    <Property key="default.lon">-96.5000</Property>
    ...
Change the latitude/longitude and zoom level do your desire location.
(Rebuild/redeploy the 'track.war' file after making any changes to the 'private.xml' file.)
top

C.4) How do I change the speed settings for the pushpin colors displayed on the Device map? [_]
The actual pushpin icon selection is determined in the JavaScript function "evHeadingMarkerURL" found in the JavaScript module located at "war/track/js/maps/jsmap.js". You can change the chosen pushpin, based on the current speed, by modifying this function. To set the matching "Legend" displayed on the Device map, you will need to modify the "Legend" tag section of the currently active MapProvider.
top

C.5) How do I change the displayed data/time formats? [_]
This can be changed in the 'private.xml' file. Look for the "DateFormat" and "TimeFormat" tag sections.
(Rebuild/redeploy the 'track.war' file after making any changes to the 'private.xml' file.)
top

C.6) How do I change the map provider? [_]
This can be changed in the 'private.xml' file. Look for the "MapProvider" tag sections and enable the desired MapProvider (ie. 'active="true"'), while disabling the other MapProviders (ie. 'active="false"'). Make sure you comply with the terms-of-use for the map-provider which you are using.
(Rebuild/redeploy the 'track.war' file after making any changes to the 'private.xml' file.)
top

C.7) How do I change the maximum number of pushpins displayed on the map? [_]
In most cases there is no actual limit on the number of pushpins that may be displayed on a map, however there may be a "practical" limit on the number of pushpins that a user may be able to comprehend or assimilate. The 'default' maximum number of pushpins that can be displayed on a map is set to 1000, however this limit can be set lower, or higher, in the 'private.xml' file within the active "MapProvider" section. The following properties may be set to control the maximum pushins displayed on the "Device" map, "Fleet" map, or the map available on certain reports:
     <Property key="map.maxPushpins.device">500</Property>
     <Property key="map.maxPushpins.fleet">500</Property>
     <Property key="map.maxPushpins.report">500</Property>
The above example properties will set the maximum number of displayed pushpins to 500 for the Device, Fleet, and report maps.
(Rebuild/redeploy the 'track.war' file after making any changes to the 'private.xml' file.)
top

C.8) How do I enable reverse-geocoding (ie. turning a latitude/longitude into an address)? [_]
There are a couple parts to the reverse-geocoding configuration:
  • First the "ReverseGeocodeProvider" must be enabled in the 'private.xml' file. "Geonames" is one of the free available reverse-geocode providers, however, you will need to check to see if reverse-geocoding is supported in the area that you are interested in. In the 'private.xml' file, enable the ReverseGeocodeProvider you wish to use (set 'active="true"' for the desired ReverseGeocodeProvider, while setting the other ReverseGeocodeProvider's 'active="false"').
  • Next the 'geocodeMode' in the various Account records must be set to '3' for "full" reverse-geocoding (this allows you to control which Accounts may have reverse-geocoding service, since some reverse-geocoders are a premium/fee service).
Reverse-Geocoding only occurs on events which arrive after this configuration has been completed (Reverse geocoding will not be retroactively applied to events which have already been placed into the EventData table). Monitor the device communication server log files for reverse-geocoding attempts, to verify that it is working properly.
The following command will test the configured active reverse-geocode provider:
    %  cd $GTS_HOME
    %  bin/rgTest.sh -pl=default -gp=39.12345/-142.12345
Where "-pl=" specifies the "default" private-label configuration, and "-gp=" specifies the latitude/longitude (GeoPoint) that you wish to test with the active reverse-geocoding provider.
(Rebuild/redeploy the 'track.war' file after making any changes to the 'private.xml' file.)
top

C.9) I've enabled reverse-geocoding, but why are my address still blank? [_]
This can occur for one of several possible reasons:
  • The enabled reverse-geocoder does not support addresses in the area where the vehicle is traveling (a different reverse-geocode provider will likely need to be chosen).
  • The enabled reverse-geocoder may support the general geographic area, but does not have an address for the specific latitude/longitude.
  • The enabled reverse-geocoder is currently off-line, or has refused to reverse-geocode a location.
  • A reverse-geocoder was enabled after the events have been placed into the database (the reverse-geocode provider only reverse-geocodes events arriving after it has been enabled).
A combination of the reverse-geocode "rgTest.sh" command (see above) and the log files from the running device communication server (DCS) should diagnose the reverse-geocoding issue.
top

C.10) My report addresses are fine, but why are the addresses in my email notifications blank? [_]
- Reverse geocode providers that publish their service over the web are considered "slow" reverse-geocoding operations because they are dependent on Internet network latencies and often cannot return their address information quickly enough (Internet-based reverse-geocode providers typically take a few seconds to return their result).
- If the reverse-geocode provider is considered a slow Internet-based service, then when an event arrives in a device communication server (DCS) it spawns a thread which is allowed to take its time to query the reverse-geocode an address, allowing the main thread to continue quickly. The main thread then continues and if any notifications need to be sent, they will not yet have an address value ("${address}", "${fullAddress}", etc, will be blank) because the reverse-geocoder has not yet obtained an address.
- If having an available address value is required at the time a notification is sent, there are two possible solutions:
  1. Within the "active" ReverseGeocodeProvider section set the "alwaysFast" property to "true" (add the property "<Property key="alwaysFast">true</Property>" if it does not already exist). This will force the main thread to assume that the operation can occur quickly and continue to wait for the reverse-geocode process to complete before continuing with any notifications, thus providing non-blank values for "${address}" and "${fullAddress}". (However, if the DCS is receiving a large number of events every second, this can end up holding on to system resources (threads, memory, etc) for an extended period of time and may limit the number of devices that the server can ultimately handle)
  2. Or install a locally hosted reverse-geocode provider on your own servers so that the reverse-geocoding service does not need to reach out over Internet. Examples include GISGraphy, and a few of the Geonames premium reverse-geocoding services. (This is the recommended method of reverse-geocoding prior to event notification)
top

C.11) How do I change the map and report Calandars to show Monday as the first day of the week? [_]
This can be changed in the 'private.xml' file. Look for the following Property definition:
    <Property key="calendar.firstDayOfWeek">0</Property>
Then set the value to '1' (ie. 0=Sunday, 1=Monday, ...).
(Rebuild/redeploy the 'track.war' file after making any changes to the 'private.xml' file.)
top

C.12) How do I configure outbound SMTP (EMail) service? [_]
Outbound SMTP (EMail) support can be configured in the 'custom.conf' file. Look for the following Property definitions:
    # --- SMTP
    # - (outgoing email configuration parameters)
    smtp.host=smtp.example.com
    smtp.port=465
    smtp.user=someuser
    smtp.user.emailAddress=someuser@example.com
    smtp.password=somepass
    smtp.enableSSL=true
Set "smtp.port" to the SMTP server IP address or host name. Set "smtp.port" to the SMTP service port number. Set "smtp.user" and "smtp.password" to the outbound SMTP service username and password. Set "smtp.user.emailAddress" to the "From" email address (if required). Set "smtp.enableSSL" to "true" if the outbound SMTP service requires SSL.
(Rebuild/redeploy the 'track.war' file after making any changes to the 'custom.conf' file.)
top

C.13) How do I send outbound SMS messages from OpenGTS? [_]
The easiest way to send outbound SMS message is through an email-to-SMS service available from your wireless service provider. Most wireless service providers support assigning an email address to a phone, such as "1234567890@phone.example.com", where they will translate emails sent to this phone email address into an SMS message which they will forward on to the phone. Contact your wireless service provider to see if they support this email-to-SMS service.
top

C.14) How do I set the first page viewed after logging in (other than the main menu)? [_]
After logging in, the default first page viewed is the main menu. To set this to a different page (such as the vehicle or fleet maps), create a user (such as the default user "admin"), then edit the user to set the "First Login Page" pull-down menu to the desired default page to first display after the user logs in.
top

C.15) How do I download and serve my own local copy of "OpenLayers.js"? [_]
The "OpenLayers.js" JavaScript is used to display map tiles in the client browser when using the OpenLayers/OpenStreetMaps MapProvider. In some cases it may be more advantageous to download your own copy of the "OpenLayers.js" JavaScript and serve it yourself from your own server. The following steps describe how to configure the GTS to use your own copy of the "OpenLayers.js" JavaScript, rather than use the version pulled directly from the OpenLayers.org server:
  • Download (and unzip if necessary) a copy of the latest "OpenLayers.js" from "http://www.openlayers.org/download/" and place it at the following location inside the GTS installation folder:
      war/track/js/openlayers/OpenLayers.js
    (create the "war/track/js/openlayers" directory if it does not already exist)
  • Modify the "private.xml" file and change the "openlayers.js" property configuration in the "openLayers" MapProvider section. Change this line:
      <Property key="openlayers.js">http://openlayers.org/api/OpenLayers.js</Property>
    To this (or add this proeprty line if it does not already exist):
      <Property key="openlayers.js">./js/openlayers/OpenLayers.js</Property>
  • Rebuild/Redeploy the "track.war" file to test this configuration.
Note: If you do serve your own local copy of the "OpenLayers.js" JavaScript, you may wish to periodically check for updates from OpenLayers.org and download/install the latest version.
(Rebuild/Redeploy the "track.war" file, and restart any running DCS modules, after making any changes to the runtime configuration files.)
top



D.1) How do I change the Tomcat listen port? [_]
The default port "8080" can be changed in the Tomcat 'server.xml' configuration file at "$CATALINA_HOME/conf/server.xml". Note that on Linux, binding to to a port less than (or equal-to) 1024 requires that Tomcat be run as 'root',which is not recommended. If you wish to access the web-interface on port 80, an alternative method would be to use 'iptables' to forward requrest on port 80 to port 8080. This can be accomplished with the following example 'iptables' entries:
    /sbin/iptables -t nat -I PREROUTING -p tcp --dport 443 -j REDIRECT --to-ports 8443
    /sbin/iptables -t nat -I PREROUTING -p tcp --dport  80 -j REDIRECT --to-ports 8080
top

D.2) How do I remove the ":8080" port and "/track/Track" requirements from the Login URL? [_]
The typical login URL is "http://track.example.com:8080/track/Track" (where "track.example.com" is the domain name of your server). This URL is usually placed in a link from another company webpage so the user never needs to specifically enter this URL. However, in some cases it may be necessary, or desireable, to instead only require that a user go directory to a url such as "http://login.example.com" to login, instead of requiring that the ":8080" and "/track/Track" also be included. The easiest way to accomplish this is to create an "index.html" file which loads the login url into a single frame. This way the user can enter a url such as "http://login.example.com", and have the "index.html" file load the actual login url into a frame.
The latest version of OpenGTS provides a feature will create this 'frame' html for you. Assuming that "http://track.example.com:8080/track/Track" is the URL used to view the login page, the following URL will automatically produce the html 'frame' page required that can be used on another static web server to eliminate the need to enter the ":8080" or the "/track/Track" specification (change the domain name and port to fit your specific requirement):
    http://track.example.com:8080/track/loginFrame.html
Right-click and save this HTML page (ie. "Save Page As") and copy the resulting file to a directory on your static web-server. For instance, if you have a static web-server at the location "http://login.example.com", and you copy the above html to a file called "index.html" in the root directory of your web-server (typically "htdocs"), then you should be able to see the login page at "http://login.example.com".
top

D.3) How do I change the default session timeout value for Tomcat? [_]
This can be changed in the Tomcat default "web.xml" file found in the Tomcat directory "$CATALINA_HOME/conf/web.xml". Here is the section of the "web.xml" file that sets the timeout to 30 minutes:
     <session-config>
         <session-timeout>30</session-timeout>
     </session-config>
You can change this value to any desired length of time. Tomcat should be restarted after this value has been changed. (Note: setting this value too large may cause excessive resources to be consumes by users which have logged in, but are not actually using the system).
top

D.4) How do I configure SSL (ie. "https") in Tomcat? [_]
Configuring SSL (Secure Socket Layer) within Tomcat allows secure access to the GTS login, ensuring that all data sent between the server and client web-browser is encrypted. The followig Apache Tomcat SSL configuration URL will describe how to configure SSL withint Tomcat:
     http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html
top

D.5) I've copied my changed "track.war" file to Tomcat, but I don't see my changes? [_]
Servlet .war files, such as "track.war" are typically deployed to the Tomcat webapps/ directory. If Tomcat is configured with autoDeploy="true" (the default configuration in "conf/server.xml"), then any .war file copied to the Tomcat webapps/ directory should be automatically deployed. However, if for some reason your installation of Tomcat is not automatically deploying the new track.war file, you can usually force a deployment using the following steps:
  1. Stop the currently running Tomcat (ie. "$CATALINA_HOME/bin/shutdown.sh").
  2. Remove the old deployed Tomcat webapps/track/ directory.
  3. Copy the new track.war file to the Tomcat webapps/ directory.
  4. Restart Tomcat (ie. "$CATALINA_HOME/bin/startup.sh").
  5. Monitor the Tomcat "logs/catalina.out" log file for deployment of the new track.war file.
top



E.1) How do I increase the number of allowed MySQL connections? [_]
Currently, each thread process is allocated a MySQL connection (for simultaneous device communication server connections, etc). The MySQL command "SHOW PROCESSLIST" will display all current connections, and the command "SHOW VARIABLES LIKE 'max_%connections'" will show the current value of the MySQL connection variables. To increase the number of allowed MySQL connections, add the following to the MySQL config file "/etc/my.cnf", in the "[mysqld]" section (or increase their current value if these properties are already defined):
     max_connections=300
     max_user_connections=300
Then restart MySQL after changing this configuration.
The following MySQL website will provide more information on this issue:
     http://dev.mysql.com/doc/refman/5.5/en/too-many-connections.html
top

E.2) How do I reset the MySQL 'root' password? [_]
If you have forgotten the MySQL 'root' password, it can be reset using this procedure recommended by 'dev.mysql.com':
     http://dev.mysql.com/doc/refman/5.0/en/resetting-permissions.html
top

E.3) How do I repair a MySQL reported error indicating an "Incorrect key file"? [_]
During a normal system shurdown or reboot, the MySQL service is stopped gracefully, however if the MySQL database was not shutdown normally (as can occur during a power-fail, etc) a MySQL table key index can be come corrupted, resulting in an error similar to the following:
     java.sql.SQLException: Incorrect key file for table './gts/EventData.MYI'; try to repair it
Or, possibly an error similar to the following:
     java.sql.SQLException: Table './gts/EventData' is marked as crashed and should be repaired
The following MySQL website describes how to repair key file issues:
     http://dev.mysql.com/doc/refman/5.0/en/myisam-repair.html
top

E.4) How do I copy the MySQL "gts" database to another computer? [_]
The default name of the MySQL GTS database is "gts" (overridable in the "common.conf" file with the property "db.sql.dbname"). This database can be copied from one computer to another using the procedures outlined by MySQL at the following link:
     http://dev.mysql.com/doc/refman/5.0/en/copying-databases.html
top



F.1) How do I use a Boost Mobile Motorola GPS phone with OpenGTS? [_]
For information regarding support for various Boost Mobile Motorola phones, please see the document at "MotoDMTP/MotoDMTP.txt" in the OpenGTS installation directory.
top

F.2) How do I use a Sanav GC-101/GX-101 with OpenGTS? [_]
Additional documentation for installing and configuring the GC-101 server within OpenGTS can be found in the "README.txt" file in the "gc101" source directory at "src/org/opengts/war/gc101/README.txt".
top

F.3) How do I use the "Aspicore GSM Tracker" Nokia phone tracking software with OpenGTS? [_]
The document "OpenGTS_Config.pdf", included in the downloaded zip file package, contains information for installing/configuring the device communication server for Aspicore supported phones.
top

F.4) Why am I getting a "Read timeout" when using the "sipgear" DCS with a TK102 device. [_]
Some TK102 devices do not provide a proper packet terminating character which would indicate to the server that the packet is complete and can be processed. If this is the case, you can try adding the following property to the "dcservers.xml" file, in the "sipgear" DCServer section:
    <Property key="packetLenEndOfStream">true</Property>
This configuration will cause the data end-of-stream to be considered the packet termination so that the packet can then be parsed and processed.
top

F.5) What is the best GPS tracking/telematic hardware? [_]
The best hardware greatly depends on the specific requirements for the GPS tracking/telematic application.
Here are some of the questions that need to be answered to best fit the GPS tracking/telematic hardware to the applicaton:
  • Is the device for personal tracking, vehicle-installed tracking, or for rarely-moved-asset (RMA) tracking? Personal tracking devices are self-contained, while devices used for vehicle tracking usually require specialized installation. For personal tracking, a cell phone tracking application may be adequate, however battery-life requirements should be considered, as well as the fact that cell-phone tracking applications can usually be stopped by the operator.
  • What are the application power requirements for the device? Does it need to be self-powered (ie. for tracking untethered trailers, etc.), or is a power-source available?
  • Is notification of digital inputs required? (such as door open/closed events, etc).
  • Is notification of analog inputs required? (such as temperature, fuel level sensors, etc).
  • Does the application require the ability to query the location of the device, or send commands to the device?
  • Does the application require the ability to set digital 'outputs' on the device? (ie. unlock doors, disable starter, etc).
  • Does the device need to store unsent events (due to loss of coverage) until connection to the server can again be obtained? (often called "store-and-forward").
  • What are the data transport requirements for the device? (ie. TCP, UDP, SMS, Satellite, WiFi, Bluetooth, etc.)
  • Is text-based communication with the operator or driver of the vehicle required?
  • Is voice-based communication with the operator or driver of the vehicle required?
  • Does the application require the ability to send 'next-stop' information to the driver, with navigation to the next stop?
  • Is the cell phone coverage area adequate for the application? (ie. will the GSM/GPRS or CDMA wireless data provider cover the areas that you require)
  • Is satellite-based communication required? (ie. for areas that do not have adequate GSM/GPRS or CDMA coverage). Satellite-based communication options include Iridium, OrbComm, Globalstar, and Theraya.
  • Is engine diagnostic information required, including actual odometer, fuel usage, engine temperatures, etc? (ie. J1708, J1939, OBDII, EOBR, CANBus)
  • Is temperature monitoring information required? (ie. refrigerated containers, etc.)
  • Does the device need to be PTCRB certified? (This is a question often overlooked. In the US, all tracking devices which transmit data over a wireless modem need to be PTCRB certified.)
  • etc.
Each of these features potentially has an additional cost associated with it as well. The more features required, the more costly the solution, and the cost of the solution will need to be weighed against the benefit of the information that it provides. Once the required features have been determined, the search for the best device that fits the requirements can begin.
top

F.6) How many devices can OpenGTS track? [_]
OpenGTS has been successfully used to track thousands of devices on a single server. Here are some of the factors that can effect the number of devices that a single server can track:
  • TCP vs. UDP - A TCP 'session' consumes more resources that a UDP connection, especially if the device always expects to maintain a constantly connected TCP session. Using UDP for data transport is more scalable and is the recommended method of sending data from the device to the server.
  • Event Reporting Interval - A more frequent reporting interval will have a higher load on the system. If 1000 devices transmit location data once every 5 minutes (300 seconds), this averages about 3.33 messages per second arriving at the server (1000 devices / 300 seconds). However, if the same 1000 devices needed to transmit data every 20 seconds, that averages about 50 messages per second (1000 devices / 20 seconds), creating a much higher load on the system.
  • Network Speed - The Internet service provider, and/or local Intranet speeds also effect the ability of the server to receive data from the remote devices, and still perform other network queries that it may need for any required event analysis.
  • Computer Resources - The more RAM that a computer system has installed, generally the faster it will run. It is recommended that a system running OpenGTS have at least 4Gb of RAM installed.
These are only guidelines, and a system tracking 1000's of devices, or tracking at a much more frequent interval, will require more system resources than a system tracking fewer devices at a less frequent reporting interval.
top

F.7) How is GPS tracking/telematic data sent from the device to the server? [_]
Depending on the capabilities of the device, data can be transmitted to the server in one of several ways. The following describes some of the methods used by devices to transmit data to the server:
  • Cellphone Network - The most common method of transmitting data to the server. The GPS tracking device contains a Cellphone modem which typically uses a SIM card provided by a Wireless Data Provider (ie. AT&T, T-Mobile, Sprint, Rogers, etc). The modem uses this wireless data-plan to establish a connection to Internet, and then a socket connection with the server. Once connected to the server, it typically sends its location information, then disconnects. Data can be transmitted using UDP or TCP. Each has their advantages and disadvantages, however UDP is generally preferred due to its much greater data bandwidth efficiency. In some cases, data may be sent to the server using SMS through the use of an SMS-Gateway. The following graphic displays how GPS data may be transmitted to the server over a GPRS/Mobile network:
    (click to enlarge)
  • Satellite Communications - The GPS tracking device contains a satellite modem which connects to one of the major satellite communication data providers (ie. Iridium, OrbComm, Globalstar, etc.). The data from the tracking device is sent to an orbiting communication satellite, which then relays the data to a ground station, which then forwards the data to a server over a stanrd socket connection, or may use SMTP to forward the data to the server. Satellite data communications tend to be much more expensive, and have much greater data limitations, than using a cellphone network. The following graphic displays how GPS data may be transmitted to the server over a Satellite Communication network:
    (click to enlarge)
  • WiFi Network - The GPS tracking device contains an 802.11 compiant WiFi modem when connects to a wireless router to send data to the server. This type of application is typically limited to very localized environments, such as tracking vehicles traveling within a closed yard, or mining plant. The advantage with this solution is that there is no associated cost with the tracking of the vehicle, however, the coverage area is limited to a very specific geographical area.
  • Bluetooth - The GPS tracking device contains a Bluetooth modem, which it uses to connect to a local bluetooth enabled server, or router, to send data to the server. This type of application tends to be used only in very customized applications.
  • Memory Card - The GPS tracking device contains a removable memory card (such as a "Secure Digital (SD)" card). At the end of the day's travels, the memory card is removed from the device and inserted into a reader which downloads the data to the server. The advantage with this solution is that there is no associated cost with the tracking of the vehicle, however, obtaining near real-time tracking on a map is not possible using this solution.
Once the data is received by the server, the modem-id (ie. IMEI number, etc), or other uniquely identifying number, is used to associate the event with an account/device on the server. Once the event has been associated with an account/device, the event is ready for viewing on a report or map.
top

F.8) How do I create my own device communication server (DCS)? [_]
In order for OpenGTS to receive data from a device, a customized "Device Communication Server" (DCS) will need to be implemented that understands the protocol used to communicate with the remote device, and insert received events into the SQL database. A chapter in the "OpenGTS_Config.pdf" installation/configuration document ("Creating Your Own Device Communication Server") describes the starting point for implementing your own device communication server.
top

F.9) Why do the TCP sessions in my DCS module always time-out? [_]
The default behavior of most of the supported DCS modules is to force a TCP session closed after a certain timeout to release/reuse system resources used by the TCP session. This allows greater scalability for supporting a larger number of devices. However, some devices which use TCP mode to send data to the server may require that they always maintain a constant connection with the server (sometimes even if they have no data to transmit). In this case it may be necessary to configure the DCS module to increase the timeout to a larger value. This can be configured in the "dcservers.xml" file (or "dcservers/dcserver_XXXXX.xml" file, where XXXXX is the DCS id) by increasing the TCP session timeout value (for example, '7200' seconds - 2 hours) as follows:
    <Property key="tcpIdleTimeoutMS">1800000</Property>
    <Property key="tcpPacketTimeoutMS">1800000</Property>
    <Property key="tcpSessionTimeoutMS">7200000</Property>
(Note that the timeout values are specified in milliseconds)
This will cause the DCS, for which the above properties were set, to leave the TCP session open for at least 2 hours, before forcing the session to close. (Note: each connected TCP connesion consumes system resources - memory, threads, filehandles, etc. Having many such connected TCP sessions may significantly limit the number of devices which can connect with your server).
top

F.10) Why does my event table contain events dated in the future, and how do I delete them? [_]
Occasionally some GPS tracking devices will send an event to the server with a date/time which is in the future, sometimes a long time into the future. This can be caused by marginal GPS converage. This condition can be prevented by setting the following properties in the "common.conf" file:
     Device.futureDate.action=ignore
     Device.futureDate.maximumSec=86400
The above specification will cause all events to be ignored which are more than 1 day (86400 seconds) into the future.
The following command can be used to obtain a count of all future events for a specific account and device:
     cd $GTS_HOME
     bin/admin.sh Device -account=myaccount -device=mydevice -countFutureEvents=3600
The above command will display a count of events which are more than 1 hour (3600 seconds) into the future. [replace "myaccount" and "mydevice" with the desired account/device id.]
The following command can be used to delete these future events for a specific account and device:
     cd $GTS_HOME
     bin/admin.sh Device -account=myaccount -device=mydevice -deleteFutureEvents=3600
The above command will delete events which are more than 1 hour (3600 seconds) into the future. [replace "myaccount" and "mydevice" with the desired account/device id.]
(make sure you back-up the EventData table before deleting any records)
top

F.11) How do I trim/delete old events from the EventData table? [_]
The following command can be used to obtain a count of all old events for a specific account and device:
     cd $GTS_HOME
     bin/admin.sh Device -account=myaccount -device=mydevice -countOldEvents=-120d
The above command will display a count of events which are more than 120 days old. [replace "myaccount" and "mydevice" with the desired account/device id.]
The following command can be used to delete these old events for a specific account and device:
     cd $GTS_HOME
     bin/admin.sh Device -account=myaccount -device=mydevice -deleteOldEvents=-120d
The above command will delete events which are more than 120 days old. [replace "myaccount" and "mydevice" with the desired account/device id.]
(make sure you back-up the EventData table before deleting any records)
top

F.12) Why does my GPS-based odometer calculation not match my vehicles actual odometer? [_]
Using a GPS-based odometer calculation, which accumulates the distances between successive GPS events, tends to underestimate the actual odometer while the vehicle is moving, because it tends to "straighten out" the roads, since GPS event is typically only sent to the server every few minutes. In some cases it can also overestimate the vehicle odometer while the vehicle is stopped because stray GPS events can cause the accumulated distance to increase even while the vehicle is stopped. If the device itself is capable of obtaining the actual vehicle odometer, this would be the most accurate as it would exactly reflect the actual odometer of the vehicle.
top



G.1) When attempting to build the project, why do I get a "Permission Denied" error? [_]
This error can occur on Linux when building the OpenGTS project as one user (such as "opengts"), when another user (such as "root") happens to own some, or all, of the files in the installation directory. All of the files within the GTS installation directory should be owned by the same user which is building the project. To make sure that all of the files are owned by the proper user, the following command may be executed as "root":
     chown -R opengts:opengts /usr/local/OpenGTS_1.2.3
The "-R" indicates that a recursive ownership change should be performed. The "opengts:opengts" indicates the user and group to which the directory ownership should be changed (change this to your preferred user:group). And "/usr/local/OpenGTS_1.2.3" should be the absolute path of where GTS was installed (change this to the actual directory path where GTS was installed).
(see the Linux "man" page for "chown" for more information on this command - ie. command "man chown")
top

G.2) How do I fix the compile error "... package javax.mail does not exist"? [_]
This compile error occurs when the JavaMail library has not yet been installed. Please refer to the "OpenGTS_Config.pdf" document (section 2.2) for additional information.
top

G.3) How do I fix the login error "Error reading Account"? [_]
When attempting to log-in, if you see an error panel which displays "Error reading Account", this is usually due to the OpenGTS database not having been properly initialized for MySQL (or if MySQL is not currently running). Refer to the "OpenGTS_Config.pdf" document for how to initialize the OpenGTS database for MySQL, then run the "bin/checkInstall.sh" command to check the installation (see "How do I check my OpenGTS installation to see if it was installed properly?" above). If the error persists, then also check the Tomcat log files (ie. "$CATALINA_HOME/logs/catalina.out") to see if it presents any clues regarding why the database error is occurring.
top

G.4) How do I fix the web-page Status 404 error "'private.xml' contains syntax/parsing errors"? [_]
This occurs when the file 'private.xml' has been modified, and XML syntax errors have been introduced into the file. Running the command "bin/checkInstall.sh" should help pinpoint where in the file the XML syntax errors exist. Fix the XML syntax errors, then re-run the "bin/checkInstall.sh" command to see if the XML syntax errors were corrected. Then rebuild/redploy the 'track.war' file.
top

G.5) How do I fix the web-page Status 404 error "The requested resource (/track/Track) is not available"? [_]
This occurs when Tomcat is running, but the 'track.war' file has not been properly deployed to Tomcat's "webapps" directory (ie. "$CATALINA_HOME/webapps/."). Make sure that the OpenGTS "build/track.war" file has been copied to the Tomcat "webapps" directory. Tomcat should then automatically deploy the "track.war" file by unzipping the file and making it available through the web-interface (if Tomcat does not automatically deploy the track.war file, make sure that Tomcat's "autoDeploy" property is set to "true", in the Tomcat "conf/server.xml" file). Also make sure that you are using the proper URL when attempting to access the login page. Assuming that you have installed Tomcat on the server "localhost", using port "8080", the correct URL should be "http://localhost:8080/track/Track".
top

G.6) How do I fix the web-page error "The requested resource (/track/track) is not available"? [_]
URLs are case-sensitive. The correct URL should be specified as "http://localhost:8080/track/Track", with the first letter of the second "Track" capitalized. ("localhost" should be replaced with your appropriate domain name).
top

G.7) After logging-in, selecting any menu option logs me out again. [_]
If everytime you log-in and select a menu option, it always logs you out and displays the login page again, then the most likely reason is that your client browser is not accepting cookies from the server. The GTS server uses client-side cookies to maintain session state. If cookies are disabled, the server is not able to determine that the user has logged-in. To correct this, configure your client browser to accept cookies from the server providing the GTS service.
top

G.8) How do I fix the command-line error "Can't locate .../common.pl in @INC ..."? [_]
This command-line error can occur when executing a Perl command script, and the "GTS_HOME" environment variable is not set, or is set to an invalid location. Set the "GTS_HOME" environment variable to the proper location, and try the command again.
top

G.9) How do I enter command-line options on Windows? [_]
When running a command from the command-prompt on Windows, command options/value pairs must be separated by a colon ":" character as in the following example:
   >  bin\dbConfig.bat -tables:cak
Note that if the "=" character is used to separate the option key from the value (as in "-tables=ca'), Windows may not parse the option/value properly to send to the executing program. (On Linux, using either the "=" or ":" separator character is acceptable).
top



H.1) How do I find out more about other commercially available tracking/telematic features? [_]
You can find additional information regarding the features available in the commercial GTS Enterprise at the following link:
     http://www.geotelematic.com/gts.html
top



Glossary: (terms/abbreviations, and their brief descriptions follow)
  • APN - Access Point Name
    Configuration attributes for a GSM/GPRS modem when used on a specific wireless service provider's network.
    [more information on Wikipedia]
  • AVL - Automatic Vehicle Location
    Generic term used to describe the various types of available GPS tracking applications.
    [more information on Wikipedia]
  • CANBUS - Controller area network
    Vehicle engine-bus communication standard for providing engine diagnostic information.
    [more information on Wikipedia]
    (see also OBD)
  • CDMA - Code Division Multiple Access (also "cdmaOne" and "CDMA2000")
    A cell-phone communication standard.
    [more information on Wikipedia]
    (see also GSM)
  • DCS - Device Communication Server
    Generic term for any GTS service which listens for incoming connections from remote GPS tracking/telematic devices. The purpose of the DCS is to receive incoming packets from a remote GPS tracking/telematic device, parse the received data, and insert the data into the appropriate database tables.
  • DTC - Diagnostic Trouble Code
    A set of SAE fault codes generated by OBD-II (see below) to indicate touble issues with the vehicle. [more information on Wikipedia]
  • Geosynchronous
    Often confused with "Geostationary", a satellite in Geosynchronous orbit means that the satellite is at the same location in the sky at a specific time each day. A satellite with a Geostationary orbit is Geosynchronous, however a satellite with a Geosynchronous orbit is not necessarily Geostationary.
    [more information on Wikipedia]
    (see also Geostationary)
  • Geostationary, also Geostationary Earth Orbit (GEO)
    A satellite in Geostationary orbit means that it is positioned directly above the Earth's equator, and has a orbit period equal to that of the Earth's rotation (and in the direction of the Earth's rotation).
    [more information on Wikipedia]
    (see also Geosynchronous)
  • GNSS - Global Navigation Satellite System
    Generic term for "GPS".
    [more information on Wikipedia]
    (see also GPS)
  • GPRS - General Packet Radio Service
    A packet based mobile data service used for providing Internet connectivity to mobile devices.
    [more information on Wikipedia]
  • GPS - Global Positioning System
    A network of satellites, maintained by the US, which provides location information to ground-based receivers.
    [more information on Wikipedia]
    (see also GNSS)
  • "GPS Drift"
    A phenomenon effecting GPS receivers which gives the appearance that the GPS receiver is moving, sometimes with significant distances within a large area, even though the GPS receiver has remained stationary. The effect is more pronounce when the GPS receiver is located inside or near tall buildings, in canyons, etc.
  • "GPS Logger" or "GPS Data Logger"
    A device used to record periodic GPS tracking information within its internal memory which is intended to be downloaded to a computer at a later time.
  • GSM - Global system for Mobile Communications
    A cell-phone communication standard.
    [more information on Wikipedia]
    (see also CDMA)
  • GTC - GeoTelematic Client
    Commercialized version of the OpenDMTP client application.
  • GTS - GeoTelematic Server / GPS Tracking System
    Generic term to be either of OpenGTS, or the GTS Enterprise tracking systems.
  • J1587
    Engine diagnostic protocol standard (developed by SAE)
    [more information on Wikipedia]
    (see also J1708)
  • J1708
    Engine diagnostic serial communications hardware standard (developed by SAE)
    [more information on Wikipedia]
    (see also J1587)
  • J1939
    Engine diagnostic communications/protocol standard (developed by SAE)
    [more information on Wikipedia]
  • LBS - Location Based Services
    Any service which integrates the geographical location of the service requestor. Typically used in mobile devices.
    [more information on Wikipedia]
  • LEO - Low Earth Orbit
    The area above the surface of the Earth typically extending from 200 to 2000 kilometers.
    [more information on Wikipedia]
  • MEO - Mid/Medium Earth Orbit
    The area above the surface of the Earth typically extending from 2000 to 35000 kilometers.
    [more information on Wikipedia]
  • OBD - On Board Diagnostics
    Generic term for any computer resident in a vehicle which provides engine diagnostic information.
    [more information on Wikipedia]
  • OBD-II - On Board Diagnostic interface, Standard 2
    Standardized type of engine diagnostic interface.
    [more information on Wikipedia]
  • OpenGTS - Open Source GPS Tracking System
    The Open-Source GPS Tracking system available for download from SourceForge.
  • "Real-Time" GPS Tracking
    A "Real-Time" GPS Tracking is essentially any system where the remote tracking device is able to immediately send GPS location information and telematics to the server over some form of transport media, such as GPRS, CDMA, Satellite, WiFi, etc., allowing the GPS data to be available for reporting and mapping shortly after the event was generated on the device. The term "immediate" here is relative, however. There are several external factors which can delay the delivery of the generated GPS event to the server. These factor may include, but are not necessarily limited to, coverage area limitations, wireless network delays, etc. Non-Real-Time GPS Tracking systems would include those that use "GPS Loggers" to collect data which the vehicle in in transit, and where the logged data is captured when the vehicle finally returns to the office or other home-base.
  • SAE - SAE International
    A professional organization which establishes standards in the automotive industry. [more information on Wikipedia]
  • SBAS - Satellite Based Augmentation System
    Generic term for systems which augment/improve the accuracy of calculated GPS locations.
    [more information on Wikipedia]
    (see also WAAS)
  • SMS - Short Messaging Service
    A text-based communications service used on mobile devices.
    [more information on Wikipedia]
  • TCP - Transmission Control Protocol
    A connection/session-based communications transport.
    [more information on Wikipedia]
    (see also UDP)
  • UDP - User Datagram Protocol
    A connectionless communications transport.
    [more information on Wikipedia]
    (see also TCP)
  • WAAS - Wide Area Augmentation System
    Developed by the FAA to improve the accuracy of a calculated GPS location.
    [more information on Wikipedia]
    (see also SBAS)

top
Copyright© 2007-2011 GeoTelematic Solutions, Inc., All rights reserved. SourceForge.net