SenML overview

Introduction

Data contained in a SenML message is structured as a single array (SenML Pack) including one or a series of measurements (SenML Records) that can contain fields such as a unique identifier for the sensor, the time the measurement was made, the unit the measurement is in, and the current value of the sensor.

For example, the following shows a measurement from a temperature gauge encoded in the JSON syntax.

[{ "n": "urn:dev:ow:10e2073a01080063", "u": "Cel", "v": 23.1 }]

In the example above, the array has a single SenML Record with a measurement for a sensor named urn:dev:ow:10e2073a01080063 with a current value of 23.1 degrees Celsius.

Supported formats

According to the SenML spec, messages can be represented in different ways. The table below shows for every format the current support status by Connhex.

Format	Supported
JSON (JavaScript Object Notation )	✅
CBOR (Concise Binary Object Representation)	✅
XML (Extensible Markup Language)	🚧
EXI (Efficient XML Interchange)	🚧

Records and fields

In the SenML format, each Record (single SenML measurement), can contain values of different types, such as:

• Number: used to communicate a number;
• Boolean: used to communicate an on/off state;
• String: used to communicate a string;
• Data: used to communicate raw data.

Each value is expressed together with other fields that characterize the measurements.

There are two type of fields: base and regular. Both the base and regular fields can be included in any SenML Record.

• The base fields apply to the entries in the Record and also to all Records after it up to, but not including, the next Record that has that same base field. All base fields are optional.
• The regular fields can be included in any SenML Record and apply only to that Record.

In the next paragraph you can find a non-exhaustive list of some base and regular fields available in the SenML format together with their associated label.

Base fields

• Base Name (bn): this is a string that is prepended to the names found in the entries.
• Base Time (bt): a base time that is added to the time found in an entry.
• Base Unit (bu): a base unit that is assumed for all entries, unless otherwise indicated. If a record does not contain a Unit value, then the Base Unit is used. Otherwise, the value found in the Unit (if any) is used.
• Base Value (bv): a base value is added to the value found in an entry, similar to Base Time.

Regular fields

• Name(n): name of the sensor or parameter. When appended to the Base Name field, this must result in a globally unique identifier for the resource. The name is optional, if the Base Name is present. If the name is missing, the Base Name must uniquely identify the resource.
• Time(t): time when the value was recorded (optional).
• Unit(u): unit for a measurement value (optional).
• Value : value of the entry. As stated before, values are represented using basic data types:
  • v: floating point numbers;
  • vb: boolean value;
  • vs: string;
  • vd: data/binary value.

Message examples - JSON format

Single data point

The following shows a temperature reading taken approximately "now" by a 1-wire sensor device (ow) that was assigned the unique 1-wire address of 10e2073a01080063.

N.B. if no time is specified, the time of receiving the measurement is taken as base time.

[{ "n": "urn:dev:ow:10e2073a01080063", "v": 3.6, "u": "V" }]

Multiple data points

The following example shows current measurements at Tue Jun 8 18:01:16.001 UTC 2010 and at each second for the previous 5 seconds.

[
  {
    "bn": "urn:dev:ow:10e2073a0108006:",
    "bt": 1.276020076001e9,
    "bu": "A",
    "bver": 5,
    "n": "voltage",
    "u": "V",
    "v": 120.1
  },
  { "n": "current", "t": -5, "v": 1.2 },
  { "n": "current", "t": -4, "v": 1.3 },
  { "n": "current", "t": -3, "v": 1.4 },
  { "n": "current", "t": -2, "v": 1.5 },
  { "n": "current", "t": -1, "v": 1.6 },
  { "n": "current", "v": 1.7 }
]

RFC8428

If you need more information about the SenML format, please refer to RFC 8428.