idnits 2.17.1 draft-ietf-core-senml-more-units-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (19 March 2020) is 1496 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'IEC-80000-13' -- Possible downref: Non-RFC (?) normative reference: ref. 'IEC-80000-6' -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE-1459' Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Bormann 3 Internet-Draft Universitaet Bremen TZI 4 Intended status: Standards Track 19 March 2020 5 Expires: 20 September 2020 7 Additional Units for SenML 8 draft-ietf-core-senml-more-units-06 10 Abstract 12 The Sensor Measurement Lists (SenML) media type supports the 13 indication of units for a quantity represented. This short document 14 registers a number of additional unit names in the IANA registry for 15 Units in SenML. It also defines a registry for secondary units that 16 cannot be in SenML's main registry as they are derived by linear 17 transformation from units already in that registry. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on 20 September 2020. 36 Copyright Notice 38 Copyright (c) 2020 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 43 license-info) in effect on the date of publication of this document. 44 Please review these documents carefully, as they describe your rights 45 and restrictions with respect to this document. Code Components 46 extracted from this document must include Simplified BSD License text 47 as described in Section 4.e of the Trust Legal Provisions and are 48 provided without warranty as described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 2. New Primary Units . . . . . . . . . . . . . . . . . . . . . . 2 54 2.1. Rationale . . . . . . . . . . . . . . . . . . . . . . . . 3 55 3. New Registry for Secondary Units . . . . . . . . . . . . . . 4 56 4. Operational Considerations . . . . . . . . . . . . . . . . . 7 57 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 58 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 59 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 60 7.1. Normative References . . . . . . . . . . . . . . . . . . 8 61 7.2. Informative References . . . . . . . . . . . . . . . . . 9 62 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 9 63 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 65 1. Introduction 67 The Sensor Measurement Lists (SenML, [RFC8428]) media type supports 68 the indication of a unit, using the SenML field "u", for the quantity 69 given as a data value in a SenML record. For this purpose, SenML 70 defines an IANA registry of defined Unit names and their meanings; in 71 the present document, we call the Unit names registered there 72 "primary Unit names". 74 This short document registers a number of additional units in the 75 IANA registry for Units in SenML that appear to be necessary for 76 further adopting SenML in other Standards Development Organizations 77 (SDOs). 79 The document also defines a registry for secondary Unit names that 80 cannot be in SenML's main registry as they are derived by linear 81 transformation from units already in that registry. Although SenML 82 version 10 [RFC8428] does not provide for the direct use of these 83 secondary units, they are planned to be supported via the use of 84 SenML extension mechanisms, one of which is proposed in 85 [I-D.bormann-core-senml-versions]. 87 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 88 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 89 "OPTIONAL" in this document are to be interpreted as described in 90 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 91 capitals, as shown here. 93 2. New Primary Units 95 IANA is requested to assign new units in the "SenML Units" 96 subregistry of the SenML registry [IANA.senml] (as defined in 97 [RFC8428]): 99 +--------+--------------------------------------+-------+-----------+ 100 | Symbol | Description | Type | Reference | 101 +========+======================================+=======+===========+ 102 | B | Byte (information content) | float | RFCthis | 103 +--------+--------------------------------------+-------+-----------+ 104 | VA | volt-ampere (Apparent Power) | float | RFCthis | 105 +--------+--------------------------------------+-------+-----------+ 106 | VAs | volt-ampere second (Apparent | float | RFCthis | 107 | | Energy) | | | 108 +--------+--------------------------------------+-------+-----------+ 109 | var | volt-ampere reactive (Reactive | float | RFCthis | 110 | | Power) | | | 111 +--------+--------------------------------------+-------+-----------+ 112 | vars | volt-ampere reactive second | float | RFCthis | 113 | | (Reactive Energy) | | | 114 +--------+--------------------------------------+-------+-----------+ 115 | J/m | joule per meter (Energy per | float | RFCthis | 116 | | distance) | | | 117 +--------+--------------------------------------+-------+-----------+ 118 | kg/m3 | kilogram per cubic meter (mass | float | RFCthis | 119 | | density, mass concentration) | | | 120 +--------+--------------------------------------+-------+-----------+ 121 | deg | degree (angle)* | float | RFCthis | 122 +--------+--------------------------------------+-------+-----------+ 124 Table 1: New units registered for SenML 126 2.1. Rationale 128 SenML [RFC8428] takes the position that unscaled SI units should 129 always be used. However, SenML makes one exception: The degree 130 Celsius (as Cel) is allowed as an alternative to the K (Kelvin). 132 This document takes the position that the same should apply to a 133 small number of alternative units in wide use: 135 * The Byte. [IEC-80000-13] defines both the bit (item 13-9.b) and 136 the byte (item 13-9.c, also called octet) as alternative names for 137 the coherent unit used for dimensionless quantities, for the 138 purpose of giving storage capacity and related quantities. While 139 the name octet is associated with the symbol o, this is in wide 140 use only in French-speaking countries. Globally more wide-spread 141 is the symbol B for byte, even though B is already taken in SI for 142 bel. [RFC8428] therefore registers dB as the SenML unit for 143 logarithmic relative power, leaving B free for the usage proposed 144 here. While this is potentially confusing, the situation is 145 widely understood in engineering circles and is unlikely to cause 146 actual problems. 148 * The Volt-Ampere. [IEC-80000-6]} item 6-57.a defines the VA (volt 149 ampere) as a unit for apparent power; items 6-59.a, 6-60.a and 150 6-61.a also use the unit for complex, reactive, and non-active 151 power. 153 * The Volt-Ampere-reactive. [IEC-80000-6] item 6-60.b defines the 154 var (volt ampere reactive) as an alternative (and fully 155 equivalent) unit to VA specifically for reactive power (with the 156 primary unit VA); it has become clear that there is strong 157 interest in using this unit specifically for the imaginary content 158 of complex power, i.e., reactive power [IEEE-1459]. 160 The unit "degrees" is in wide use in practice for plane angles (as in 161 heading, bearing, etc.). It is marked with an asterisk because the 162 preferred coherent SI unit is radian ("rad"). 164 The Joule per meter is not a traditional electromagnetic unit. It 165 and its scaled derivatives (in particular Wh/km) are used to describe 166 the energy expended for achieving motion over a given distance, e.g., 167 as an equivalent for electrical cars of the inverse of "mileage". 169 3. New Registry for Secondary Units 171 IANA is requested to create a "secondary units" subregistry in the 172 SenML registry [IANA.senml] defined in [RFC8428]. 174 The registry has six columns: 176 * secondary unit: a newly registered name allocated within the same 177 namespace as SenML units 179 * description: short description (usually just expansion of 180 abbreviation) 182 * SenML unit: an existing SenML unit from the SenML units registry 184 * scale, offset: two rational numbers, expressed in decimal 185 (optionally, with a decimal exponent given) or as a fraction 186 represented using a "/" character to separate numerator and 187 denominator. 189 * Reference: where does the entry come from. 191 Quantities expressed in the secondary unit can be converted into the 192 SenML unit by first multiplying their value with the scale number and 193 then adding the offset, yielding the value in the given SenML unit. 195 The initial content of the secondary units registry is provided in 196 Table 2: 198 +-----------+----------------------+------+-----------+---+---------+ 199 | secondary | description |SenML | scale |off| refer- | 200 | unit | | unit | |set| ence | 201 +===========+======================+======+===========+===+=========+ 202 | ms | millisecond | s | 1/1000 | 0 | RFCthis | 203 +-----------+----------------------+------+-----------+---+---------+ 204 | min | minute | s | 60 | 0 | RFCthis | 205 +-----------+----------------------+------+-----------+---+---------+ 206 | h | hour | s | 3600 | 0 | RFCthis | 207 +-----------+----------------------+------+-----------+---+---------+ 208 | MHz | megahertz | Hz | 1000000 | 0 | RFCthis | 209 +-----------+----------------------+------+-----------+---+---------+ 210 | kW | kilowatt | W | 1000 | 0 | RFCthis | 211 +-----------+----------------------+------+-----------+---+---------+ 212 | kVA | kilovolt-ampere | VA | 1000 | 0 | RFCthis | 213 +-----------+----------------------+------+-----------+---+---------+ 214 | kvar | kilovar | var | 1000 | 0 | RFCthis | 215 +-----------+----------------------+------+-----------+---+---------+ 216 | Ah | ampere-hour | C | 3600 | 0 | RFCthis | 217 +-----------+----------------------+------+-----------+---+---------+ 218 | Wh | watt-hour | J | 3600 | 0 | RFCthis | 219 +-----------+----------------------+------+-----------+---+---------+ 220 | kWh | kilowatt-hour | J | 3600000 | 0 | RFCthis | 221 +-----------+----------------------+------+-----------+---+---------+ 222 | varh | var-hour | vars | 3600 | 0 | RFCthis | 223 +-----------+----------------------+------+-----------+---+---------+ 224 | kvarh | kilovar-hour | vars | 3600000 | 0 | RFCthis | 225 +-----------+----------------------+------+-----------+---+---------+ 226 | kVAh | kilovolt-ampere-hour | VAs | 3600000 | 0 | RFCthis | 227 +-----------+----------------------+------+-----------+---+---------+ 228 | Wh/km | watt-hour per | J/m | 3.6 | 0 | RFCthis | 229 | | kilometer | | | | | 230 +-----------+----------------------+------+-----------+---+---------+ 231 | KiB | kibibyte | B | 1024 | 0 | RFCthis | 232 +-----------+----------------------+------+-----------+---+---------+ 233 | GB | gigabyte | B | 1e9 | 0 | RFCthis | 234 +-----------+----------------------+------+-----------+---+---------+ 235 | Mbit/s | megabit per second |bit/s | 1000000 | 0 | RFCthis | 236 +-----------+----------------------+------+-----------+---+---------+ 237 | B/s | byte per second |bit/s | 8 | 0 | RFCthis | 238 +-----------+----------------------+------+-----------+---+---------+ 239 | MB/s | megabyte per second |bit/s | 8000000 | 0 | RFCthis | 240 +-----------+----------------------+------+-----------+---+---------+ 241 | mV | millivolt | V | 1/1000 | 0 | RFCthis | 242 +-----------+----------------------+------+-----------+---+---------+ 243 | mA | milliampere | A | 1/1000 | 0 | RFCthis | 244 +-----------+----------------------+------+-----------+---+---------+ 245 | dBm | decibel (milliwatt) | dBW | 1 |-30| RFCthis | 246 +-----------+----------------------+------+-----------+---+---------+ 247 | ug/m3 | microgram per cubic |kg/m3 | 1e-9 | 0 | RFCthis | 248 | | meter | | | | | 249 +-----------+----------------------+------+-----------+---+---------+ 250 | mm/h | millimeter per hour | m/s | 1/3600000 | 0 | RFCthis | 251 +-----------+----------------------+------+-----------+---+---------+ 252 | m/h | meter per hour | m/s | 1/3600 | 0 | RFCthis | 253 +-----------+----------------------+------+-----------+---+---------+ 254 | ppm | parts per million | / | 1e-6 | 0 | RFCthis | 255 +-----------+----------------------+------+-----------+---+---------+ 256 | /100 | percent (Note 1) | / | 1/100 | 0 | RFCthis | 257 +-----------+----------------------+------+-----------+---+---------+ 258 | /1000 | permille | / | 1/1000 | 0 | RFCthis | 259 +-----------+----------------------+------+-----------+---+---------+ 260 | hPa | hectopascal | Pa | 100 | 0 | RFCthis | 261 +-----------+----------------------+------+-----------+---+---------+ 262 | mm | millimeter | m | 1/1000 | 0 | RFCthis | 263 +-----------+----------------------+------+-----------+---+---------+ 264 | cm | centimeter | m | 1/100 | 0 | RFCthis | 265 +-----------+----------------------+------+-----------+---+---------+ 266 | km | kilometer | m | 1000 | 0 | RFCthis | 267 +-----------+----------------------+------+-----------+---+---------+ 268 | km/h | kilometer per hour | m/s | 1/3.6 | 0 | RFCthis | 269 +-----------+----------------------+------+-----------+---+---------+ 271 Table 2: Secondary units registered for SenML 273 Note 1: This registration does not use the obvious name "%" because 274 this name has been taken in [RFC8428] already, where it is a NOT 275 RECOMMENDED synonym for "/" (unity) for legacy reasons. Note that 276 the presence of both "%" and "/100" with different meanings is likely 277 to create confusion, so the present document adds some weight to the 278 recommendation against using the counterintuitive unit name "%". 280 Example: the value of a quantity given as 100 ms is first multiplied 281 by 1/1000, yielding the number 0.1, and then the offset 0 is added, 282 yielding the number 0.1 again, leading to a quantity of 0.1 s. The 283 value of a quantity given as 10 dBm is first multiplied by 1, 284 yielding the number 10, and then the offset -30 is added, yielding 285 the number -20, leading to a quantity of -20 dBW. 287 New entries can be added to the registration by Expert Review as 288 defined in [RFC8126]. Experts should exercise their own good 289 judgment, with the same guidelines as used for SenML units 290 (Section 12.1 of [RFC8428]), but without applying the rules 4, 5, and 291 8. Note that rule 7 limits the use of what could be understood as 292 prefixes on their own, not the use of prefixes inside secondary unit 293 names. Guidelines to the difference between units (which can go into 294 the registry) and quantities (which cannot) are widely available, see 295 for instance [RS] and [BIPM]. 297 As of SenML version 10 [RFC8428], SenML packs are limited to using 298 primary units in "u" fields. The use of primary units enables direct 299 comparison of measurements from different sources. Also, it 300 facilitates implementations that trigger on the presence of a 301 quantity in a certain unit, without the need to track any additional 302 secondary units that may be registered for this quantity. 304 Where the benefits of directly using a secondary unit in a SenML pack 305 outweigh the above considerations, the use of secondary units in "u" 306 fields MAY be enabled by indicating a new SenML version that 307 specifically allows this and/or by using a field with a label name 308 that ends with the "_" character ("must-understand" field) whose 309 definition specifically allows this. The definition of these 310 versions and fields is outside the scope of the present 311 specification; one such definition is proposed in 312 [I-D.bormann-core-senml-versions]. 314 4. Operational Considerations 316 The secondary unit registry is expected to grow at a faster pace than 317 the registry of primary unit names. It also is amenable to automatic 318 interpretation, by making use of the scale and offset columns. 320 Implementers may be tempted to equip each instance of their systems 321 with code to download new versions of the registry from IANA 322 frequently, in order to be able to make use of newly defined 323 secondary unit names. This can create high load at IANA and a 324 potential single point of failure. Instead of pulling the registry 325 in each individual instance of the code, the software update 326 mechanism (or a similar mechanism that leads to less frequent IANA 327 visits) SHOULD be used to disseminate updated units registries 328 obtained from IANA towards the instances via common repositories. 330 5. Security Considerations 332 The security considerations of [RFC8428] apply. 334 The introduction of new measurement units poses no additional 335 security considerations except from a possible potential for 336 additional confusion about the proper unit to use, and from the risk 337 that an implementation based on the assumption described in the 338 penultimate paragraph of Section 3 no longer works properly. 340 However, an implementation processing a pack while making use of 341 secondary units is guaranteed to have been developed with an 342 awareness of the risks of having multiple units available for the 343 same logical type. In any case, the existing risk of an existing 344 SenML implementation not understanding a unit that was not in the 345 initial registry content provided in [RFC8428], is unchanged, and 346 implementations are warned properly about the potential use of 347 secondary units by the need for a must-understand field or an updated 348 version field. 350 6. IANA Considerations 352 See Section 2 and Section 3. 354 7. References 356 7.1. Normative References 358 [IANA.senml] 359 IANA, "Sensor Measurement Lists (SenML)", 360 . 362 [IEC-80000-13] 363 "Quantities and units - Part 13: Information science and 364 technology", Edition 1.0, IEC 80000-13, 1 March 2008. 366 [IEC-80000-6] 367 "Quantities and units - Part 6: Electromagnetism", 368 Edition 1.0, IEC 80000-6, 1 March 2008. 370 [IEEE-1459] 371 "IEEE Standard Definitions for the Measurement of Electric 372 Power Quantities Under Sinusoidal, Nonsinusoidal, 373 Balanced, or Unbalanced Conditions", IEEE Std 1459-2010, 374 19 March 2010. 376 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 377 Requirement Levels", BCP 14, RFC 2119, 378 DOI 10.17487/RFC2119, March 1997, 379 . 381 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 382 Writing an IANA Considerations Section in RFCs", BCP 26, 383 RFC 8126, DOI 10.17487/RFC8126, June 2017, 384 . 386 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 387 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 388 May 2017, . 390 [RFC8428] Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C. 391 Bormann, "Sensor Measurement Lists (SenML)", RFC 8428, 392 DOI 10.17487/RFC8428, August 2018, 393 . 395 7.2. Informative References 397 [BIPM] Bureau International des Poids es Mesures, "The 398 International System of Units (SI), 9th edition", 2019, 399 . 402 [I-D.bormann-core-senml-versions] 403 Bormann, C., "SenML Features and Versions", Work in 404 Progress, Internet-Draft, draft-bormann-core-senml- 405 versions-01, 6 March 2020, . 408 [RS] Rohde&Schwarz, "Standard-compliant usage of quantities, 409 units and equations", version 4.0, November 2016, 410 . 414 Acknowledgements 416 Ari Keranen pointed out the need for additional units in SenML. 417 Comments provided by him as well as by Thomas Fossati, Joaquin Prado, 418 Jaime Jimenez, Benjamin Kaduk, and Rob Wilton helped improve the 419 document. 421 Author's Address 423 Carsten Bormann 424 Universitaet Bremen TZI 425 Postfach 330440 426 D-28359 Bremen 427 Germany 429 Phone: +49-421-218-63921 430 Email: cabo@tzi.org