5/23/2018 Gps Gate Server Protocol 200
1/26
GpsGate Server Protocol Specification
v1.0, v1.1 and v2.0
(last update January 26, 2009)
Copyright Franson Technology AB, 2009
5/23/2018 Gps Gate Server Protocol 200
2/26
Contents
Introduction.................................................................................................................................4Login commands.........................................................................................................................
Login !ith username and pass!ord.......................................................................................Login !ith hard!are I"#I num$er........................................................................................%uccess&ul login message.......................................................................................................#rror message.........................................................................................................................'
(osition data messages................................................................................................................')ser position re*uest..............................................................................................................')ser position update re*uest..................................................................................................+(osition update F-(%........................................................................................................+
(osition update /(-"C......................................................................................................%ample scenarios !ith TC(1I(...............................................................................................TT( position updates.........................................................................................................33
/ps/ate %erer (rotocol 3.3 Frame!or5...............................................................................32/ps/ate (rotocol oer TC(1I(............................................................................................32
Client ersion noti&ication...............................................................................................32Command structure..........................................................................................................32#rror handling..................................................................................................................34
Interrupted commands................................................................................................34Failed to e6ecute command........................................................................................34Command not supported.............................................................................................3Inalid use o& protocol................................................................................................3
/ps/ate (rotocol oer 7"L1TT(.........................................................................................3Incoming commands.................................................................................................................3'
8getupdaterules.....................................................................................................................3+8%end(osition.......................................................................................................................38CreateTrac5-ecorder..........................................................................................................398%aeTrac5ata...................................................................................................................208%end"essage......................................................................................................................238Cmd:ueue%tatus................................................................................................................228Cmd:ueue-eset.................................................................................................................22
8eice-eset........................................................................................................................228(ing.....................................................................................................................................228%etTrac5-ecorder...............................................................................................................228%upports(ro6y"essage......................................................................................................228#ndTrac5............................................................................................................................228(ro6y"essage....................................................................................................................22Custom incoming /ps/ate Command plugins....................................................................22
utgoing commands.................................................................................................................228/prs%ettings.......................................................................................................................228%tartTrac5ing......................................................................................................................228%topTrac5ing......................................................................................................................22
8(oll(osition........................................................................................................................22
Copyright Franson Technology AB, 2009
5/23/2018 Gps Gate Server Protocol 200
3/26
8(lainTe6t............................................................................................................................228%eteiceTrac5-ecorder....................................................................................................22Custom outgoing /ps/ate Command plugins.....................................................................22
Appendi6 3 ;"#A chec5sum calculation.............................................................................2 "essages /ps/ate ;amespace..........................................................................2Appendi6 4 > "essages /ps/ateeice ;amespace...............................................................2'
Copyright Franson Technology AB, 2009
5/23/2018 Gps Gate Server Protocol 200
4/26
ntroduction
I& you plan to integrate a ?trac5er@, please ta5e a loo5 at ?/ps/ate Trac5erne@descri$ed in http11&ranson.com1gpsgateserer1/ps/ateTrac5erne.pd&
This document descri$es communication to /ps/ate %erer using /ps/ate (rotocol. The main purpose isposition updates, status messaging, trac5 reports and con&iguration. %o&t!are and hard!are deelopers areencouraged to use this protocol to integrate !ith /ps/ate.com and /ps/ate %erer.
Communication can $e made oer TC(1I(, )(, TT(, %"% and 7"L1TT(. Full &unctionality is achieedoer TC(1I(.
The protocol can $e used !ith /ps/ate %erer and /ps/ate.com. The address to /ps/ate.com isonline.gpsgate.com port
5/23/2018 Gps Gate Server Protocol 200
5/26
!o"in co##andsThis section contains in&ormation on login commands. This includes $oth commands sent &rom client to sererand possi$le serer replies.
Login with username and password
Syntax:
$FRLIN,domain,username,password*XX
domain Al!ays empty. -esered &or &uture use.
username The /ps/ate.com 1 %erer username
Password (ass!ord !ith a ery simple encryption. Algorithm is descri$ed in Appendi6 2
XX ;"#A chec5sum. Algorithm to calculate sho!n in Appendi6 3
Sample sentence:
$FRLIN,,user1,8IVHF*7A
Login with hardware IMEI number
Syntax:
$FRLIN,domain,username,password*XX
domain should $e the string I"#I
username the deice I"#I num$er e.g. 32
5/23/2018 Gps Gate Server Protocol 200
6/26
Sample sentence:
$FR#E#,11%8*"%
Error message
#rror message. Kill $e returned &rom serer on &ailed login. The serer can also simply close the connection i&some 5ind o& error or timeout condition occur.
Syntax:
$FRERR,err&'ode,err&messa(e*XX
err&'ode Currently only alue is Auth#rror
err&messa(e uman reada$le error message
XX ;"#A chec5sum. Algorithm to calculate sho!n in Appendi6 3
Sample sentence:
$FRERR,Au)Error,+ou a-e pro-ided wron( username or password*18
Position data #essa"es
User position request
)sed to re*uest position data &rom another user in re*uesting users $uddy list. (osition data is sent as /(-"C
sentences &rom serer.Syntax:
$FRR./,username,in)er-a0*XX
username The username in the $uddy list to receie position data &rom. r 8$uddies to get data &romall the users $uddies.
In)er-a0 in seconds. Can hae decimals. 0 G receie all data un&iltered.
XX ;"#A chec5sum. Algorithm to calculate sho!n in Appendi6 3
)sername can $e either one user or the $uddy list. epending on the alue o& ?username@ the &ollo!ing actions
are ta5en
One user An /(-"C sentence is sent right a!ay &rom serer !ith latest 5no!n position, and the )TC time!hen that position !as reported.
"_buddies" An F-(% sentence is sent right a!ay &rom serer &or each user !ith 5no!n position !ith latest5no!n position, and the )TC time !hen that position !as reported.
Notes:
ata is not sent $ac5 to the client &aster than the interal speci&ied.
ata is not sent i& the position hasnEt $een updated.
I& there is any error, the soc5et is closed.
Copyright Franson Technology AB, 2009
5/23/2018 Gps Gate Server Protocol 200
7/26
Sample sentence:
$FRR./,&uddies,1232*7E
User position update request
%ent &rom client that !ants to !rite position data to the serer. This is the same thing as adding a /ps/ate.com%endM plugin to /ps/ate utputs.
Syntax:
$FR4./,da)a)5pe*XX
da)a)5pe Can $e ALL or ;"#A. I& ALL, then all data !ill $e passed through un&iltered. I& ;"#Aonly N/(-"C data is accepted.
XX ;"#A chec5sum. Algorithm to calculate sho!n in Appendi6 3
Sample sentence:
$FR4./,NMEA*78
Position update !"P#S
-eceied &rom serer i& positions &rom ?8$uddies@ are re*uested.
Syntax:
$FRP6#,..MM3mmmm,N,..MM3mmmm,E,AA3a,###3ss,HHH3,..MM++,mmss3dd,udd5*XX
03 ..MM3mmmm Latitude ;"#A &ormatM
02 N#9 emisphere ; or %
0< ..MM3mmmm Longitude "".mmmm ;"#A &ormatM
04 E49 emisphere # or K
0 AA3a Altitude in meters a$oe sea leel
0' ###3ss %peed oer ground in 5nots
0+ HHH3 eading oer ground in degrees
0 ..MM++ date
09 mmss3dd Time )TCM
30 udd5 name o& $uddy this position in&o $elongs to.
33 XX ;"#A chec5sum. Algorithm to calculate sho!n in Appendi6 3
Sample sentence:
$FRP6#,%!113%"12,N,21"!8327"2,E,232,23222,232,72727,1""2!3222,:oan*18
Copyright Franson Technology AB, 2009
5/23/2018 Gps Gate Server Protocol 200
8/26
Position update $P"M%
The position in&ormation sentence is used $oth to send and receie updates.It is receied &rom serer !hen
re*uesting updates &or a single user. It is sent to serer !hen updating position &or a single user.
Syntax:
$;PRM
5/23/2018 Gps Gate Server Protocol 200
9/26
Scenario$ &eceive data fro# fro# t'e server for one user
The &ollo!ing scenario sho!s the &lo! !hen a user connects to the serer and starts receiing position updates&or one user.
5/23/2018 Gps Gate Server Protocol 200
10/26
Scenario$ rite data to server
5/23/2018 Gps Gate Server Protocol 200
11/26
%ame scenario !ith real sample data
5/23/2018 Gps Gate Server Protocol 200
12/26
GpsGate Server Protocol v1.1 %ra#e*or-3.3 o& the protocol adds a &rame!or5 to send commands &rom client to serer, and &rom serer to client.
Note: The client must send a F-O#- sentence a&ter it has receied F-%#% to indicate it supports 3.3
$ps$ate Protocol o)er &%P'IP
Client version notification
%ent $y client to serer to indicate !hich ersion o& /ps/ate %erer protocol it supports.
This sentence is al!ays ans!ered $y a similar &rom the serer !hich contains the serer protocol ersion, theserer name, and the serer ersion.
$FRVER,ma=or,minor,name&and&-ersion*XX
ma=or "aPor ersion o& the protocol used. %hould $e 3
minor "inor ersion o& protocol used. %hould $e 3
name&and&-ersion ;ame o& peer sending this message. #.g. TestClient 3.0. This should al!ays $e aname &ollo!ed $y a ersion num$er.
Note!ere you should hae the real name o& your client plus the ersion num$er.
XX ;"#A chec5sum. Algorithm to calculate sho!n in Appendi6 3
Example:
5/23/2018 Gps Gate Server Protocol 200
13/26
XX ;"#A chec5sum. Algorithm to calculate sho!n in Appendi6 3
or
Syntax:
$FR
5/23/2018 Gps Gate Server Protocol 200
14/26
username The logged in user. This &ield can $e empty.
'ommand the command to $e e6ecuted. #.g. 8getupdaterules
In0ine indicates that the rest o& the &ields in the sentence are arguments to the command.
param1 C N (arameters to the command
XX ;"#A chec5sum. Algorithm to calculate sho!n in Appendi6 3
Co##and ariales
%entence !hich holds a aria$le. Is typically used in com$ination !ith F-C" and F--#T
Syntax:
$FRVAL,name,-a0ue*XX
name ;ame o& aria$le
-a0ue Oalue o& aria$le.
XX ;"#A chec5sum. Algorithm to calculate sho!n in Appendi6 3
Example:
$FRVAL,.is)an'eFi0)er,2232*%7
/rror 'andlin"I& a command &or some reason cannot $e e6ecuted F-#-- is returned and not F--#T. The reason can $e thatthe there is some 5ind o& e6ecution error, the command is not supported, or there is a protocol error. KhenF-#-- is returned the client should assume no data has $een a&&ected on the serer. The protocol is transaction
$ased.
In all cases e6pect !hen there is a protocol or connection error the e6change o& commands can continue $et!eenthe serer and the client.
Interrupted commands
I& seeral F-C" is sent !ithout the preious one $eing &inished, the peer e6ecuting the command should roll$ac5 the current command and start e6ecuting the ne! command. #6ample I& t!o F-C" is receied in a ro!,
the last F-C" should $e e6ecuted.
!ailed to execute command
I& a F-C" &ails to e6ecute a F-#-- sentence !ith code ?Cannot#6ecute@ is returned. The client is &ree toe6ecute a ne! command a&ter receiing F-#--.
Sample communication:
I& the client tries to sae data to a trac5 recorder !hich doesnEt $elong to the logged in user.
5/23/2018 Gps Gate Server Protocol 200
15/26
ound or user*>
%ommand not supported
A client or serer that implements 3.3 o& the /ps/ate protocol does not need to implement any o& thecommands see $lo! &or a list o& supported commandsM descri$ed in this document. For commands that arenEtsupported a F-#-- !ith code ?;ot%upported@. The client is &ree to e6ecute a ne! command a&ter receiing thiserror message.
Sample communication:
The command ?8dummy@ is not supported $y the peer in this case the sererM.
5/23/2018 Gps Gate Server Protocol 200
16/26
A post can include any num$er o& commands. "ost commands re*uires you to login, there&or you should start!ith a 8Login command.
'md name@G&Lo(inG9nmea9d9$FRVALd9d9sernamed9d9user1d9nmea9nmea9d9$FRVALd9d9P4d9d98IVHFd9nmea9
'md9
;ote that the pass!ord uses a simple encryption algorithm descri$ed in Appendi6 2
"ost commonly you then e6ecute the 8%end"essage command. )se a /ps/ate /eneric eice deicemapper. %end status messages to the /ps/ateeice namespace. But you can e6ecute any command supported
$y your /ps/ate %erer installation.
A sample dump including TT( headerM. From client to serer. In this sample chun5ed data is used, &i6ed siQeis also o5. ;ote the path 1/ps/ate1
P6#/ ;ps;a)e H//P131Hos)J 0o'a0os)J722/ranserCEn'odin(J 'unDedEpe')J 122C'on)inue
5/23/2018 Gps Gate Server Protocol 200
17/26
updates to the serer.
The alues typically include distance interal, time interal, speed and direction changes.
The rules should $e -ed $y the client. -ules not understood should simply $e ignored.
Sample communication:
5/23/2018 Gps Gate Server Protocol 200
18/26
$FR#E#,11%"2*"F
$FRVER,1,1,/es)
5/23/2018 Gps Gate Server Protocol 200
19/26
$FR
5/23/2018 Gps Gate Server Protocol 200
20/26
*Sa)e&rac+,ata
GpsGate Server 1.2 build 383 or later
The command ?8%aeTrac5ata@ saes a range o& positions to a trac5 recorder created $y?8CreateTrac5-ecorder@. ?8%aeTrac5ata@ cannot $e used to store data to the ?li&e trac5@.
;ote that the serer has trac5 recorder settings that !ill limit the num$er o& saed positions in the trac5depending on ho! the settings are made. %ee ?8getupdaterules@ &or more in&ormation.
I& the command &ails no positions are stored into the trac5. A F--#T returned &rom the serer indicates thepositions has $een success&ully saed to the serer trac5.
Syntax:
$FR
5/23/2018 Gps Gate Server Protocol 200
21/26
*SendMessage
GpsGate Server v2.0 and later.
The command ?8%end"essage@ is used $y a client send geo coded messages to the serer.The alues typically include status in&ormation &rom a ehcile, li5e pressure, temperature, engine on1o&&, analarm signal etc.
Sa#ple co##unication to GpsGate essa"e a#espace$
5/23/2018 Gps Gate Server Protocol 200
22/26
*%md-ueueStatus
*%md-ueue"eset
*,e)ice"eset
*Ping
*Set&rac+"ecorder
*SupportsProxyMessage
*End&rac+
*ProxyMessage
%ustom incoming $ps$ate %ommand plugins
7ut"oin" co##ands
*$prsSettings
*Start&rac+ing
*Stop&rac+ing
*PollPosition
*Plain&ext
*Set,e)ice&rac+"ecorder
%ustom outgoing $ps$ate %ommand plugins
"ore in&ormation http11&ranson.com1&orum1topic.aspT(IC8IG09
Copyright Franson Technology AB, 2009
http://franson.com/forum/topic.asp?TOPIC_ID=8098http://franson.com/forum/topic.asp?TOPIC_ID=8098http://franson.com/forum/topic.asp?TOPIC_ID=80985/23/2018 Gps Gate Server Protocol 200
23/26
8ppendi5 1 /8 c'ec-su# calculation
>LEHEX'O 'O 9 ? 'O QAQ C 12 J 'O Q2QO
u is a 'arS arra5 wi' 'on)ains )e NMEA sen)en'e wi)ou) )rai0in('e'Dsum3 E3(3 G$FRLIN,,user1,8IVHFG and G*7AG wi00 e added
u&in is an inde )o )e 0as) ree posi)ion in )e uer
in) 'e'Dsum @ 2Tin) inT
orin @ 1T in u&inT inOU
'e'Dsum @ uinSTW
uu&inS @ Q*QTuu&inS @ NI>>LEHEX'e'Dsum 99 "O 2OTuu&inS @ NI>>LEHEX'e'Dsum 2OT
Copyright Franson Technology AB, 2009
5/23/2018 Gps Gate Server Protocol 200
24/26
8ppendi5 2 Pass*ord al"orit'# in C:
pri-a)e s)rin( m&In-er)#)rin(s)rin( s)r/oIn-er)OU #)rin(>ui0der ui0der @ nu00T
i s)r/oIn-er) @ nu00O U ui0der @ new #)rin(>ui0derOT
in) iLen() @ s)r/oIn-er)3Len()T
or in) iInde @ iLen() C 1T iInde 9@ 2T iIndeCCO U 'ar ' @ s)r/oIn-er)iIndeST
i ' 9@ Q2Q ' @ Q?QO U ui0der3Append'arO? C ' C Q2QO Q2QOOT W e0se i ' 9@ QaQ ' @ QBQO U ui0der3Append'arOQBQ C QaQO C ' C QaQO QAQOOT W e0se i ' 9@ QAQ ' @ QYQO U ui0der3Append'arOQYQ C QAQO C ' C QAQO QaQOOT W W W
re)urn ui0der @ nu00 ui0der3/o#)rin(O J nu00TW
En'r5p)ion samp0eJ G'oo0nessG C9 GHHVM6LLXG
Copyright Franson Technology AB, 2009
5/23/2018 Gps Gate Server Protocol 200
25/26
8ppendi5 ; < essa"es GpsGate a#espace"essage aria$les GpsGatenamespace. "essages in this namespace !ill $e saed on the serer !ithout passinga eice "apper. The alues $elo! are mapped into the /ps/ate "essage ;amespace Appendi6
5/23/2018 Gps Gate Server Protocol 200
26/26
8ppendi5 = < essa"es GpsGateevice a#espace"essage aria$les GpsGateDevicenamespace. "essages in this namespace !ill use the eice "apper &or?/ps/ate /eneric eice@.
Data type Name Unit
#5s)em3>oo0ean #wi)'1 swi)'#5s)em3>oo0ean #wi)' swi)'#5s)em3>oo0ean #wi)'! swi)'#5s)em3>oo0ean #wi)'" swi)'#5s)em3>oo0ean #wi)' swi)'#5s)em3>oo0ean #wi)'% swi)'#5s)em3>oo0ean #wi)'7 swi)'#5s)em3>oo0ean #wi)'8 swi)'#5s)em3>oo0ean #wi)'? swi)'
#5s)em3>oo0ean #wi)'12 swi)'#5s)em3>oo0ean #wi)'11 swi)'#5s)em3>oo0ean #wi)'1 swi)'#5s)em3>oo0ean #wi)'1! swi)'#5s)em3>oo0ean #wi)'1" swi)'#5s)em3>oo0ean #wi)'1 swi)'#5s)em3>oo0ean #wi)'1% swi)'#5s)em3>oo0ean >u))on1 u))on#5s)em3>oo0ean >u))on u))on#5s)em3>oo0ean >u))on! u))on#5s)em3>oo0ean >u))on" u))on#5s)em3.ou0e Ana0o(1 none#5s)em3.ou0e Ana0o( none
#5s)em3.ou0e Ana0o(! none#5s)em3.ou0e Ana0o(" none#5s)em3.ou0e Ana0o( none#5s)em3.ou0e Ana0o(% none#5s)em3.ou0e Ana0o(7 none#5s)em3.ou0e Ana0o(8 none
Copyright Franson Technology AB, 2009
Top Related