RFC 8798

Additional Units for Sensor Measurement Lists (SenML)

📅 published June 2020, from ietf

Additional Units for Sensor Measurement Lists (SenML) 🎀

Okay so bestie, let's talk about this RFC! 💖 It's RFC 8798, titled Additional Units for Sensor Measurement Lists (SenML), and it's giving main character energy 🦋✨

Here's the lowdown 💅: it was written by C. Bormann from Universität Bremen TZI, and it's a Standards Track document, which means it's the real deal and not just somebody's opinion 👑. It's dated June 2020 🌸 and it is an IETF document, so the whole community signed off on it 🫶. It doesn't obsolete anything and it doesn't update anything either, so it's totally standalone vibes 🌈. The ISSN is 2070-1721 💜.

Abstract

Okay so the Sensor Measurement Lists (SenML) media type lets you say what unit a quantity is measured in 📏✨ This short doc adds a bunch of extra unit names to the IANA registry for SenML units 💖. It also makes a brand new registry for secondary units, which are units that can't go in the main registry because they're derived by linear transformation from units already in there 🧚

Status of This Memo

This is an Internet Standards Track document 🔥. It's a product of the Internet Engineering Task Force (IETF), it represents the consensus of the IETF community 🫶, it got public review, and the Internet Engineering Steering Group (IESG) approved it for publication 👑. If you want more info about Internet Standards, check out Section 2 of RFC 7841 🎀.

You can find out the current status of this document, any errata, and how to give feedback on it at https://www.rfc-editor.org/info/rfc8798 🌸.

Copyright (c) 2020 IETF Trust and the persons identified as the document authors 💅. All rights reserved 🦋.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they were in effect on the date of publication 📜. Please read these carefully, bestie, because they spell out your rights and restrictions 🙈. Code Components pulled out of this document must include the Simplified BSD License text described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, as described in the Simplified BSD License 💀.

Table of Contents

  • 1. Introduction
  • 2. New Primary Units
    • 2.1. Rationale
  • 3. New Registry for Secondary Units
  • 4. Operational Considerations
  • 5. Security Considerations
  • 6. IANA Considerations
  • 7. References
    • 7.1. Normative References
    • 7.2. Informative References
  • Acknowledgements
  • Author's Address

1. Introduction ✨

Okay so the Sensor Measurement Lists (SenML) [RFC8428] media type supports indicating a unit using the SenML field "u" 📏, for the quantity given as a data value in a SenML record. SenML has its own IANA registry of defined unit names and what they mean, and in this doc we call those registered names "primary unit names" 🧚.

This short doc registers a bunch of additional units in the IANA registry for SenML units 💖. These units seem necessary for other Standards Development Organizations (SDOs) to adopt SenML too 🌈.

The doc also defines a registry for secondary unit names that can't go in SenML's main registry, since they're derived by linear transformation from units already in there 🦋. SenML version 10 [RFC8428] doesn't directly support these secondary units yet 🙈, but future support is intended through SenML's extension mechanisms, one of which is proposed in [SENML-VERSIONS] ✨.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here 🎀.

2. New Primary Units 💅

IANA has assigned new units in the "SenML Units" subregistry of the "Sensor Measurement Lists (SenML)" registry [IANA.SENML] (as defined in [RFC8428]) 🌸:

+========+======================================+=======+===========+
| Symbol | Description                          | Type  | Reference |
+========+======================================+=======+===========+
| B      | Byte (information content)           | float | RFC 8798  |
+--------+--------------------------------------+-------+-----------+
| VA     | volt-ampere (Apparent Power)         | float | RFC 8798  |
+--------+--------------------------------------+-------+-----------+
| VAs    | volt-ampere second (Apparent         | float | RFC 8798  |
|        | Energy)                              |       |           |
+--------+--------------------------------------+-------+-----------+
| var    | volt-ampere reactive (Reactive       | float | RFC 8798  |
|        | Power)                               |       |           |
+--------+--------------------------------------+-------+-----------+
| vars   | volt-ampere-reactive second          | float | RFC 8798  |
|        | (Reactive Energy)                    |       |           |
+--------+--------------------------------------+-------+-----------+
| J/m    | joule per meter (Energy per          | float | RFC 8798  |
|        | distance)                            |       |           |
+--------+--------------------------------------+-------+-----------+
| kg/m3  | kilogram per cubic meter (mass       | float | RFC 8798  |
|        | density, mass concentration)         |       |           |
+--------+--------------------------------------+-------+-----------+
| deg    | degree (angle)*                      | float | RFC 8798  |
+--------+--------------------------------------+-------+-----------+

                  Table 1: New Units Registered for SenML

2.1. Rationale 🧚

Okay so SenML [RFC8428] says unscaled SI units should always be used 📐. BUT 🙈 it makes one exception: the degree Celsius (written as Cel) is allowed as an alternative to the K (Kelvin) 🌡️.

This doc says the same should apply to a small number of alternative units that are widely used 💖:

  • The Byte: [IEC-80000-13] 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 giving storage capacity and related quantities 💾. The name octet goes with the symbol o, but that's only really used in French-speaking countries 🇫🇷. The symbol B for byte is way more common globally, even though B is already taken in SI for bel 😭. [RFC8428] registers dB as the SenML unit for logarithmic relative power, so B is free for the usage proposed here 🦋. It's potentially confusing, sure, but engineers widely understand the situation and it's unlikely to cause actual problems 💅.
  • The Volt-Ampere: [IEC-80000-6] 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 🌈.
  • The Volt-Ampere Reactive: [IEC-80000-6] 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's become clear there's strong interest in using this unit specifically for the imaginary content of complex power, i.e., reactive power [IEEE-1459] 👑.
  • The Joule per meter: this one isn't a traditional electromagnetic unit 🙈. It and its scaled versions (especially Wh/km) describe the energy spent getting something to move over a given distance 🚗🔋. For electric cars, it's like the inverse of "mileage" 💜.
  • The unit "degree": this one is widely used in practice for plane angles (like heading, bearing, etc.) 🧭. It's marked with an asterisk because the preferred coherent SI unit is the radian ("rad") 📐✨.

3. New Registry for Secondary Units ✨

okay so IANA made a brand-new "Secondary Units" subregistry 🎀 and it lives inside the "Sensor Measurement Lists (SenML)" registry [IANA.SENML], which is defined in [RFC8428].

The registry has six columns 💅:

  • Secondary Unit: a newly registered name allocated within the same namespace as SenML units
  • Description: a short description (usually just the expansion of an abbreviation)
  • SenML Unit: an existing SenML unit from the SenML Units registry
  • 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
  • Reference: where the entry comes from

Quantities in a secondary unit can be converted into the SenML unit by first multiplying their value by the scale number and then adding the offset. That gives you the value in the given SenML unit, and it's honestly so clean 🧚

The initial content of the "Secondary Units" subregistry is in Table 2 🌸

+=========+======================+=====+=========+======+===========+
|Secondary| Description          |SenML|   Scale |Offset| Reference |
| Unit    |                      |Unit |         |      |           |
+=========+======================+=====+=========+======+===========+
| ms      | millisecond          | s   |  1/1000 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| min     | minute               | s   |      60 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| h       | hour                 | s   |    3600 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| MHz     | megahertz            | Hz  | 1000000 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| kW      | kilowatt             | W   |    1000 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| kVA     | kilovolt-ampere      | VA  |    1000 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| kvar    | kilovar              | var |    1000 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| Ah      | ampere-hour          | C   |    3600 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| Wh      | watt-hour            | J   |    3600 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| kWh     | kilowatt-hour        | J   | 3600000 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| varh    | var-hour             |vars |    3600 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| kvarh   | kilovar-hour         |vars | 3600000 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| kVAh    | kilovolt-ampere-hour | VAs | 3600000 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| Wh/km   | watt-hour per        | J/m |     3.6 |    0 | RFC 8798  |
|         | kilometer            |     |         |      |           |
+---------+----------------------+-----+---------+------+-----------+
| KiB     | kibibyte             | B   |    1024 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| GB      | gigabyte             | B   |     1e9 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| Mbit/s  | megabit per second   |bit/s| 1000000 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| B/s     | byte per second      |bit/s|       8 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| MB/s    | megabyte per second  |bit/s| 8000000 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| mV      | millivolt            | V   |  1/1000 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| mA      | milliampere          | A   |  1/1000 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| dBm     | decibel (milliwatt)  | dBW |       1 |  -30 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| ug/m3   | microgram per cubic  |kg/m3|    1e-9 |    0 | RFC 8798  |
|         | meter                |     |         |      |           |
+---------+----------------------+-----+---------+------+-----------+
| mm/h    | millimeter per hour  | m/s |1/3600000|    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| m/h     | meter per hour       | m/s |  1/3600 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| ppm     | parts per million    | /   |    1e-6 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| /100    | percent (Note 1)     | /   |   1/100 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| /1000   | permille             | /   |  1/1000 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| hPa     | hectopascal          | Pa  |     100 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| mm      | millimeter           | m   |  1/1000 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| cm      | centimeter           | m   |   1/100 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| km      | kilometer            | m   |    1000 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+
| km/h    | kilometer per hour   | m/s |   1/3.6 |    0 | RFC 8798  |
+---------+----------------------+-----+---------+------+-----------+

Table 2: Secondary Units Registered for SenML

Note 1: okay this one's a little tea ☕ The registration doesn't use the obvious name "%" because [RFC8428] already took that name, where it's a NOT RECOMMENDED synonym for "/" (unity), kept around for legacy reasons. Having both "%" and "/100" with different meanings is likely to create confusion, so this document adds some weight to the recommendation against using the counterintuitive unit name "%". 🙈

Example time 🍓: a quantity given as 100 ms is first multiplied by 1/1000, which gives 0.1. The offset 0 is then added, so you still get 0.1, which means a quantity of 0.1 s. Next, a quantity given as 10 dBm is first multiplied by 1, giving 10. Then the offset -30 is added, giving -20, which means a quantity of -20 dBW. Math that's giving main character energy 💖

New entries can be added to the registration by Expert Review as defined in [RFC8126]. Experts should exercise their own good judgment, using the same guidelines as for SenML units (Section 12.1 of [RFC8428]), but without applying rules 4, 5, and 8. Also, rule 7 limits the use of what could be understood as prefixes on their own. It does not limit the use of prefixes inside secondary unit names. If you want to know the difference between units (which can go in the registry) and quantities (which can't), there are tons of resources out there. See, for instance, [RS] and [BIPM] 📚

As of SenML version 10 [RFC8428], SenML packs are limited to using primary units in "u" fields. Using primary units means you can directly compare measurements from different sources. It also makes life easier for implementations that trigger on a quantity showing up in a certain unit, without having to track any extra secondary units that might be registered for that quantity. Iconic, honestly 👑

That said, when the perks of directly using a secondary unit in a SenML pack outweigh those considerations, the use of secondary units in "u" fields MAY be enabled. You can do this by indicating a new SenML version that specifically allows it, and/or by using a field with a label name that ends with the "_" character (a "must-understand" field) whose definition specifically allows it. The definitions of those versions and fields are outside the scope of this specification. One such definition is proposed in [SENML-VERSIONS] 🦋

4. Operational Considerations 🌈

The "Secondary Units" subregistry is expected to grow faster than the subregistry of primary unit names. It's also easy for machines to interpret automatically, thanks to the scale and offset columns 🧚

Now, implementers might be tempted to give each instance of their systems code that downloads new versions of the registry from IANA frequently, so they can use newly defined secondary unit names. Lowkey, that can create high load at IANA and a potential single point of failure 😭 Instead of pulling the registry into every individual instance, the software update mechanism (or a similar mechanism that leads to less frequent IANA visits) SHOULD be used to disseminate updated units registries obtained from IANA to the instances via common repositories. Less traffic, more vibes 💅

5. Security Considerations 🔐

The security considerations of [RFC8428] apply.

Introducing new measurement units poses no additional security considerations, except for a potential for extra confusion about the proper unit to use, and the risk that an implementation based on the assumption described in the penultimate paragraph of Section 3 no longer works properly. That said, 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. Anyway, the existing risk of an existing SenML implementation not understanding a unit that wasn't in the initial registry content provided in [RFC8428] is unchanged. Implementations are properly warned about the potential use of secondary units by the need for a must-understand field or an updated version field. Be careful out there, bestie 🫶

6. IANA Considerations 📋

See Section 2 and Section 3.

7. References 📚

7.1. Normative References 📚

7.2. Informative References 🧚

Acknowledgements 🫶

Ari Keränen pointed out the need for additional units in SenML. Comments provided by him as well as by Thomas Fossati, Joaquin Prado, Jaime Jiménez, Benjamin Kaduk, and Rob Wilton helped improve the document. The whole crew 😭💜

Author's Address 🦋

Carsten Bormann
Universität Bremen TZI
Postfach 330440
D-28359 Bremen
Germany

Phone: +49-421-218-63921
Email: cabo@tzi.org
📦 where this page comes from