JSON Data Description for Treon Products

Oct 23, 2023 · 17 minutes to read

Introduction

Treon IoT-devices like the Treon Industrial Node, Treon Industrial Node 6, Treon Node and Treon Asset Sensor forward their measurements as binary data via the mesh network. The data is the processed by the Treon Gateway which then produces the JSON formatted data.
 

JSON Data

All Treon IoT-products contain a set of sensors which take readings depending on their individual specification and settings. The sensor data of these sensors is sent to the Treon Gateway through the mesh network. The Gateway then parses the messages and constructs a JSON message that is sent to a cloud backend. A JSON data dictionary structure contains values only from one IoT-device.

The contents of the JSON data depend on the configuration and the type of the IoT-device. JSON may also contain some additional key/value-pairs for development purposes. Any process using the JSON data can just ignore the keys it does not recognize.

Please note: Vibration data is only available from those Treon IoT-devices which are targeted for vibration analysis purposes.

JSON Message Types

Two main types of publish data exist: scalar values and stream data.

Scalar values are single readings or calculated values sent once from an IoT-device per measurement event.

Stream data contains array of data related to sampled measurement. Stream data is sent as a series of messages due to message size limitations of transfer technology.

The Treon Gateway with software releases from 6.2 onward may send also ‘diagnostic’ type JSON messages. These messages are not covered in this article.

Scalar Values JSON Formatting

Scalar-type messages are produced from all types of Treon IoT-devices. JSON message presents sensor values as key/value -pairs. Data type names (keys) start with capital letter.

Values for NodeRole

The value of HwVer varies inside a range. Treon can map these values for a specific hardware version.

Boolean values

JSON Fields

Acceleration contains information per axis:

Note: scalar-type acceleration data is not sent by Treon Industrial sensors. These sensors report acceleration raw data as burst data.

The axis data is dependent on the IoT-device. Only data for some of the axis may be sent.

DeviceType contains the following information:

Scalar Values For Vibration data

Vibration data uses MeasDetails and BurstDetails parameters to report the calculated values and measurement parameters.

MeasDetails contain information about the current measurement event.

The measurement id range is either [0:255] or [0:65535] depending on the sensor type.

The calculation id is used in measurement data, like FFT burst, to reference the certain set of FFT and filtering parameters.

A measurement may contain multiple stream data elements based on the configuration of the Iot-device. Each stream data element is sent as a burst described by BurstDetails**:

The BurstId range is either [0:255] or [0:65535] depending on the sensor type.

Values for DataType:

The format of the data is defined by ValueMapping.

Enum values for FftWindow:

Enum values for Precision:

Bitmap values for Trigger:

Information contained in FFT:

A separate FFT structure may be used instead of including FFT information into the body of MeasDetails. Reporting of FFT parameters depends on the sensor type and the software version.

Information contained in Filter:

The value is set to 0 if it is not applicable, like a higher cutoff frequency for a highpass filter.

Information contained in Fail:

Vibration data contains calculated scalar values for a measurement event:

On the JSON payload, all acceleration parameters have A- in front. Parameters without A- are velocity and not acceleration.

All vibration values are calculated from the same measurement event indicated by MeasId. The content of the JSON depends on the sensor configuration. E.g. if the sensor is configured to measure only the Y-axis, the RMS value is {“Y”: 34}.

Acceleration, Velocity, Crest and Kurtosis values are coefficient values multiplied by 100. That means the values received in the backend must be divided by 100 again to reach the correct measurement value.

Scalar Data Example

This is an example for scalar data. The calculated values from a Treon Industrial Node are: RMS, Kurtosis and amplitude.

\begin{Verbatim}[fontsize=\scriptsize]
{
  "SensorNodeId":"1bb9aebf",
  "SourceAddress":"12562103",
  "GatewayId":"bb3ff36a",
  "Temperature":23.67,
  "Timestamp":1631010967,
  "Vibration":
    {
      "RMS":
        {"Y":2,"X":2,"Z":2},
      "Kurtosis":{"Y":300,"X":311,"Z":296},
      "P2P":{"Y":11023,"X":16400,"Z":40130},
      "Z2P":{"Y":6096,"X":9346,"Z":25764}
    },
  "MeasDetails":
    {
      "FftSize":4096,
      "FftWindow":2,
      "G-range":4,
      "Precision":1,
      "BinSize":1000,
      "ValueOffset":0,
      "Trigger":1,
      "Id":200
    },
  "Type":"scalar"
}
\end{Verbatim}

The trigger value 1 (“Trigger”:1) indicates that the measurement was triggered by the measurement interval timer.

The measurement time interval is 181us, indicating a sample frequency of 1/181us = 5525Hz.

The frequency values from the values array are:

• $$ n \in [0,values array length-1] $$

• $$Frequency[n] = (ValueOffset/10) + (BinSize/1000)*n Hz $$

E.g.: The example frequency bin is (1000/1000) = 1 Hz. The FFT coefficients start from 0 Hz.

Stream Values JSON Formatting

Treon IoT-devices for vibration analysis like the Treon Industrial Node and Treon Industrial Node 6 send an array of sampled values or FFT coefficients as stream data. The data consists of several burst messages.

A Burst-type message contains:

Scalar-type JSON containing BurstDetails has been send prior starting a burst.

If ValueMapping indicates compressed values, the Values-array must be processed by a decompression algorithm.

DataSize and BurstDataOffset values refer to compressed data.

The fields Values and Val are mutually exclusive, either one of them is present depending on the application configuration.

Example JSON messages for a burst data fragment. Default configuration using Values-field:

\begin{Verbatim}[fontsize=\scriptsize]
{
  "Type":"burst",
  "MeasurementId":63,
  "BurstId":141,
  "DataType":2,
  "ValueMapping":7,
  "MeasurementTimeInterval":149,
  "BurstDataOffset":24480,
  "DataSize":24576,
  "Values":[-46,31,-79,-1,17,0,24,32,-69,-1,-9,-1,49,32,-80,-1,-11,-1,19,32,-83,-1,5,0,16,32,-85,
    -1,3,0,11,32,-84,-1,-2,-1,32,32,-60,-1,7,0,22,32,-42,-1,8,0,0,32,-93,-1,7,0,-1,31,119,-1,-28,
    -1,-7,31,-91,-1,-40,-1,50,32,-111,-1,8,0,3,32,-107,-1,26,0,-12,31,-82,-1,14,0,23,32,-100,-1,
    32,0,8,32,-82,-1,14,0],
  "SensorNodeId":"dd0102c3",
  "GatewayId":"bb3ff36a"
}
\end{Verbatim}

Here following an alternative format which uses base64 encoded data for Values. Enabling this format requires a configuration change to the Treon Gateway. The field name is changed from Values to Val.

\begin{Verbatim}[fontsize=\scriptsize]
{
  "Type":"burst",
  "MeasurementId":59,
  "BurstId":137,
  "DataType":2,
  "ValueMapping":7,
  "MeasurementTimeInterval":149
  "BurstDataOffset":1536,
  "DataSize":24576,
  "Val":["+B/F//H/2B+o//j/2R+l//v/CCDK/xcADyC0/ycA8x+k/w0AIiCU/xEACyCT/wYA5h+O
    /wAA9h+F/wAA+h+2//3/DSDO/wEAGyDI/+r/CyCq/wUAECCk/+X/LyCh/+b/"],
  "SensorNodeId":"dd0102c3",
  "GatewayId":"bb3ff36a"
}
\end{Verbatim}

DataType: ‘2’ indicates that this is raw acceleration data.

ValueMapping: ‘7’ tells that Values or Val contains data sampled using 4G acceleration range and it should be read as signed 16 bit numbers.

MeasurementTimeInterval: ‘149’ tells the sampling interval in microseconds. The here used sampling frequency is 1/149 us = 6711 Hz.

Acceleration Data Burst

Indicated by DataType:2

For the ValueMaps 10-15 the G-range setting must be read from MeasDetails.

The Values array contains byte values as ‘signed’ bytes [-128,127].

If the number range is [-32768,32767], the values in the array are ordered as:

\begin{Verbatim}[fontsize=\scriptsize]
X[0]_LSB,X[0]_MSB, Y[0]_LSB,Y[0]_MSB,Z[0]_LSB,Z[0]_MSB,X[1]_LSB,X[1]_MSB, etc...
\end{Verbatim}

Acceleration data samples must be interpreted as signed integers (int16). Byte ordering is ‘little-endian’.

Here an example of pseudocode for decoding the Values array:

\begin{Verbatim}[frame=leftline,fontsize=\scriptsize]
  n = 0
  lsb_byte = Values[n]
  if lsb_byte < 0:
    lsb_byte = lsb_byte + 256
  n = 1
  msb_byte = Values[n]
  if msb_byte < 0:
    msb_byte = msb_byte + 256
  sample_reading = msb_byte*256 + lsb_byte
\end{Verbatim}

Please note that sample_reading must be interpreted as signed 16bit integer!

ValueMapping 4 indicates that Values array contains triplets of x,y,z acceleration data as int8 value using range -2G,2G. First acceleration value for X-axis is 15/127 * 2G = 0,236G

FFT Data Burst

Indicated by DataType:19

By default, the Treon Industrial Node selects the output compression automatically if that produces less data. E.g. ValueMapping of consecutive x-axis FFT bursts may change between the values 0 and 3.

Values array contents must be read differently depending if delta compression is used or not:

• No compression: Unsigned integer (uint16) numbers are read as ‘little-endian’ from Values array. It contains data only for one axis indicated by ValueMapping. Pseudocode is similar to the Acceleration Data example with the exception that sample_reading is interpreted as unsigned integer.

• Compression: Refer to the next chapter ‘Compression’.

By default values are FFT coefficient values multiplied by 100, hence received values need to be divided by 100. FFT multiplier may be explicitly defined in MeasDetails.

Compression

Here an example for the FFT coefficient decompression:

\begin{Verbatim}[frame=leftline,fontsize=\scriptsize]
  i = 2
  n = 0

  Bytes = []
  for v in Values: 
    if v < 0:
      v = 256 + v
    Bytes.append(v)

  #Initial value is always presented as 2 byte integer
  Coefficient[n] = Bytes[0] + 256*Bytes[1] 
  n = n + 1
  while (i < len(Values)):
    # Small difference with consecutive values is handled as delta to the previous value
    if -127 < Values[i] < 127:
      Coefficient[n] = Coefficient[n-1] + Values[i]
      i = i + 1
      n = n + 1
    # value -128 is a marker byte used when difference is large. Coefficient is 2 byte integer
    elif Values[i] == -128:           
      Coefficient[n] = Bytes[i+1] + 256*Bytes[i+2] 
      i = i + 3 
      n = n + 1
\end{Verbatim}

If e.g. consecutive values are shown as delta to the previous value as long as the abs(delta) is less than 128. Otherwise value -128 is a marker indicating that next two bytes must be decoded as little-endian integer (uint16).

Example:
The received value array looks the like this:

\begin{Verbatim}
"Values": [52, 63, -128, 0, 0, 0, 0, 0, -128, -3, -123, -128, 85, 47,
56, -45, 0, 0,...
\end{Verbatim}

Interpretation:

• The initial value is 16-bit unsigned integer, presented by little endian bytes 52 (0x34) and 63 (0x3F). This results first coefficient 0x3F34 = 16180 (base 10).
• The next value ‘-128’ is a marker byte indicating that following two values in the array make up 16-bit unsigned integer: 0,0 -> 0
• The next 3 values ‘0,0,0’ indicate the difference to the previous value -> next three coefficients are 0
• The next value ‘-128’ is again a marker byte indicating that following two values form 16-bit unsigned integer: -3 (0xFD) -123 (0x85) -> 0x85FD = 34301 (base 10)
• The next value'-128' is again a marker byte. The next coefficient is 85 (0x55), 47 (0x2F) -> 0x2F55 = 12117 (base 10)
• Value 56 is the difference, so the next coefficient is: 12117 + 56 = 12173
• Value -45 is the difference, so the next coefficient is: 12173 - 45 = 12128

Finally, all decompressed values have to be divided by 100 to get the original calculated coefficients.

Measurement Sequence

The measurement event for the Industrial Node sensors proceeds like this:

1. Acceleration sensor is sampled for the period MeasurementTimeInterval.
   The temperature is also measured. The data is processed per each axis. The FFT axis data is sent when it is ready. Scalar values are aggregated for all requested axis prior sending scalar data.

2. Burst Start message (with BurstId) is sent to the Gateway and MeasDetails is sent.
   The Gateway forwards these messages to the cloud backend. The scalar message with BurstDetails and MeasDetails is sent.

3. FFT burst data is sent
   The Gateway forwards these messages to the cloud (BurstId is the same for all messages). The cloud backend decompresses the burst values data if needed.

4. Repeat step 3 for all requested axes

5. Scalar data with vibration values sent
   The Gateway forwards this message to the cloud backend.

Example Measurement

\begin{Verbatim}[frame=leftline,fontsize=\scriptsize]
{"Type":"scalar","Temperature":24.00,"GatewayId":"bb3ff36a","Timestamp":1605623123,"SensorNodeId":"d75eea0a",
  "BurstDetails":{"DataType":19,"MeasurementTimeInterval":152,"BurstId":69,"ValueMapping":5},
  "MeasDetails":{"FftSize":4096,"FftWindow":1,"G-range":4,"Precision":1,"BinSize":1000,"ValueOffset":0,
  "Trigger":1,"Id":16},
  "SourceAddress":"715359"}

{"FragCount":0,"ValueMapping":5,"DataType":19,"BurstId":69,"SensorNodeId":"d75eea0a",
  "Values":[9,0,-9,11,-1,-10,7,2,-9,6,-6,3,1,-4,3,-2,-1,1,-1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
  0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
  "GatewayId":"bb3ff36a","BurstDataOffset":0,"DataSize":1002,"Type":"burst",
  "MeasurementId":16,"MeasurementTimeInterval":152}

{"FragCount":1,"ValueMapping":5,"DataType":19,"BurstId":69,"SensorNodeId":"d75eea0a",
  "Values":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
  0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
  "GatewayId":"bb3ff36a","BurstDataOffset":99,"DataSize":1002,"Type":"burst",
  "MeasurementId":16,"MeasurementTimeInterval":152}

... 8 more message fragments ...

{"FragCount":10,"ValueMapping":5,"DataType":19,"BurstId":69,"SensorNodeId":"d75eea0a",
  "Values":[0,0,0,0,0,0,0,0,0,0,0,0],  
  "GatewayId":"bb3ff36a","BurstDataOffset":990,"DataSize":1002,"Type":"burst",
  "MeasurementId":16,"MeasurementTimeInterval":152}

{"SourceAddress":"715359","SensorNodeId":"d75eea0a","Timestamp":1605623127,"GatewayId":"bb3ff36a",
  "MeasDetails":{"Id":16},"Type":"scalar"}
\end{Verbatim}

Bluetooth Low Energy

When Bluetooth Low Energy parsing is enabled, the JSON data sent by the Treon Gateway can also contain data from the Bluetooth Low Energy sensors.

Additional JSON keys:

iBeacon data:

Eddystone data:

Burst Fragments

Each burst will have a unique measurement id, e.g: "MeasurementId":225 and burst id e.g: "BurstId":133. (Ids are not completely unique but cycle from 0..n depending on the node.) You should identify your burst with this information along with SensorNodeId.

After you have your burst fragments you can start combining them into complete bursts with their "Values", "Valuemapping", "BurstDataOffset" and "DataSize"-fields where:

How bursts are split into fragments

Bursts are split into smaller fragments and sent via wirepas to gateway which sends them to cloud. Each fragment contains partial array of the data-bytes from the complete burst. Because these fragments cannot be guaranteed to come in correct order and some might be missing they have field "BurstDataOffset" which tells to whoever processes nodes messages that this bursts fragment starts at at this byte-offset.

Below figure should illustrate how burst offset works:

In addition to all of this data sent there is also field "FragCount" which should never be used when reconstructing the complete burst. Field "FragCount" is added by the gateway and is just incrementing counter of how many fragments have arrived to the gateway. This means that if a fragment with "BurstDataOffset" of 96 would come before fragment with "BurstDataOffset" of 0 it would get smaller "FragCount" than the fragment with offset of 0.

Treon Support

You still have questions? Our dedicated team of experts is happy to help you! Please contact Treon Support directly by e-mail.

Did you know? Treon offers Premium Support and Maintenance Packages for our customers. Get even more out of Treon and boost your sales - inquire now about features and prices!