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 submitted to Freematics Hub by the most common HTTP GET or POST methods which have best compatibility across all types of systems.  Response payloads are organized in JSON format. A prerequisite server key is required for any communications. HTTPS is always suggested for better security and protecting the server key.

The reference code for a data feed device is telelogger_sim800 (Arduino sketch for Freematics ONE with SIM800) or telelogger_esp8266 (Arduino sketch for Freematics ONE with ESP8266).

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 in browser. The stub can be developed to perform actions including user authentication, data storing and a lot more.

 

Feeding Data

A data logging device which collects telematics data from a target feeds the data to Freematics Hub by continuous HTTP GET or POST requests. The feeding sequence is simple as following regardless of the mechanism of data collection and caching inside the device as is illustrated in the reference code.

  1. Registering a data feed
  2. Feeding data (repeating)
  3. De-registering a data feed

 

Registering

This is an action to mark the start of a trip. When this is done, data cached from previous trip will be dumped. Vehicle identification number (VIN) is used as the unique identifier for the registration. A FEED ID is obtained after registering and should be kept for subsequent operations.

Request URL

http[s]://hub.freematics.com/<SERVER KEY>/reg?vin=<VIN>

Request Arguments

  • vin – vehicle identification number is used as identifier of a data feed. It can be literally arbitrary string but should be unique among all your feeds and the the length must be at least 16 characters

Response (success)

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

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

Response (erroneous)

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

 

De-registering

This is to deactivate a data feed and mark an end of a trip.

Request URL

http[s]://hub.freematics.com/<SERVER KEY>/reg/[FEED ID]?off=1

Request Arguments

  • id – FEED ID
  • off=1 – indicates this is a de-registering request

Response (success)

{"result":"done"}

n is an arbitrary integer number which is used for subsequent data feeding.

Response (erroneous)

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

 

Feeding instant data (GET)

This is to submit a set of instant data with a HTTP GET request. Multiple PID number and value pairs are accepted. PID numbers are in hex format and values are in decimal format (integer, float or x/y/z). 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]?[pid1]=[value1]&[pid2]=[value2]...

Request Arguments

  • id – FEED ID
  • pid – data type in hex number
  • value – data value as string

Please refer to Freematics Packed Data Format for more 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]

Request Arguments

  • id – 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

The software (web based, server side or App) which illustrate, process, analyze or store data, send HTTP GET 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","data":26253,"tick":505269,"age":2250,"flags":1,"csq":220},
{"id":"2","vin":"A1JC5236R3243232","data":432432,"tick":1205269,"age":1125,"flags":1,"csq":250},
...
]}

Properties:

  • id – FEED ID
  • vin – vehicle identification number
  • data – data received (bytes) in current 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":{"data":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

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,"data":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.data – 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 ID and some properties of a 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