Basics

Freematics Hub is a free telemetry data exchange service which is highly efficient and easy to work with from systems of any footprint. The design goal is to seamlessly connect multiple telemetry data logging devices with software that deals with telemetry data, web-based, server-side or Apps running on mobile devices.

Freematics Hub receives data from remote data logging devices, caches the data in large capacity, and supply the data as requested. As it caches data generated from a whole trip (up to 12 hours), data logging devices and requesting peers can work at different pace without missing any data samples. Data from multiple sources can also be aggregated with least efforts. 15203164_633189226862766_2006367074178906345_nData are transmitted from device as UDP datagrams or HTTP transactions and available to peers requiring them by simple HTTP/REST APIs.

The reference code for a data feed device is telelogger_sim5360 (Arduino sketch for Freematics ONE with SIM5360 3G module) or telelogger_esp8266 (Arduino sketch for Freematics ONE with ESP8266 WIFI module).

Demo code for a web-based vehicle tracker built on Freematics Hub is available here which works like the screenshot. A server stub is required for cross-domain AJAX access to Freematics Hub from your domain in browser. The stub can be developed to perform user authentication, persistent data storage and a lot more.

 

Notifying

The device notifies server of events like start/end of a data transmission session. An event ID is a numeric value which indicates the type of event.

Login Event (Event ID: 1)

This event indicates the data transmission session is about to start and some identifications are submitted including Vehicle identification number (VIN) is used as A unique identifier.

Logout Event (Event ID: 2)

This event indicates the data transmission session is about to end, most likely as a trip is over.

UDP Request

A typical notifying request by UDP has the payload like following.

0#EV=1,SK=TEST_SERVER_KEY,TS=39539,VIN=A1JC5444R7252367*XX

0# indicates that a new Feed ID is requested which is used for subsequent live data transmission. If a Feed ID is already obtained, replace 0 with the actual ID.

EV=1 indicates a login event

SK=… specifies server key

TS=… the current timestamp (normally the device timer counter)

VIN=… speicfies the VIN which should be unique and is used to allocate Feed ID

*XX is the checksum (in hex) of all previous bytes

UDP Reply

After server received a UDP request, it replies a UDP datagram as reply. A typical reply is like following.

1#EV=1,RX=n,TS=39539*X

EV=n is the event ID from request

TS=… is the timestamp from the request

RX=… is the number of received requests/data transmissions

*XX is the checksum (in hex) of all previous bytes

HTTP Request Format

Alternatively, notifying request can be sent by HTTP or more secure HTTPs request with the following request format. The parameters are identical to that with UDP.

http[s]://hub.freematics.com/<SERVER KEY>/notify/[Feed ID]?EV=<event ID>&TS=<timer counter>&VIN=<VIN>

HTTP Response on success

{"result":"done","id":n}

n is an arbitrary integer number which is used for subsequent data feeding referred as Feed ID.

HTTP Response on error

{"result":"failed","error":"Invalid server key"}
{"result":"failed","error":"Invalid VIN"}

Feeding Data (from device to server)

A data logging device collects telematics data and feeds them to Freematics Hub by sending UDP datagrams or continuous HTTP GET or POST requests. The feeding sequence is straight-forward as following and reference code is available to demonstrate the process.

  1. Notifying server that a data feed is going online
  2. Sending data to server (repeating)
  3. Notifying server that a data feed is going offline

 

Feeding live data (UDP)

Using UDP to feed live data is the simplest and most efficient way. Please refer to this for how UDP datagram is formed to transmit live data.

 

Feeding live data (HTTP GET)

Using a HTTP GET request to feed live data is straight-forward and easy for testing (even from browser). Multiple PID and value pairs are accepted as URL arguments for one request. PID numbers are in hex format and values are in decimal format (integer, float or semicolon separated values). All data values submitted are treated as on-the-spot with current time stamp.

Request URL

http[s]://hub.freematics.com/<SERVER KEY>/push/[FEED ID]?TS=[timestamp]&[pid1]=[value1]&[pid2]=[value2]...

Please refer to Freematics Packed Data Format for details about PID/value pair.

Response (success)

{"result":n}

n is the number of accepted PID/value pairs.

Response (erroneous)

{"result":"failed","error":"Invalid server key"}
{"result":"failed","error":"Invalid FEED ID"}

 

 

 

Feeding data stream (POST)

This is to submit a stream of time stamped data with a HTTP POST request. The payload is in Freematics Packed Data Format. All data values are time stamped by data logging device.

Request URL

http[s]://hub.freematics.com/[SERVER KEY]/post/[FEED ID]

Post Payload

The payload is directly and strictly the data stream represented in Freematics Packed Data Format which is a series of time stamped data type and value pairs.

Response (success)

{"result":n}

n is the number of accepted data PID/value pairs.

Response (erroneous)

{"result":"failed","error":"Invalid server key"}
{"result":"failed","error":"Invalid FEED ID"}

 

Fetching Data (from server)

The software (web based, server side or App) which illustrate, process, analyze or store data, send HTTP/HTTPs requests to Freematics Hub to fetch the data with a obtained Feed ID.

 

Obtaining list of data feeds

Request URL

http[s]://hub.freematics.com/<SERVER KEY>/channels

Response

The response is an object array in which each element is corresponding to a data feed.

{"channels":[
{"id":"1","vin":"A1JC5444R7252367","recv":26253,"tick":505269,"age":2250,"flags":1,"csq":220},
{"id":"2","vin":"A1JC5236R3243232","recv":432432,"tick":1205269,"age":1125,"flags":1,"csq":250},
...
]}

Properties:

  • id – Feed ID
  • vin – vehicle identification number
  • recv – data received (bytes) during current session/trip
  • tick – device system clock tick (ms)
  • age – time elapsed (ms) since latest data entry received till it’s requested
  • csq – signal strength index (in 0.1dB)
  • flag – 1 for driving/active, 0 for parked/inactive

Fetching instant data

This is the simple way to request up-to-date data of a data feed.

Request URL

http[s]://hub.freematics.com/<SERVER KEY>/get/[FEED ID]

Response

The response contains statistic data and the requested instant data queue represented as an array of PID/value pairs. PID is in decimal instead of hexadecimal. Value is in string format. Following is a response example.

{"stats":{"recv":72624,"elapsed":3037,"age":1544,"flags":1},
"data":[[10,"-33.717677"],[11,"151.160207"],[12,"171"],[13,"0"],[15,"8"],[16,"5163220"],[17,"291116"],
[36,"1290"],[48,"69446"],[260,"74"],[261,"63"],[268,"4375"],[269,"87"],[271,"97"],[273,"65"]]
}

Operation Sequence

The basic sequence of fetching instant data is like following.

  1. Getting data feed list (containing ID and some properties of a data feed)
  2. Fetching instant data (with Feed ID)
  3. Parsing response JSON payload and deal with the data
  4. Repeating 2 and 3

 

Fetching data queue (history data)

A data queue is a serious of data with time stamp. The request for a data queue can specify time stamp range or time to rollback. The data is organized as a 2-dimension JSON array. This is useful for rendering a data chart or route on map with complete data samples, so the line on chart or the shape of route looks smooth. This is also necessary for caching or storing data from a data feed.

Request URL

http[s]://hub.freematics.com/<SERVER KEY>/pull/<FEED ID>?[ts=<ms>][&endts=<ms>][&rollback=<ms>]

Request Arguments

  • id – Feed ID
  • ts is used to specify start time of requested data queue. The time is presented in device system clock tick in ms.
  • endts is used to specify end time of requested data queue. The time is presented in device system clock tick in ms.
  • rollback sets start time with relative time in ms without need for knowing device local clock tick. For example, rollback=60000 indicates requesting for data from 1 minute ago.

Response (success)

The response contains statistic data and the requested data queue represented as an array of 3-element sub-array (timestamp, PID, data). Timestamp is from device system clock in ms. PID is in decimal instead of hexadecimal. Value is in string format. A response example is shown below.

{"stats":{"tick":93385265,"recv":3754583,"elapsed":93365,"age":546,"flags":1},
"data":[[92690810,269,"71"],[92690810,260,"74"],[92690810,273,"68"],[92690810,261,"55"],
[92690810,32,"4/1/97"],[92690881,36,"1290"],[92692981,48,"1765263"],[92693184,268,"2500"],
[92693184,269,"71"],[92693184,260,"74"],[92693184,273,"65"],[92693184,271,"97"],[92693184,32,"4/1/97"],
[92693231,16,"3395000"],[92693231,10,"-33.721328"],[92693231,11,"151.163440"],[92693256,36,"1280"],
[92694010,268,"2500"],[92694010,269,"71"],[92694010,260,"78"],[92694010,273,"68"],[92694010,261,"55"],
[92694010,32,"4/1/97"],[92694081,36,"1290"],[92694809,268,"2500"],[92694809,269,"71"],[92694809,260,"74"],
[92694809,273,"68"],[92694809,271,"97"],[92694809,32,"4/1/97"],[92694880,36,"1290"],[92695609,268,"2500"],
[92695609,269,"71"],[92695609,260,"74"],[92695609,273,"65"],[92695609,261,"55"],[92695609,32,"4/1/97"],
[92695680,36,"1290"],[92698173,48,"1765362"],[92698354,268,"2500"],[92698354,269,"71"],
[92698354,260,"78"],[92698354,273,"65"],[92698354,271,"97"],[92698354,32,"4/1/97"],
[92698401,16,"3395500"],[92698401,10,"-33.721328"],[92698401,11,"151.163440"],[92698426,36,"1290"],
[92699224,268,"2500"],[92699224,269,"71"],[92699224,260,"74"],[92699224,273,"65"],[92699224,261,"55"],
[92699224,32,"4/1/97"],[92699294,36,"1290"],[92700001,268,"2500"],[92700001,269,"71"],[92700001,260,"78"],
[92700001,273,"65"],[92700001,271,"97"],[92700001,32,"4/1/97"],[92700071,36,"1290"],[92700823,268,"2500"],
[92700823,269,"71"],[92700823,260,"78"],[92700823,273,"68"],[92700823,261,"55"],[92700823,32,"4/1/97"],
[92700894,36,"1280"],[92703366,48,"1765460"],[92703547,268,"2500"],[92703547,269,"71"],
[92703547,260,"78"],[92703547,273,"68"],[92703547,271,"97"],[92703547,32,"4/1/97"],
[92703594,16,"3400000"],[92703594,10,"-33.721328"],[92703594,11,"151.163440"],[92703619,36,"1290"],
[92704396,268,"2500"],[92704396,269,"71"],[92704396,260,"74"],[92704396,273,"68"],[92704396,261,"55"],
[92704396,32,"4/1/97"],[92704466,36,"1290"]],
"eos":true}

Description of properties:

  • stats.tick – device system clock tick (ms)
  • stats.recv- data received (bytes) in current trip
  • stats.elapsed – time elapsed (seconds) in current trip
  • stats.age – time elapsed (ms) since latest data entry received till it’s requested
  • stats.flag – 1 for driving/active, 0 for parked/inactive
  • data[] – data queue represented as an array of 3-element array consisting of timestamp, data type and data value
  • eos – indicates if this is the end of stream (no more data) at the time the request is made

Response (erroneous)

{"result":"failed","error":"Invalid server key"}
{"result":"failed","error":"Invalid FEED ID"}

Operation Sequence

The sequence of fetching complete data queue is like following.

  1. Getting data feed list (containing Feed  ID and some properties of the data feed)
  2. Fetching a data queue with rollback time specified
  3. Parsing response JSON payload, deal with the data and keep the time stamp of last data sample
  4. Fetching next data queue with time stamp specified (start time set as last data sample plus 1)
  5. Repeating 3 and 4