Post Telemetry Device Data

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 w 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 or 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

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:

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