TrackBoxes do a plain HTTP-POST  (no HTTPs*) to push their box location and TrackPing data to your server.

TrackBox expects a HTTP-200 reply if your server was able to receive the data. As long as it does not receive a HTTP-200 reply, the TrackPing data will be stored and retried endlessly every 10 seconds. If your server replies HTTP-503 "Service Unavailable" the next call will be delayed for one full minute.

URL/Forwarding

Your server can:

1. Be directly called by a track box. The URL of this must be configured on the Track Box manually, check configuration for Passive and Active. The base part includes every character up to and including the "?". It can be a maximum of 89 characters including the "?".
2. Be called by our server in a simple call forwarding scheme. This is used if the data should also be available for time keeping purposes. The user must configure forwarding in RR12 timing module. Be aware, that a HTTP 503 reply to our server will just delay the retry of the current call from our server to yours using expontial backoff. New data from that box and data from other boxes will still be forwarded immediately. If a call is repeatedly answered with a 503 status code for ~24 hours (~30 calls), it will be droped by our server.

Typical Call with moving position and TrackPings

/trackping?v=2&custId=10000&boxId=T-20034&boxType=PTrack&boxName=NikiasV10EU%5FTESTBOX&boxTime=210827T110003Z&boxPos=M,49.05802,008.47133,105&index=1&count=10&dataIndex=0&auth=13953
ZCTAA66;22;-40;15;92832;;;;20;-90;\r 
ZCTAA55;22;-42;19;157302;;;;18;-80;\r 
ZCTAA53;22;-53;15;113108;;;;17;-77;\r 
ZCTAA62;22;-42;21;91281;;;;16;-76;\r 
ZBAAA48;15;-71;5;80109;;;;13;-77;\r 
ZCTAA66;22;-50;15;92832;;;;11;-70;\r
ZCTAA55;22;-42;19;157302;;;;10;-76;\r
ZCTAA53;22;-63;15;113108;;;;9;-70;\r
ZCTAA62;22;-42;21;91281;;;;6;-50;\r
ZBAAA48;15;-71;5;80109;;;;3;-77;\r
\r

HTTP Post Parameters

boxPos=U
boxPos=S,49.01469,008.52240
boxPos=M,49.01469,008.52240,226
boxPos=T,49.01469,008.52240,226
boxPos=X,49.01469,008.52240,226

HTTP Post Body TrackPing Record

Multiple TrackPings of a transponder are reduced to one TrackPing record. See data reduction algorithm below for more details. Every line represents one TrackPing record and is delimited by a <carriage return>. The last is always an empty line with one <carriage return>. This indicates the end of the call and is the only content sent in an empty TrackPing call.

Each row seperated by semi-colon represents one data field. Data fields can be empty meaning that they default to 0 if they are numeric.

[transponderId];[peakDiffTime];[peakRSSI];[hits];[peakIndex];[flags];[latitudeDiff];[longitudeDiff];[minDiffTime];[minRSSI];[orderID]\r

Data fields:

Optional values can be left empty, but semicolons must always be present to assure future version compatibility. A typical case would be data from a non moving timing system with flags and all following values missing.

HTTP Post Responce Body

A server can call commands on the box by putting them into the HTTP Post Response Body. See status call documentation for formating and possible commands.

Example (Stationary Timing System):

[transponderId];[peakDiffTime];[peakRSSI];[hits];

/trackping?v=2&custId=012345&boxId=D-5061&boxType=Timing&boxName=Start&boxTime=171024T144243Z&boxPos=S,49.01464,008.52243&count=2
224;62.345;-63;55;;;;;;\r
3465;22.123;-64;76;;;;;;\r
\r

Example (Moving->Traveling TrackBox):

/trackping?v=2&custId=012345&boxId=T-20061&boxName=test&boxTime=171024T144243Z&boxPos=M,49.01469,008.52240,226&count=4
ZBAAA48;12;-34;6;79834;M;1;-1;19;-40\r
ZCTAA55;12;-44;18;156766;M;1;-1;15;-60\r
ZCTAA62;16;-72;15;90739;T;1;-1;11;-80\r
ZCTAA53;13;-77;5;112570;T;1;-1;8;-85\r
\r

Example (Moving TrackBox, no new GPS fix at the begining)

/trackping?v=2&custId=012345&boxId=T-20061&boxName=test&boxTime=171024T144219Z&boxPos=M,49.01470,008.52239,225&count=7
ZCTAA66;24;-45;31;92226;X;-10;;18;-50\r
ZCTAA55;23;-33;31;156696;X;-10;;16;-40\r
ZCTAA53;24;-45;39;112501;X;-10;;13;-60\r
ZCTAA62;24;-46;40;90675;X;-10;;13;-50\r
ZBAAA48;23;-41;15;79799;X;-10;;11;-45\r
ZCTAA66;9;-18;17;92254;M;;;9;-18\r
ZCTAA55;10;-8;12;156723;M;;;8;-28\r
\r

Example (Passive TrackBox, no GPS)

http://rrsproxy.raceresult.com:48080/v1/trackping?v=2&custId=10000&boxId=T-20003&boxTime=200129T110044Z&boxPos=U&cell=B876&lac=118D703&index=603&count=8&auth=04883
8787;1.7;-55;3;;U;;;;;12345\r
8788;1.6;-55;2;;U;;;;;12345\r
8789;1.6;-55;2;;U;;;;;12345\r
8790;1.5;-55;3;;U;;;;;12345\r
8791;1.5;-55;2;;U;;;;;12345\r
8792;1.4;-55;3;;U;;;;;12345\r
8793;1.4;-55;2;;U;;;;;12345\r
8794;1.3;-55;2;;U;;;;;12345\r
\r

Example (empty call):

/trackping?v=2&custId=012345&boxId=T-20061&boxName=test&boxTime=171024T144245Z&boxPos=M,49.01469,008.52240,226&count=0
\r

HTTP Post Header

POST HTTP/1.1
Accept: */*
User-Agent: QUECTEL_MODULE
Connection: Keep-Alive
Content-Type: application/x-www-form-urlencoded

*HTTPS/AUTH Parameter

HTTPs is no option for multiple reasons:

Plain HTTP is allowed by most networks around the world.

HTTPs would need additional negotiation leading to increased battery drain. TrackBoxes only have limited capacity and we want it to run for 3 days. It completely shuts down its communication, as long as it is not transmitting anything. For placing a call it connects to the network and disconnect within 100ms again. Communication is what costs energy, it must be done as quick as possible.  

Furthermore: Whats missing in this diagram, is that one also needs to contact the certifying third party server to verify the certificate.

Furthermore HTTPs does not really give us a big benefit as it is actually not authenticating the calling client, but your server. Encryption would be nice, but the data is not really worth anything without context.

We need to make sure not to open up the server for everyone to call and push data. Thats why you can authenticate the calling device using the auth parameter. Contact RACE RESULT to obtain the public key and algorithm with which you check wether the call is coming from a genuine RACE RESULT device or not.

The USB Tag Reader can be implemented using a DLL file specifically written for working with RACE RESULT transponders. If you plan to implement the USB Tag Reader please contact us via support@raceresult.com to request access to the DLL file

int NewTagReader(int vid, int pid)

int TRConnect(int tagReaderID)

int TRDisconnect(int tagReaderID)

int TRDoReaderAction(int tagReaderID, int action)

char* TRSendCommand(int tagReaderID, int cmd, char* data)

int TRSetReaderPower(int tagReaderID, int powerLevel)

*char TRGetSerialNumber(int tagReaderID)

*char TRGetSerialNumber(int tagReaderID)

HMODULE handle = LoadLibrary(TEXT("C:\\Users\\example\\Documents\\tagReaderDLL\\tagReader.dll"));

typedef int(NEWTAGREADERFUNC)(int, int);

NEWTAGREADERFUNC *pNEWTAGREADERFUNC = (NEWTAGREADERFUNC *)::GetProcAddress(handle, "NewTagReader");

tagReaderID = (*pNEWTAGREADERFUNC)(0xe6a,0x350);

#include <windows.h>
#include <iostream>

using namespace std;

typedef int(NEWTAGREADERFUNC)(int, int);
typedef int(CONNECTFUNC)(int);
typedef int(DOREADERACTIONFUNC)(int, int);
typedef int(GETCHIPIDFUNC)(int);

int main(int argc, char **argv)
{

   HMODULE handle = LoadLibrary(TEXT("C:\\Users\\example\\Documents\\project\\tagReader.dll"));

   if (NULL == handle)
   {
      cout << "Could not load library" << endl;
      return -1;
   }

   NEWTAGREADERFUNC *pNEWTAGREADERFUNC = (NEWTAGREADERFUNC *)::GetProcAddress(handle, "NewTagReader");
   int tagReaderID;

   if (pNEWTAGREADERFUNC)
   {
      tagReaderID = (*pNEWTAGREADERFUNC)(0xe6a, 0x350);
      cout << tagReaderID << endl;
   }
   else
   {
      return -1;
   }

   CONNECTFUNC *pCONNECTFUNC = (CONNECTFUNC *)::GetProcAddress(handle, "TRConnect");
   int connect;

   if (pCONNECTFUNC)
   {
      connect = (*pCONNECTFUNC)(tagReaderID);
      cout << "successfully connected: " << connect << endl;
   }

   DOREADERACTIONFUNC *pDOREADERACTIONFUNC = (DOREADERACTIONFUNC *)::GetProcAddress(handle, "TRDoReaderAction");
   int actionResult;

   if (pDOREADERACTIONFUNC) {
      actionResult = (*pDOREADERACTIONFUNC)(tagReaderID, 7);
      cout << "actionResult is: " << actionResult << endl;
   }

   GETCHIPIDFUNC *pGETCHIPIDFUNC = (GETCHIPIDFUNC *)::GetProcAddress(handle, "TRGetChipID");

   if (pGETCHIPIDFUNC) {
      char *chipID = (*pSENDCOMMANDFUNC)(tagReaderID);
      cout << "chipID is: " << chipID << endl;
   }

   return 0;
}