Warning
WARNING: The TrackAbout MetaWiki has been deprecated and is no longer being updated. Please visit our new TrackAbout Knowledge Base at https://supportkb.trackabout.com for the most-up-to-date documentation on TrackAbout and TrackAbout Mobile.

Post Telemetry Device Data

From TrackAbout MetaWiki
Jump to navigation Jump to search
TrackAbout Feature
Feature Name: Post Telemetry Device Data
In Module: High Pressure Telemetry
Short Description Automatic readings from telemetry devices are posted to the TrackAbout website through this web service interface.
Available In:
← Back to list


<< Back to Web Services

Overview

This service requires that the Telemetry Module be enabled in your TrackAbout account. Contact your TrackAbout sales representative for details.

The Telemetry Module allows for the collection of readings from external telemetry devices, such as gas pressure monitors. It also allows for manually collecting readings using a mobile handheld device. Automatic readings from telemetry devices are posted to the TrackAbout website through this web service interface. Manually collected readings are posted when the mobile device is synced. All posted readings can be graphed on the web site, and email alerts can be set up when levels cross certain thresholds.

This TrackAbout web service was originally designed to accept readings from a specific type of device named the PMI2000 - which explains the name of the url seen below.

Use of SSL

It is recommended that the caller use SSL when possible for security.

Prior to Sending Readings

Prior to sending readings, the telemetry device must be registered on the TrackAbout web site. Navigate to Use Points >> Telemetry Devices and click on the Add New link. TrackAbout will ignore any readings posted from a device that has not been registered on the web site.

It is necessary for every telemetry device to have a globally unique ID. Today, we use the device's ethernet MAC Address for this purpose, as MAC Addresses are globally unique and centrally registered/controlled.

Constructing the Payload

The web service can be called using a variety of methods (see Usage below) but HTTP POST is probably the easiest and is conservative with the bytes sent. Using SOAP/XML will increase the number of bytes sent.

Example of an HTTP POST Payload

The following example shows the POST payload for a call to the web service. This particular call is from a (fake) device with MAC Address 001122334455 on the date shown in the POST. The device apparently has two sensors, sending readings of 0.45 and 76.0

POST /telemetry/PMI2000.asmx/PostReadings HTTP/1.1
Host: www.trackabout.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 128

MacAddress=001122334455&ReadingDateUtc=2010-05-06T20:52:01Z&Values=0.45&Values=76.0&Signature=FAB32728F100F0CB80A5B3998E2A6EE0

Parameters

Friendly Name Parameter Name Description
MAC Address MacAddress The globally unique MAC Address of the telemetry device sending the data. Maximum 20 characters.
Reading Date in UTC time ReadingDateUtc A UTC date/time, in the standardized format of: yyyy-MM-ddTHH:mm:ssZ (e.g. 2010-05-06T20:52:01Z)
Readings/Values Values One or more readings, one per sensor. Precision: 18 Scale: 2. Precision is the maximum total number of decimal digits that can be stored, both to the left and to the right of the decimal point. Scale is the maximum number of decimal digits that can be stored to the right of the decimal point.
MD5 Sum/Signature Signature Calculated as specified below, and UPPERCASED.

Calculating the MD5 Signature

To generate the string for input to the MD5 algorithm, concatenate together, separating with commas, the following:

  • MacAddress
  • ReadingDateUtc
  • All the Values

To this concatenated string, append without a comma the shared secret key, which you will need to get from TrackAbout. MD5 sum the resulting concatenated string using an ASCII encoding. Uppercase the result.

Psuedocode of the concatenation algorithm might look something like:

signature = MD5SumWithAsciiEncoding("MacAddress,ReadingDateUtc,Values,Values,ValuesSHARED_SECRET_KEY").ToUppercase()

Note that there is no comma between the last value and the secret key

The MD5 sum (or signature) is sent in the request as a separate posted value. The server will perform the same concatenation and MD5 sum operation, then compare its result to the passed-in sum to guarantee the payload is not corrupted. The addition of the shared secret key to the string provides additional authentication and prohibits unwanted outsiders from posting invalid readings. No outsider would have access to the shared secret key, and thus no outsider would be able to create an MD5 sum that would be accepted by the server.

Return Values and Validation

The web service will return a document containing one of the following messages.

Return Value Description
SUCCESS Successful processing
ERROR: ReadingDateUtc 'XXXX' is not a valid date. The specified date was not able to be parsed or was not otherwise valid.
ERROR: Value 'XXX' is not a valid number. One of the reading values was not able to be parsed as a valid number.
ERROR: Invalid Signature The server was not able to calculate the same MD5 hash that the caller provided.
ERROR: Unknown Mac Address The device's MAC Address was not registered on the TrackAbout web site.
ERROR: Unknown Some other unforeseen error has occurred.

Usage

If you request one of the following URLs, it will return further implementation details for calling the web service including the supported protocols.

Production Environment

  • Web Service URL: https://www.trackabout.com/telemetry/PMI2000.asmx

Test Environment

  • Web Service URL: https://test.trackabout.com/telemetry/PMI2000.asmx