gps gate server protocol 200

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


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



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'



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/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


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


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.


)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.



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.


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



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


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.


10/26

Scenario$ rite data to server


11/26

%ame scenario !ith real sample data


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.


Example:


13/26


or

Syntax:

$FR


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


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.


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.


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.


The command ?8dummy@ is not supported $y the peer in this case the sererM.


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


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.



18/26

$FR#E#,11%"2*"F

$FRVER,1,1,/es)


19/26

$FR


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


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$


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

http://franson.com/forum/topic.asp?TOPIC_ID=8098http://franson.com/forum/topic.asp?TOPIC_ID=8098http://franson.com/forum/topic.asp?TOPIC_ID=8098


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



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



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


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


gps gate server protocol 200

Documents