doc: Add RFC documents

1 files changed, 432 insertions, 0 deletions

diff --git a/doc/rfc/rfc8798.txt b/doc/rfc/rfc8798.txt
new file mode 100644
index 0000000..ae2ce88
--- /dev/null
+++ b/doc/rfc/rfc8798.txt
@@ -0,0 +1,432 @@
+
+
+
+
+Internet Engineering Task Force (IETF)                        C. Bormann
+Request for Comments: 8798                        Universität Bremen TZI
+Category: Standards Track                                      June 2020
+ISSN: 2070-1721
+
+
+         Additional Units for Sensor Measurement Lists (SenML)
+
+Abstract
+
+   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.
+
+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/rfc8798.
+
+Copyright Notice
+
+   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) 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
+   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
+
+   The Sensor Measurement Lists (SenML) [RFC8428] 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".
+
+   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).
+
+   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 [RFC8428] 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 [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
+
+   SenML [RFC8428] 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).
+
+   This document takes the position that the same should apply to a
+   small number of alternative units in wide use:
+
+   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 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.
+      [RFC8428] 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.
+
+   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 has become clear that there is strong
+      interest in using this unit specifically for the imaginary content
+      of complex power, i.e., reactive power [IEEE-1459].
+
+   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".
+
+   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").
+
+3.  New Registry for Secondary Units
+
+   IANA has created a "Secondary Units" subregistry in the "Sensor
+   Measurement Lists (SenML)" registry [IANA.SENML] 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 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.
+
+   The initial content of the "Secondary Units" subregistry is provided
+   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: This registration does not use the obvious name "%"
+      |  because this name has been taken in [RFC8428] already, where it
+      |  is a NOT RECOMMENDED 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 "%".
+
+   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.
+
+   New entries can be added to the registration by Expert Review as
+   defined in [RFC8126].  Experts should exercise their own good
+   judgment, with the same guidelines as used for SenML units
+   (Section 12.1 of [RFC8428]), 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, [RS] and [BIPM].
+
+   As of SenML version 10 [RFC8428], 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.
+
+   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 MAY 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 [SENML-VERSIONS].
+
+4.  Operational Considerations
+
+   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.
+
+   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) SHOULD be used to
+   disseminate updated units registries obtained from IANA towards the
+   instances via common repositories.
+
+5.  Security Considerations
+
+   The security considerations of [RFC8428] apply.
+
+   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
+   Section 3 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
+   [RFC8428] 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.
+
+6.  IANA Considerations
+
+   See Section 2 and Section 3.
+
+7.  References
+
+7.1.  Normative References
+
+   [IANA.SENML]
+              IANA, "Sensor Measurement Lists (SenML)",
+              <https://www.iana.org/assignments/senml>.
+
+   [IEC-80000-13]
+              IEC, "Quantities and units - Part 13: Information science
+              and technology", Edition 1.0, IEC 80000-13, March 2008.
+
+   [IEC-80000-6]
+              IEC, "Quantities and units - Part 6: Electromagnetism",
+              Edition 1.0, IEC 80000-6, March 2008.
+
+   [IEEE-1459]
+              IEEE, "IEEE Standard Definitions for the Measurement of
+              Electric Power Quantities Under Sinusoidal, Nonsinusoidal,
+              Balanced, or Unbalanced Conditions", IEEE Std 1459-2010,
+              DOI 10.1109/IEEESTD.2010.5439063, March 2010,
+              <https://doi.org/10.1109/IEEESTD.2010.5439063>.
+
+   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
+              Requirement Levels", BCP 14, RFC 2119,
+              DOI 10.17487/RFC2119, March 1997,
+              <https://www.rfc-editor.org/info/rfc2119>.
+
+   [RFC8126]  Cotton, M., Leiba, B., and T. Narten, "Guidelines for
+              Writing an IANA Considerations Section in RFCs", BCP 26,
+              RFC 8126, DOI 10.17487/RFC8126, June 2017,
+              <https://www.rfc-editor.org/info/rfc8126>.
+
+   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
+              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
+              May 2017, <https://www.rfc-editor.org/info/rfc8174>.
+
+   [RFC8428]  Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C.
+              Bormann, "Sensor Measurement Lists (SenML)", RFC 8428,
+              DOI 10.17487/RFC8428, August 2018,
+              <https://www.rfc-editor.org/info/rfc8428>.
+
+7.2.  Informative References
+
+   [BIPM]     Bureau International des Poids et Mesures, "The
+              International System of Units (SI)", 9th edition, version
+              1.06, 2019, <https://www.bipm.org/utils/common/pdf/si-
+              brochure/SI-Brochure-9-EN.pdf>.
+
+   [RS]       Rohde & Schwarz, "Standard-compliant usage of quantities,
+              units and equations", version 5.0, July 2017,
+              <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_v05
+              00.pdf>.
+
+   [SENML-VERSIONS]
+              Bormann, C., "SenML Features and Versions", Work in
+              Progress, Internet-Draft, draft-ietf-core-senml-versions-
+              00, 13 May 2020, <https://tools.ietf.org/html/draft-ietf-
+              core-senml-versions-00>.
+
+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.
+
+Author's Address
+
+   Carsten Bormann
+   Universität Bremen TZI
+   Postfach 330440
+   D-28359 Bremen
+   Germany
+
+   Phone: +49-421-218-63921
+   Email: cabo@tzi.org