OpenGTS Installation and Configuration Manual

OpenGTS Installation and Configuration Manual

Copyright © 2007-2014 GeoTelematic Solutions, Inc. All rights reserved

OpenGTS Configuration and Installation Manual

Page 1 of 62

Manual Revision HIstory Rev

Date

Changed

Author

0.0.1

2007/03/25

Initial Release

MDF

0.0.2

2007/03/30

Added information for 'User' table administration

MDF

0.0.3

2007/04/22

Changed top-level ant targets for event, mologogo, and track servlet builds. Minor type changes, and paragraph/page format changes..

MDF

0.0.4

2007/05/06

Added notes for Windows users. All command-line prompts in italic font.. Added note about registering for a Google Map key.

MDF

0.0.5

2007/05/25

Added notes regarding support for Microsoft Virtual Earth. Added notes for Windows users regarding setting installation environment variables.

MDF

0.0.6

2007/06/03

Updated MySQL download links. Include Ant v1.7.0 download links.

MDF

0.0.7

2007/06/13

Added additional myaccount" or "" indicates a value that should be replaced with a specific value matching your requirements. 7) In various locations within this document, the displayed command-line options may command-line parameters which are optional (they only need to be included to for some applications, or to change the default behavior). These optional parameters will be displayed within square-brackets '[' ... ']' (eg. "[-dir=/tmp/gts]") These square-bracket will indicate that the parameter specified within the brackets is optional, depending on the command requirements. The square-brackets themselves are not to be included in the entered command. OpenGTS Configuration and Installation Manual

Page 6 of 62

2) Loading the Prerequisite Packages Important Note: Installation of the OpenGTS prerequisite modules does require at least an intermediate knowledge of how to install and configure systems services such as the Java compiler, Apache Ant, MySQL (or other SQL '. If your changes to not appear after rebuilding and redeploying the "track.war" file, then it may be necessary to force Tomcat to update the "track.war" servlet by following these steps: – Stop Tomcat (ie. "$CATALINA_HOME/bin/shutdown.sh") – Delete the existing "track" servlet (ie. "rm -rf $CATALINA_HOME/webapps/track*") – Deploy the new "track" servlet (ie. "cp $GTS_HOME/build/track.war $CATALINA_HOME/webapps/.") – Restart Tomcat (ie. "$CATALINA_HOME/bin/startup.sh") 5.5) Testing the Installation 5.5.a) Secure web access: Configuration and use of 'https' (ie. SSL) is highly recommended as the URL includes the account password and will be encrypted via 'https', but will be sent in the clear if plain 'http' is used. Instructions for configuring Tomcat to support SSL can be found on the Apache Tomcat website. After building/deploying 'track.war', you should be able to view the login page with a URL similar to the following: http://localhost:8080/track/Track (replace "'localhost:8080" with your own domain name where 'track.war' was installed.) Note that the specification for the URL directory "/track/Track" is case sensitive. Support for reverse-geocoding (turning a latitude/longitude into an address), using services such as Geonames (http://geonames.org) and Google, has also been included. Look for the "ReverseGeocodeProvider" tags in the 'private.xml' file for more information. 5.5.b) Browser Compatibility: The GPS tracking map page in the web interface makes heavy use of JavaScript and HTML formatting. Firefox v3.X.X, Chrome 8.0.X, and Safari 5.0.X, are the platforms targeted, but it also appears to work fine (with some minor differences) on Microsoft IE 6.0/7.0/8.0 (some visual anomalies have been reported with earlier versions of IE). Other browsers have not been fully tested.

5.6) Installing Multiple Versions of "track.war" The URL for accessing the login page is normally as follows: http://localhost:8080/track/Track 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 instance, if you copy the " track.war" file to Tomcat as follows: /usr/local/OpenGTS_1.2.3> cp build/track.war $CATALINA_HOME/webapps/track1.war Then you could access this installed version with the following URL:

http://localhost:8080/track1/Track OpenGTS Configuration and Installation Manual

Page 21 of 62

6) Installing “events.war” The "events.war" (Web-ARchive) runs in a Java Servlet container and works with the SQL DB ') 6.3) Testing the Installation Access the • udpPort="31000" TK10X: • •

tcpPort="31272" udpPort="31272"

Aspicore: • tcpPort="31265" • udpPort="31265" These ports are specified on the "ListenPorts" tag for their respective "DCServer", and are the default ports on which these servers listen for incoming connections from the remote devices. You can change this port by changing the value on this tag attribute. You can also indicate multiple ports by specifying them with comma separators. (ie. 'tcpPort="31000,31100"'). 8.2) Starting the Device Communication Server The "gtsdmtp", "tk10x", or "aspicore" server can be started as follows: /zzz> cd $GTS_HOME /usr/local/OpenGTS_1.2.3> bin/runserver.sh -s server

Where "server" should be replaced with the specific name of the server to start (ie. "gtsdmtp", "tk10x", or "aspicore").


Page 30 of 62

8.2a) Important note regarding ".sh" and ".bat" command files: Commands ending with ".sh" or ".bat" MUST be executed from the OpenGTS installation directory. Attempting to execute these commands from another directory may result in a "ClassNotFoundException" or "NoClassDefFoundError" error, or similar. (This means that you must cd to $GTS_HOME, then execute the command as "bin/") Or, the Perl version of this command can be used without needing to be in the OpenGTS installation directory: /zzz> $GTS_HOME/bin/runserver.pl -s server

On Windows, the command can omit the "-s" and can be entered as follows: C:\> cd \OpenGTS_1.2.3 C:\OpenGTS_1.2.3\> \bin\runserver.bat server

The server will initialize and start listening on the port(s) specified by the "ListenPorts" tag in the "dcservers.xml" file for the specific named DCServer. To change the listen port on the command line, you can add a "-port" argument as follows: /zzz> $GTS_HOME/bin/runserver.pl -s server -port 31123

Or on Windows: C:\OpenGTS_1.2.3\> \bin\runserver.bat server -port:31123

To set listening on port "31123". You can also add the command-line option "-debugMode" to enable debug-level logging. While running in "background" mode, the output logs are stored in the file "$GTS_HOME/logs/server.log". (The file "server.out" is also created by "runserver.pl" to capture output to stdout/stderr, but will typically remain empty). When testing/debugging, you may also start a server "interactively". That is, the server is run in the foreground (ie. not 'backgrounded'), and all logging output is sent to the console instead of the log file. To start a server "interactively", add the option "-i" to the command line, as follows: /zzz> $GTS_HOME/bin/runserver.pl -s server -i

(To stop the server in this mode, simply press 'Control-C') 8.3) Stopping the Device Communication Server When started in "background" mode (ie. Without the "-i" option), a "Process ID" (PID) file is created at "$GTS_HOME/logs/server.pid", which contains the process-id of the backgrounded task. This file is used to stop the server with the command: /zzz> $GTS_HOME/bin/runserver.pl -s server -kill

Where "server" should be replaced with the specific name of the server to start (ie. "gtsdmtp", "tk10x", or "aspicore").


Page 31 of 62

On Linux systems, the Perl command "psjava", included with OpenGTS, can be used to display information regarding which Device Communication Servers are currently runningr: /zzz> $GTS_HOME/bin/psjava PID Parent ------ -----215( 1) 8115( 1) 8120( 1) 8123( 1) 8129( 1)

L 1 1 1 1 1

User -------opengts opengts opengts opengts opengts

Java class/jar ------------------------------------------------------org.apache.catalina.startup.Bootstrap /usr/local/OpenGTS_1.2.3/build/lib/gtsdmtp.jar /usr/local/OpenGTS_1.2.3/build/lib/tk10x.jar /usr/local/OpenGTS_1.2.3/build/lib/aspicore.jar /usr/local/OpenGTS_1.2.3/build/lib/template.jar

This command lists all known running Java processes, with their associated PID (process-id), parent PID, user, and Java class or jar file which is currently running. The " org.apache.catalina.startup.Bootstrap" process indicates that Apache Tomcat is running with the indicated PID. " gtsdmtp", "tk10x", "aspicore", and "template" indicate their respective running Device Communication Servers. 8.4) Adding a New Device Record Once the proper device communication server (DCS) is running, login to an account you wish to have own the device/phone you will be tracking and add a new Device/Vehicle record on the "Device Admin" page. OpenDMTP: OpenDMTP devices typically use the actual "account" and "device" ID's. In this case make sure the account and device id programmed into the OpenDMTP compliant device match the same account and device id created within the OpenGTS system. TK10x: TK102/TK103 devices typically report their unique identifying information using the IMEI number of the modem. On the "Device Admin" page, set the "Unique ID" field to the IMEI value in the format [ tk_12345679012345 ], where "123456789012345" is the IMEI number of the phone (The "tk_" prefix is used to help identify the type of device communication server used to parse the backlog="" portOffset="0" includeDir="dcservers" > ... ... The attributes for the DCServerConfig tag include the following: bindAddress : This attribute specifies the local IP address or host name to which the server will bind. This is useful when the local server has more than one IP address, and needs to send UDP packets back to a client device. If left blank, the server will bind to the default local IP address. backlog : The maximum queue length for incoming connection indications (a request to connect). If a connection indication arrives when the queue is full, the connection is refused. If left blank, or is 0 or less, then the default backlog value will be used. See the class "java.net.ServerSocket" for more information. portOffset : This value is added to any port specification. Unless otherwise needed for specific system requirements, this value should remain "0". includeDir : If the "DCServerConfig" tag contains any "Include" sub-tags, this is the directory that will be search for the included files. OpenGTS Configuration and Installation Manual

Page 39 of 62

An example "Include" tag format is as follows: The attributes for the Include tag include the following: file : This attribute specifies the name of the file to include. The included file must also be a properly formatted DCServerConfig XML file. All device communication servers defined within this included file (as defined by the "DCServer" tags) will be added to the device communication servers defined elswhere in this XML file. Recursive Include directives are not allowed. optional : This attribute specifies whether the include file is required to exist. If this value is "true" and the include file does not exist, and error will be displayed. If this value is "false" and the include file does not exist, then the Include directory is quietly ignored. An example "DCServer" tag format is as follows: 4.0 true true The attribute for the DCServer tag are as follows: name : This attribute is required and specifies the name of the device communication server. The specified name should be unique among all loaded device communication servers. If a name of a device communication server is encountered that has already been defined, the subsequent named DCServer entry will be ignored. "Description" sub-tag: This tag specifies the optional description of the device communication server. "UniqueIDPrefix" sub-tag: This tag specifies the optional "Unique-ID" prefixes that will be used when looking up the device mobile-id in the Device table. In the order specified, the specified prefix is prepended to the mobile-id then the resulting ID is looked-up in the Device table "uniqueID" field. If not found, then the next prefix will be used. The prefix specification "*" means that the mobile-id will be used as-is (without any prepended prefix).


Page 40 of 62

"ListenPorts" sub-tag: This tag specifies the ports on which the device communication server will listen for incoming connections from remote devices. The attribute "tcpPort" specifies the port on which a TCP listener will be started. The attribute "udpPort" specified the port on which a UDP listener will be started. If either "tcpPort" or "udpPort" is blank, or not specified, the the corresponding "listener" will not be started. "Properties" sub-tag: This tag includes "Property" sub-tags which specify runtime properties which can be used to further specify the behavior of the device communication server at runtime. The standard properties that most device communication server recognize are as follows: minimumSpeedKPH : (Double) This property specifies the minimum acceptable GPS-based speed. A speed value beow the value specified by this property will be considered a speed of '0'. This is used to mitigate GPS speed values which can indicate motion, even when the GPS receiver is stationary. estimateOdometer : (Boolean) This property specifies the whether a GPS-based odometer value should be automatically calculated from the valid GPS locations reported by the incoming event. The odometer value of the current event is calculated by determining the distance from the previous event location to the current event location, then adding this distance to the previous odometer value. simulateGeozones : (Boolean) This property specifies whether incoming events should be checked for Geozone arrive/depart occurances. If the current event was found to have arrive, or have departed, from a Geozone (as listed in the Geozone table), then the appropriate event, with the arrive/depart status code, will be generated and inserted into the Event'. 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.)


Page 42 of 62

11) Creating/Modifying Reports OpenGTS comes with a very simple and configurable report generation engine. Reports are comprised of 3 main components: the report layout, the report type="device.detail" > Event Detail

acl.report.eventDetail acl.report.eventSummary


Page 45 of 62

Appendix) A) Support for Microsoft SQL Server Initial support for Microsoft SQL Server has been included with the standard OpenGTS. Microsoft SQL Server 2005 can be downloaded/installed from the following Microsoft webpage(s): http://www.microsoft.com/sqlserver/2005/en/us/express.aspx http://www.microsoft.com/Sqlserver/2005/en/us/express-down.aspx To enable support for SQL Server, modify the file "common.conf" accordingly to turn off support for MySQL, and turn on support for Microsoft SQL Server: # --- Microsoft SQL Server db.sql.provider=sqlserver db.sql.host=localhost db.sql.port=3193 db.sql.dbname=gts db.sql.user=gts db.sql.password=opengts db.sql.url=jdbc:sqlserver://${db.sql.host}:${db.sql.port} db.sql.url.db=${db.sql.url};mologogo". If you wish to use a specific account and device id, you can replace the "?ID=" with "?acct=&dev=".


Page 48 of 62

Appendix) C) Optional Table Columns Various tables within the OpenGTS provide for additional table columns which can be used for special application requirements. These table columns can be enabled by setting specific propery values within one of the available ".conf" files (ie. "config.conf", etc). The following section describes the various optional table columns, and the property name that can be used to enable these columns. After adding the specified property to the chosen ".conf" file, the tables will need to be updated with the newly added columns. To update the columns within the various

Or on Windows: cd %GTS_HOME% bin\trackstick.bat -account:ACCOUNT -device:DEVICE -tmz:TIMEZONE -csv:"2011-03-26 04.05.10.csv"

Where "ACCOUNT" and "DEVICE" are the account/device to which the imported data will be applied, and "TIMEZONE" is the timezone of the times represented within the CSV file. (Note: "-a:ACCOUNT -d:DEVICE" may also be used to specify the account and device). Set the "-csv" file to the name of the file exported from the "Trackstick Manager". The command will then output header informaton indicating the values of the event filtering as follows (the values displayed below are only an example of the values that may be displayed): --------------------------------------------Account : demo Device : demo Debug Mode : false Default Timezone : GMT Min Speed Km/H : 0.0 Min Heading Chg : 15.0 Min Moving Sec : 120 Min Dormant Sec : 1800 Estimate Odometer: true ---------------------------------------------

Followed by a display of each event parsed and inserted into the EventData table: ... --------------------------------------------Include Event: true - Start Event (kph) Timestamp : [1301012280] Thu Mar 24 17:18:00 PDT 2011 Status : Start GeoPoint : 39.25054/-142.33508 Altitude : 562.7 meters (1846.1 feet) Speed : 4.0 km/h (2.5 mph) heading 337.6 (North) Temp : 28.4 C (83.1 F) Odometer : 0.0 km (0.0 miles) Stored Event : [0xF111] Start


Page 61 of 62

--------------------------------------------Include Event: true - Periodic Moving Event Timestamp : [1301012520] Thu Mar 24 17:22:00 PDT 2011 Status : InMotion GeoPoint : 39.25052/-142.33528 Altitude : 564.5 meters (1852.0 feet) Speed : 0.0 km/h (0.0 mph) heading 62.0 (NorthEast) Temp : 28.9 C (84.0 F) Odometer : 0.0 km (0.0 miles) Stored Event : [0xF112] InMotion --------------------------------------------...

If the option "-nosave" is added to the command-line, then the data parsing will occur, but the EventData records will not be stored, nor will any odometer information be updated in the Device record. Using "-nosave" is usually recommended for the initial check of the data to make sure that the timezone has been specified properly (otherwise the time may be off by several hours). E.3) Capturing the Device Temperature Information: The temperature information can also be stored into the EventData table, provided that the following optional "ThermoFieldInfo" EventData field set has been enabled (configured in "config.conf"): startupInit.EventData.ThermoFieldInfo=true Then update the EventData table columns: cd $GTS_HOME bin/dbAdmin.pl -tables=ca The "reports.xml" file can then be modified to display the temperature values on one of the EventDetail reports.


Page 62 of 62