SenML Last Modified: 2017-09-21
Data Model for Sensor Measurement Lists
SenML IoT

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

Format Content-Type
JSON application/senml+json
CBOR application/senml+cbor
XML application/senml+xml
EXI application/senml+exi

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 Label Type Required
Base Name bn String No
Base Time bt Number No
Base Unit bu String No
Base Value bv Number No
Base Sum bs Number No
Version bver Number No
Name n String Yes, unless bn is in effect
Unit u String No
Value v Number See Value Fields
String Value vs String See Value Fields
Boolean Value vb Boolean See Value Fields
Data Value vd String See Value Fields
Value Sum s Number No
Time t Number No
Update Time ut Number No
Link l String No

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:

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:

base64 base64url
+ -
/ _
= %3D

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

Symbol Description Type  
m meter float  
kg kilogram float  
g gram* float  
s second float  
A ampere float  
K kelvin float  
cd candela float  
mol mole float  
Hz hertz float  
rad radian float  
sr steradian float  
N newton float  
Pa pascal float  
J joule float  
W watt float  
C coulomb float  
V volt float  
F farad float  
Ohm ohm float  
S siemens float  
Wb weber float  
T tesla float  
H henry float  
Cel degrees Celsius float  
lm lumen float  
lx lux float  
Bq becquerel float  
Gy gray float  
Sv sievert float  
kat katal float  
m2 square meter (area) float  
m3 cubic meter (volume) float  
l liter (volume) float  
m/s meter per second (velocity) float  
m/s2 meter per square second (acceleration) float  
m3/s cubic meter per second (flow rate) float  
l/s liter per second (flow rate) float  
W/m2 watt per square meter (irradiance) float  
cd/m2 candela per square meter (luminance) float  
bit bit (information content) float  
bit/s bit per second (data rate) float  
lat degrees latitude (note 2) float  
lon degrees longitude (note 2) float  
pH pH value (acidity; logarithmic quantity) float  
dB decibel (logarithmic quantity) float  
dBW decibel relative to 1 W (power level) float  
Bspl bel (sound pressure level; logarithmic quantity) float  
count 1 (counter value) float  
/ 1 (Ratio e.g., value of a switch) float  
% 1 (Ratio e.g., value of a switch) float  
%RH Percentage (Relative Humidity) float  
%EL Percentage (remaining battery energy level) float  
EL seconds (remaining battery energy level) float  
1/s 1 per second (event rate) float  
1/min 1 per minute (event rate, “rpm”) float  
beat/min 1 per minute (Heart rate in beats per minute) float  
beats 1 (Cumulative number of heart beats) float  
S/m Siemens per meter (conductivity) float  

Other Material