General

SenML is a sensor measurement (and actuator command) list data model with multiple representations. Read the current RFC Draft here: Media Types for Sensor Measurement Lists (SenML)

Quote from Abstract:

This specification defines media types for representing simple sensor measurements and device parameters in the Sensor Measurement Lists (SenML). Representations are defined in JavaScript Object Notation (JSON), Concise Binary Object Representation (CBOR), eXtensible Markup Language (XML), and Efficient XML Interchange (EXI), which share the common SenML data model. A simple sensor, such as a temperature sensor, could use this media type in protocols such as HTTP or CoAP to transport the measurements of the sensor or to be configured.

Representations

There is a tool for converting between representations here: https://github.com/cisco/senml. The tool can also act as gateway server to other services.

Actuation

In addition to carrying measurements, the format can also be used for triggering actuators or configuration.

SenML can also be used for configuring parameters and controlling actuators. When a SenML Pack is sent (e.g., using a HTTP/CoAP POST or PUT method) and the semantics of the target are such that SenML is interpreted as configuration/actuation, SenML Records are interpreted as a request to change the values of given (sub)resources (given as names) to given values at the given time(s).

Data Model

The data format consists of the pack (array of records), the records (objects in array) and fields (attributes). The attribute names are called labels.

For example, multiple numeric measurements at 1 second intervals for a single sensor:

[
	{ "n": "urn:xxx/temp", "t":1.276020076e+09, "u": "Cel", "v":1.0 },
	{ "n": "urn:xxx/temp", "t":1.276020077e+09, "u": "Cel", "v":1.0 },
	{ "n": "urn:xxx/temp", "t":1.276020078e+09, "u": "Cel", "v":1.0 },
	{ "n": "urn:xxx/temp", "t":1.276020079e+09, "u": "Cel", "v":1.0 },
	{ "n": "urn:xxx/temp", "t":1.276020080e+09, "u": "Cel", "v":1.0 }
]

Base fields (prepended with b) can be used for expressing base values or to prevent repetition.

[
	{ "bn": "urn:xxx/", "n": "temp", "bu":"Cel", "bt":1.276020076e+09, "v":1.0 },
	{ "n": "temp", "t":1, "v":1.0 },
	{ "n": "temp", "t":2, "v":1.0 },
	{ "n": "temp", "t":3, "v":1.0 },
	{ "n": "temp", "t":4, "v":1.0 }
]

Resolving a pack means normalizing away all base values from the pack. This is done by applying the base values into the records in the order that they appear from first to last (When processing a record, the last “seen” base value in order of appearance is in effect when resolving a record). The records must must also be sorted in chronological order after applying the base values.

The rules for applying the base labels are listed below. If a field needed for resolving is missing, it is assumed to have the value 0 or the empty string depending on the field data type.

• Base Name (bn): prepended to Name (n)
• Base Time (bt): add to Time (t)
• Base Unit (bu): default Unit (u); use bu if u is not present
• Base Value (bv): add to Value (v)
• Base Sum (bs): add to Value Sum (vs)

The first example is basically a resolved version of the second one.

There are still traces of an old version of the spec in many writings on the subject. Base fields have since been moved onto the records from outside of the array, and the surrounding container object with the “e” attribute for the record list is no longer mentioned in the spec.

Labels

Name

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, Base Name must uniquely identify the resource. This can be used to represent a large array of measurements from the same sensor without having to repeat its identifier on every measurement.

Using URIs or URNs is recommended e.g.

• URI https://example.org/sensor1
• DEV URN: urn:dev:<subtype>:<value>
• UUID URN urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Subtypes for the DEV URN namespace:

• mac: EUI-64 identifier
• ow: Dallas Semiconductor 1-Wire identitifers
• cgi: Cryptographically Generated Identifiers

Value Fields

Value of the entry. Optional if a Sum value is present, otherwise required. Values are represented using basic data types. This specification defines floating point numbers (“v” field for “Value”), booleans (“vb” for “Boolean Value”), strings (“vs” for “String Value”) and binary data (“vd” for “Data Value”). Exactly one value field MUST appear unless there is Sum field in which case it is allowed to have no Value field.

The Data Value (vd) contents are base64url-encoded binary data. See Base 64 Encoding with URL and Filename Safe Alphabet.

Mappings between base64 and base64url-encodings:

Value Sum

Integrated sum of the values over time. This field is in the units specified in the Unit value multiplied by seconds.

See Usage Considerations in the RFC draft.

Time

Epoch time when value was recorded, e.g. 1.276020076e+09, or difference to Base Time (bt) e.g. -3. If time is missing, the record is considered to represent a “live” value (recorded “just now”).

Update Time

Max seconds to next measurement (use for failure detection or polling interval).

An optional time in seconds that represents the maximum time before this sensor will provide an updated reading for a measurement. This can be used to detect the failure of sensors or communications path from the sensor.

Custom Fields

Use custom regular or base labels at will, unknown fields are ignored unless the custom field ends with _.

Units

Other Material

• http://cse.aalto.fi/en/midcom-serveattachmentguid-1e46690ad37ffca669011e49c5b1326da53692a692a/iot_data_semantics_2906.pdf
• https://www.iab.org/wp-content/IAB-uploads/2016/03/IAB_IOTSI_Keranen_Jennings_SenML.pdf