Article for advanced users

Information on this page is intended for users with advanced technical knowledge.

Sensors - JSON Data Description

Sep 30, 2022 · 15 minutes to read

Treon Industrial Node Treon Industrial Node 6 Treon Node Treon Asset Node Treon Gateway

This article describes the JSON formatted sensor data sent from Treon Gateway to the backend.

IoT-devices like the Treon Node, Treon Industrial Node and Treon Asset Sensor send 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 individudal 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 measumenet 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.

JSON keyNotes
AccelerationSingle x,y,z acceleration value (JSON)
AirQualityAir quality index, volatile organic compounds
AirQualityStaticSlowly changing AirQuality (more hysteresis)
Ambient_lightLightning (lux)
BatteryAlertBattery alert (boolean). Note: only true-value is sent.
BatteryLevelBattery level (%).
BatteryVoltageBattery voltage (mV)
BurstDetailsDetailed information about burst that is starting (JSON)
CO2IndexCO2 equivalent index
DeviceTypeSensor device type (JSON)
DistanceDistance reading
GatewayIdSerial number of the gateway that sent the message. Number shown as HEX formatted string
HallMagnetic hall switch (boolean)
HwVerSensor HW version
HumidityAir humidity (%)
IAQaccuracyAir quality sensor calibration status
IAQaccuracyStaticIAQaccuracy for AirQualityStatic
McuFwApplication MCU software version.
MeasDetailsDetails of the measurement (JSON)
MovementMovement detected (boolean): acceleration was larger than a predefined value
NodeRoleWirepas role of the sensor node
NodeStatusStatus sent by the sensor node (bitmask)
ObjectsObject detected (boolean), PIR sensor
PressureAir pressure (hPa)
SelfTestSelftest result bitmask (value 0 indicates that all tests are passed)
SensorNodeIdIoT-device unique id as in the type label
SourceAddressWirepas node address of the sensor node
TemperatureTemperature (C)
TimestampUnix epoch timestamp added by the gateway (seconds)
TypeMessage type (scalar/burst/diagnostic)
UserUser button (boolean)
VibrationVibration data (JSON)
WeightWeight (g)
WpFwWirepas stack software version

 

Values for NodeRole
ValueNotes
2routing node
3non-routing node
18low-latency routing node
19low-latency non-routing node
130routing node, automatic role selection
131non-routing node, automatic role selection
146low-latency routing node, automatic role selection
147low-latency non-routing node, automatic role selection

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

 

Boolean values
ValueNotes
0false
1true

 

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.

ParameterNotes
XAcceleration reading
YAcceleration reading
ZAcceleration reading

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

DeviceType contains the following information:

ParameterNotes
ClassSensor device class
ModelSensor device model

 

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.

MeasDetails Data TypesNotes
BinSizeFrequency bin for FFT values (multiplied by 1000)
CalcIdCalculation id
FailMeasurement failure (JSON)
FFTFFT details (JSON)
FftWindowNode’s internal FFT calculation parameter (enum)
FftSizeNode’s internal FFT calculation parameter 512,1024,2048,4096
FilterFiltering details (JSON)
G-rangeG-range used in the measurement: 2G,4G,8G,16G
IdMeasurement id
PrecisionPrecision used in calculations (enum)
TriggerMeasurement reason (bitmap)
ValueOffsetFrequency Value offset for value array (multiplied by 10)

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**:

BurstDetails Data TypesNotes
MeasurementTimeIntervalSample time used to collect the samples (microseconds)
DataTypeDefines the type of data in the values array
ValueMappingDefines the semantics of the values contained in the Values array
BurstIdId used in each bust data fragment related to this data

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

Values for DataType:

ValueNotes
2Acceleration data
19FFT coefficients

The format of the data is defined by ValueMapping.

Enum values for FftWindow:

FFT Window (enum)Notes
0no window
1hanning

Enum values for Precision:

Precision (enum)
0float
1fixed point Q15

Bitmap values for Trigger:

Trigger (bit)Notes
0Timed measurement
1Alert
2Response to request
3Timed measurement 2
4Timed measurement 3

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.

ParameterNotes
BinSizeFrequency bin for FFT values (multiplied by 1000)
CalcIdCalculation id reference
FftWindowNode’s internal FFT calculation parameter (enum)
FftSizeNode’s internal FFT calculation parameter 512,1024,2048,4096
MultiplierMultiplier for FFT coefficients
OverlapSample overlap (%)
PrecisionPrecision used in calculations (enum)
ValueOffsetFrequency Value offset for value array (multiplied by 10)

Information contained in Filter:

ParameterNotes
CalcIdCalculation id reference
Decimationdecimation multiplier or 0 (no decimation)
HighCutoffHigher cutoff frequency (Hz), multiplied by 10
LowCutoffLower cutoff frequency (Hz), multiplied by 10
TypeFilter type: high pass(1),low pass(2), band pass (3)

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

Information contained in Fail:

ParameterNotes
CalcIdCalculation id reference
MeasSetIdMeasurement set id reference
ReasonProduct specific failure code
TriggerMeasurement trigger (enum)

Vibration data contains calculated scalar values for a measurement event:

Vibration Data TypesNotes
KurtosisKurtosis (JSON)
V-P2PVelocity amplitude (JSON), mm/s
A-P2PAcceleration amplitude (JSON), m/s^2
V-RMSVelocity RMS (JSON), mm/s
A-RMSAcceleration RMS (JSON), m/s^2
V-Z2PMax zero-to-peak amplitude, mm/s
A-Z2PMax zero-to-peak acceleration, m/s^2
CrestCrest (JSON)
UsedRangeMax %-value of range used in raw data (JSON)

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:

JSON NamesNotes
BurstIdBurst identifier. Same for all JSON messages belonging to the same burst
BurstDataOffsetStart offset of the values in the data array. Offset starts from 0
CalcIdCalculation id used as reference to calculation parameters
DataSizeTotal amount of bytes in the complete burst i.e. same burst id
DataTypeDefines the type of data in the values array, e.g. acceleration
MeasurementIdMeasurement id associated with current measurement event
MeasurementTimeIntervalSample time used to collect the samples (microseconds)
SensorNodeIdSensor node serial number
Type“burst”. Indicates JSON containing burst data
ValuesByte array containing the burst data
ValValues array as base64 encoded bytes
ValueMappingDefines the semantics of the values contained in the Values array

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

ValueMappingNotes
4Triplet of X,Y,Z acceleration 2G range [-128,127]
5Triplet of X,Y,Z acceleration 4G range [-128,127]
6Triplet of X,Y,Z acceleration 2G range [-32768,32767]
7Triplet of X,Y,Z acceleration 4G range [-32768,32767]
8Triplet of X,Y,Z acceleration 8G range [-32768,32767]
9Triplet of X,Y,Z acceleration 16G range [-32768,32767]
10X-axis [-32768,32767]
11Y-axis [-32768,32767]
12Z-axis [-32768,32767]
13X-axis filtered and decimated values [-32768,32767]
14Y-axis filtered and decimated values [-32768,32767]
15Z-axis filtered and decimated values [-32768,32767]

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

ValueMappingNotesUnit
0FFT values from X-axis, uint16Unit is mm/s
1FFT values from Y-axis, uint16Unit is mm/s
2FFT values from Z-axis, uint16Unit is mm/s
3Delta compressed FFT values from X-axis, uint8Unit is mm/s
4Delta compressed FFT values from Y-axis, uint8Unit is mm/s
5Delta compressed FFT values from Z-axis, uint8Unit is mm/s
6FFT values from X-axis, uint16Unit is m/s2
7FFT values from Y-axis, uint16Unit is m/s2
8FFT values from Z-axis, uint16Unit is m/s2
9Delta compressed FFT values from X-axis, uint8Unit is m/s2
10Delta compressed FFT values from Y-axis, uint8Unit is m/s2
11Delta compressed FFT values from Z-axis, uint8Unit is m/s2
12FFT values from X-axis, uint16Unit is m/s2. Multiplier from Measurement Details
13FFT values from Y-axis, uint16Unit is m/s2. Multiplier from Measurement Details
14FFT values from Z-axis, uint16Unit is m/s2. Multiplier from Measurement Details

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:

JSON keyNotes
BtAdvBluetooth advertising frame contents (base64 encoded).
BtRssiRSSI value reported by bluetooth.
SensorNodeIdBluetooth MAC address
iBeaconiBeacon data (JSON)
EddystoneEddystone data (JSON)
TxPowerTransmit power

iBeacon data:

JSON keyNotes
UUIDiBeacon unique ID
MajorMajor id
MinorMinor id

Eddystone data:

JSON keyNotes
FrameEddystone UID,URL
NamespaceEddystone UID
InstanceEddystone UID
UrlEddystone URL
AdvertisingCountEddystone TLM
SecondsSinceBootEddystone TLM

 

If you need any additional help with the interpretation of JSON data, or at any point are unsure how to proceed, please contact Treon Customer Support.

   


Was this article helpful? Let us know.
Next