OpenGTS_Config.pdf

5/25/2018 OpenGTS_Config.pdf

1/60

OpenGTSInstallation and Configuration

Manual

Copyright 2007-2013 GeoTelematic Solutions, Inc.

ll rights reser!e"

OpenGTS Configuration and Installation Manual Page 1 of 60


2/60

Manual Revision HIstory

Rev Date Changed Author

0.0.1 2007#03#2$ Initial %elease &'(

0.0.2 2007#03#30 ""e" in)ormation )or *+ser* tale a"ministration &'(

0.0.3 2007#0#22 Change" top-le!el ant targets )or e!ent, mologogo, an" trac ser!let uil"s. &inor type changes, an" paragraph#page )ormat changes.. &'(

0.0. 2007#0$#0/ ""e" notes )or in"os users. ll comman"-l ine prompts in i tali c )on t. . ""e" no te aout register ing )or a Goog le &ap ey. &'(

0.0.$ 2007#0$#2$ ""e" notes regar"ing support )or &icroso)t irtual arth. ""e" notes )or in"os users regar"ing setting installation en!ironment !ariales. &'(

0.0./ 2007#0/#03 +p"ate" &yS45 "onloa" lins. Inclu"e nt !1.7.0 "onloa" lins. &'(

0.0.7 2007#0/#13 ""e" a""itional "ataase a"ministration "ocumentation. ""e" note regar"ing installing a 6erl interpreter on in"os. (ie" minor typos. &'(

0.0.8 2007#0/#30 ""e" a""itional lin )or &yS45 in96 "onloa". &'(

0.0.: 2007#07#1 ""itional comments regar"ing ;a!amys?l.@= to =ser!er>"mtp.@=.

&'(

0.0.10 2007#07#27 %emo!e" re)erence to the creation o) "e)ault account =open"mtp=, "e!ice =moile=, hen initialiAing the "ataase ith =init"=. ""e" comman"shich are e?ui!alent to running =init"=. ""e" comments regar"ing customiAation o) the =eapp.con)= ser!let runtime con)iguation )ile.

&'(

0.0.11 2007#08#0: ""e" some a""itional comments regar"ing the *!ents* ser!let. Tale a"min comman"s change" )rom =in#a"minBTale.sh ...= to =a"min.shBTale ...=. '&T6 ser!er startup script change" to =runser!er.sh -s gts"mtp=.

&'(

0.0.12 2007#0:#1/ ""e" comments regar"ing atch )ile use on in"os. ""e" notes regar"ing using *template* an" *gprmc* )or creating custom "e!ice ser!ers.. &'(

0.1.1 2007#11#30 ""e" a""itional note on using *""min.pl* to a"" missing tale columns. &inor tet changes ma"e. &'(

0.1.2 2008#02#0/ ""e" comment to prere?uisites regar"ing the installation o) Tomcat on 5inu. &'(

0.1.3 2008#02#17 ""e" section on InternationaliAation#5ocaliAation. ""e" in)ormation regar"ing the implementation o) "e!ice communication ser!ers. &'(

0.1. 2008#02#20 ""e" a""itional comments regar"in con)iguration o) Tomcat on 'eian#+untu &'(

0.1.$ 2008#03#28 ;a!a S'D $.0 is no re?uire" to uil" EpenGTS. &'(

0.1./ 2008#0#11 ""e" a section on installation testing &'(

0.1.7 2008#0$#1 +p"ate" =Compile= section to inclu"e =ant all=. ""e" a""itional comments to 5ocaliAation section.. &'(

0.1.8 2008#0/#20 +p"ate" location o) *pri!ate.ml* )ile. +p"ate" the "onloa" lin in)ormation )or !arious mo"ules. &'(

0.1.: 2008#07#08 ""e" a""itional comments regar"ing uil"ing the eample *template* ser!er. &'(

0.1.10 2008#07#27 ""e" note regar"ing *inF"Con)ig.at* comman" a!ailale )or in"os users. ""e" in)ormation regar"ing customiAation o) map 6ushpins.. &'(

0.1.11 2008#10#1/ arious minor changes &'(

0.1.12 2008#12#01 +p"ate" the *'ataase "ministration* section &'(

0.1.13 2008#12#1/ +p"ate pache Tomcat "onloa" +%5 &'(

0.1.1 200:#02#01 &iscellaneous up"ates &'(

0.2.0 200:#0#02 ""e" &ac ES 9 con)iguration in)ormation. %earrange" chapters. ""e" a""itional *"e!ice communication ser!er* start#stop in)ormation. &'(

0.2.1 200:#0$#2 ""e" section on installing &oto'&T6 &'(

0.3.0 200:#07#01 ""e" notes regar"ing =e!ents.ar= support )or eporting G69 )ormatte" e!ents. ""e" section on =Creating#&o"i)ying %eports=. ""e" notes

on !ali"ating 5ocalStrings )iles.

&'(

0.3.1 200:#08#02 ""e" a""itional comments regar"ing =e!ents.ar= use )or Google arth map up"ates, note regar"ing customiAing the loog-an"-)eel, etc. &'(

0.3.2 200:#08#23 ""e" comments regar"ing running =runser!er.at= on in"os. +p"ate" Tomcat !ersion to $.$.28. &'(

0.3.3 200:#10#30 ""e" *-sen"&ail* option to *checInstall* comman". &'(

0.3. 2010#0/#18 +p"ate" in)ormaton regar"ing *runser!er*, starting#stopping "e!ice communication ser!ers, an" using *psa!a*. ""e" in)ormation regar"ing the"e!ice communication ser!ers runtime con)iguration ="cser!ers.ml= )ile.

&'(

0.3.$ 2010#07#08 ""e" GTS system architecture section. +p"ate" !arious pre-re?uisite lins. +p"ate" starting#stopping 'CS. &'(

0.3./ 2010#0:#10 ""e" a""itional ='e!ice= a"min options. ""e" =Eptional Tale Columns= &'(

0..1 2011#03#08 6lace" 6rere?uisite an" EpenGTS installations into separate chapters. %enumere" chapters. ""e" a""itional in)ormation on the =gprmc= http-ase" "e!ice communication ser!er.

&'(

0..2 2011#0#01 ""e" Tracstic CS "ata import in)ormation H!2.3.2. (ie" minor typos, etc. &'(

0..3 2011#08#21 &isc changes. ""e" ;SEJ )ile )ormat to =e!ents.ar= "escription. +p"ate ;a!a&ail "onloa" ersion#+%5. ""e" in)ormation on starting theTD10 'CS mo"ule.

&'(

0.. 2012#12#27 Inc lu"e" ta le op tiona l ) iel" names.

0..$ 2013#KK#KK +p"ate lins.



3/60

OpenGTS Installation/Configuration

Contents:

1 Introduction11 Supported !latfor"s1# S$ste" Architecture1% !lanned &nhance"ents1' Docu"ent Conventions

# (oading the !rere)uisite Modules#1 *ava Co"piler## *avaMail Support#% Apache +Ant+ ,uild Tool#' Apache +To"cat+ Servlet Container#- M$S.( Dataase !rovider#0 M$S.( *D,C Driver

% Installing/Co"piling the OpenGTS Source%1 n2ipping/Installing the OpenGTS Source%# Setting the &nviron"ent 3ariales%% Co"piling the Supporting GTS (irar$ 4iles

' Initiali2ation and Installation Testing'1 Initiali2ing the S.( Dataase Tales

'# Testing the Installation'% (oading the Sa"ple Data'' Creating the +s$sad"in+ Account

- Installing 5trac67ar8-1 Configuring the 57eappconf8 4ile-# Configuring the Availale Reports-% Configuring the !rivate (ael (oo6 and 4eel-' Co"piling/Installing the 5trac67ar8 Servlet-- Testing the Installation-0 Installing Multiple 3ersions of +trac67ar+

0 Installing 5events7ar801 Configuring the 57eappconf8 file0# Co"piling/Installing the 5events7ar8 *ava Servlet0% Testing the installation

9 Dataase Ad"inistration91 Creating/&diting Accounts9# Creating/&diting sers9% Creating/&diting Devices9' General Dataase Ad"inistrative 4unctions

Installing/Starting the OpenDMT!; T; and Aspicore DCS Modules1 Configuring the +dcservers>"l+ 4ile# Starting the Device Co""unication Server% Stopping the Device Co""unication Server' Adding a ?e7 Device Record

@ Creating our O7n Device Co""unication Server@1 BTT!,ased Device Co""unication Servers using the +gpr"c+ servletE

@11 Configuring the +gpr"c+ Servlet

@1# Default +gpr"c+ Configuration@1% ,uilding the +gpr"c+ Servlet

@# Ra7 Soc6et,ased Device Co""unication Server@#1 Starting the Device Co""unication Server@## Stopping the Device Co""unication Server

@% Runti"e FM( Configuration 4ile



4/60

OpenGTS Installation/Configuration

Contents: continuedE

1= Internationali2ation/(ocali2ation1=1 Supporting a ?e7 (anguage1=# Changing the Displa$ed (anguage

11 Creating/Modif$ing Reports111 Report (a$out11# Report Data Iterator11% Report Definition FM(11' Availale Report Specifications

Appendi>:AE Support for Microsoft S.( Server,E Support for Mologogo Capale !honesCE Optional Tale Colu"nsDE Installing MotoDMT!&E I"porting G!S &vents fro" the Trac6Stic6 Mini



5/60

1E Introduction

OpenGTSHOpenSource G6S Tracing System is inten"e" to pro!i"e a generic ac-en" e-ase" ser!ice )or?uerying an" !ieing G6S relate" "ata. It is "esgine" to operate in"epen"ently o) any speci)ic G6S tracing "e!ice oprotocol, ut comes ith support )or se!eral "e!ice protocol )ormats Hsuch as OpenDMT!- Epen Source 'e!ice&onitoring an" Tracing 6rotocol L httpM##.open"mtp.org.

It is speci)ically "esigne" )or use in small to me"ium siAe" commercial enterprises ishing to tae a"!antage o) G6Stracing )or =)leets= o) !ehicles. Noe!er, OpenGTSis highly con)igurale an" scalale to larger enterprises as ell.

En the ser!er si"e, OpenGTSis "esigne" to e "e!ice an" protocol in"epen"ent. In or"er to use the )eatures o)OpenGTS, a speci)ic "e!ice#protocol communication ser!er ill nee" to e implemente" to communicate ith theremote "e!ice an" place the "ata in the S45 "ataase. OpenGTSships ith support )or OpenDMT!HhttpM##.open"mtp.org so that OpenDMT!compliant "e!ices ill e rea"y to imme"iately utiliAe the ser!ices o)OpenGTS. custom "e!ice communication ser!er can also e implemente" using the inclu"e" eample ser!er sourco"e. See the chapter title" =Creating Oour En 'e!ice Communication Ser!er= )or more in)ormation.

En the e-inter)ace si"e, the user presentation is easily customiAale to )it the in"i!i"ual "esire" moti). &enu optionan" )eatures are also easily customiAale to )it speci)ic re?uirements.

The source co"e )or the EpenGTS proect may e "onloa"e" )rom Source(orge at the )olloing linM

httpsM##source)orge.net#proects#opengts#)iles#H5icense" un"er the pache 5icense ersion 2MhttpM##.apache.org#licenses#5ICJS-2.0

DISC(AIM&R:OpenGTS/OpenDMT! "ust not e used for an$ illegal activities The providers of this proect assu"e noresponsiit$ for an$ illegal activities that "a$ e conducted $ users of this soft7are

11E Supported !latfor"s

OpenGTSis completely implemente" in ;a!a an" shoul" run )ine on any system that )ully supports the ;a!a %untimen!ironment. Noe!er, this implementation "oes re?uire an S45 "ataase ser!er, an" is there)ore also limite" tosystems on hich your chosen S45 "ataase runs. See the respecti!e S45 "ataase support esite )or theirsupporte" systems Hie. )or &yS45 see =httpM##.mys?l.org= L hich has een teste" ith OpenGTSon 5inu, &acES 9, (ree


6/60

1%E !lanned &nhance"ents

OpenGTSis alays e!ol!ing, an" ne )eatures are continually eing ma"e a!ailale. Nere are some generalcategories o) the )eatures that are in the planning or implementation stageM

""itonal map )eatures. ""itional reports.

GTS &nterpriseas uilt on OpenGTSan" has se!eral a""itional )eatures a!ailale as ell Hmore in)ormationregar"ing the GTS nterprise can e )oun" at =httpM##.geotelematic.com#gts.html=M

Support )or se!eral Pcommercial useQ mapping ser!ice pro!i"ers. Support )or many a""itional remote G6S tracing "e!ices. ""itional reporting options. Simple *%ules* engine to sen" noti)ications ase" on criteria )rom incoming e!ents Henhance" !ent Joti)icatio

%ules ngine is also a!ailale.

Contact us regar"ing the a!ailaility o) these an" other )eatures at =opengtsRgeotelematic.com=.

1'E Docu"ent Conventions

In or"er to pro!i"e a generic installation#con)iguration "ocument that co!ers !arious systems types Hie. in"os 96,&ac ES 9, an" the !arious 5inu "istriutions, an" the !arious !ersions o) the OpenGTSsystem, the )olloing

con!entions an" assumptions ha!e een a"opte" ithin this "ocumentM

1 This "ocument ill assume that the target operating system is 5inu-ase". (or other operating system typesthe appropriate path separators an" "irectory speci)ications ill nee" to e use" that match the re?uirements your speci)ic operating system. n!ironment !ariale speci)ication may also !ary eteen operating systems(or instance, to "e-re)erence the *A3AHBOM&en!ironment !airale, =%JAVA_HOME%= oul" e speci)ie" on in"os system, hile =$JAVA_HOME= is speci)ie" on 5inu an" &ac ES 9.

2 This "ocument ill assume that the "irectory in hich OpenGTSill e installe" is =/usr/local/=. I) you e installing OpenGTSin a "i))erent "irectory, you ill nee" to replace the "irectory re)erences in this "ocumeto the "irectory in hich OpenGTSas installe".

3 OpenGTShas a )re?uent release sche"ule. (or consistency, this "ocument ill assume that the !ersion o)OpenGTSto e installe" is =OpenGTS_1.2.3=. So re)erences to =OpenGTS_1.2.3= ithin this "ocumentshoul" e replace" ith the actual name an" !ersion o) OpenGTSthat you ill e installing.

En !arious comman" line eamples, you may see the "irectory speci)ication =/zzz=. This speci)ication is sima placehol"er name representing some current "irectory on your system, an" not a literal "irectory nameeisting on your system.

$ In !arious locations ithin this "ocument, comman"-line options are speci)ie" as =-argNae!"alue=, here=argNae= is the name o) a comman"-line argument, an" ="alue= is the !alue to e assigne" to the commanine argument. hen entering comman"s in in"os at a 'ES comman" prompt Hsuch as hen using the=.#a= !ersion o) the comman"s, comman" arguments such as -rootUser=rootMSTeither e enclosein ?uotes, as in "-rootUser=root", or e speci)ie" ith a colon instea" o) an e?ual-sign, as in-rootUser:rootHpre)erre".

/ In !arious locations ithin this "ocument, the "isplaye" comman"-line options may inclu"e eample !alues thare to e replace" ith !alues speci)ic to your re?uirements. (or eample, a comman"-line option in"icatingaccount may e speci)ie" as =-accoun!myaccount= or as =-accoun!&accoun>=. In this case theargument name =-accoun!= may e taen literally, hile =myaccount= or =&accoun>= in"icates a !aluethat shoul" e replace" ith a speci)ic !alue matching your re?uirements.

7 In !arious locations ithin this "ocument, the "isplaye" comman"-line options may comman"-line parametershich are optional Hthey only nee" to e inclu"e" to )or some applications, or to change the "e)ault eha!ior.These optional parameters ill e "isplaye" ithin s?uare-racets ** ... ** Heg. ='-()r!/p/gs*= Theses?uare-racet ill in"icate that the parameter speci)ie" ithin the racets is optional, "epen"ing on thecomman" re?uirements. The s?uare-racets themsel!es are not to e inclu"e" in the entere" comman".

http://www.geotelematic.com/gts.htmlhttp://www.geotelematic.com/gts.htmlmailto:[email protected]://www.geotelematic.com/gts.htmlmailto:[email protected]


7/60

#E (oading the !rere)uisite !ac6ages

I"portant ?ote:Installation o) the OpenGTSprere?uisite mo"ules "oes re?uire at least an interme"iate nole"ge o) ho to install ancon)igure systems ser!ices such as the ;a!a compiler, pache nt, &yS45 Hor other S45 "ataase ser!er, pacheTomcat Hor other ser!let container, an" other relate" technologies.

Compiling OpenGTSre?uires that the )olloing pacages or applications e installe", con)igure", an" running on thelocal systemM

#1E *ava Co"piler

6acageM ;'D 7 +p"ate 99 Hthe GTS also currently ors on =;'D / +p"ate 99='onloa"M httpM##.oracle.com#technetor#a!a#a!ase#"onloa"s#in"e.htmlJotesM download just JDK 7 Update XX

Note:To avoid potential headaches trying to get the OpenGTS code to compile,make sure you are using the "unMi!rosystems" version o the Java !ompiler. The 'other' versions have problems compiling this code.

Ater installing the !ava compiler, chec" your version with the ollowing command:java -version

#a"e sure it says $Java(TM)$ and $Java HotSpot(TM) Client VM$.

?ote:&ae sure that the ;a!a S'D installation *#)n* "irectory has een a""e" to the !ATBen!ironment !ariale Hsee elo(ailing to "o so may result in compiler errors.

IM!ORTA?T ?OT&:Onl$ install the *D< co"ponent; do not install the separate *R& co"ponent The *D< alread$ contains a *R&co"ponent; and the *D< is needed to co"pile the *ava code Baving oth the *D< and *R& installed on $ours$ste"; "a$ cause so"e confusion 7hen it co"es to co"piling and running the application

#1aE Mac OS F users:The ;a!a ;'D !1./.0 is liely alrea"y installe" on your &ac ES 9 system, so it may not e necesary to"onloa" another copy o) the ;a!a ;'D. Oour installe" !ersion o) the ;a!a ;'D !.1./.0 may e in the )olloing"irectoryM /S&se/,)#rar&/raeors/Ja"aVM.0raeor/Vers)ons/1../Hoe

#1E 4edora/CentOS (inu> users:The (e"ora#CentES ;a!a =Epen;'D 'e!elopment n!ironment= can e installe" an" use" instea" o)"onloa"ing the ;'D/ "irectly )rom Sun &icrosystems. The comman" to install the ;a!a 1./.0 "e!eloperen!ironment on (e"ora#CentES is as )ollos Hmust e *root* to installM &u )nsall 4a"a-1..-open4(-(e"el

The JAVA_HOMEen!ironment !ariale shoul" then e set to the )olloingM

e5por JAVA_HOME!/usr/l)#/4"/4a"a-1..-open4(Hmae sure that =/usr/l)#/4"/4a"a-1..-open4(= matches the name o) the installe" ;a!a ;'D"irectory

It is recommen"e" to also create a =4a"a= symolic lin in the =/usr/local/= "irectory hich points to the;a!a ;'D installation, as )ollosM

c( /usr/local ln -s $JAVA_HOME 4a"a



8/60

##E *avaMail Support

6acageM Sun ;a!a&ail 6I H!1.$.0+%5M httpsM##a!a.net#proects#a!amail#pages#NomeUipM 4a"a5.a)l.4ar

The ar )ile =4a"a5.a)n.4ar= )rom this "onloa" )ile shoul" e installe" into the ;a!a eten"e" lirary "irectory as)ollos H*root* access re?uire"M

c( /p/ cp 4a"a5.a)l.4ar $JAVA_HOME/4re/l)#/e5/.

Hhere =/p/= is the "irectory here =4a"a5.a)l.4ar= as unAippe"

##aE Mac OS F users:En &ac ES 9, the ;a!a eten"e" lirary "irectory may e at the )olloing locationM $JAVA_HOME/l)#/e5

This ill allo the ;a!a&ail "ri!er to e a!ailale to all running ;a!a co"e, an" Tomcat ser!let en!ironments.HImportant Note# make sure the permissions on the li$rary %ar iles are &orld'reada$le

#%E Apache +Ant+ ,uild Tool

6acageM nt !1.:.0'onloa"M httpM##ant.apache.org#in"onloa".cgiUipM httpM##archi!e.apache.org#"ist#ant#inaries#apache-ant-1.:.0-in.Aip

?ote:&ae sure that the nt installation *#)n* "irectory has een a""e" to the !ATBen!ironment !ariale Hsee elo.

#%aE Mac OS F users:The latest nt !ersion is liely alrea"y installe" on your &ac ES 9 system, so it may not e necesary to"onloa" another copy o) the pache nt. Oour installe" !ersion o) pache nt may e in the )olloing"irectoryM

/usr/s6are/an

#%E 4edora/CentOS (inu> users:The (e"ora#CentES pache =nt= can e installe" an" use" instea" o) "onloa"ing the =nt= installation"irectly )rom pache. The comman" to install the =nt= uil" en!ironment on (e"ora#CentES is as )ollosHmust e *root* to installM &u )nsall an



9/60

#'E Apache +To"cat+ Servlet Container

6acageM pache Tomcat !7. ser!let container+%5M httpM##tomcat.apache.org#"onloa"-70.cgiUipM httpM##.apache.org#"ist#tomcat#tomcat-7#!7.0.0#in#apache-tomcat-7.0.0.Aip

?ote:I) your !ersion o) 5inu "istriution alrea"y comes ith a !ersion o) Tomcat installe", it is still highl$ reco""endedthyou start ith a !ersion o) Tomcat "onloa"e" "irectly )rom the pache esite. This ill eliminate or re"uce any

permissions or classpath prolems that may e encountere". Then hen e!erything is up an" oring properly, i) youchoose to "o so, you can go ac an" install OpenGTSin the !ersion o) pache Tomcat that as shippe"#installe" iyour 5inu "istriution.

#'aE (inu> users installing the do7nloaded Apache To"cat:It is recommen"e" that the manual Tomcat installation e installe" in the =/usr/local/= "irectory H*root*access ill e re?uire" to install into this "irectory.

The CATALINA_HOMEen!ironment !ariale shoul" then e set to the )olloingM $ e5por 7ATA,8NA_HOME!/usr/local/apac6e-oca-5.55.55

here =/usr/local/apac6e-oca-5.55.55= matches the name o) the Tomcat installation "irectory.

It is recommen"e" to also create a =oca= symolic lin in the =/usr/local/= "irectory hich points to the

Tomcat installation, as )ollosM c( /usr/local

ln -s $7ATA,8NA_HOME oca

ithin the Tomcat installation *in* "irectory Hie. =$7ATA,8NA_HOME/#)n=, mae sure the eecutepermissions it is set on all =.s6= )iles. I) not set, the )olloing comman" ill set the eecution itM $ c( $7ATA,8NA_HOME/#)n $ c6o( a95 :.s6I) the eecute it is not set on these )iles, Tomcat =sarup.s6= an" =s6u(on.s6= comman"s may not eale to eecute.

#'E Deian/untu users using a preinstalled Apache To"cat:e recommen" "onloa"ing the Tomcat !ersion "irectly )rom pache, hoe!er, i) you still plan on using the'eian#+untu installe" !ersion o) Tomcat, an" your Tomcat log )iles are )illing up ith=a!a.security.ccessControlception= messages hen attempting to access System properties, then youmay nee" to create#e"it a Tomcat policy )ile in the =/ec/oca/pol)c&.(= "irectory that contains the)olloing in)ormation Hor similarM

gran co(e;ase caal)na.6oe?/e#apps/rac/@E;-8N/-< > per)ss)on 4a"a.u)l.roper&er)ss)on


10/60

#-E M$S.( Dataase !rovider

6acageM &yS45 !$.9.9+%5M httpM##"e!.mys?l.com#"onloa"s#mys?l#

#-aE indo7s users:En in"os, "onloa"#install the )olloing )ileM &sDl-essen)al-.X.XX-2-)nF.s)here =&sDl-essen)al-.X.XX-2-)nF.s)= is the name o) the latest &yS45 installation )orin"os.

#-E Mac OS F users:&yS45 can e "onloa"e" in the ES 9 pacage )ormat )rom the )olloing locationMM httpM##"e!.mys?l.com#"onloa"s#mys?l#$.$.htmlV"onloa"s

#-cE 4edora/CentOS (inu> users:The (e"ora#CentES =&yS45= can e installe" an" use" instea" o) "onloa"ing the =&yS45= installation"irectly )rom &yS45. The comman" to install =&yS45= on (e"ora#CentES is as )ollos Hmust e *root* toinstallM &u )nsall &sDl-ser"er &sDl

?ote:&ae sure that the &yS45 installation =#)n= "irectory has een a""e" to the !ATBen!ironment !ariale.

#0E M$S.( *D,C Driver

6acageM &yS45 Connector#; !$.1.99 ;' users:The (e"ora#CentES &yS45 ;'


11/60

%E Installing/Co"piling the OpenGTS Source

I"portant ?ote:Installation o) the supporte" OpenGTS)eatures "oes re?uire at least an interme"iate nole"ge o) ho to install an"con)igure systems ser!ices such as the ;a!a compiler, pache nt, &yS45 Hor other S45 "ataase ser!er, pacheTomcat Hor other ser!let container, an" other relate" technologies.

%1E n2ipping/Installing the OpenGTS Source

En 5inu systems, it is recommen"e" that the OpenGTSAip )ile e unAippe" an" installe" in the =/usr/local/="irectory. En in"os, it can e installe" in any con!enient "irectory, such as in the root partition o) =7==.

(or the purposes o) this "ocument, e ill assume that the target operating system is 5inu-ase", an" that the locathere OpenGTSill e installe"#unAippe" is =/usr/local/OpenGTS_1.2.3/= HJoteM you may nee" to chooseanother installation "irectory i) you "o not ha!e *root* access on the target system. "ust the )ile#path separators an"comman"s as necessary )or your particular operating system, an" chosen installation "irectory.

Install the OpenGTS source code:+nAip the OpenGTSpacage in =/usr/local/= Hthis ill nee" to e "one as the =roo= user, or other con!enient"irectory Hon in"os, choose a "irectory here you oul" lie this pacage to e place" L pre)erraly a path hich"oes not contain any eme""e" spaces. (or instance, i) the OpenGTSpacage to e installe" is=OpenGTS_1.2.3.)p=, then the comman" to unAip the pacage oul" eM

/zzz>c( /usr/local

/usr/local>su roo/usr/localun)p /p/OpenGTS_1.2.3.)p/usr/localc6on -I user=group OpenGTS_1.2.3/usr/locale5)/usr/local>e5por GTS_HOME!/usr/local/OpenGTS_1.2.3

Hthe ao!e assumes that OpenGTS_1.2.3.)pas "onloa"e" to =/p/=. I) the OpenGTSAip )ile as "onloa"into a "i))erent "irectory, mo"i)y the ao!e "irectory location an" "onloa"e" )ile name accor"ingly. lso, replace theuser name =user=, an" group name =group=, ao!e ith the name o) the user=groupthat you ish to ha!e on the

OpenGTSinstallation.

Hlso note that the =/zzz= "irectory name ao!e is ust a placehol"er name hich represents any current "irectory thamay e in e))ect e)ore the =c(= comman" is issue".

%#E Setting the &nviron"ent 3ariales

The )olloing en!ironment !ariale shoul" e set to the installation "irectory o) the correspon"ing pacage orapplicationM

JAVA_HOMEL The ;a!a ;'D H?OTthe ;% installation "irectory. ANT_HOMEL The pache nt installation "irectory. CATALINA_HOMEL The pache Tomcat installation "irectory. GTS_HOMEL The EpenGTS installation "irectory.

http://c/http://c/http://c/


12/60

%#aE indo7s users:The location o) the installation *#)n* "irectories )or the ;a!a S'D, nt, an" S45 "ataase ser!er installations,nee"s to e a""e" to the comman" eecution !ATBen!ironment !ariale Hi) the installation process has notalrea"y a""e" them to the !ATB!ariale.

n!ironment !ariales can e set manually in a comman"-prompt ith the PsetQ comman", as in the )olloingeampleM C:\>set GTS_HOME=C:\OpenGTS_1..!%hen setting environment variables, (uotes should not be used to enclose an installation directory, even i thedirectory contains embedded spaces&

n!ironment !ariales are re)erence" y enclosing them in *%*. (or instance, a)ter setting the en!ironment!ariale JAVA_HOMEto point to your ;'D installation "irectory, this en!ironment !ariale oul" e"ere)erence" as PJAVA_HOMEQ.

The )ile path separator is the ac-slash character PQ. So, hile on 5inu a )ile#"irectory coul" e re)erence"as P#JAVA_HOME$%re$&'($e)t$.Q, on in"os this same "irectory oul" e re)erence" as PJAVA_HOME\%re\&'(\e)t\.P

The ao!e en!ironment !ariales can e set to e automatically "e)ine" hen starting a comman"-promptthrough the =S$ste" !roperties= in"o as )ollosM %ight-clic on =M$ Co"puter= an" select =!roperties=, the =S$ste" !roperties= in"o ill "isplay.

Select the =Advanced= ta, then press the =&nviron"ent 3ariales= utton. In the =S$ste" 3ariales$section, a"" the )olloing !arialesM

ariale JameM *A3AHBOM& %re(uired or building OpenGTS, and running Tomcat& alueM %The location o your !A)A DK*nstallation +older, N()the !-&

ariale JameM A?THBOM& alueM %The location o your Ant *nstallation +older&

ariale JameM CATA(I?AHBOM& %re(uired or building OpenGTS& alueM %The location o your Apach Tomcat *nstallation +older&

ariale JameM GTSHBOM&alueM %The location o your OpenGTS *nstallation +older&

%uotes should N()be used to enclose an installation directory or these environment variablespeciications, even i the directory contains embedded spaces&

6re)i the )olloing to the =!ath= en!ironment !ariale in the =S$ste" 3ariales$section Hcreate a ne

=!ath= !ariale i) one "oes not alrea"y eistM.C%JAVA_HOME%#)nC%MSK,_HOME%#)nC%ANT_HOME%#)nC%uotes may be added to the /AT0 variable i necessary&

Clic =O users:It is recommen"e" that the )olloing symolic lins e create" ithin the =/usr/local/= "irectory hich pointto their correspon"ing *home* "irectories Hsip a gi!en symolic lin i) it has alrea"y een create"M c( /usr/local ln -s $JAVA_HOME 4a"a ln -s $7ATA,8NA_HOME oca ln -s $GTS_HOME gs



13/60

%%E Co"piling the Supporting GTS (irar$ 4iles

%%aE !reco"piled 3ersions of GTS:I) you ha!e recei!e" a pre-compile" !ersion o) the GTS pacage, this section may e sippe" Hhoe!er youmay reuil" the !arious ser!lets an" ar )iles i) you ish to mae any changes to the runtime con)iguratione)ore "eployment.

Co"pile the OpenGTS lirar$ +ar +and servlet +7ar+ files:

*c(* into the OpenGTSinstallation "irectory an" compile the ar )iles, an" ser!let ar )iles, using the supplie" nt=#u)l(.5l= scriptM

/usr/local>c( $GTS_HOME/usr/local/!pen"TS#$%&%'>an all

This ill uil" se!eral ar )iles, an" ar )iles, in the =$GTS_HOME/#u)l(/= "irectory, inclu"ingM

=l)#/gsu)ls.4ar= L This ar contains the ase utilities an" " access tools. =l)#/gs(#.4ar= L This ar contains the "ataase access utilities an" tale "e)inition. =l)#/gs(p.4ar= L This ar contains the S45 " "atastore rappers aroun" the OpenDMT!ser!er. =l)#/ools.4ar= L This ar contains miscellaneous system chec an" a"ministrati!e tools. =rac.ar= L This =ar= )ile He-archi!e contains the e-inter)ace *Trac* ser!let.

=e"ens.ar= L This =ar= )ile contains the e accessile !ent'ata access ser!let. =ologogo.ar= L This =ar= )ile contains the &ologogo "e!ice ser!let. =gc11.ar= L This =ar= )ile contains support )or the Sana! GC-101 "e!ice. =gprc.ar= L This =ar= )ile contains a ser!let support ser!er )or a generic http-ase" "e!ice ser!er.

HJoteM this is only a partial list. Ether mo"ules ill e create" as ell.

The uil" shoul" complete normally. There may e some arnings "isplaye", hoe!er i) the arning or error can eignore", there ill also e a message in"icating this net to the arning#error Hor on a line ust elo the arning#erro



14/60

'E Initiali2ation and Installation Testing

#)n/)n)(#.s6 -rooLser!rootser>-rooass!root*ass>

here rootser>is the user ith root access to the S45 ser!er, an" root*ass>is the root user passor" Hmaye optional "epen"ing on the con)iguration o) your S45 ser!er. JETM This is not the same as the 5inu =root= user

'1aE I"portant note regarding +sh+ and +at+ co""and files:Comman"s en"ing ith =.s6= or =.#a= MSTe eecute" )rom the OpenGTSinstallation "irectory.

ttempting to eecute these comman"s )rom another "irectory may result in a =ClassJot(oun"ception= or=JoClass'e)(oun"rror= error, or similar. HThis means that you must c" to JGTSHBOM&, then eecute the

comman" as =#)n/comman+= in"os users may ish to install a 6erl interpreter on their machine inor"er to use the 6erl !ersions H=.pl= o) the comman"-line scripts hich "o not re?uire that they e eecute")rom the OpenGTSinstallation "irectory. &ore in)ormation on possile 6erl "istriutions a!ailale on in32plat)orms may e )oun" at this locationM =httpM##in32.perl.org#ii#in"e.phpKtitleWin32>'istriutions=

'1E I"portant note for indo7s users:hen using the =.#a= !ersion o) the comman"s in a 'ES in"o, comman" arguments such as-rootUser=rootmust either e enclose" in ?uotes, as in "-rootUser=root", or e speci)ie" ith a coloninstea" o) an e?ual-sign, as in -rootUser:root. Thus, on in"os, the comman" isM#)n)n)(#.#a #)n/(#A()n.pl -creae(# -user!rootser>

/usr/local/!pen"TS#$%&%'>#)n/(#A()n.pl -gran -user!rootser>

/usr/local/!pen"TS#$%&%'>#)n/(#A()n.pl -a#les!ca

http://win32.perl.org/wiki/index.php?title=Win32_Distributionshttp://win32.perl.org/wiki/index.php?title=Win32_Distributionshttp://win32.perl.org/wiki/index.php?title=Win32_Distributions


15/60

?ote for indo7s sers:=#)n/(#A()n.pl= is only a!ailale )or 5inu users, an" in"os users hich are running ithin a Cyginen!ironment. =#)n(#7on0)g.#a= pro!i"es a suset o) the )eatures a!ailale in =#)n/(#A()n.pl= hich ill run)rom a in"os comman" prompt.

'#E Testing the Installation

'#aE I"portant note regarding +sh+ and +at+ co""and files:Comman"s en"ing ith =.s6= or =.#a= MSTe eecute" )rom the OpenGTSinstallation "irectory.ttempting to eecute these comman"s )rom another "irectory may result in a =ClassJot(oun"ception= or=JoClass'e)(oun"rror= error, or similar. HThis means that you must c" to JGTSHBOM&, then eecute thecomman" as =#)n/comman+=

The )olloing comman" has een inclu"e" to assist in checing the installation o) the system an" "isplaying anyinconsistencies that might cause prolems at runtimeM

/zzz>c( $GTS_HOME

/usr/local/!pen"TS#$%&%'>#)n/c6ec8nsall.s6

Er, on in"osM

C.>c( %GTS_HOME%

C.!pen"TS#$%&%'>#)nc6ec8nsall.#a

This comman" ill "isplay !arious con)igure" "irectories an" en!ironment !ariales. I) any errors are "isplaye", theyshoul" e correcte" Hor at least un"erstoo" e)ore continuing system "eployment.

S&T6 con)iguration is re?uire" to support )eatures such as sen"ing )orgotten email noti)ications, emailing reports, etcThe properties re?uire" )or S&T6 can e con)igure" in one o) the =.con0= runtime con)iguration )iles Htypically=cuso.con0=. I) you ish to test your S&T6 email con)iguration, you can a"" the option =-sen(Ma)lea)lA((ress=, hich ill attempt to sen" a test email to the speci)ie" email a""ressM

/usr/local/!pen"TS#$%&%'>#)n/c6ec8nsall.s6 -sen(Ma)l &ea)la((resse5aple.co

Hnote that there are is a space eteen the *-sen(Ma)l

* option an" the email a""ress

Er, on in"osM

C.!pen"TS#$%&%'>#)nc6ec8nsall.#a -sen(Ma)l=&ea)la((resse5aple.co

Hnote that there are is a *M* eteen the *-sen(Ma)l* option an" the email a""ress )or the in"os !ersion o) the comman"

%eplace =&ea)la((resse5aple.co= ith the email a""ress you ish to ha!e recei!e the test email.

'%E (oading the Sa"ple Data

Some sample "ata has een pro!i"e" ith the OpenGTSinstallation hich can e loa"e" an" !iee" ithin the e-

inter)ace. 6lease re)er to the "ocument at =sapleaa/IEAME.5= ithin the OpenGTSinstallation "irectory )orin)ormation regar"ing ho to loa" the sample "ata.



16/60

''E Creating the +s$sad"in+ Account

Hthe =sysa"min= )eature is only a!ailale ith EpenGTS !ersion 2.2.7 an" ao!e

hen logging in to the =s&sa()n= account a ne menu *ta* ill e a!ailale, ith ne e-page selections, that allthe creating o) ne accounts. The )olloing comman" can e use" to create the =s&sa()n= accountM

/usr/local/!pen"TS#$%&%'>#)n/a()n.s6 Accoun -accoun!s&sa()n -pass!passor( -creae

Er, on in"osM

C.!pen"TS#$%&%'>#)na()n.#a Accoun -accoun=s&sa()n -pass=passor( -creae

%eplace the ao!e =passor(= speci)ication ith a secure passor".

Oou shoul" then e ale to log in to the =s&sa()n= account to see the ne =System "min= ta.



17/60

-E Installing 5trac67ar8

The =rac.ar= He-ARchi!e runs in a ;a!a Ser!let container an" ors ith the S45 '< "atastore to pro!i"e a ))eature" e inter)ace to the G6S location "ata capture" in the S45 "ataase )rom remote "e!ices. The mappingsupport currently uses Epen5ayers#EpenStreet&ap, ut can e con)igure" to use other commercial mapping ser!icepro!i"ers.

-1E Configuring the +7eappconf+ file

The "e)ault runtime con)iguration )ile =e#app.con0= inclu"es the )ile =coon.con0=, hich in-turn inclu"es=s&se.con0= an" =cuso.con0=. (or most installations, the "e)ault !alues speci)ie" in this )ile can e le)t as-is.Noe!er, some items, such as your S&T6 ser!er speci)ications, shoul" e con)igure" to )it your system re?uirements

-#E Configuring the availale reports

arious "etail an" summary reports can e "e)ine" using the )ile =repors.5l=, hich can e )oun" at=$GTS_HOME/repors.5l=.

&ore "etaile" in)ormation can e )oun" in the ao!e =repors.5l


18/60

OpenGTSinclu"es mapping support )or Epen5ayers#EpenStreet&ap, Google &aps, &icroso)t irtual arth, an"&apstraction Hhich can support se!eral other mapping ser!ice pro!i"ers as ell. Contact us regar"ing support )orother commercial mapping ser!ice pro!i"ers. I) you ill e using Google &aps )or your map pro!i"er, you must alsoregister )or a Google &ap ey Hmae sure you comply ith their terms o) ser!ice an" place the returne" ey in the=pr)"ae.5l= Hor =pr)"ae_coon.5l= )ile at the location in"icate" Hie. replace =::: lace Google MapsPe& Here :::= ith your ?uote" ey. To change the "e)ault "isplaye" map pushpins, you can create your on*6ushpins* section ithin your chosen &ap6ro!i"er. See the *pr)"ae.5l* )ile 6ushpins section Hin the=open,a&ers= &ap6ro!i"er section )or more in)ormation regar"ing customiAing pushpin icons.

Consult the contents o) the pro!i"e" pri!ate-lael )ile at =$GTS_HOME/pr)"ae.5l= )or more in)ormation on speci)iccustomiAations Heperiance in the general )ormat, e"iting, an" synta o) 9&5 )iles ill e necessary.

-%aE Maintain proper FM( s$nta> 7hen "odif$ing +pr)"ae.5l+ or +repors.5l+&ae sure that any changes to the *pr)"ae.5l* )ile still comply ith proper 9&5 synta. 9&5 is !eryparticular aout proper synta, an" intro"ucing an 9&5 synta error o)ten results in an error message similar tothe )olloing hen attempting to !ie the login page in a e roserM

8n"al)( Qpr)"ae.5lQ con0)gura)onB please conac 6e S&se A()n)sraor

%un =#)n/c6ec8nsall.s6= to help "iagnose any 9&5 synta errors that may ha!e een intro"uce".

The general loo-an"-)eel o) the e-inter)ace can also e change" y mo"i)ying the ;S6 )ile

=$GTS_HOME/ar/rac/4sp/log)nSess)on.4sp= an" the !arious CSS )iles in the "irectory=$GTS_HOME/ar/rac/css/=. 5oo )or the =@e#ages= tag section in the =pr)"ae.5l= )ile )or a""itionalin)ormation regar"ing the customiAation o) the =log)nSess)on.4sp= )ile.

-%E IM!ORTA?T: Redeplo$ all servlets after "odif$ing an$ runti"e configuration fileChanges to any o) =pr)"ae.5l=, =repors.5l=, =e#app.con0=, =coon.con0=, =s&se.con0=, or=cuso.con0= )iles Hor other =.5l= or =.con0= )ile ill re?uire that the =rac.ar= Has ell as the otherser!lets )ile e re-uilt an" re-"eploye".

-'E Co"piling/Installing the +trac67ar+ *ava Servlet

To uil" the =rac.ar= )ile, run the nt uil" comman" as )ollosM

/zzz>c( $GTS_HOME

/usr/local/!pen"TS#$%&%'>an rac

Hnote, the =an all= per)orme" ao!e also uil"s the =rac.ar= )ile

The target =rac= is a rapper )or ant targets =rac.cop)le= an" =rac.ar=. The target =rac.cop)le=compiles all necessary classes an" con)iguration )iles into the uil" "irectory =$GTS_HOME/#u)l(/rac=. The targ=rac.ar= then creates the *e archi!e* )ile =$GTS_HOME/#u)l(/rac.ar=. I) any o) the runtimecon)iguration )iles ha!e change", such as =pr)"ae.5l=, =repors.5l=, =e#app.con0=, or =coon.con0= )ileHor possily any other =:.con0= o) =:.5l= )ile, then the =rac.ar= )ile must e reuilt an" re"eploye". shortcto reuil"ing the =rac.ar= )ile, i) all source mo"ules ha!e alrea"y een compile", is to issue the )olloingcomman"M

/zzz>c( $GTS_HOME /usr/local/!pen"TS#$%&%'>an rac.ar

This ill simply repacage the =rac.ar= )ile )rom the pre-uilt source mo"ules, an" change" runtime con)iguratio)iles. I) e!erything has alrea"y een compile", this comman" typically taes only a )e secon"s to complete.



19/60

Install the create" =rac.ar= )ile per the pache Tomcat installation#con)iguration instructions. Typically, this meancopying the =rac.ar= )ile to the "irectory =$7ATA,8NA_HOME/e#apps/.=M

/usr/local/!pen"TS#$%&%'>cp #u)l(/rac.ar $7ATA,8NA_HOME/e#apps/.

Er, the )olloing =ant= target may also e use"M

/usr/local/!pen"TS#$%&%'>an rac.(eplo&

The ao!e metho" )or "eployment assumes that Tomcat is set )or *auoeplo&!


20/60

0E Installing 5events7ar8

The =e"ens.ar= He-ARchi!e runs in a ;a!a Ser!let container an" ors ith the S45 '< "atastore to allo"onloa"ing selecte" portions o) a se?uence o) e!ents o!er the e. This can e use" ith e-ase" mappingapplications to pro!i"e near real-time tracing o) a !ehicle or person. The *=e"ens.ar= ser!let currently supports"ata retrie!al in D&5, 9&5, CS, T9T, G69, or ;SEJ )ile )ormats, an" can e use" in mapping programs such asGoogle arth, or &S &ap6oints.

01E Configuring the +7eappconf+ 4ile

The "e)ault runtime con)iguration )ile =e#app.con0= inclu"es the )ile =coon.con0=, hich in-turn inclu"es=s&se.con0= an" =cuso.con0=. (or most installations, the "e)ault !alues speci)ie" in this )ile can e le)t as-is.Noe!er, some items, such as your S&T6 ser!er speci)ications, shoul" e con)igure" to )it your system re?uirements

Shoul" you ish to customiAe the =e#app.con0= )ile speci)ically )or the =e"ens.ar= ser!let, copy this )ile to the"irectory =$GTS_HOME/ar/e"ens/@E;-8N/= an" mo"i)y this copy.

0#E Co"piling/Installing the +events7ar+ *ava Servlet

To uil" the =e"ens.ar= )ile, run the nt uil" comman" as )ollosM

/zzz>c( $GTS_HOME /usr/local/!pen"TS#$%&%'>an e"ens

Hnote, the =an all= per)orme" ao!e also uil"s the =e"ens.ar= )ile

The target =e"ens= is a rapper )or ant targets =e"ens.cop)le= an" =e"ens.ar=. The target=e"ens.cop)le= compiles all necessary classes an" con)iguration )iles into the uil" "irectory=$GTS_HOME/#u)l(/e"ens=. The target =e"ens.ar= then creates the *e archi!e* )ile=$GTS_HOME/#u)l(/e"ens.ar=.

Install the =e"ens.ar= )ile per the pache Tomcat installation#con)iguration instructions. Typically, this simplyin!ol!es copying the =e"ens.ar= )ile to the "irectory =$7ATA,8NA_HOME/e#apps/.=. HThe ao!e metho" )or"eployment assumes that Tomcat is set )or *auoeplo&!


21/60

JoteM The *r0* an" *r* "ate ranges may e speci)ie" in *+ni poch* time )ormat Hnumer o) secon"s since mi"night ;1 1:70 or in =&&&&//((/HH=MM=SS= )ormat. I) not speci)ie", the last 100 e!ents ill e returne".

0%aE ?ote regarding secure 7e access:Con)iguration an" use o) *4ttps* Hie. SS5 is highly recommen"e" as the +%5 inclu"es the account passor"an" ill e encrypte" !ia *6ps*, ut ill e sent in the clear i) plain *6p* is use". Instructions )orcon)iguring Tomcat to support SS5 can e )oun" on the pache Tomcat esite.

So"e e>a"ples:

6ps=//local6os=RR/e"ens/(aa.cs"a!open(pUp!&passU(!o#)le

Return a CSV formatted data file ('(aa.cs"' !ontaining t"e la#t 100 e$ent re!ord for t"e de$i!e'opendmtp'%'mobile'& "e data i# returned $ia an "tt SS) !onne!tion& (*ote+ rela!e 'mypass' ,it"t"e roer a##,ord

6p=//local6os=RR/e"ens/(aa.4sona!(eoUp!&passU(!(eo

Return a -S.* formatted data file ('(aa.4son' !ontaining t"e la#t 100 e$ent re!ord for t"e de$i!e'demo'%'demo'& (*ote+ rela!e 'mypass' ,it" t"e roer a##,ord

6p=//local6os=RR/e"ens/(aa.la!gsUp!&passU(!(e"Ur0!11FXXUr!11FXXX

Return a /) () fomatted data file ('(aa.l' ,it" t"e fir#t 100 e$ent# ,it"in t"e #e!ifiedrange for t"e de$i!e gt#%de$&

6p=//local6os=RR/e"ens/(aa.gp5a!gsUp!&passU(!(e"Ur0!11FXXUr!11FXXX

Return a P () fomatted data file ('(aa.gp5' ,it" t"e fir#t 100 e$ent# ,it"in t"e #e!ifiedrange for t"e de$i!e gt#%de$ (#ee "tt+%%,,,&toografi&!om%g&a# for information regarding t"P data format&

oogle art" "a# t"e !aailit of automati!all olling data from t"i# R) at #e!ified inter$al#& o!onfigure oogle art" to read e$ent data oint# from t"e #er$er !li!: on ;dd on t"e main menu ar t"en

#ele!t *et,or: )in:& ;dd t"e /) retrie$al R) to t"e #er$er and !li!: Refre#" Parameter# to e ale enter eriodi! refre#" time#& o al,a# di#la t"e mo#t re!ent e$ent# ,it"in oogle art" omit t"e daterange otion (r0 and r and in#tead #e!if t"e otion l)) to !au#e t"e returned li#t to al,a#in!lude t"e late#t #et of e$ent#&

6p=//local6os=RR/e"ens/(aa.la!gsUp!&passU(!(e"Ul))!1

Return a /) () fomatted data file ('(aa.l' ,it" t"e la#t 100 a$ailale e$ent# for t"ede$i!e gt#%de$&

6p=//local6os=RR/e"ens/(aa.la!gsUp!&passU(!(e"Ul))!1

Return a /) () fomatted data file ('(aa.l' ,it" onl t"e la#t (mo#t re!ent e$ent for t"ede$i!e gt#%de$&

http://www.topografix.com/gpx.asphttp://www.topografix.com/gpx.asp


22/60

9E Dataase Ad"inistration

9aE I"portant note regarding +sh+ and +at+ co""and files:Comman"s en"ing ith =.sh= or =.at= MSTe eecute" )rom the OpenGTSinstallation "irectory. ttemptingto eecute these comman"s )rom another "irectory may result in a =ClassJot(oun"ception= or=JoClass'e)(oun"rror= error, or similar. HThis means that you must c" to JGTSHBOM&, then eecute the

comman" as =#)n/comman+=

9E I"portant note for indo7s users:hen using the =.#a= !ersion o) the comman"s in a 'ES in"o, comman" arguments such as-rootUser=rootmust either e enclose" in ?uotes, as in "-rootUser=root", or e speci)ie" ith a coloninstea" o) an e?ual sign, as in -rootUser:root .

&ost "ataase a"ministration Hccount, +ser, an" 'e!ice, etc can e per)orme" through either the comman"-lineutilities or through the e-inter)ace. The eample ccount#+ser#'e!ice e"iting eamples shon elo "escrie ona )e o) the possile )iel"s in each o) these tales. The )ile *S7HEMA.5*, inclu"e" ith the OpenGTSpacage,contains a list o) the current tales, an" the )iel"s in each o) the a!ailale tales.

list o) the currently "e)ine" tales an" )iel"s can also e generate" ith the )olloing comman"M

/zzz>c( $GTS_HOME

/usr/local/!pen"TS#$%&%'>#)n/(#A()n.pl -sc6ea

Er, on in"osM

C.zzz>c( %GTS_HOME%

C.!pen"TS#$%&%'>#)n(#A7on0)g.#a -sc6ea

91E Creating/&diting Accounts

The comman" =#)n/a()n.s6 Accoun= supports many a"ministrati!e )unction hich act on the S45 =Accoun=tale. Nere are a )e o) the )unctions that can e per)orme" using the =#)n/a()n.s6 Accoun= comman"M

Creating an Account:

/usr/local/!pen"TS#$%&%'>#)n/a()n.s6 Accoun -accoun!acc -creae

This creates the speci)ie" ccount ith "e)ault !alues Hreplace =acc= ith the account i" you ish to create.

&diting an Account:

/usr/local/!pen"TS#$%&%'>#)n/a()n.s6 Accoun -accoun!acc -e()

This comman" "isplays a comman"-line ccount )iel" e"itor, similar to the )olloingM



23/60

*N()+# )he ollo&ing is only an e,ample- .our implementation &ill !ontain addtional ield deinitions- /leaserevie& the ile 01H+M2-t,t0 in the (pen3) pa!kage or a list o possi$le ield deinitions-4

-----------------------------------------Pe&= open(p-----------------------------------------W assor( = #)n/a()n.s6 Accoun -l)s

This lists all ccounts an" one" 'e!ices.



24/60

9#E Creating/&diting sers

The comman" =#)n/a()n.s6 Lser= supports se!eral a"ministrati!e )unctions hich act on the S45 =Lser= tale.Nere are a )e o) the )unctions that can e per)orme" using the =#)n/a()n.s6 Lser= comman"M

Creating a ser:

/usr/local/!pen"TS#$%&%'>#)n/a()n.s6 Lser -accoun!acc -user!user -creae

This creates the speci)ie" +ser ith "e)ault !alues Hreplace =user= ith the user i" you ish to create. The username =a()n= is reser!e" )or use y the ccount a"ministrator. hen the ccount a"ministrator logs in Hy lea!ing thuser name )iel" lan on the log in screen, then the log in process ill chec to see i) the user =a()n= eists. I) thisuser name "oes eist, then the passor" an" access-control assigne" to the =a"min= user ill e use" )or the ccouna"ministrator HJoteM the "e)ault login user can e change" on the ccount "min e page, or on the ccountcomman"-line e"it.

&diting a ser:

/usr/local/!pen"TS#$%&%'>#)n/a()n.s6 Lser -accoun!acc -user!user -e()

This comman" "isplays a comman"-line +ser )iel" e"itor, similar to the )olloingM

*N()+# )he ollo&ing is only an e,ample- .our implementation &ill !ontain addtional ield deinitions- /leaserevie& the ile 0SCHEMA.txt0 in the (pen3) pa!kage or a list o possi$le ield deinitions-4

-----------------------------------------Pe&= open(pBuser-----------------------------------------W assor( =


25/60

9%E Creating/&diting Devices

The comman" =#)n/a()n.s6 e")ce= supports many a"ministrati!e )unctions hich act on the S45 =e")ce=tale. Nere are a )e o) the )unctions that can e per)orme" using the =#)n/a()n.s6 e")ce= comman"M

Creating a Device:

/usr/local/!pen"TS#$%&%'>#)n/a()n.s6 e")ce -accoun!acc -(e")ce!(e" -creae

This creates the speci)ie" 'e!ice ith "e)ault !alues Hreplace =(e"= ith the "e!ice i" you ish to create.

&diting a Device:

/usr/local/!pen"TS#$%&%'>#)n/a()n.s6 e")ce -accoun!acc -(e")ce!(e" -e()

This comman" "isplays a comman"-line +ser )iel" e"itor, similar to the )olloingM

*N()+# )he ollo&ing is only an e,ample- .our implementation &ill !ontain addtional ield deinitions- /leaserevie& the ile "SCHEMA.txt+in the (pen3) pa!kage or a list o possi$le ield deinitions-4

-----------------------------------------Pe&= open(pBo#)le-----------------------------------------W escr)p)on =


26/60

Ma> Total Connections per MinuteL HOpenDMT!only This is the maimum numer o) TC6 or +'6connections that are alloe" "uring a /0 secon" inter!al.

Ma> Duple> Connections per IntervalL HOpenDMT!only This is the maimum numer o) TC6 connections thaare alloe" "uring the ao!e speci)ie" inter!al.

Ma> Duple> Connections per MinuteL HOpenDMT!only This is the maimum numer o) TC6 connections thatare alloe" "uring a /0 secon" inter!al.

Retrieving Device &vents through the co""andline:

/usr/local/!pen"TS#$%&%'>#)n/a()n.s6 e")ce -accoun!acc -(e")ce!(e" -e"ens

This comman" returns the last )e e!ents in CS )ormat.

aeBT)eB7o(eB,a)u(eB,ong)u(eBSpee(BHea()ngBAl)u(eBA((ress2X/3/XB23=13=21B8nMo)onB2Z.X2F1B-1F2.XRRZB13.ZB1XR.3B2RX.B#)n/a()n.s6 e")ce -accoun!acc -(e")ce!(e" -counOl(E"ens!-Z(

To "elete these =ol"= e!entsM

...>#)n/a()n.s6 e")ce -accoun!acc -(e")ce!(e" -(eleeOl(E"ens!-Z(

The arguement !alue )or the =counOl(E"ens= an" =(eleeOl(E"ens= can e speci)ie" using a relati!e time, suas =-12(=, in"icating e!ents ol"er than 120 "ays ago, or ith a speci)ic time speci)ication, such as=21/3/12B13=1=BGMT= in"icating e!ents eisting e)ore &arch 12, 2010 1M1$pm G&T.

AR?I?G: Deleting old events fro" the &ventData tale is final Once the events have een deleted; the$cannot e recovered



27/60

9'E General Dataase Ad"inistrative 4unctions

The comman" =(#A()n.pl= Honly a!ailale as a 6erl script can per)orm !arious a"ministrati!e )unctions on the S4"ataase HJoteM the comman" *#)n(#7on0)g.#a* is pro!i"e" )or in"os users, an" per)orms a suset o) theoperations a!ailale to the =(#A()n.pl= comman". Nere are a )e o) the )unctions that can e per)orme" using th=(#A()n.pl= comman"M

3erif$/pdate tale colu"ns:

/usr/local/!pen"TS#$%&%'>#)n/(#A()n.pl -a#les

This comman" ill chec the column con)iguration o) all OpenGTStales an" report on any missing columns, or otheanomolies. I) an OpenGTStale "oes not eist, it ill e create".

/usr/local/!pen"TS#$%&%'>#)n/(#A()n.pl -a#les!c

hen upgra"ing to a neer !ersion o) OpenGTSin hich ne columns ha!e een a""e" to !arious tales, the ao!ecomman" ill issue the re?uire" =A,TEI TA;,E= comman"s to the tales as re?uire" in or"er to a"" any ne talecolumns. I) a speci)ic column *type* has change", using =-a#les!ca= ill cause column types to e altere".


Er, on in"osM

C.!pen"TS#$%&%'>#)n(#7on0)g.#a -a#les=ca

This comman" shoul" e use" hene!er upgra"ing to a neer !ersion o) OpenGTS.

Du"p tales to dis6:

/usr/local/!pen"TS#$%&%'>#)n/(#A()n.pl -(up -()r!/p/gs

This comman" ill "ump all OpenGTStales to the "irectory speci)ie" y the =-()r= argument H=/p/gs= is the"e)ault "estination i) the =-()r= option is not speci)ie". I) re?uire" y your &yS45 installation, you may also nee" tospeci)y the "ataase root user Hie. as in =-rooLser!user=. In"i!i"ual tales can then later e reloa"e" ith the=-loa(!a#le= option.

HJote )or 5inu usersM En some !ersions o) 5inu hich employ S5inu, you may recei!e an error in"icating that&yS45 is not alloe" to rite into the speci)ie" "irectory. In these cases, you may nee" to either speci)y a "irectory t&yS45 is alloe" to rite to, or change the S5inu security settings to pro!i"e &yS45 ith authoriAation to rite tothe =/p= "irectory.

(oad tales fro" Dis6:

/usr/local/!pen"TS#$%&%'>#)n/(#A()n.pl -loa(!ta2le>-()r!/p/gs

This comman" ill loa" the speci)ie" tale )rom the )ile pre!iously create" y the =-(up= argument. 'uring the taleloa", columns are matche" here possile. I) a column is present in the *"umpe"* )ile, ut has een remo!e" in thecurrent GTS tale, a arning ill e generate" that the column has een "roppe". This comman" is use)ul hen smatale changes nee" to e ma"e in the column structure. JoteM the s?uare racets speci)ie" ao!e in"icate that theoption ithin the racets is optional. The s?uare racets shoul" not e speci)ie" literally on the comman"-line i) theoptional argument ithin the racets is use".



28/60

E Installing/Starting the OpenDMT!; T; and Aspicore DCS Modules

This section "escries ho to start an" stop the =gs(p=, =15=, an" =asp)core= "e!ice communication ser!erH'CS mo"ules, hoe!er these instructions are also applicale to other "e!ice communication ser!ers hich may alsoe installe" or implemente".

&ore in)ormation on the OpenDMT!proect may e )oun" at the lin =httpM##.open"mtp.org=. Support )or

OpenDMT!compliant "e!ices is inclu"e" in OpenGTSith the =gs(p= "e!ice communication ser!er H'CS.

The =15= 'CS mo"ule supports most common TD102#TD103 protocol compliant "e!ices HJoteM some manu)acturpro"ucing a TD102#TD103 "e!ice may e using their on custom protocol !ariant that is not compatile ith thecommon TD102#TD103 protocol.

Aspicorepro!i"es client phone so)tare )or tracing !arious Joia, Samsung, an" Sony ricsson phones. Thespicore 'CS ithin the EpenGTS pacage is "esigne" to or ith the TC6 or +'6 "ata transport metho" hich cae con)igure" ithin the spicore client phone application. (or more in)ormation on their supporte" phones, an" tootain their client so)tare, !istit their esite at =httpM##.aspicore.com#en#tuotteet>tracer.aspKtaW2XsuW1=.

1E Configuring the +dcservers>"l+ 4ile

The )ile =(cser"ers.5l= contains a )e con)igurale properties that e))ect the eecution o) the OpenDMT!H=gs(p= an" AspicoreH=asp)core= ser!ers. &ost o) the properties !alues shoul" e le)t as their "e)ault !alue,ut the )olloing properties !alues can e set to those appropriate to your operating en!ironmentM

OpenDMT!M cpor!


29/60

#aE I"portant note regarding +sh+ and +at+ co""and files:Comman"s en"ing ith =.s6= or =.#a= &+ST e eecute" )rom the OpenGTSinstallation "irectory.

ttempting to eecute these comman"s )rom another "irectory may result in a =ClassJot(oun"ception= or=JoClass'e)(oun"rror= error, or similar. HThis means that you must c" to JGTSHBOM&, then eecute thecomman" as =#)n/comman+=

Er, the 6erl !ersion o) this comman" can e use" ithout nee"ing to e in the OpenGTSinstallation "irectoryM

/zzz>$GTS_HOME/#)n/runser"er.pl -s server

En in"os, the comman" can omit the =-s= an" can e entere" as )ollosM

C.>c( OpenGTS_1.2.3

C.!pen"TS#$%&%'.>#)nrunser"er.#a server

The ser!er ill initialiAe an" start listening on the portHs speci)ie" y the =,)senors= tag in the =(cser"ers.5l)ile )or the speci)ic name" 'CSer!er. To change the listen port on the comman" line, you can a"" a =-por= argumeas )ollosM

/zzz>$GTS_HOME/#)n/runser"er.pl -s server-por 31123

Er on in"osM

C.!pen"TS#$%&%'.>#)nrunser"er.#a server-por=31123

To set listening on port =31123=.

Oou can also a"" the comman"-line option =-(e#ugMo(e= to enale "eug-le!el logging.

hile running in =acgroun"= mo"e, the output logs are store" in the )ile =$GTS_HOME/logs/server.log=. HThe )i=server.ou= is also create" y =runser"er.pl= to capture output to st"out#st"err, ut ill typically remain empty.

hen testing#"eugging, you may also start a ser!er =interacti!ely=. That is, the ser!er is run in the )oregroun" Hie. no*acgroun"e"*, an" all logging output is sent to the console instea" o) the log )ile. To start a ser!er =interacti!ely=, a"the option =-)= to the comman" line, as )ollosM

/zzz>$GTS_HOME/#)n/runser"er.pl -s server-)

HTo stop the ser!er in this mo"e, simply press *Control-C*

%E Stopping the Device Co""unication Server

hen starte" in =acgroun"= mo"e Hie. ithout the =-)= option, a =6rocess I'= H6I' )ile is create" at=$GTS_HOME/logs/server.p)(=, hich contains the process-i" o) the acgroun"e" tas. This )ile is use" to stop ser!er ith the comman"M

/zzz>$GTS_HOME/#)n/runser"er.pl -s server-)ll

here =server= shoul" e replace" ith the speci)ic name o) the ser!er to start Hie. =gs(p=, =15=, or=asp)core=.



30/60

En 5inu systems, the 6erl comman" =ps4a"a=, inclu"e" ith OpenGTS, can e use" to "isplay in)ormation regar"inghich 'e!ice Communication Ser!ers are currently runningrM

/zzz>$GTS_HOME/#)n/ps4a"a

8 aren , Lser Ja"a class/4ar------ ------ - -------- ------------------------------------------------------- 21 1W 1 opengs org.apac6e.caal)na.sarup.;oosrapR11 1W 1 opengs /usr/local/OpenGTS_1.2.3/#u)l(/l)#/gs(p.4ar

R12 1W 1 opengs /usr/local/OpenGTS_1.2.3/#u)l(/l)#/15.4arR123 1W 1 opengs /usr/local/OpenGTS_1.2.3/#u)l(/l)#/asp)core.4arR12Z 1W 1 opengs /usr/local/OpenGTS_1.2.3/#u)l(/l)#/eplae.4ar

This comman" lists all non running ;a!a processes, ith their associate" 6I' Hprocess-i", parent 6I', user, an";a!a class or ar )ile hich is currently running. The =org.apac6e.caal)na.sarup.;oosrap= process in"icatesthat pache Tomcat is running ith the in"icate" 6I'. =gs(p=, =15=, =asp)core=, an" =eplae= in"icate theirrespecti!e running 'e!ice Communication Ser!ers.

'E Adding a ?e7 Device Record

Ence the proper "e!ice communication ser!er H'CS is running, login to an account you ish to ha!e on the"e!ice#phone you ill e tracing an" a"" a ne 'e!ice#ehicle recor" on the ='e!ice "min= page.

OpenDMT!:Epen'&T6 "e!ices typically use the actual =account= an" ="e!ice= I'*s. In this case mae sure the account an" "e!ii" programme" into the Epen'&T6 compliant "e!ice match the same account an" "e!ice i" create" ithin theEpenGTS system.

T:TD102#TD103 "e!ices typically report their uni?ue i"enti)ying in)ormation using the I&I numer o) the mo"em. En th=Device Ad"in= page, set the =ni)ue ID= )iel" to the I&I !alue in the )ormat t8_1!;?1!; , here=1!;?1!;= is the I&I numer o) the phone HThe =t8_= pre)i is use" to help i"enti)y the type o) "e!icecommunication ser!er use" to parse the "ata L in this case TD102#TD103.

AspicoreMThe spicore client so)tare reports the uni?ue i"enti)ying in)ormation using the I&I numer o) the phone. En the=Device Ad"in= page, set the =ni)ue ID= )iel" to the I&I !alue in the )ormat s


31/60

@E Creating $our o7n Device Co""unication Server

In or"er )or OpenGTSto recei!e "ata )rom a "e!ice, a customiAe" ='e!ice Communication Ser!er= ill nee" to eimplemente" that un"erstan"s the protocol use" to communicate ith the remote "e!ice, an" insert recei!e" e!ents inthe S45 "ataase. This section pro!i"es a rie) "escription o) the eample *template* ser!ers pro!i"e" ith OpenGTS)or implementing your on remote "e!ice communication ser!er.

The metho" use" y remote "e!ices to transport e!ents to the ser!er !aries greatly ith the manu)acturer o) the "e!icSome transport "ata to a ser!er !ia S&S messages, some use an S&T6 email transport to sen" "ata to a ser!er, somuse an NTT6-ase" protocol hich enco"e "ata in the re?uest to the ser!er, an" many use some )orm o) ra-socetase" communication H!ia TC6#+'6 to connect to a listener on the ser!er to transmit "ata. In or"er to create a "e!iccommunication ser!er that is ale to parse incoming "ata )rom a "e!ice, an intimate un"erstan"ing o) the speci)ics o)the protocol use" y the "e!ice manu)acturer is re?uire". OpenGTSinclu"es eamples )or NTT6-ase" ser!ers, an"ra-socet ase" ser!ers Hsupporting oth TC6 an" +'6, hoe!er, since each "e!ice manu)acturer typically has theon protocol an" ay o) transporting "ata, these eample ser!ers cannot e assume" to ust-or ith any#e!ery"e!ice. 'epen"ing on the particular "e!ice chosen, there may e a signi)icant an" sustantial amount o) ornecessary in or"er to support the chosen har"are "e!ice.

The )irst, an" most important, step hen starting to implement a "e!ice communication ser!er )or a chosen har"are"e!ice is to otain an" )ully un"erstan" the protocol "ocumentation )rom the manu)acturer o) the "e!ice. hile http-ase" communication can o)ten e re!erse-engineere" )rom oser!ing the "ata arri!ing at the ser!er, attempting to

re!erse-engineer a ra-socet ase" protocol can pro!e etremely "i))icult, i) not impossile, ithout proper protocol"ocumentation.

@aE I"portant note regarding the i"ple"ention of a device co""unication server:Implementing a "e!ice communication ser!er )or a gi!en "e!ice may tae a signi)icant an" sustantial amounto) programming or to accomplish, "epen"ing on the "e!ice protocol. To implement a ser!er, you ill lielynee" an in-"epth un"erstan"ing o) TC6#+'6 ase" communication, an" a goo" un"erstan"ing o) ;a!aprogramming techni?ues, inclu"ing socet communication, multi-threa"ing, an" possily itise manipulationtechni?ues )or etracting it )iel"s )rom inary "ata Hinclu"ing noing hether the tracing "e!ice sen"s "atain ig-en"ian or little-en"ian )ormats. I) using an http-ase" protocol, you may also nee" an un"erstan"ing o)ho ser!lets are uilt, an" ho they operate ithin a Ser!let container, such as pache Tomcat.



32/60

@1E BTT! ,ased Device Co""unication Servers using the +gpr"c+ servletE

1S"ills re(uired: !ava, Servlets, 0TT/ based protocols2

NTT6-ase" communication is typically the easiest to implement. I) your remote tracing "e!ice sen"s messages to tser!er using an NTT6-ase communication protocol, then the eample ser!er *gprc* can e mo"i)ie" to parserecei!e" "ata an" insert it into the S45 "ataase. The sources )or the *gprc* ser!er Hname" a)ter the YG6%&C recoin the J&-0183 protocol can e )oun" in the OpenGTSsource "irectory =src/org/opengs/ar/gprc= an"runs as a Ser!let in a ser!let container such as pache Tomcat Han" uses the same access ports con)igure" )or Tomc

@11E Configuring the +gpr"c+ ServletM

This mo"ule has many uilt-in con)igurale options an" may only nee" special customiAation properties hich can especi)ie" in the =e#app.con0= )ile. The )olloing is a list o) con)igurale properties a!ailale )or the =gprc= http-ase" "e!ice communication ser!erM

'ata )ormat#!alue 6roperty DeysM

*pr6.&o*N,e5ogging output name.'e)ault !alueM *pr6

*pr6.0n'B0e7re')

+ni?ueI' pre)i, use" hen looup up 'e!ice.'e)aults !alueM %same as $*pr6.&o*N,e$ property value&

*pr6.2e,0&tA66o0ntI'e)ault account I'.'e)ault !alueM *pr6

*pr6.'n'0Spee27H&inimum acceptale spee" Hspee"s less than this !alue ill e set to *0*'e)ault !alueM ?.?

*pr6.est',teO2oeterI) true, a G6S ase" o"ometer ill e calculate".'e)ault !alueM ,&se

*pr6.s'0&,teGeoDones

I) true, a geoAone arri!al#"epartures ill e "etecte", an" the appropriate a""itional e!ents ill e create".'e)ault !alueM ,&se

*pr6.2,te3or,t'ate )ormat )or *"ate* parameter.ali" !aluesMNONE, E7OCH, M, M,M'e)ault !alueM M

*pr6.response.o8%esponse returne" to "e!ice on on success)ul "ata receipt.'e)ault !alueM %nothing returned&

*pr6.response.error%esponse on returne" to "e!ice on on unsuccess)ul Herror "ata receipt.'e)ault !alueM %nothing returned&



33/60

+%5 6arameter 6roperty DeysM

*pr6.p,r.0n'B0e+%5 6arameter DeyM +ni?ue-I''e)ault !alueM '2

*pr6.p,r.,66o0nt+%5 6arameter DeyM ccount-I''e)ault !alueM ,66t

*pr6.p,r.2e'6e+%5 6arameter DeyM 'e!ice-I'

'e)ault !alueM de$*pr6.p,r.,0t4

+%5 6arameter DeyM uth#6assor" Hnot use"'e)ault !alueM %blan"&

*pr6.p,r.st,t0s+%5 6arameter DeyM StatusCo"e'e)ault !alueM 6o2e

*pr6.p,r.*pr6+%5 6arameter DeyM G6%&C Hthe J&-0183 YG6%&C recor" is epecte" )or this !alue o) this parameter'e)ault !alueM *pr6

*pr6.p,r.2,te+%5 6arameter DeyM 'ate Hignore" i) *

*pr6.p,r.*pr6* is speci)ie"

'e)ault !alueM 2,te*pr6.p,r.t'e

+%5 6arameter DeyM Time Hignore" i) **pr6.p,r.*pr6* is speci)ie"'e)ault !alueM t'e

*pr6.p,r.&,t't02e+%5 6arameter DeyM 5atitu"e Hignore" i) **pr6.p,r.*pr6* is speci)ie"'e)ault !alueM &,t

*pr6.p,r.&on*'t02e+%5 6arameter DeyM 5ongitu"e Hignore" i) **pr6.p,r.*pr6* is speci)ie"'e)ault !alueM lon

*pr6.p,r.spee2+%5 6arameter DeyM Spee"Hph parameter ey Hignore" i) **pr6.p,r.*pr6* is speci)ie"

'e)ault !alueM spee2*pr6.p,r.4e,2'n*

+%5 6arameter DeyM Nea"ingH"egrees Hignore" i) **pr6.p,r.*pr6* is speci)ie"'e)ault !alueM 4e,2

*pr6.p,r.,&t't02e+%5 6arameter DeyM ltitu"eHmeters'e)ault !alueM ,&t

*pr6.p,r.o2oeter+%5 6arameter DeyM E"ometerHilometers'e)ault !alueM odo"

*pr6.p,r.,22ress+%5 6arameter DeyM %e!erse-Geoco"e" ""ress'e)ault !alueM ,22r

*pr6.p,r.2r'er+%5 6arameter DeyM 'ri!er I''e)ault !alueM 2r

*pr6.p,r.ess,*e+%5 6arameter DeyM &essage'e)ault !alueMs*



34/60

@1#E Default +gpr"c+ ConfigurationM

The "e)ault =gprc= co)iguration Hith no special con)iguration changes ma"e in the =e#app.con0= )ile epects ahttp-ase" +%5 )ormatte" as )ollosM Hthe +%5 elo "isplays the !arious )iel"s on separate lines, ut is normally sento the ser!er as a single +%5 all on a single lineM

6p=//e5aple.co=RR/gprc/aa)(!123FXRZ123FUco(e!52U

[email protected]:17

here

6p=//e5aple.co=RR/gprc/aa

%epresents the hostMport H=e5aple.co=RR= an" =gprc.ar= ser!let location H=#gprc/aa=

123FXRZ123F

%epresents the uni?ue moile I' o) the "e!ice Hsuch as the I&IV. HThis !alue shoul" e entere" into the ='e!ice "min=page =+ni?ue I'= )iel" in the )ormat =gprc_123FXRZ123F=.

52%epresents the status co"e use" )or i"enti)ying the reason )or the e!ent. The status co"e use" here shoul" match the he, "ecimal !alue o) a status co"e liste" in the =Status Co"es an" 'escriptions= manual at the )olloing locationM6p=//.geoelea)c.co/(ocs/Saus7o(es.p(0

In a""ition to one o) the ao!e he#"ecimal status co"es, any o) the )olloing tet co"e names may also e use", hich illautomatically e con!erte" into it*s correspon"ing he-ase" status co"e hen it is entere" into the !ent'ata taleM GS,AN87, @AMAIP, etc, Hsee gprmc source mo"ule =aa.4a"a= )or a current list.

[email protected]:17

%epresents the J&-0183 YG6%&C recor" straight )rom the G6S recei!er.

@1%E ,uilding the +gpr"c+ ServletM

The =gprc.ar= )ile is automatically uilt y the EpenGTS =an all= comman", ut can also e uilt speci)ically the )olloing comman"M

an gprc

)ter maing any con)iguration changes to the ao!e properties, the =gprc.ar= )ile must e reuilt an" re"eploye"or"er )or the con)iguration changes to tae e))ect.

I) you nee" to mae changes to this source mo"ule to support your "e!ice, it is recommen"e" that you copy the sourc)iles to an ne "irectory Hrememer to change the ;a!a pacage name, an" also copy#mo"i)y the =e#.5l= in)ormat)oun" at =ar/gprc/@E;-8N/e#.5l=, then mo"i)y the copie" sources ith the speci)ic changes re?uire" y yotracing "e!ice.

This mo"ule ill nee" to e con)igure" an" installe" in a ser!let container, similar to the installation process use" )orother ser!lets in this "ocumentation.

Consult the *gprc* ser!er source co"e "irectly )or a""itional in)ormation. HSource co"e )or this mo"ule can e )oun"

the "irectory =src/org/opengs/ar/gprc/=.

http://www.geotelematic.com/docs/StatusCodes.pdfhttp://www.geotelematic.com/docs/StatusCodes.pdf


35/60

@#E Ra7 Soc6et ,ased Device Co""unication Server

1S"ills re(uired: !ava, T3/456/ soc"et communication, multi7threading, bitwise manipulation, general client4serverprotocols2

I) your remote tracing "e!ice sen"s messages to the ser!er using a socet-ase" communication protocol, then theeample *eplae* ser!er can e mo"i)ie" to parse recei!e" "ata an" insert it into the S45 "ataase. The sources the *eplae* ser!er can e )oun" in the OpenGTSsource "irectory =src/org/opengs/ser"ers/eplae=.This ser!er type runs as a separate process listening on a selecte" socet port )or incoming TC6#+'6 connections.

Oou ill liely nee" to mae some signi)icant changes to the source co"e to support your particular "e!ice. It isrecommen"e" that you copy the source )iles to an ne "irectory Hrememer to change the ;a!a pacage name, thenmo"i)y the copie" sources ith the speci)ic changes re?uire" y your tracing "e!ice.

Nere are some o) the main attriutes o) the protocol that nee" to e "etermine" e)ore starting to implement a TC6#+socet ase" "e!ice communication ser!erM

re the protocol pacets transmitte" in SCII,


36/60

@#1E Starting the Device Co""unication Server

Ence your ser!er ar )ile has een create", you can use the =#)n/runser"er.s6= comman" Hor =runser"er.#a= onin"os to start your "e!ice communication ser!er as )ollosM

/zzz>c( $GTS_HOME /usr/local/!pen"TS#$%&%'>#)n/runser"er.s6 -s eplae

@#1aE I"portant note regarding +sh+ and +at+ co""and files:Comman"s en"ing ith =.sh= or =.at= &+ST e eecute" )rom the OpenGTSinstallation "irectory. ttemptingto eecute these comman"s )rom another "irectory may result in a =ClassJot(oun"ception= or=JoClass'e)(oun"rror= error, or similar. HThis means that you must c" to JGTSHBOM&, then eecute thecomman" as =#)n/comman+=

Er, the 6erl !ersion o) this comman" can e use" ithout nee"ing to e in the OpenGTSinstallation "irectoryM

/zzz>$GTS_HOME/#)n/runser"er.pl -s eplae

En in"os, the comman" can omit the =-s= an" can e entere" as )ollosM

C.>c( OpenGTS_1.2.3

C.!pen"TS#$%&%'.>#)nrunser"er.#a eplae

The ser!er ill initialiAe an" start listening on the portHs speci)ie" in the =(cser"ers.5l= )ile )or the =eplae=ser!er. The "e)ault port is 312. To change the listen port on the comman" line, a =-por= can e a""e" as )ollos

/zzz>$GTS_HOME/#)n/runser"er.pl -s eplae -por 31123

Er, on in"osM

C.!pen"TS#$%&%'.>#)nrunser"er.#a eplae -por=31123

To set listening on port =31123= H)or eample.

Oou can also a"" the comman"-line option =-(e#ugMo(e= to enale "eug-le!el logging.

hile running in =acgroun"= mo"e, the output logs are store" in the )ile =$GTS_HOME/logs/eplae.log=. HThe)ile =eplae.ou= is also create" in this "irectory to catch any st"out#st"err messages hich are "isplaye" ithin tser!er that "on*t use the *6rint* logging )eature uilt into EpenGTS. Typically, this )ile shoul" alay e empty.

hen testing#"eugging, you may also start a ser!er =interacti!ely=. That is, the ser!er is run in the )oregroun" Hie. no*acgroun"e"*, an" all logging output is sent to the console instea" o) the log )ile. To start a ser!er =interacti!ely=, a"the option =-i= to the comman" line, as )ollosM

/zzz>$GTS_HOME/#)n/runser"er.pl -s eplae -)

HTo stop the ser!er in this mo"e, simply press *Control-C*



37/60

@##E Stopping the Device Co""unication Server

hen starte" in =acgroun"= mo"e Hie. ithout the =-)= option, a =6rocess I'= H6I' )ile is create" at=$GTS_HOME/logs/eplae.p)(=, hich contains the process-i" o) the acgroun"e" tas. This )ile is use" to stthe ser!er ith the comman"M

/zzz>$GTS_HOME/#)n/runser"er.pl -s eplae -)ll

En 5inu systems, the 6erl comman" =ps4a"a=, inclu"e" ith OpenGTS, can e use" to "isplay in)ormation regar"inghich 'e!ice Communication Ser!ers are currently running, inclu"ing the =eplae= ser!erM

/zzz>$GTS_HOME/#)n/ps4a"a

8 aren , Lser Ja"a class/4ar------ ------ - -------- ------------------------------------------------------- 21 1W 1 opengs org.apac6e.caal)na.sarup.;oosrapR11 1W 1 opengs /usr/local/OpenGTS_1.2.3/#u)l(/l)#/gs(p.4arR12Z 1W 1 opengs /usr/local/OpenGTS_1.2.3/#u)l(/l)#/eplae.4ar

This comman" lists all non running ;a!a processes, ith their associate" 6I' Hprocess-i", parent 6I', user, an";a!a class or ar )ile hich is currently running. The =org.apac6e.caal)na.sarup.;oosrap= process in"icatesthat pache Tomcat is running ith the in"icate" 6I'. =gs(p= an" =eplae= in"icate their respecti!e running'e!ice Communication Ser!ers.

@%E Runti"e FM( Configuration 4ile

The ra socet-ase" "e!ice communication ser!ers Hsuch as the eample *template* ser!er support the runtimecon)iguration using the )ile =(cser"ers.5l=. n eample )ormat o) the =(cser"ers.5l= is as )ollosM

7Ser"er7on0)g #)n(A((ress!


38/60

n eample =8nclu(e= tag )ormat is as )ollosM

8nclu(e 0)le!


39/60

=,)senors= su-tagMThis tag speci)ies the ports on hich the "e!ice communication ser!er ill listen )or incoming connections )romremote "e!ices. The attriute =cpor= speci)ies the port on hich a TC6 listener ill e starte". The attriute=u(por= speci)ie" the port on hich a +'6 listener ill e starte". I) either =cpor= or =u(por= is lan, ornot speci)ie", the the correspon"ing =listener= ill not e starte".

=roper)es= su-tagMThis tag inclu"es =roper&= su-tags hich speci)y runtime properties hich can e use" to )urther speci)y theeha!ior o) the "e!ice communication ser!er at runtime. The stan"ar" properties that most "e!ice communicationser!er recogniAe are as )ollosM

)n)uSpee(PH M H'oule This property speci)ies the minimum acceptale G6S-ase" spee". spee"!alue eo the !alue speci)ie" y this property ill e consi"ere" a spee" o) *0*. This is use" to mitigate G6Sspee" !alues hich can in"icate motion, e!en hen the G6S recei!er is stationary.

es)aeO(oeer M H


40/60

1=E Internationali2ation/(ocali2ation

The OpenGTSsource co"e is i18n H=internationaliAation= compliant, hich means that it can a"apte" to !ariouslanugages ithout re?uiring any co"e changes Hie. no )ie" har"co"e" tet that cannot e change" at "isplay time.5ocaliAation H=510n= is the process o) applying language speci)ic tet )or a gi!en 5ocale.

1=1E Supporting a ?e7 (anguage

ll nglish tet hich is "isplayale ithin the OpenGTSe-inter)ace can e )oun" in the resource property )iles cal=,ocalSr)ngs_en.proper)es= )oun" ithin the !arious source )ile "irectories. These )iles contain a listing o) th"e)ault nglish tet hich ill e "isplaye" i) no speci)ic locale has een chosen. The )ormat o) this )ile is=te5Pe&!"alue=, here the =e5Pe&= is a uni?ue i" )or the speci)ic tet ="alue=.

1=1aE Do7nload the latest (ocale files for the ne>t release:Oou can "onloa" a Aip )ile containing the =,ocalSr)ngs_55.proper)es= )iles )or the net release o)EpenGTS at the )olloing +%5M 6p=//.geoelea)c.co/(onloa(.6l,ocalSr)ngs

To support a ne language#locale, search )or e!ery occurance o) the )ile =,ocalSr)ngs_en.proper)es= an"

create a copy name" =,ocalSr)ngs_XX.proper)es= in the same "irectory, here =XX= in this case is the ISO0%2-letter language co"e. Then in the ne )ile, remo!e the pre)iing == comment character on each eyW!alue line, an"mo"i)y the tet !alue to match your speci)ic language synta an" meaning. &ae sure to lea!e the tet ey as-is. Thcontents o) the =,ocalSr)ngs_XX.proper)es= )iles "uste ritten using only ISO-@1enco"e" charactersHper =4a"a.u)l.roper)es= an" =4a"a.u)l.Iesource;un(le= restrictions. Characters that cannot e"irectly represente" in ISO-@1can e inclu"e" using nicodeescapes y speci)ying the )ormat *uXXXX*, here*XXXX* is the he representation o) the unico"e character. The ;a!a ;'D installation inclu"es the tool *na)"e2asc))to assist ith con!erting unico"e tet to unico"e escape" tet.

I) a =,ocalSr)ngs_\\.proper)es= )ile "oes not contain proper nicodeenco"ing Hie. an in!ali" =uXXXX=speci)ication, then ;a!a may e unale to loa" the properties )ile, an" the speci)ic 5ocalStrings )ile may not e use". !eri)y that no in!ali" =uXXXX= speci)ications are present, the )olloing ChecInstall comman" ill !ali"ate the=,ocalSr)ngs_XX.proper)es= )ilesM

/zzz>$GTS_HOME/#)n/c6ec8nsall.s6 -- -localSr)ngs!$GTS_HOME/src

This comman" ill search )or all =,ocalSr)ngs_XX.proper)es= )iles in the =$GTS_HOME/src= "irectory an"eamine their contents )or in!ali" =uXXXX= speci)ications. I) any 5ocalStrings )ile contains in!ali" =uXXXX=speci)ications, the error message =&al)orme" Fu enco"ing= ill e "isplaye" )or the particular )ile. This comman"ill also chec to see that only ISO-@1characters are use" in the 5ocalStrings )iles.

The speci)ic language locale "isplaye" on the e-inter)ace is controlle" y the =locale= attriute on the =oa)n= tain the =pr)"ae.5l= )ile.

)ter maing any changes to the =pr)"ae.5l= )ile, or any o) the =,ocalSr)ngs_\\.proper)es= )iles, maesure you reuil" an" re"eploy the =rac.ar= )ile.

1=#E Changing the Displa$ed (anguage

Setting the "isplaye" language can e con)igure" in the *pr)"ae.5l* )ile. En the =oa)n= tag, change the=locale= to the "esire" 2-letter country co"e. (or eample, to change the language to German, set the 'omain=locale= attriute to *locale!


41/60

11E Creating/Modif$ing Reports

OpenGTScomes ith a !ery simple an" con)igurale report generation engine. %eports are comprise" o) 3 maincomponentsM the report layout, the report "ata iterator, an" the report speci)ication 9&5.

The report speci)ication 9&5 speci)ies a report "ata iterator, reporting constraints, an" the columns hich are to appeon the report. The report "ata iterator constructs the "ata hich ill e inclu"e" in the report ase" on the reporting

constraints. The report "ata layout then iterates through the report "ata an" generates a report ase" on the column)ormatting in)ormation pro!i"e" y the report speci)ication 9&5.

The =%eport 5ayout= an" =%eport 'ata Iterator= components must e implemente" in ;a!a co"e y a ;a!aprogrammer, an" shoul" e con)igurale )or a general use. The =%eport Speci)ication 9&5= is a report con)igurationtet )ile that speci)ies the type, columns, an" contraints )or a speci)ic report. 6ro!i"e" the report layout an" "ataiterator are implemente" )or general use, many "i))erent in"s o) reports may e create" that utiliAe the same layoutan" "ata iterator.

111E Report (a$out

The %eport 5ayout is a ;a!a mo"ule that "e)ines hat columns are a!ailale )or a gi!en report, an" their respecti!e)ormatting options.

report layout must eten" the astract ;a!a class =org.opengs.ar.repor.Iepor,a&ou= an" must "e)ine=aaIo= suclass that un"erstan"s ho to parse report columna#)iel"s )rom report ro oects pro!i"e" y the repo"ata iterator.

The class =org.opengs.ar.repor.e"en.E"enaa,a&ou = is an eample %eport5ayout suclass that"e)ines the a!ailale columns an" )ormatting options )or the !ent 'etail an" Summary reports.

11#E Report Data Iterator

The %eport 'ata Iterator is a ;a!a mo"ule that constructs the list o) recor"s that are to e inclu"e" in the report ase"on the constraints speci)ie" in the report speci)ication 9&5.

report "ata iterator must eten" the astract ;a!a class =org.opengs.ar.repor.Ieporaa= an" pro!i"eimplementations )or the =ge;o(&aa8eraor= an" =geToalaa8eraor= metho"s. It must also in" to aspeci)ic %eport5ayout y pro!i"ing an implementation )or the =geIepor,a&ou= metho".

The class =org.opengs.ar.repor.e"en.E"enea)lIepor = is an eample %eport'ata suclass thatgenerates the !ent 'etail report.



42/60

11%E Report Definition FM(

The )ile =repor.5l= "e)ines the html style use" )or a column "e)ine" in a %eport5ayout. I) also "e)ines speci)icreports y speci)ying hich %eport'ata iterator, an" hich columns ill e inclu"e" in a gi!en report. It also speci)iesthe constraints that are to e applie" to the "ata hich the report ill contain.

Nere is an eample report "e)inition )rom the *repor.5l* )ile )or the =!ent 'etail= reportM

[--

!!! T6e QnaeQ pro")(es a nae 0or 6e reporB re0erence( )n Qpr)"ae.5lQ!!! T6e Q&peQ pro")(es a repor group naeB re0erence( )n Qpr)"ae.5lQ!!! T6e QclassQ spec)0)es 6e repor (aa )eraor use( o generae 6e repor--Iepor nae!


43/60

11'E Availale Report Specifications

Ence a report has een "e)ine" in the =repor.5l= )ile, it can e ma"e a!ailale )or user selection in the e-inter)ace y re)erencing the report name in the =pr)"ae.5l= )ile in the =Iepors= tag.

Nere is an eample report speci)ication )rom the =pr)"ae.5l= )ileM

[-- e0)ne( repors !!! All repors re0erence( 6ere us #e pre(e0)ne( )n Qrepors.5lQ

-- Iepors Iepor nae!


44/60

Appendi>E

AE Support for Microsoft S.( Server

Initial support )or &icroso)t S45 Ser!er has een inclu"e" ith the stan"ar" OpenGTS. &icroso)t S45 Ser!er 200$ ce "onloa"e"#installe" )rom the )olloing &icroso)t epageHsM

6p=//.)croso0.co/sDlser"er/2/en/us/e5press.asp56p=//.)croso0.co/SDlser"er/2/en/us/e5press-(on.asp5

To enale support )or S45 Ser!er, mo"i)y the )ile =coon.con0= accor"ingly to turn o)) support )or &yS45, an" turnsupport )or &icroso)t S45 Ser!erM

--- M)croso0 SK, Ser"er(#.sDl.pro")(er!sDlser"er(#.sDl.6os!local6os(#.sDl.por!31Z3(#.sDl.(#nae!gs(#.sDl.user!gs(#.sDl.passor(!opengs

(#.sDl.url!4(#c=sDlser"er=//$>(#.sDl.6os?=$>(#.sDl.por?(#.sDl.url.(#!$>(#.sDl.url?C(aa#aseNae!$>(#.sDl.(#nae?

The ;'


45/60

Appendi>E

,E Support for Mologogo Capale !hones

OpenGTSinclu"es the ser!let *ologogo.ar* H7e-archi!e to recei!e "ata )rom &ologogo capale phonesHhttpM##.mologogo.com using their =alt+%5= )eature. *ologogo.ar* runs in a ;a!a Ser!let container an" storesrecei!e" "ata in the S45 '< hich can e !iee" through the e inter)ace Hsee *rac.ar*.

Configuring the +7eappconf+ file:

The "e)ault runtime con)iguration )ile =e#app.con0= )ile, an" =coon.con0= )ile, are )oun" in the EpenGTSinstallation "irectory. (or most installations, the "e)ault !alues speci)ie" in this )ile can e le)t as-is.

Shoul" you ish to customiAe this )ile speci)ic )or the =ologogo.ar= ser!let, then copy this )ile to the "irectory=$GTS_HOME/ar/ologogo/@E;-8N/= an" mo"i)y this copy.

,1E Co"piling/Installing the +"ologogo7ar+ *ava Servlet:

To uil" the =ologogo.ar= )ile, run the nt uil" comman" as )ollosM

/zzz>c( $GTS_HOME /usr/local/!pen"TS#$%&%'>an ologogo

The target =ologogo= is a rapper )or ant targets =ologogo.cop)le= an" =ologogo.ar=. The target=ologogo.cop)le= compiles all necessary classes an" con)iguration )iles into the uil" "irectory=$GTS_HOME/#u)l(/ologogo=. The target =ologogo.ar= then creates the *e archi!e* )ile=$GTS_HOME/#u)l(/ologogo.ar=.

Install the =ologogo.ar= )ile per the pache Tomcat installation#con)iguration instructions. Typically, this meanscopying the =ologogo.ar= )ile to the "irectory =$7ATA,8NA_HOME/e#apps/.=.

,#E Creating the +"ologogo+ account in OpenGTS:

+se the comman" line a"min tools to create an account calle" =mologogo= as )ollosM

/zzz>c( $GTS_HOME/usr/local/!pen"TS#$%&%'>#)n/a()n.s6 Accoun -accoun!ologogo -creae

Then, )or each phone, create a ne "e!iceM

/usr/local/!pen"TS#$%&%'> #)n/a()n.s6 e")ce -accoun!ologogo -(e")ce!o -creae/usr/local/!pen"TS#$%&%'> #)n/a()n.s6 e")ce -accoun!ologogo -(e")ce!(a( -creae

Hetc.

,#aE I"portant note regarding +sh+ and +at+ co""and files:

Comman"s en"ing ith =.s6= or =.#a= &+ST e eecute" )rom the OpenGTSinstallation "irectory.ttempting to eecute these comman"s )rom another "irectory may result in a =ClassJot(oun"ception= or=JoClass'e)(oun"rror= error, or similar. HThis means that you must c" to JGTSHBOM&, then eecute thecomman" as =#)n/comman+=

,#E I"portant note for indo7s users:hen using the =.#a= !ersion o) the comman"s in a 'ES in"o, comman" arguments such as-,66o0nt=s't4 must either e enclose" in ?uotes, as in "-,66o0nt=s't4", or e speci)ie" ith acolon instea" o) an e?ual sign, as in -,66o0nt:s't4 .



46/60

,%E Setting the +altR(+ feature on $our Mologogo phone:

Set the =alt+%5= )eature o) your &ologogo capale phone to the )olloing +%5M

=6p=//my+omainname>/ologogo/aa8!i+>U=%eplace my+omainname>ith the "omain name o) your ser!er running Tomcat, an" replace i+>ith the I' o) thespeci)ic phone Hsuch as =o= or =(a(= in this case.Jote that i) you le)t Tomcat running on the "e)ault port 8080, then your +%5 may nee" to e set to the )olloingM

=6p=//&(oa)nnae=RR/ologogo/aa8!)(U =

,'E Testing the installation:

Ence e!erything is set up, loo )or "ata coming in )rom your &ologogo enale" phone.

JoteM+sing the =8!= eyor" attempts to loo up the i"entity o) the "e!ice y using the "e)ault account i" ="ologogo=. I)you ish to use a speci)ic account an" "e!ice i", you can replace the =8!i+>= ith =acc!acct>U(e"!+ev>



47/60

Appendi>E

CE Optional Tale Colu"ns

arious tales ithin the EpenGTS pro!i"e )or a""itional tale columns hich can e use" )orspecial application re?uirements. These tale columns can e enale" y setting speci)ic propery

!alues ithin one o) the a!ailale =.con0= )iles Hie. =con0)g.con0=, etc. The )olloing section"escries the !arious optional tale columns, an" the property name that can e use" to enalethese columns.

)ter a""ing the speci)ie" property to the chosen =.con0= )ile, the tales ill nee" to e up"ate"ith the nely a""e" columns. To up"ate the columns ithin the !arious "ataase tales, run the=(#A()n.pl= comman" as )ollosM


Er, on in"osM

C.!pen"TS#$%&%'>#)n(#7on0)g.#a -a#les=ca

The )olloing comman" ill "isplay the columns "e)ine" ithin each o) the tales use" y EpenGTS HnoteM the ao!e=dbAdmin.pl= or =dbConfig.bat= comman"s are still re?uire" to ensure that the "e)ine" tale columns are alsoa""e" to the actual "ataase taleM

/usr/local/!pen"T

OpenGTS_Config.pdf

Documents

Transcript of OpenGTS_Config.pdf