RFC 9100

Sensor Measurement Lists (SenML) Features and Versions

📅 published August 2021, from ietf

RFC 9100: Sensor Measurement Lists (SenML) Features and Versions ✨

Okay bestie, this is RFC 9100 💖 It's a Standards Track doc by C. Bormann from Universität Bremen TZI, dated August 2021. It's published under ISSN 2070-1721 and updates RFC 8428 (that's "Sensor Measurement Lists (SenML)"). 🎀

Quick rundown of the title block:

  • Category: Standards Track 🌸
  • Date: August 2021 📅
  • Updates: RFC 8428 🔁

Abstract

This short doc updates RFC 8428, "Sensor Measurement Lists (SenML)", by specifying the use of independently selectable "SenML Features" and mapping them to SenML version numbers. 🦋

Status of This Memo

This is an Internet Standards Track document. 🌈

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841. 💅

Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc9100. ✨

Copyright (c) 2021 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) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. 🫶

Table of Contents 📖

  • 1. Introduction
    • 1.1. Terminology
  • 2. Feature Codes and the Version Number
    • 2.1. Discussion
    • 2.2. Updating Section 4.4 of RFC 8428
  • 3. Features: Reserved0, Reserved1, Reserved2, Reserved3
  • 4. Feature: Secondary Units
  • 5. Security Considerations
  • 6. IANA Considerations
  • 7. References
    • 7.1. Normative References
    • 7.2. Informative References
  • Acknowledgements
  • Author's Address

1. Introduction 🌷

The Sensor Measurement Lists (SenML) spec [RFC8428] gives us a version number that's initially set to 10, but it doesn't say anything about how to actually make use of different version numbers. 🤷‍♀️

Here's the vibe: the usual idea with a version number is that it goes up one step at a time as the format picks up new stuff over the years. But for SenML, the likely plan is that independently selectable capability features get added on top of the basic spec that's marked by version number 10. 🧚 So this doc repurposes the single version number that comes with a pack of SenML records. It gets read as a bitmap, showing the set of features a recipient would need to have implemented in order to process the pack. It's giving clever. 😭

This short doc specifies the use of SenML Features and maps them to the SenML version number space, updating [RFC8428]. 💖

1.1. Terminology

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. 📌

When we do bit arithmetic, this doc uses the notation you already know from the C programming language [C], including the "0b" prefix for binary numbers defined in Section 5.13.2 of the C++ language standard [CPLUSPLUS]. The one difference is that superscript notation (example for two to the power of 64: 2^64) means exponentiation. In the plain text version of this doc, superscript notation is shown in paragraph text using C-incompatible surrogate notation, like in that example. In display math, it's a crude plain text representation, and the sum (Sigma) sign gets the same treatment. 🧮

2. Feature Codes and the Version Number 🎀

This spec defines "SenML Features." Each one is identified by a "feature name" (a text string) and a "feature code" (an unsigned integer less than 53). ✨

A specific version of a SenML pack is made up of a set of features. The SenML version number ("bver" field) is then a bitmap of those features, represented as an unsigned integer. Specifically, it's the sum of, for each feature present, two taken to the power of that feature's feature code (Figure 1). 🔢

              __ 52                     fc
   version = \           present(fc) ⋅ 2
             /__ fc = 0

Figure 1: Feature Bitmap as a Sum (Sigma Symbol) of Feature Bits

Here, present(fc) is 1 if the feature with the feature code "fc" is present, and 0 otherwise. (The expression 2^fc can be implemented as 1 << fc in C and related languages.) 💅

2.1. Discussion

Representing features as a bitmap inside a number is super efficient, as long as feature codes are handed out sparingly (see also Section 6). 🍓

Compatibility with the existing SenML version number, 10 decimal (0b1010), means four of the least significant bit positions have to be reserved for the base version, as described in Section 3. There's an upper limit on the range of integers that can be represented in all SenML representations: practical JSON limits this to 2^53-1 [RFC7493]. So feature codes 4 to 52 are available. One of them is taken by the feature defined in Section 4, which leaves 48 for allocation. (The current version 10, with all other feature codes unset, can be visualized as "0b00000000000000000000000000000000000000000000000001010".) 🧠 Over a lifetime of several decades, approximately two feature codes per year or fewer should be allocated. Also, less generally applicable features can always be communicated via fields labeled with names that end with the "_" character ("must-understand fields"). See Section 4.4 of [RFC8428] for details. 🦋

Most representations that engineers see in SenML use decimal numbers. For instance, 26 (0b11010, 0x1a) denotes a version that adds the "Secondary Units" feature (Section 4). It's a little unwieldy, but people will memorize it quickly. 🌈

Here's the tea 🍵: if you end up with dozens of individually selectable optional extensions over time, you get too many variants of what different implementations support, and interoperability takes a hit. So in practice, it's still desirable to batch up extensions that are expected to be supported together into a single feature bit. That makes it a sort of hybrid between fully independent extensions and a linear version scheme. This is another reason why a space of 48 remaining feature codes should be enough for a while. 👑

2.2. Updating Section 4.4 of RFC 8428

The last paragraph of Section 4.4 of [RFC8428] can be read as giving the impression that SenML version numbers are totally ordered. That means an implementation that understands version n also always understands all versions k < n. If that was ever true for SenML versions before 10, it's definitely no longer true with this spec. 🙈

Any SenML pack that sets feature bits beyond the first four will lead to a version number greater than 10. So the requirement in Section 4.4 of [RFC8428] will prevent false interoperability with version 10 implementations. 🛡️

Implementations that do implement feature bits beyond the first four (so, versions greater than 10) will instead need to do a bitwise comparison of the feature bitmap, as described in this spec. They also need to make sure all indicated features are understood before using the pack. For example, an implementation that supports basic SenML (version number 10) plus only a future feature code 5 will accept version number 42. But it won't be able to work with a pack indicating version number 26 (base spec plus feature code 4). (If the implementation requires feature code 5 without being backwards compatible, it will accept 42 but not 10.) 😭💅

3. Features: Reserved0, Reserved1, Reserved2, Reserved3 🧚

For SenML version 10 as described in [RFC8428], the feature codes 0 to 3 are already in use. Reserved1 (1) and Reserved3 (3) are always present. The features Reserved0 (0) and Reserved2 (2) are always absent. In other words, the four least significant bits set to 0b1010 indicate a version number of 10 if no other feature is in use. ✨

These four reserved feature codes aren't to be used with any more specific semantics, except in a specification that updates this one. (Note that Reserved0 and Reserved2 could be used in such a specification in a way similar to how feature codes 4 to 52 are used in the present specification.) 🌸

4. Feature: Secondary Units 🍓

The feature "Secondary Units" (code number 4) indicates that secondary unit names [RFC8798] MAY be used in the "u" field of SenML records, in addition to the primary unit names already allowed by [RFC8428]. 🌈

Note that the most basic use of this feature just sets the SenML version number to 26 (10 + 2^4). 💖

5. Security Considerations 🔐

⚠️ Serious security business ahead, bestie. Read this one carefully! 😤

The security considerations of [RFC8428] apply. This spec gives structure to how the SenML version number gets interpreted. That poses no additional security considerations, except for some potential for surprise, since version numbers don't simply increase linearly. 🙀

6. IANA Considerations ✨

okay bestie, IANA gets a brand new "SenML Features" subregistry inside the "Sensor Measurement Lists (SenML)" registry [IANA.SENML] 💖. The registration policy is "Specification Required" [RFC8126] 🫶, and the columns are:

  • Feature Code (an unsigned integer less than 53)
  • Feature Name (text)
  • Reference

To make feature names easy to use in programs 🧚, the designated expert is requested to make sure feature names work as identifiers in most programming languages. That means lowercasing the feature name in the registry entry and replacing blank space with underscores or hyphens, and the names also have to stay distinct in that form. No lookalike duplicates, periodt 💅.

The initial content of this registry is below, and it's giving very clean energy 🌸:

      +==============+=================+=====================+
      | Feature Code | Feature Name    | Reference           |
      +==============+=================+=====================+
      | 0            | Reserved0       | [RFC9100]           |
      +--------------+-----------------+---------------------+
      | 1            | Reserved1       | [RFC9100]           |
      +--------------+-----------------+---------------------+
      | 2            | Reserved2       | [RFC9100]           |
      +--------------+-----------------+---------------------+
      | 3            | Reserved3       | [RFC9100]           |
      +--------------+-----------------+---------------------+
      | 4            | Secondary Units | [RFC9100] [RFC8798] |
      +--------------+-----------------+---------------------+

         Table 1: Features Defined for SenML at the Time of
                              Writing

Now the important part, so listen up 👑. Feature codes are a hard-limited resource, with only 48 codes left at the time of writing 😭. So the designated expert is specifically instructed to run a frugal regime of code point allocation. The goal is to keep code points free for SenML Features that will be useful for non-trivial subsets of the SenML ecosystem. As a number, the expert could, for instance, aim for not allocating more than 10% of the remaining set per year. Protect the codes, bestie 🦋.

Where the specification of the feature code lives in a different document from the specification of the feature itself (like feature code 4 above), both specifications should be listed 🎀.

7. References 📚

7.1. Normative References

7.2. Informative References

Acknowledgements 🫶

Big hugs to everyone who made this happen! Ari Keränen proposed using the version number as a bitmap and gave more input on this spec 💜. Jaime Jiménez reviewed the document, clarified it, and acted as Document Shepherd 🌈. Elwyn Davies did a detailed GENART review with directly implementable text suggestions, and those suggestions now form part of this specification ⭐. Rob Wilton left comments, and one of them became the last paragraph of Section 2.1. Éric Vyncke helped with Section 2 🎀. Extra thanks go to the other IESG reviewers, you're all iconic 👑.

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