Custom device integration with GpsGate protocol
This article describes the requisites when creating a custom tracker integration to allow client-server communication with GpsGate using HTTP or HTTPS.
Tracker-server communication specs
When sending reports using HTTP / HTTPS the tracker 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 tracker 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.0000,N,3530.0000,E,34.6,234.00,90.0,170109,
120523.65,1
Example for HTTPS
https://demo.server.com:443/comGpsGate/protocols/gpsgate/?cmd=$FRCMD,353857014816785,_SendMessage,,4748.0000,N,3530.0000,E,34.6,234.00,90.0,170109,
120523.65,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.
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 (deprecated). | 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 (deprecated). | 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 asset 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 the 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
Device Mapper
The main function of the Device Mapper is assigning tracker 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.