Post Telemetry Device Data - Revision history

Lsilverman: adjust formatting (by SublimeText.Mediawiker)

2023-01-13T19:47:17Z

adjust formatting (by SublimeText.Mediawiker)

Jwolbert at 13:24, 21 June 2016

2016-06-21T13:24:26Z

Tfusco at 16:52, 6 May 2010

2010-05-06T16:52:20Z

Tfusco at 16:48, 6 May 2010

2010-05-06T16:48:29Z

Lsilverman at 16:33, 6 May 2010

2010-05-06T16:33:24Z

Lsilverman at 16:32, 6 May 2010

2010-05-06T16:32:36Z

Lsilverman at 16:30, 6 May 2010

2010-05-06T16:30:19Z

Lsilverman at 16:26, 6 May 2010

2010-05-06T16:26:07Z

Lsilverman: Created page with '<< Back to Web Services === Overview === This service requires that the '''Telemetry Module''' be enabled in your TrackAbout account. Contact your TrackAbout …'

2010-05-06T16:24:06Z

Created page with '<< Back to Web Services === Overview === This service requires that the '''Telemetry Module''' be enabled in your TrackAbout account. Contact your TrackAbout …'

New page

[[Web_Services|<< 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 designed to accept readings from a specific type of device named the PMI2000.

=== 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|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

<pre>
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
</pre>

====Parameters====
{| class="wikitable" border="1" cellpadding="5"
|-
! 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.
* "SUCCESS" - Successful processing
* "ERROR: ReadingDateUtc 'XXXX' is not a valid date."
* "ERROR: Value 'XXX' is not a valid number."
* "ERROR: Invalid Signature"
* "ERROR: Unknown Mac Address"
* "ERROR: Unknown"

=== Usage ===

Production Environment

* '''Web Service URL:''' <nowiki>https://www.trackabout.com/telemetry/PMI2000.asmx</nowiki>

Test Environment

* '''Web Service URL:''' <nowiki>https://test.trackabout.com/telemetry/PMI2000.asmx</nowiki>

← Older revision		Revision as of 13:24, 21 June 2016
Line 1:		Line 1:
		+	{{TrackAbout Feature
		+	\|Parent Module=High Pressure Telemetry
		+	\|Feature Description=Automatic readings from telemetry devices are posted to the TrackAbout website through this web service interface.
		+	}}
	[[Web_Services\|<< Back to Web Services]]		[[Web_Services\|<< Back to Web Services]]

@@ Line 7: / Line 7: @@
 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 designed to accept readings from a specific type of device named the PMI2000.
+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===

← Older revision		Revision as of 16:33, 6 May 2010
Line 8:		Line 8:

	This TrackAbout web service was designed to accept readings from a specific type of device named the PMI2000.		This TrackAbout web service was designed to accept readings from a specific type of device named the PMI2000.
		+
		+	===Use of SSL===
		+	It is recommended that the caller use SSL when possible for security.

	=== Prior to Sending Readings ===		=== Prior to Sending Readings ===

← Older revision		Revision as of 16:26, 6 May 2010
Line 78:		Line 78:

	=== Usage ===		=== 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		Production Environment

@@ Line 106: / Line 106: @@
 Production Environment
-* '''Web Service URL:''' https://www.trackabout.com/telemetry/PMI2000.asmx
+* '''Web Service URL:''' <nowiki>https://www.trackabout.com/telemetry/PMI2000.asmx</nowiki>
 Test Environment
-* '''Web Service URL:''' https://test.trackabout.com/telemetry/PMI2000.asmx
+* '''Web Service URL:''' <nowiki>https://test.trackabout.com/telemetry/PMI2000.asmx</nowiki>

@@ Line 3: / Line 3: @@
 === Overview ===
-This service requires that the '''Telemetry Module''' be enabled in your TrackAbout account.  Contact your TrackAbout sales representative for details.
+This service requires that the '''[[High_Pressure_Telemetry|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.

@@ Line 70: / Line 70: @@
 ===Return Values and Validation===
 The web service will return a document containing one of the following messages.
-* "SUCCESS" - Successful processing
+{| class="wikitable" border="1" cellpadding="5"
-* "ERROR: ReadingDateUtc 'XXXX' is not a valid date."
+|-
-* "ERROR: Value 'XXX' is not a valid number."
+! Return Value
-* "ERROR: Invalid Signature"
+! Description
-* "ERROR: Unknown Mac Address"
+|-
-* "ERROR: Unknown"
+| SUCCESS
 === Usage ===