<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629-xhtml.ent">
<rfc xmlns:xi="http://www.w3.org/2001/XInclude" ipr="trust200902"
docName="draft-ietf-core-senml-more-units-06" number="8798"
submissionType="IETF" category="std" consensus="true" obsoletes=""
updates="" xml:lang="en" tocInclude="true" tocDepth="3" symRefs="true"
sortRefs="true" version="3">
<front>
<title abbrev="Additional Units for SenML">Additional Units for Sensor
Measurement Lists (SenML)</title>
<seriesInfo name="RFC" value="8798"/>
<author initials="C." surname="Bormann" fullname="Carsten Bormann">
<organization>Universität Bremen TZI</organization>
<address>
<postal>
<street>Postfach 330440</street>
<city>Bremen</city>
<code>D-28359</code>
<country>Germany</country>
</postal>
<phone>+49-421-218-63921</phone>
<email>cabo@tzi.org</email>
</address>
</author>
<date year="2020" month="June" />
<keyword>Internet of Things (IoT)</keyword>
<keyword>data model</keyword>
<keyword>quantities and units</keyword>
<keyword>International System of Units (SI)</keyword>
<keyword>International System of Quantities (ISQ)</keyword>
<keyword></keyword>
<abstract>
<t>The Sensor Measurement Lists (SenML) media type supports the
indication of units for a quantity represented. This short document
registers a number of additional unit names in the IANA registry for
units in SenML. It also defines a registry for secondary units that
cannot be in SenML's main registry, as they are derived by linear
transformation from units already in that registry.</t>
</abstract>
</front>
<middle>
<section anchor="intro" numbered="true" toc="default">
<name>Introduction</name>
<t>The Sensor Measurement Lists (SenML) <xref target="RFC8428"
format="default"/> media type supports the indication of a unit, using
the SenML field "u", for the quantity given as a data value in a SenML
record. For this purpose, SenML defines an IANA registry of defined
unit names and their meanings; in the present document, we call the unit
names registered there "primary unit names".</t>
<t>This short document registers a number of additional units in the
IANA registry for units in SenML that appear to be necessary for further
adopting SenML in other Standards Development Organizations (SDOs).</t>
<t>The document also defines a registry for secondary unit names that
cannot be in SenML's main registry, as they are derived by linear
transformation from units already in that registry.
Although SenML version 10 <xref target="RFC8428" format="default"/> does not provide for the direct use
of these secondary units, future support is intended via the use
of SenML extension mechanisms, one of which is proposed in <xref
target="I-D.ietf-core-senml-versions" format="default"/>.</t>
<t>
The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>",
"<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL
NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>",
"<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
"<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in this document are
to be interpreted as described in BCP 14 <xref target="RFC2119"/>
<xref target="RFC8174"/> when, and only when, they appear in all capitals,
as shown here.
</t>
</section>
<section anchor="new-units" numbered="true" toc="default">
<name>New Primary Units</name>
<t>IANA has assigned new units in the "SenML Units"
subregistry of the "Sensor Measurement Lists (SenML)" registry <xref target="IANA.SENML" format="default"/> (as defined in <xref target="RFC8428" format="default"/>):</t>
<table anchor="new-unit-tbl" align="center">
<name>New Units Registered for SenML</name>
<thead>
<tr>
<th align="left">Symbol</th>
<th align="left">Description</th>
<th align="left">Type</th>
<th align="left">Reference</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">B</td>
<td align="left">Byte (information content)</td>
<td align="left">float</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">VA</td>
<td align="left">volt-ampere (Apparent Power)</td>
<td align="left">float</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">VAs</td>
<td align="left">volt-ampere second (Apparent Energy)</td>
<td align="left">float</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">var</td>
<td align="left">volt-ampere reactive (Reactive Power)</td>
<td align="left">float</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">vars</td>
<td align="left">volt-ampere-reactive second (Reactive Energy)</td>
<td align="left">float</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">J/m</td>
<td align="left">joule per meter (Energy per distance)</td>
<td align="left">float</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">kg/m3</td>
<td align="left">kilogram per cubic meter (mass density, mass concentration)</td>
<td align="left">float</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">deg</td>
<td align="left">degree (angle)*</td>
<td align="left">float</td>
<td align="left">RFC 8798</td>
</tr>
</tbody>
</table>
<section anchor="rationale" numbered="true" toc="default">
<name>Rationale</name>
<t>SenML <xref target="RFC8428" format="default"/> takes the position
that unscaled SI units should always be used. However, SenML makes
one exception: The degree Celsius (as Cel) is allowed as an
alternative to the K (Kelvin).</t>
<t>This document takes the position that the same should apply to a
small number of alternative units in wide use:</t>
<dl spacing="normal">
<dt>The Byte:</dt> <dd><xref target="IEC-80000-13" format="default"/>
defines both the bit (item 13-9.b) and the byte (item 13-9.c, also
called octet) as alternative names for the coherent unit used for
dimensionless quantities, for the purpose of giving storage capacity
and related quantities. While the name octet is associated with the
symbol o, this is in wide use only in French-speaking countries.
Globally more widespread is the symbol B for byte, even though B is
already taken in SI for bel. <xref target="RFC8428"
format="default"/> therefore registers dB as the SenML unit for
logarithmic relative power, leaving B free for the usage proposed
here. While this is potentially confusing, the situation is widely
understood in engineering circles and is unlikely to cause actual
problems.</dd>
<dt>The Volt-Ampere:</dt> <dd><xref target="IEC-80000-6" format="default"/>
defines the volt ampere (VA) (item 6-57.a) as a unit for apparent
power; items 6-59.a, 6-60.a, and 6-61.a also use the unit for
complex, reactive, and non-active power.</dd>
<dt>The Volt-Ampere Reactive:</dt> <dd><xref target="IEC-80000-6"
format="default"/> item 6-60.b defines the volt-ampere
reactive (var) as an alternative (and fully equivalent) unit to VA
specifically for reactive power (with the primary unit VA); it has
become clear that there is strong interest in using this unit
specifically for the imaginary content of complex power, i.e.,
reactive power <xref target="IEEE-1459" format="default"/>.</dd>
</dl>
<t>The Joule per meter is not a traditional electromagnetic unit. It
and its scaled derivatives (in particular Wh/km) are used to describe
the energy expended for achieving motion over a given distance, e.g.,
as an equivalent for electrical cars of the inverse of "mileage".</t>
<t>The unit "degree" is in wide use in practice for plane angles (as
in heading, bearing, etc.). It is marked with an asterisk because the
preferred coherent SI unit is radian ("rad").</t>
</section>
</section>
<section anchor="new-registry" numbered="true" toc="default">
<name>New Registry for Secondary Units</name>
<t>IANA has created a "Secondary Units" subregistry in the
"Sensor Measurement Lists (SenML)" registry <xref target="IANA.SENML" format="default"/> defined in
<xref target="RFC8428" format="default"/>.</t>
<t>The registry has six columns:</t>
<ul spacing="normal">
<li>Secondary Unit: a newly registered name allocated within the same
namespace as SenML units</li>
<li>Description: a short description (usually just the expansion of
an abbreviation)</li>
<li>SenML Unit: an existing SenML unit from the SenML Units registry</li>
<li>Scale, Offset: two rational numbers, expressed in decimal
(optionally, with a decimal exponent given) or as a fraction
represented using a "/" character to separate numerator and
denominator</li>
<li>Reference: where the entry comes from</li>
</ul>
<t>Quantities expressed in the secondary unit can be converted into the
SenML unit by first multiplying their value with the scale number and
then adding the offset, yielding the value in the given SenML unit.</t>
<t>The initial content of the "Secondary Units" subregistry is provided in
<xref target="secondary-unit-tbl" format="default"/>:</t>
<table anchor="secondary-unit-tbl" align="center">
<name>Secondary Units Registered for SenML</name>
<thead>
<tr>
<th align="left">Secondary Unit</th>
<th align="left">Description</th>
<th align="left">SenML Unit</th>
<th align="right">Scale</th>
<th align="right">Offset</th>
<th align="left">Reference</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">ms</td>
<td align="left">millisecond</td>
<td align="left">s</td>
<td align="right">1/1000</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">min</td>
<td align="left">minute</td>
<td align="left">s</td>
<td align="right">60</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">h</td>
<td align="left">hour</td>
<td align="left">s</td>
<td align="right">3600</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">MHz</td>
<td align="left">megahertz</td>
<td align="left">Hz</td>
<td align="right">1000000</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">kW</td>
<td align="left">kilowatt</td>
<td align="left">W</td>
<td align="right">1000</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">kVA</td>
<td align="left">kilovolt-ampere</td>
<td align="left">VA</td>
<td align="right">1000</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">kvar</td>
<td align="left">kilovar</td>
<td align="left">var</td>
<td align="right">1000</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">Ah</td>
<td align="left">ampere-hour</td>
<td align="left">C</td>
<td align="right">3600</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">Wh</td>
<td align="left">watt-hour</td>
<td align="left">J</td>
<td align="right">3600</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">kWh</td>
<td align="left">kilowatt-hour</td>
<td align="left">J</td>
<td align="right">3600000</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">varh</td>
<td align="left">var-hour</td>
<td align="left">vars</td>
<td align="right">3600</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">kvarh</td>
<td align="left">kilovar-hour</td>
<td align="left">vars</td>
<td align="right">3600000</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">kVAh</td>
<td align="left">kilovolt-ampere-hour</td>
<td align="left">VAs</td>
<td align="right">3600000</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">Wh/km</td>
<td align="left">watt-hour per kilometer</td>
<td align="left">J/m</td>
<td align="right">3.6</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">KiB</td>
<td align="left">kibibyte</td>
<td align="left">B</td>
<td align="right">1024</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">GB</td>
<td align="left">gigabyte</td>
<td align="left">B</td>
<td align="right">1e9</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">Mbit/s</td>
<td align="left">megabit per second</td>
<td align="left">bit/s</td>
<td align="right">1000000</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">B/s</td>
<td align="left">byte per second</td>
<td align="left">bit/s</td>
<td align="right">8</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">MB/s</td>
<td align="left">megabyte per second</td>
<td align="left">bit/s</td>
<td align="right">8000000</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">mV</td>
<td align="left">millivolt</td>
<td align="left">V</td>
<td align="right">1/1000</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">mA</td>
<td align="left">milliampere</td>
<td align="left">A</td>
<td align="right">1/1000</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">dBm</td>
<td align="left">decibel (milliwatt)</td>
<td align="left">dBW</td>
<td align="right">1</td>
<td align="right">-30</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">ug/m3</td>
<td align="left">microgram per cubic meter</td>
<td align="left">kg/m3</td>
<td align="right">1e-9</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">mm/h</td>
<td align="left">millimeter per hour</td>
<td align="left">m/s</td>
<td align="right">1/3600000</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">m/h</td>
<td align="left">meter per hour</td>
<td align="left">m/s</td>
<td align="right">1/3600</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">ppm</td>
<td align="left">parts per million</td>
<td align="left">/</td>
<td align="right">1e-6</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">/100</td>
<td align="left">percent (Note 1)</td>
<td align="left">/</td>
<td align="right">1/100</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">/1000</td>
<td align="left">permille</td>
<td align="left">/</td>
<td align="right">1/1000</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">hPa</td>
<td align="left">hectopascal</td>
<td align="left">Pa</td>
<td align="right">100</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">mm</td>
<td align="left">millimeter</td>
<td align="left">m</td>
<td align="right">1/1000</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">cm</td>
<td align="left">centimeter</td>
<td align="left">m</td>
<td align="right">1/100</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">km</td>
<td align="left">kilometer</td>
<td align="left">m</td>
<td align="right">1000</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
<tr>
<td align="left">km/h</td>
<td align="left">kilometer per hour</td>
<td align="left">m/s</td>
<td align="right">1/3.6</td>
<td align="right">0</td>
<td align="left">RFC 8798</td>
</tr>
</tbody>
</table>
<aside>
<t>Note 1: This registration does not use the obvious name "%" because
this name has been taken in <xref target="RFC8428" format="default"/> already, where it is a <bcp14>NOT
RECOMMENDED</bcp14> synonym for "/" (unity) for legacy reasons. Note that the
presence of both "%" and "/100" with different meanings is likely to
create confusion, so the present document adds some weight to the
recommendation against using the counterintuitive unit name "%".</t>
</aside>
<t>Example: The value of a quantity given as 100 ms is first multiplied by
1/1000, yielding the number 0.1, and the offset 0 is then added, yielding the
number 0.1 again, leading to a quantity of 0.1 s. The value of a quantity
given as 10 dBm is first multiplied by 1, yielding the number 10, and the
offset -30 is then added, yielding the number -20, leading to a quantity of -20
dBW.</t>
<t>New entries can be added to the registration by Expert Review as
defined in <xref target="RFC8126" format="default"/>. Experts should
exercise their own good judgment, with the same guidelines as used for
SenML units (<xref target="RFC8428" sectionFormat="of"
section="12.1"/>), but without applying rules 4, 5, and 8. Note
that rule 7 limits the use of what could be understood as prefixes on
their own, not the use of prefixes inside secondary unit names.
Guidelines to the difference between units (which can go into the
registry) and quantities (which cannot) are widely available; see, for
instance, <xref target="RS" format="default"/> and <xref target="BIPM"
format="default"/>.</t>
<t>As of SenML version 10 <xref target="RFC8428" format="default"/>, SenML packs are limited to
using primary units in "u" fields.
The use of primary units enables direct comparison of measurements
from different sources. Also, it facilitates implementations that
trigger on the presence of a quantity in a certain unit, without the
need to track any additional secondary units that may be registered
for this quantity.</t>
<t>Where the benefits of directly using a secondary unit in a SenML pack
outweigh the above considerations,
the use of secondary units in "u" fields <bcp14>MAY</bcp14> be enabled by indicating a new SenML
version that specifically allows this and/or by using a field with a label name that ends with the "_"
character ("must-understand" field) whose definition specifically allows this.
The definition of these versions and fields is outside the scope of
the present specification; one such definition is proposed in <xref target="I-D.ietf-core-senml-versions" format="default"/>.</t>
</section>
<section anchor="operational-considerations" numbered="true" toc="default">
<name>Operational Considerations</name>
<t>The "Secondary Units" subregistry is expected to grow at a faster pace than
the subregistry of primary unit names. It also is amenable to automatic
interpretation, by making use of the scale and offset columns.</t>
<t>Implementers may be tempted to equip each instance of their systems
with code to download new versions of the registry from IANA
frequently in order to be able to make use of newly defined secondary
unit names. This can create high load at IANA and a potential single
point of failure. Instead of pulling the registry in each individual
instance of the code, the software update mechanism (or a similar
mechanism that leads to less frequent IANA visits) <bcp14>SHOULD</bcp14> be used to disseminate
updated units registries obtained from IANA towards the instances via
common repositories.</t>
</section>
<section anchor="seccons" numbered="true" toc="default">
<name>Security Considerations</name>
<t>The security considerations of <xref target="RFC8428" format="default"/> apply.</t>
<t>The introduction of new measurement units poses no additional security
considerations except a potential for additional
confusion about the proper unit to use and the risk that an
implementation based on the assumption described in the penultimate
paragraph of <xref target="new-registry" format="default"/> no longer works properly.
However, an implementation processing a pack while making use of
secondary units is guaranteed to have been developed with an awareness
of the risks of having multiple units available for the same logical
type.
In any case, the existing risk of an existing SenML implementation not
understanding a unit that was not in the initial registry content
provided in <xref target="RFC8428" format="default"/> is unchanged, and implementations are warned
properly about the potential use of secondary units by the need for a
must-understand field or an updated version field.</t>
</section>
<section anchor="iana" numbered="true" toc="default">
<name>IANA Considerations</name>
<t>See <xref target="new-units" format="default"/> and <xref target="new-registry" format="default"/>.</t>
</section>
</middle>
<back>
<displayreference target="I-D.ietf-core-senml-versions" to="SENML-VERSIONS"/>
<references>
<name>References</name>
<references>
<name>Normative References</name>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8428.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8126.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"/>
<reference anchor="IANA.SENML" target="https://www.iana.org/assignments/senml">
<front>
<title>Sensor Measurement Lists (SenML)</title>
<author>
<organization>IANA</organization>
</author>
</front>
</reference>
<!-- [IEC-80000-6] URL https://www.iso.org/standard/31891.html -->
<reference anchor="IEC-80000-6">
<front>
<title>Quantities and units - Part 6: Electromagnetism</title>
<author>
<organization>IEC</organization>
</author>
<date year="2008" month="March"/>
</front>
<seriesInfo name="IEC" value="80000-6"/>
<refcontent>Edition 1.0</refcontent>
</reference>
<!-- [IEC-80000-13] URL https://www.iso.org/standard/31898.html -->
<reference anchor="IEC-80000-13">
<front>
<title>Quantities and units - Part 13: Information science and technology</title>
<author>
<organization>IEC</organization>
</author>
<date year="2008" month="March"/>
</front>
<seriesInfo name="IEC" value="80000-13"/>
<refcontent>Edition 1.0</refcontent>
</reference>
<!--[IEEE-1459] URL https://ieeexplore.ieee.org/document/5439063 -->
<reference anchor="IEEE-1459">
<front>
<title>IEEE Standard Definitions for the Measurement of Electric
Power Quantities Under Sinusoidal, Nonsinusoidal, Balanced, or
Unbalanced Conditions</title>
<author>
<organization>IEEE</organization>
</author>
<date year="2010" month="March"/>
</front>
<seriesInfo name="IEEE Std" value="1459-2010"/>
<seriesInfo name="DOI" value="10.1109/IEEESTD.2010.5439063"/>
</reference>
</references>
<references>
<name>Informative References</name>
<!-- [I-D.bormann-core-senml-versions] replaced by draft-ietf-core-senml-versions-00
IESG state I-D Exists -->
<xi:include href="https://www.rfc-editor.org/refs/bibxml3/reference.I-D.ietf-core-senml-versions.xml"/>
<!-- [RS] The URL below resolves to the home page for Rohde & Schwarz GmbH &
Co. KG and is in German. Found URL
https://www.fisicalinda.com/wp-content/uploads/2018/10/Rohde-Schwarz-Correct-Usage-Quantities-Units-Equations.pdf
-->
<reference anchor="RS" target="https://scdn.rohde-schwarz.com/ur/pws/dl_downloads/dl_common_library/dl_brochures_and_datasheets/pdf_1/Standard-compliant_usage_of_quantities_units_and_equations_bro_en_5214-5061-62_v0500.pdf">
<front>
<title>Standard-compliant usage of quantities, units and
equations</title>
<author>
<organization>Rohde & Schwarz</organization>
</author>
<date year="2017" month="July"/>
</front>
<refcontent>version 5.0</refcontent>
</reference>
<reference anchor="BIPM" target="https://www.bipm.org/utils/common/pdf/si-brochure/SI-Brochure-9-EN.pdf">
<front>
<title>The International System of Units (SI)</title>
<author>
<organization>Bureau International des Poids et Mesures</organization>
</author>
<date year="2019"/>
</front>
<refcontent>9th edition</refcontent>
<refcontent>version 1.06</refcontent>
</reference>
</references>
</references>
<section numbered="false" anchor="acks" toc="default">
<name>Acknowledgements</name>
<t><contact fullname="Ari Keränen"/> pointed out the need for additional units in SenML.
Comments provided by him as well as by <contact fullname="Thomas Fossati"/>,
<contact fullname="Joaquin Prado"/>,
<contact fullname="Jaime Jiménez"/>, <contact fullname="Benjamin Kaduk"/>, and
<contact fullname="Rob Wilton"/> helped improve the document.</t>
</section>
</back>
</rfc>