Custom device integration with GpsGate protocol

This article describes the requisites when creating a custom device integration to allow client-server communication with GpsGate using HTTP or HTTPS.

Device-server communication specs

When sending reports using HTTP / HTTPS the device has to send the data in the following format:

Send message URL

_SendMessage is sent by the tracker when it should send a position according to any event on the tracker, like when a button is being pressed, or a motion sensor is activated. Any number of status inputs can be added to the end of _SendMessage. 

The URL to send a message has the following structure:

transport://hostname:port/comGpsGate/protocols/gpsgate/?cmd=$FRCMD,IMEI,_SendMessage,,DDMM.mmmm,N,DDMM.mmmm,E,AA.a,SSS.ss,HHH.h,DDMMYY,hhmmss.dd,valid,var=value

Field Description
transport HTTP or HTTPS
hostname The name/IP address of the server
port 80 for HTTP / 443 for HTTPS
comGpsGate/protocols/gpsgate/?cmd= Resource's path
$FRCMD A command to send to the server for the send message instruction
IMEI The IMEI number of the device that is used for authentication. 
_SendMessage Input specifying when a position must be sent to the server.
DDMM.mmmm Latitude (NMEA format) 
<N|S> Hemisphere N or S
DDMM.mmmm  Longitude DDMM.mmmm (NMEA format) 
<E|W> Hemisphere E or W 
AA.a Altitude in meters above sea level
SSS.ss  Speed over ground in knots
HHH.h  Heading over the ground in degrees 
DDMMYY date 
hhmmss.dd  Time (UTC)
valid  1 if a valid fix. 0 if not a valid fix.
var=value Status input. You can specify more than one input to use, for example, SosButton=1,BatteryLow=0, etc. See the list of inputs section below.

Example for HTTP

http://demo.server.com:80/comGpsGate/protocols/gpsgate/?cmd=$FRCMD,353857014816785,_SendMessage,,4748.00000,N,3530.00000,E,34.6,234,90,170109,
120523.657,1

Example for HTTPS

https://demo.server.com:443/comGpsGate/protocols/gpsgate/?cmd=$FRCMD,353857014816785,_SendMessage,,4748.00000,N,3530.00000,E,34.6,234,90,170109,
120523.657,1 

Testing the URL

If you want to test your HTTP/HTTPS integration, simply copy-paste the URL content into your browser to see the response.

mceclip0.png

Response

The response body contains the server reply $FRRET, the IMEI of the authenticated user, the command used, and a checksum code.

For example, the server will respond: $FRRET,IMEI,_SendMessage 

 

Inputs

The protocol has a set of custom inputs. Those can be mapped using the device mapper on the server using GpsGate TrackerOne or GpsGate Generic Device types. Add status inputs to the end of _SendMessage commands sent to the server.

Variable name Type Mandatory Description Example

Analog1-32

double No A custom input to be mapped on the server. Possible values: Analog1 to 34 (GpsGate Generic Device) Analog1=45.7

BatteryLow

boolean Yes sent to the server when the battery is low.  BatteryLow=1

Button1-4

 boolean  No Boolean input to store two-state button-like signal status. Possible values: Button1 to 4 Button1=1 

CellID

number No A number that specifies the CellID of the cellular network CellID=12345

ChatMessage

string No A custom text message to use with the Dispatch plugin. ChatMessage=helloWorld!

DriverID

string No A text field to be used for driver identification purposes. DriverID=123456789ABC

HDOP

number No A number field to express horizontal dilution of precision. HDOP=123456

JobAssignmentState

string No A custom text message to use with the Dispatch plugin. JobAssignmentState=Accepted

LAC

MCC

MNC

number No A number to express Mobile Country Code (MCC), Mobile Network Code (MNC), Location Area Code (LAC) LAC=001

Motion

boolean No This input should be included if the tracker starts tracking based on motion. On the server, this input can optionally be connected to alarms of various kinds. Motion=1

SmsMessage

string No A custom string field to be used to store SMS message content. SmsMessage=hello World!

SosButton

boolean No This input is to be mapped to the SOS event on the server. SosButton=1

Speed

number Yes This input is used to reflect the vehicle speed in m/s. Speed=5.56 

Switch1-16

 boolean  No

Boolean input to store two-state switch-like signal status. Possible values: Switch1 to 16 (GpsGate Generic Device)

 Switch1=1

Text1-30

string No A custom text message. Possible values: Text1 to 30 (GpsGate Generic Device) Text1=Hello

Odometer

double No If the tracker supports odometer (distance calculation), use this input to send it to server. The value can either be absolute or a delta value from the last odometer report. The Odometer input is scaled on the server.  Odometer=1023445.3

 

Error handling

If a command for some reason cannot be executed FRERR is returned and not FRRET. The reason can
be that there is some kind of execution error, the command is not supported, or there is a protocol error. When FRERR is returned the client should assume no data has been affected on the server. The protocol is transaction-based. In all cases except when there is a protocol or connection error the exchange of commands can continue between the server and the client.

$FRCMD is always responded to by $FRRET or $FRERR.

Error Description
200 (OK) The request was processed successfully
400 (BadRequest) Wrong request, cannot be executed
401 (Unauthorized) Authentication or login error
403 (Forbidden) Authorization error
404 (NotFound) Default HttpCode when no another HttpCodes can be triggered (except 200 and 500)
500 (InternalServerError) Internal server error, contact the administrator (default HttpCode when no another HttpCodes can be triggered)
501 (NotImplemented) Request is not supported
503 (ServiceUnavailable) Internal server error, contact the administrator

 

Error example:

Client > $FRCMD,0802,_dummy,Inline*6C

Server > $FRERR,NotSupported,_dummy not supported*66

mceclip0.png

Device Mapper

The main function of the Device Mapper is assigning device inputs to variables. These variables are used on screen, event rules, reports and more.

Read more about the device mapper here.

Device Mapper Scripting

Device mapper scripting lets GpsGate variables be assigned the result of a user-defined script. This allows you to create more complex mappings between variables.

Read more about device mapper scripts here.