Understanding and Interpreting SenML Data

The primary aim of this document is to provide a comprehensive guide on how to correctly interpret Sensor Measurement List (SenML) data within the KPN Things platform. This guidance is essential for ensuring accurate data processing and utilization on the receiving end of the platform.

Importance of Correctly Interpreting SenML Data

To get the most out of SenML data, it is important to interpret it correctly. Not doing so may result in missing or incorrect data in your downstream applications. As SenML data structures can be complex and varied, understanding the nuances is vital for reliable data handling.

Example SenML Records

SenML data is structured in JSON format to ensure uniformity and readability. Following are examples of correctly structured SenML records. All the records in this paragraph represent the same SenML data, this will help you understand what the SenML that arrives at your Destination might look like.

[
  {"bn": "urn:dev:ow:10e2073a0108006:", "bt": 1.320078429E+09, "n": "temperature", "u": "Cel", "v": 23.1},
  {"n": "humidity", "u": "%RH", "v": 67.3}
]

In the above example, we can see unresolved SenML. The SenML contains a base name (bn) and a base time (bt). A SenML Record is referred to as "resolved" if it does not contain any base values, i.e., labels starting with the character b, (except for Base Version fields), and has no relative times. The message above, when "resolved", looks like this:

[
  {"n": "urn:dev:ow:10e2073a0108006:temperature", "t": 1.320078429E+09, "u": "Cel", "v": 23.1},
  {"n": "urn:dev:ow:10e2073a0108006:humidity", "t": 1.320078429E+09, "u": "%RH", "v": 67.3}
]

As mentioned earlier, all the SenML in this paragraph represents the same data. So when it is resolved, it matches the SenML records in the previous example.

The records should be in chronological order in the resolved SenML, however in this example the time values are equal so switching the order still represents the same SenML:

[
  {"n": "urn:dev:ow:10e2073a0108006:humidity", "t": 1.320078429E+09, "u": "%RH", "v": 67.3},
  {"n": "urn:dev:ow:10e2073a0108006:temperature", "t": 1.320078429E+09, "u": "Cel", "v": 23.1}
]

Numeric values should be valid JSON numbers, which means that they can have a decimal point and an exponent. Therefore the above example is equal to the following example:

[
  {"n": "urn:dev:ow:10e2073a0108006:humidity", "t": 1.320078429000E+09, "u": "%RH", "v": 67.3000},
  {"n": "urn:dev:ow:10e2073a0108006:temperature", "t": 1.320078429000E+09, "u": "Cel", "v": 23.1000}
]

Time values are relative to the base time. So if measurement records have time values, they are relative to the value of the previous base time record. If you look at the example below, the base time should be added to the time fields of the measurements to resolve the time of the measurement.

The SenML data is the same as all the previous SenML messages.

[
  {"bn": "urn:dev:ow:10e2073a0108006:", "bt": 1.0E+09, "n": "temperature", "t": 3.20078429E+08, "u": "Cel", "v": 23.1},
  {"n": "humidity", "t": 3.20078429E+08, "u": "%RH", "v": 67.3}
]

It is possible to have multiple base value records. The base value applies to all successive measurements until another of that base value is found. In the example below, a single base name is used for all the records. On the contrary, the base time is altered in the second record. Since in both record the base time and the time elements add up to the same value, this data still equals the previous SenML examples.

[
  {"bn": "urn:dev:ow:10e2073a0108006:", "bt": 1.0E+09, "n": "temperature", "t": 3.20078429E+08, "u": "Cel", "v": 23.1},
  {"bt": 3.20078429e+08, "n": "humidity", "t": 1.0E+09, "u": "%RH", "v": 67.3}
]

Common Mistakes in Interpreting SenML

Working with SenML requires an understanding of the SenML data structures. Simple parsing strategies, such as string splitting, might work with one SenML representation, but could fail when dealing with a different one. When SenML is sent out to your destination, we give no guarantees on the representation.

It is advised that incoming data should be parsed and normalised to an appropriate internal representation of the resolved SenML records, before any further processing is attempted.

Libraries

To assist in correctly interpreting SenML, several libraries are available for different programming languages:

• JavaScript: senml-js

• Java: senml-java TO BE RELEASED

• C#: SenML.NET

These libraries are designed to handle the complexities of the SenML data and provide more reliable parsing and data extraction.

When in doubt you can always use the RFC: rfc8428 as a reference. Or take a look at the senml-spec GitHub page.

Conclusion

At KPN Things, we strive to adhere as closely as we can to the SenML standard. This dedication sometimes necessitates modifications on our end to align more precisely with these standards. We recommend our customers to also embrace this approach, ensuring customer applications remain robust and future-proof by closely following the SenML standard.

Understanding and correctly interpreting SenML data is crucial for accurate and reliable data processing when interacting with the KPN Things platform. We urge our users to follow best practices and consult the official SenML specification. Adhering to these guidelines not only guarantees data integrity but also maximizes the benefits derived from using the KPN Things platform.